Workflow Migrator

This topic describes how to use the Workflow Migrator. The Workflow Migrator is shown in the following figure.

Migrator options

This migrator provides the following additional import behavior options:

Option Description

Replace existing special cmds?

If the workflow to be migrated references PPM special commands that already exist in the target PPM instance, you can replace them. This includes special commands that the workflow references directly, as well as special commands that these special commands reference. Special commands in validations that the workflow references are also migrated.

The default value is No. Regardless of the value, any special commands missing from the destination instance are created automatically.

Replace existing step sources?

If the workflow to be migrated references workflow decision and execution step sources that exist in the target PPM instance, you can choose to replace them or leave them in place. However, if workflows in the destination instance are using the existing step sources, you cannot change certain options (such as Workflow Scope,Validation, and Decision Type), even if you set Replace Existing Step Sources? to Yes.

Replace existing sub workflow?

To overwrite an existing subworkflow in the target environment when subworkflows are migrated (with or without the main workflow), set this option to Yes.

Add missing environments?

If the workflow to be migrated references environments or environment groups that do not exist in the target PPM instance, you can create the environments or environment groups. However, only the environment header information and user data are transferred. Application codes and extension-specific Environment tabs are not transferred. The default value is No.

Add missing request statuses?

If the workflow to be migrated references request status values that do not exist in the target PPM instance, you can create the status values. The default value is No.

For information about controls in this migrator, see Defining Entity Migrators.

Configuration considerations

The Workflow Migrator also transfers the following information:

  • Subworkflows that the workflow steps reference

  • Special commands that the command steps reference

  • Workflow step sources that the workflow steps reference

  • Validations that the parameters or workflow step sources reference

  • Environments and environment groups that the workflow steps reference

  • Environments that the environment groups referenced by workflow steps reference

  • Environments that validations reference

  • Special commands that validations reference

  • Special commands that the workflow step sources reference

  • Special commands referenced by other special commands referenced elsewhere

  • Security groups that the workflow steps reference

  • Request statuses that the workflow steps reference

  • Notifications that the workflow steps reference

  • Notification intervals that notifications reference

  • Security groups that notifications reference

  • Ownership group information for the workflow and workflow steps

If a notification in a workflow uses a notification interval that does not exist in the destination instance, the migrator creates this notification interval. The workflow migrator does not replace existing notification intervals in the destination instance.

The Workflow Migrator transfers entity restriction references to object types, but does not create an object type. If the referenced object type does not exist in the destination instance, the migrator discards the reference and records the event in its execution log.

The Workflow Migrator transfers references to request types, but does not create request types. If the referenced request type does not exist in the destination instance, the migrator discards the reference and records the event in its execution log.

If there are circular references between workflows and request types, you may have to migrate either a workflow or request type twice:

  • A new request type referring to a new workflow is migrated. Because the new workflow does not exist in the destination instance, all references to that workflow are dropped in transit.

  • The new workflow is migrated.

  • The new request type is migrated again. This time, because the referenced workflow exists, the references are preserved.

Replacing an existing workflow

There are some restrictions on using the Workflow Migrator to make change to a process that is already in use (by requests or package lines). These restrictions help to ensure that migration does not damage these existing requests or package lines.

Specifically, workflow migration cannot succeed unless the migrator logic finds a workflow step that corresponds to each step in the existing workflow. The following conditions are used to match workflow steps between instances:

  • The step source (the particular decision, execution, or condition) of a workflow step is used to match workflow steps. If the step source is not identical, then two workflow steps do not match.
  • If both the incoming and existing workflows assign a unique name to each workflow step, these workflow step names are used in combination with the step source to assess the match.

  • If a workflow step name is repeated within either workflow, the step sequence is used instead, in combination with the step source, to assess the match.

    The Workflow Migrator cannot handle a single change in which both the names of existing workflow steps and the step sequence of existing workflow steps have changed.

    To change both the names and step sequences of a workflow:

    • Change step names, but do not change any step sequences. Migrate the changed workflow.
    • Change step sequences, but do not change any step names. Migrate the changed workflow a second time.

    Because of this matching restriction, each open request is on the same process step following the migration as it was before the migration. The migration might have changed the name of this step, but it has not transitioned request workflows.

Keep in mind that the migrator does not prevent the removal of outgoing transitions from workflow steps. Therefore, avoid “stranding” open requests at a workflow step that will be deprecated. When deprecating a process step, remove incoming transitions, but leave at least one outgoing transition from the step. This lets open requests move forward. The execution log for the migration contains a table that lists old and new workflow steps.

We recommend that you use the Preview import mode first when you replace an existing workflow, and inspect this table of matched workflow steps before you run the workflow migration in non-preview mode.

Deprecating a workflow

When the changes to a workflow are extensive, you can deprecate the existing workflow and bring the changes into the production instance as a new workflow. One advantage of implementing the changes as a new workflow is simplicity, since the new workflow is not required to contain all of the steps of the old workflow for backward compatibility.

To bring a new workflow into a production instance:

  1. Rename the existing workflow and disable it in production.

    Disabling the workflow removes it from lists of workflow options when new requests are created. Requests that are in process continue to the old workflow until they close, unless each is manually shifted to the new process and transitioned to an appropriate point in the process. Existing defaulting rules and other configurations also continue to refer to the old workflow, regardless of the name change.

  2. Migrate the new version of the workflow into the production instance, under the original name.

    Because the production instance no longer contains a workflow by this name, the migrator treats it as a new workflow.

  3. After the migration, you can update defaulting rules in request types to reference this new workflow.

    You can do this manually, or by migrating in versions of the request types that refer to the new workflow by its original name.