ProcessMigration Extension

Introduction

As an Appway administrator, you are responsible for a platform with potentially many thousands of users and need to support requests requiring changes to a large number of Process Instances and Process Tokens.

The ProcessMigration Extension facilitates such tasks by allowing you to:

• Define filters to select the Process Instances and Process Tokens you want to modify.
• Define actions to perform on all Process Instances and Process Tokens that pass these filters.
• Run a batch program with the above definitions to modify Process Instances and Process Tokens in batch.

The filters and actions for Process Instances and Process Tokens are applied in this sequence:

1. If a Process Instance is accepted by all Process Instance filters, then…

2. …all Process Instance actions are executed.

3. For every Process Token in this Process Instance: If the Process Token is accepted by all Process Token Filters…

4. …all Process Token actions are executed.

Defining and Running Batch Programs

Access the ProcessMigration extension via Solution Maintenance > Migration Tools > Processes in Appway Studio.

After clicking the Start link, an overview of available and running batch programs is displayed:

Note: Batch programs are stored as 'Resource' Business Objects in the Library.

To define and run a batch program:

1. Select Edit Program from the context menu of an existing program (or click on New… to create a new program first).
2. Define filters to determine which Process Instances and Process Tokens you want to perform actions on. See Filters for details.
3. Define the actions to perform on the filtered Process Instances and Process Tokens. See Actions for details.
4. (Optional) Test your filters by selecting Preview Program from the context menu.
5. Select Run Program and follow the wizard to execute your program. Process Instances are paused during execution. See the following subsection for some tips on using the wizard.

Tips on Using the Wizard

For the most part, the wizard which guides you through the process of running your program is self-explanatory, but a few useful tips are summarized here.

Options Step Select Include Process Token Filters to select Process Instances to specify that a Process Instance is only accepted if at least one Process Token is accepted by all Process Token filters. This is helpful if there are no Process Instance filters at all or you want to execute Process Instance actions only if a Process Token with specific characteristics exists.

Execution Report Step The Execution Report step summarizes which actions were performed by your program:

At this point you have two options:

• Click on Next to proceed to the Cleanup step and finish the migration process.

Note: The Cleanup step deletes the backup of the migrated Process Instance(s) and Value Store(s).

• Select Restore Process Data before clicking on Next to restore your backup data and abort the migration.

To decide which of these two options to select, verify if your program ran successfully:

• Check the details of the migration by clicking on the links in the Execution Report (in the columns Executed, Warnings etc.).
• Clicking on a link provides more information and makes a further link available: Details. Click on this link to open the Process Instance window.
• In the Process Instance window, you can resume the Process Instance (Process Instances are paused when you run your program), make an update to it, and verify that the expected result was achieved.
• Close the window and click on Back to return to the Execution Report.
• Repeat these steps to verify other parts of the migration as applicable.

Filters

Define filters to determine which Process Instances/Tokens you want to perform actions on. Filters are combined with AND, i.e. Process Instances and Tokens must fulfill all defined filters to pass.

Filters for Process Instances

The available filters for Process Instances are:

The following options are available:

• Condition – Filters Process Instances by a condition that must be evaluated as 'true' in the specified scope (Action or Process Instance). Description of scopes:
  • Action – This is independent of the Process Instance where your condition can depend on an external resource for further evaluation – e.g. reading a file and returning either true or false depending on the content of the file.
  • Process Instance – This uses the Process Instance in evaluation – e.g. if you have a Boolean variable $isApproved in the Process Instance, then you can specify Return $isApproved. The variable is recognized during evaluation as it is defined in the Process Instance.

• Instance Attribute – Filters Process Instances by the status of the specified attribute (value, existence, not empty etc.) *
• Instance Due Date – Filters Process Instances by their due date. *
• Instance Id – Filters Process Instances by their ID. *
• Instance Modification Date – Filters Process Instances by their modification date. *
• Instance Root Process – Filters Process Instances by their root process. In this option, the root process is specified by the Process ID (e.g. TheApprovalProcess). The root process is the process that was originally started; a sub-process cannot be the root process.
• Instance Start Date – Filters Process Instances by their creation/start date (in this context, start and creation date are the same). *
• Instance Status – Filters Process Instances by their status. *
• Instance Type – Filters Process Instances according to their type. Options are:
  • Persistent – By default, any process instance which is not bound to an HTTP session is persistent, which means it is saved and has swimlanes.
  • Bound to HTTP session – Instances of this type are temporary.
  • Modified – (Deprecated, do not use)
  • Overdue – Instances which have passed their due date.

Locked (Deprecated, do not use) * Paused – Instances paused in the Console. * Live – Instances not paused in the Console.

