Updating a Model

When updating the model used by running model instance, you proceed usually as follows:

1. Import the model you want to update into your workspace: note that you can download the model from the server either using the Management perspective or the Management Console.
2. Create a copy of the model and modify it to become your new model: make sure to keep this original model unmodified.
3. Create a model update definition file for the original and new model and define in it the instructions on how to handle differences between the models.
4. Upload the new model to the server and update the model instances.

Important: If your changes include incompatible changes to your data type model, you need to suspend any running model instances and migrate your business database before update.

Creating a Model Update Configuration

How model update is executed on a running Model instance is defined in a Model update configuration file. This definition file stores mappings between modeling elements of the old and new model as well as all the related update data.

Before creating the definition, make sure your workspace contains both: the source (old) module and the target (new) model.

To create a model update configuration:

1. Go to File > New.
2. Select Model Update Configuration.
3. In the New Model Update Configuration dialog box, type the path to the source (old) and target (new) models.
4. Click Next.
5. In the updated dialog box, select the project where to save the model update configuration.
6. In the File name text box, type the configuration name.
7. Click Finish.

Whenever you change the sources (old and new models), refresh the configuration: In the GO-BPMN Explorer, right-click the configuration and select Refresh.

Important: When you generate the model update, the system attempts to map the old elements with changes to the new elements. The proposed configuration might not be accurate and it is strongly recommend to review the file thoroughly.

Copying Model Update Data

Once you have defined the update data, that is, transformations and model update processes, you can copy the data and paste it into another model update configuration.

Note that pasting works only if the Module name is the same as the original Module and the type of update data is correct: you cannot paste model update data from variables to data types.

To copy the variables, processes, or data type update data, do the following:

1. Open the .muc file.
2. Open the tab with the data.
3. Right-click the module and click Copy Module Configuration.
4. Open the target .muc file and the tab with the model update data.
5. Right-click the target module and click Paste Module Configuration.

Copying model element changes on a module

Editing Model Update Configuration

Model Update Configurations are edited in the model update multi-page editor, which is by default associated with model update configurations (.muc).

The editor opens the configuration with the update rules sorted on the following pages:

• Overview with general model update information and settings
• Data Types with differences on data types and their transformation expressions
• Variables with differences on variables and their transformation expressions
• Processes with differences on processes and their elements, and their strategies as well as their model update process references

Model Update Editor

Every page contains the following:

• Baseline column with the resource with the change
• Modification column with the respective change marker and its description (see Comparison Editor);
• Transformation/Strategy column with data on how to handle the difference.

Pre-processes and post-processes are displayed in the Outline view.

Displaying Matching Data in Model Update Configuration

When the user creates a model update definition (.muc) file, the system automatically maps the elements of the old model with the elements of the new model and compares the models. Based on the comparison, the editor provides options for update rules.

To display the matched data, which is hidden by default, do the following:

1. Open your .muc file in the Model Update Editor.
2. Click the Filter button ( ).
3. In the Differences Filter dialog box, select Matched Properties and Elements Without Changes as required.
4. Click OK.

Changing Element Mapping in Model Update Configuration

When the user creates a model update definition (.muc) file, the system maps the elements of the old model with the elements of the new model and performs diff of the models. The automatic mapping might need some manual adjustment.

When changing mapping, you can match only elements with the same parent and of the same type. Recognized element types are start event, intermediate event, task, sub-process, plan, and process.

To change or cancel the mapping of an element, do the following:

1. Open your .muc file in the Model Update Editor.
2. Display the matched elements if necessary (click the Filter ( ) button, and select Elements without Changes).
3. In the Model Update Configuration Editor, right-click the element entry with the incorrect mapping.
4. In the context menu, select the applicable option:
   • Select Change Source of Mapping and select the source element.
   • Remove mapping with Cancel Mapping.

Changing Model Update Settings

Model update configuration defines general properties that are used to control the update process, such as, the source and target model, pre-condition, etc.

To change general model update settings of your model update configuration, do the following:

