Skip to content

Migration descriptor file

Introduction

This document describes the migration configuration file (called migration descriptor) used to specify a sequence of migrations in a system. The migration descriptor file provides a way to describe the actions to be taken during the migrations in a declarative way.

The descriptor file must be named migration.yml. It can be located in the top level of the specified directory or in any of its subdirectories.

Example:

systemUnderAudit: Test_System

changesets:
  - name: 1.0.0
    changes:
      - migrate:
        dir-list: npl
      - npl-run:
        protocol: pkg/Factory
        action: create

  - name: 1.0.1
    changes:
      - migrate:
        dir-list: npl
        scripts: S0001_migration.kts

The Log

The migration log describes an ordered list of change sets to be applied to an environment. A change set will be applied to that environment to 'bring it up to date' by only applying the changes that have not yet been applied.

systemUnderAudit: my_system

changesets:
  - name: change_set_1
  - name: change_set_2
  - name: change_set_3

Properties

  • systemUnderAudit - Application name. This value will be used as prefix in naming the migration log protocol instance used to track changes that have been applied. Valid characters are alpha-numeric or an underscore(_).
  • A list of change sets each having a name.

Change Sets

One migration is made up of a set of changes to be executed in a specified order. It is characterised by a name which describes the change. The explicit order of change sets represents the order of execution. Valid characters are alpha-numeric, an underscore(_), or a period(.).

- name: release_alpha
  changes:
  # list of changes
- name: release_foo
  changes:
  # list of changes
- name: release_1.0.0
  changes:
  # list of changes

Properties

  • name - The unique identifier used to name the change.
  • changes - list of changes in the change set. The order of changes represents the execution order.

Changes

Unified migration (migrate)

Allows you to load the sources and run the migration in one step or separately. migrate has four sub-directives. Each one can be used independently of each other but at least one is required.

The sub-directives are as follows:

  • scripts - Comma separated list of scripts executed as part of the change
  • dir-list - Comma separated list of source directory prefixes. Prefix will be prepended to the change name, separated by a "-", to form the source directory name. The resulting directory must exist. For example, with a change: 1.0.0 and dir-list: npl, the resulting source directory would be npl-1.0.0.
  • run-only - see description of run-only

  • rules - Path of the party automation rules descriptor file. The file path is relative to the migration directory and can be located either at the root or in a subdirectory.

    • Rules are validated during the migration process. Invalid rules will cause the migration to fail.

    • If no rules file is provided, existing rules remain unchanged. The existing rules will then be validated to ensure the that they match any new sources.

    • To delete all existing rules, provide an empty rules descriptor file.

Samples

  • Upload NPL source files and run state migrations
- migrate:
  dir-list: npl
  scripts: S0001_migrate.kts
  • Deploying party automation rules
- migrate:
  rules: rules-dir/rules.yml
  • Uploads NPL sources, run state migrations, and deploy party automation rules
- migrate:
  dir-list: npl
  scripts: S0002_migrate.kts
  rules: rules-dir/rules.yml

Run NPL (npl-run)

Describes the loading and optional running of NPL code:

- npl-run:
  protocol: pkg/Factory
  action: create

It is possible to pass text (string) arguments for action as a comma separated list:

- npl-run:
  protocol: pkg/Factory
  action: create
  arguments: arg1, arg2, arg3

Properties

  • protocol - (required) - prototype id of factory protocol to instantiate
  • action - (required) - action to execute. If no 'arguments' property is given, it must be an action with no parameters

Reset (reset)

Declare a changeset as a reset in the history of changes. This is necessary to support breaking changes in NPL that makes it impossible to re-run/compile old parts of the history.

- reset: true

This change has a very special characteristic:

  • Any changeset in the migration descriptor file, e.g. migration.yml, before a reset becomes ineffective and only useful as a record of the migration actions that have been applied to production. They will no longer be applied to empty ( dev/test) systems. They will no longer be considered as part of checksum validations.
  • Executing a reset also closes the current migration log and opens a new one in the system being upgraded.

Properties

  • true|false - (required) - reset should always be set to true. Setting it to false is equivalent to omitting the change itself.

Run only (run-only)

Optional property on a change level. Consists of a comma-separated list of environment identifiers used to decide if the change shall be executed or skipped.

Changes without run-only are always run.

If run-only is non-empty, a change is executed only when the ENGINE_NPL_MIGRATION_RUN_ONLY environment variable is provided and matches one of the values in a run-only change list property.

Given the migration descriptor:

changes:
  - npl-load:
    run-only: DEV
    dir-list: "npl/core"

The npl-load change will only be executed when the ENGINE_NPL_MIGRATION_RUN_ONLY environment variable has the value DEV.