• Instance Version Filter – Filters Process Instances by their version filter, *Head, Latest Committed or Timestamp. *

* Information on the current value of this property for existing Process Instances is available in the Studio at Solution Maintenance > Processes > Process Instances. To access some values, you need to double-click an instance in the list and go to the Info tab.

Filters for Process Tokens

The available filters for Process Tokens are:

The following options are available:

• Condition – Filters Tokens by a condition that must be evaluated as true in the specified scope (Action or Process Instance). Description of scopes:
  • Action – This is independent of the workflow instance where your condition can depend on an external resource for further evaluation – e.g. reading a file and returning either true or false depending on the content of the file.
  • Process Instance – This uses the Process Instance in evaluation – e.g. if you have a Boolean variable $isApproved in the Process Instance, then you can specify Return $isApproved. The variable is recognized during evaluation as it is defined in the Process Instance.

• Token Attribute – Filters Tokens by the status/value of the specified attribute (value, existence, not empty etc.). *
• Token Creation Date – Filters Tokens by their creation date. *
• Token Depth – Filters Tokens by their nesting level. The value "1" indicates that the token is on the level of the root process; higher values indicate the nested depth of the token. *
• Token Due Date – Filters Tokens by their due date. *
• Token Element Type – Filters Tokens by the process element they are on. Elements you can define include Tasks, Events and Gateways. *
• Token Id – Filters Tokens by their ID. *
• Token Modification Date – Filters Tokens by their modification date. *
• Token Participant – Filters Tokens by the assigned participant (user, role, group). *
• Token Priority – Filters Tokens by their priority. *
• Token Process Element – Filters Tokens by the process they are in. Optionally, you can also define the element within the process on which the token must be. *
• Token Status – Filters Tokens by their status, e.g. Ready, Active, Suspended etc. *
• Token Type – Filters Tokens by their type. Options are:
  • Injected – Injected tokens represent sub-processes started in the context of the parent Process Instance token set at runtime, but do not have a corresponding element in the process model.
  • Hidden – A hidden Token is not visible in the worklist; this is set as a Token property.
  • Overdue – Tokens which have passed their due date.
  • Transient – Transient tokens do not affect completion of a Process Instance Token set. A parent Process Instance Token can be set to completed even if transient Tokens exist in a sub-process
  • Live – not paused in the Console. *

* Information on the current value of this property for existing Tokens is available in the Studio at Solution Maintenance > Processes > Process Instances. Double-click a Process Instance and select the Tokens tab. To access some values, you need to double-click the Token in the list.

Note: Use the inherit check-box to check the condition on the parent token if the return value on the current level is null.

Filter Best Practices

To make ideal use of filters, Appway recommends the following best practices.

Tip 1 Set your Process Instance filter to exclude processes that are:

• Bound to an HTTP Session Processes that are bound to an HTTP session (e.g. Portal) are temporary and do not need to be migrated. Kill and restart them instead.
• Paused Paused instances cannot be updated by the process engine until they are resumed. Review paused instances and resume the ones you want to migrate.
• Running in the "Head" mode This ensures you exclude Processes from migration that are running for test purposes.

Tip 2 Mark Process Instances on which your batch program runs with a special attribute. This allows you to exclude these Process Instances if you need to run the program again:

Actions

Define actions to perform on all Process Instances/Tokens that pass the filters you specified. Actions are executed in the order they are defined. An exception in one action does not prevent the execution of other actions.

Actions for Process Instances

The available actions for Process Instances are:

The following options are available:

• Cancel Instance – Cancels Process Instances.
• Delete Instance – Deletes Process Instances. Use the "Force" check-box to ignore exceptions and complete the delete action in such cases.
• Touch Instance – Sets the modification time of Process Instances to the date and time the Action is executed or to the previous modification time + 1, whichever is greater. Also see: Touch Token and Touch Instance Actions–Use Cases.
• Set Instance Attribute – Sets the specified attribute to the defined value. The attribute is modified if it exists, otherwise a new attribute is created.
• Remove Instance Attribute – Removes the specified attribute.
• Pause Instance – Pauses Process Instances.
• Resume Instance – Resumes paused Process Instances.
• Set Instance Status – Sets the selected status for the Process Instances.
• Set Instance Version Filter – Sets the selected version filter for the Process Instances. Options are Now (Timestamp), Timestamp, Head and Latest Committed.

• Define Instance Variable – Creates the variable (or overwrites it if the variable already exists) and sets it to the defined value in all Process Instances.

• Set Instance Variable – Updates an existing variable to the specified value.
• Execute Script – Executes a custom script in the defined scope (Action or Process Instance).

Actions for Process Tokens

The available actions for Process Tokens are:

Note: In addition to the actions described here, you can also select all actions available for Process Instances. If actions for Process Instances are defined here, the actions are performed on the Process Instance the Token belongs to.

The following options are available:

• Create Token – Creates a new Token in the defined process and element.

Note: You can only create a new Token in the same Process or Sub-Process where the filtered Token is located. In other words, the new Token will live in parallel to the existing selected Token.

• Move Token – Moves the Tokens to the defined process and element. Select Keep Participant to keep the current participant the token is assigned to.

Note: Use this option with care, e.g. if you move a root token forward, you can create "ghost" tokens in sub-process you have passed. In many cases, removing and restarting the Token is the better solution.

• Remove Token – Removes the Token. If you remove the root token, all Tokens in sub-processes (nested Tokens) are also removed.
• Restart Token – Restarts the Token at the beginning of the process. Select Keep Participant to keep the current participant the token is assigned to. This is recommended to avoid issues in cases where you are defining Participant expressions based on the execution context, e.g. USERID(), because USERID() will evaluate to NULL when migrating.
• Touch Token – Sets the modification time of the Token(s) to the date and time the Action is executed or to the previous modification time + 1, whichever is greater.

Note: Changing the modification time of a Token also changes the modification time of its parent Process Token(s) and the Process Instance to which is belongs.

Also see: Touch Token and Touch Instance Actions – Use Cases

• Set Token Attribute – Sets the specified attribute to the defined value. If the attribute exists, it is overwritten, otherwise the specified attribute is added for this token.
• Remove Token Attribute – Removes the specified attribute.
• Set Token Participant – Assigns the Token to the specified user, role, or group.
• Set Token Status – Sets the Token status to the selected value.
• Define Token Variable – Creates the variable (or overwrites it if the variable already exists) and sets it to the defined value for all Tokens.

• Set Token Variable – Updates an existing variable to the specified value.

Note: Use the inherit check-box to apply the action to the parent Tokens as well.

Touch Token and Touch Instance Actions – Use Cases

Using the Touch action updates the modification time to the time when the action was performed. This section explains the impact of these actions.

Touch Token The modification time of a Process Token has an impact only together with the Max Inactive Interval which you can set on a Token. When the Process engine checks if a Sub-process has ended, it ignores Tokens which have been inactive (not modified) for the given amount of time.

Touch Instance When starting a Process Instance for a Process that does not contain swim lanes, the Max Inactive Interval property is set by default. Process Instances of this type are usually bound to the HTTP session of the current user and are deleted as soon as the session expires or is invalidated. As a second "safety net", the Max Inactive Interval for these Process Instances is set to 1440 minutes (according to the configuration property nm.workflowinstances.maxinactiveinterval). If a Process Instance has not been modified for this amount of time, the Process engine cancels the Process Instance.

In addition, the modification time of a Process Instance is used together with the save time to check if an instance has been modified in memory and needs to be saved back into the distributed map during the commit phase. Touching the Process Instance therefore enforces a save operation.

Example: Typical Use Cases

Case 1: The employee 'Peter Parker' has left the company. All Workitems currently assigned to him have to be reassigned to his manager 'J. Jonah Jamesson':

Case 2: Due to a communication error with a third-party system, several Process Tokens have been suspended on a Script Task. The suspended Process Tokens have to be restarted:

Case 3: New Screen Tasks have been added to a Sub-Process. The Process Tokens in this Sub-Process have to be moved back to the Start Event.

Case 4: A parallel branch has been added to a Process. A Process Token has to be generated on the Connection leading to the merging AND Gateway.

Case 5: Tokens can be suspended for many reasons (see Recovering Suspended Tokens for an overview of potential scenarios). In some cases, the recommended solution to recover the suspended Process is to manually move the Token to a new Process and/or element.

Log Files

An audit.log log file is used to track every execution of a batch program. A separate log file is created every time a batch program is started and contains detailed information, errors, and warnings collected during execution.

Both log files can be found at: System Maintenance > System Overview > Logging > Log Files.

Supplemental Information

Custom ProcessMigration Scripts and Version Filters

Custom process migration scripts can be defined when using the Condition filter or the Execute Script action (both are available for Process Instances and Process Tokens). Be aware of the following behavior when the scripts are executed, as this can have an important impact on migration:

When the process migration scripts are executed, the filters and actions are executed with the version filter of the matching Process Instance. This has an impact if you create Data Classes or other Business Objects which encapsulate functionality to be (re-)used by multiple process migration scripts. When you change those Business Objects, the changes cannot be "seen" by Process Instances running with a version filter older than the latest committed or head filter of the Business Object: The process migration tries to load those Business Objects with the version filter of the Process Instance and then either does not find the Business Object at all or if it is able to find the Business Object, the old version of the Business Object is loaded.