1. Open the model update configuration (.muc).
2. On the Overview page in the Settings area, define the model update settings:

   • Source (old) and target (new) model

     Make sure to refresh the definition whenever the source or target model change.

   • Override source/target model hash

     The source and target models are identified by their hash codes, which change whenever a Model is changed. Therefore it is not possible to apply a model update configuration on Model instances of a Model that was changed after the model update configuration was created. If you want to use another hash code, select the option and enter the Model hash code below. You can check the hash code of uploaded modules in the Module Management view.

   • Model update pre-condition

     When a model instance update is triggered, the server evaluates the pre-condition: If false, the model update is rejected and the execution of the model instance continues.

   • Trigger model transformation automatically enables and disables automatic start of transformation phase of the model update

     If false, the transformation phase must be triggered manually by the user.

   • Trigger post-processing automatically enables and disables automatic triggering of post-processing phase after transformation

     If false, the post-processing phase must be triggered manually by the user.

     

     Changing hash code of the target Model
3. Click OK.

Defining Transformation

Transformation for added and changed records or fields and changed variables is defined as a transformation expression. When model update configuration is created or refreshed, the system attempts set automatic transformation rules for changed entities. If this is not possible, the entity entry is highlighted.

For details on the concepts behind transformation, refer to Transformation.

To change transformation strategy or expression, go to the entry in you muc file and click the Transformation cell.

Important: On user tasks with forms consider setting the Restart strategy to prevent problems with saved to-dos and incompatible changes on data.

Defining variable transformation expression

Selecting transformation strategy

Defining Process Element Transformation

To define transformation strategy for elements, do the following:

1. Open the model update configuration.
2. Click the Processes page title in the lower part of the Model Update Editor.
3. Click the Transformation/Strategy column in the row with the element entry and select Continue or Restart.

Note that if the strategy of a parent element is set to Restart and the child element has the strategy Continue, the Continue strategy will be never applied since the parent element will be always restarted.

Defining Data Type Transformation

The transformation of data types on model update is defined in the model update configuration as an expression that defines how the value of every instance of the old data type is transformed into the new data type value.

Important: It is not possible to define a transformation for the field type of a Shared Record to a field of another type, since such a process requires database migration.

Important: If your changes include incompatible changes to your data type model, you need to suspend any running model instances and migrate your business database before update.

To define transformation expression for data types, do the following:

1. Open the Data Types page of the model update configuration.
2. Click the Transformation column in the row with an added or modified data type and then the Browse button on the right.
3. Specify the transformation expression.

Example: The data type transformation is defined for a Book record:

• The ISBN record field has changed from Integer to String. The old ISBN instances will be transformed with the toString(old("ISBN")) expression.
• The field genre of the Book record was originally of the String type. In the new model, the field is an Enumeration. Any instances of the field will be transformed to the value with the switch expression.
• On the related Author Record, the fields firstName and surname have been removed and the record field name has been added. The new field will be populated with the concatenated version of the removed fields. Note that the function old() returns an Object and therefore the call must be wrapped into a toString() function call.
  

  Defining data type transformation

Defining Variable Transformation

Variable transformation is defined by a transformation expression in the model update configuration as a closure that returns a value of a basic data type evaluated within the context of the old model instance.

To define the transformation strategy for a variable do the following:

1. Open the model update configuration.
2. In the Model Update Editor, do one of the following:
   • For process variables, open the Processes tab and expand the parent element of the variable.
   • For global variables, open the Variables page.
3. Click the Transformation column in the row with the variable and click the Browse button.

4. In the Transformation Expression Editor dialog box, click Edit and specify the transformation expression in the Expression Editor.

   To use a value from the old context use the old() function call.

Creating a Model Update Process

Model update processes in model update definitions are defined in the model update configuration per relevant process element. They serve to prepare an instantiated element for transformation (pre-processes) and for renewed running of the model Instance after transformation (post-processes).

To create a model update process, do the following:

1. Open a model update configuration in Model Update Editor.
2. Open the Processes page.
3. Right-click the row with the element entry with the change (module, process, plan, sub-process, behavior, or task).
4. In the context menu, select Create Pre-proces**s or **Create Post-process.
5. Design the model update process as a common BPMN-based process.

