Model Update Configuration

Model update configuration defines how the update of the given model instances is performed.

When preparing and testing the model update configuration, you will usually proceed as follows:

1. Import the model you want to update into your workspace.
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
5. Update the model instances.

Important: If your changes include incompatible changes to your data type model, suspend any running model instances and migrate your business database before update. Therefore, make sure to prepare any required migration scripts. Consider using generating the schema update scripts to acquire the first draft of the migration scripts.

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 management tools.

   • 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-process 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.