Model update processes are accessible from the Outline view.

Importing a Module to Model-Update Processes

To import a module to all pre- or post-processes of a model update, do the following:

1. In the GO-BPMN Explorer, select the muc file.
2. In the Outline view, right-click the Pre-processing or Post-processing folder in Outline and click Add Import.
3. In the Add New Import dialog, select the module and click OK.
   

   Importing Module

Creating a Variable in a Model Update Process

To create a variable in the pre-processes or post-processes of a model update, do the following:

1. In the GO-BPMN Explorer, select the muc file.
2. In the Outline view, right-click the Pre-processing or Post-processing directory.
3. In the context menu, select New > Context Variable.

Creating variable in a model update process

Editing a Model Update Process

To edit a model update process, do the following:

1. In the Model Update Editor, open the .muc file and then the Processes page.
2. Right-click the row with the required element entry.
3. In the context menu, select Open Pre-Process or Open Post-Process.
4. In the Process editor, edit the Process and save.

Alternatively, double-click the model update process in Outline.

Deleting a Model Update Process

To delete a model update process from your muc file resource do the following:

1. In the page title bar (at the bottom of the editor), click the Processes page tab.
2. Right-click the row with the element.
3. In the context menu, select Delete Pre-Process/Delete Post-Process.

Updating a Model Instance

Before updating model instances, make sure the new Model (target) is uploaded. Note that only model instances that are Running, Suspended, Updated, or Update Aborted can be updated. During update, the model instance is suspended and becomes read-only. Such a model instance cannot be resumed manually.

When updating Model instances their IDs are preserved and the rules defined in the Model update configuration are applied.

Note: It is not possible to update a model to a model with a different version of Standard Library.

You can update model instances either from PDS or from the command line with the LSPS cli tool.

Updating a Model Instance from PDS

To update model instances, do the following:

1. Open the Model Instances view.
2. Click the Update ( ) button in the view toolbar.
3. In the Model Update dialog box, specify the model update configuration and data mapping file to be applied:
   • Click Workspace Resource to select a configuration/data mapping file from the current workspace.
   • Click External File to select a configuration/data mapping file from other location.
4. Click Next.
   

   Model update dialog

5. On the Filter page, define the filtering criteria for model instances and click Apply Filter if applicable.

   You can apply also a previously defined filter. However, status and model criteria are ignored since the model is defined in the Model Update Configuration.

6. In the Model Instances area, select the model instances to update.
   

   Model update dialog box with filtered Model instances
7. Click Next.
8. On the Summary page, chheck the settings. If you plan to perform the model update with the LSPS Command-Line Console, click Show command line script and copy the commands for later use.
9. Click Finish.

The selected instances go through the model-update process. Check their detail views and the Model Update Logs view for details. Depending on the model update settings, the update process may be waiting for manual triggering of its transformation or post-processing phase: To resume a model update of a model instance, click the Continue Model Update ( ) button in the Model Instances view in the Management perspective.

After the update has finished, the model instances remain in the status Updated and are still not running. To resume the instances, click Resume in their context menu.

To resume all model instances returned by the Filter of the view, click Resume All Updated in the context menu.

Note: If resuming a large number of instances, make sure the resumed action was applied to all of them. Resume any instances that failed to resume.

Aborting Model Update

You can abort model updates from the Management perspective: Click the Abort Model Update button ( ) in the view toolbar.

The feature is available in the Management Console as well.

Model Update Logs

The logs from a model update procedure are available in the Model Update Logs view. The view displays information on source and target models and details on updated model instances (below the list of model updates).

Model Update Detail

The Model Update Detail view contains details about the update of a model instance.

To display the view, click the model instance ID in the Model Update Logs view.

Model Update Detail

Downloading Model Update Configuration

To download a model update configuration from the LSPS Server, do the following:

1. Open the Model Update Logs view.
2. Select an update log.
3. In the view toolbar, click the Export MUC ( ) button.
4. Define the target location and file name.