Overview

Available Version: 3.0.1.8 on.

The Promotion Manager is a feature available on ProcessMaker Enterprise Edition 3.0.1.8 on. This feature allows users to export and import certain process objects between environments in ProcessMaker. For example, from one installation of ProcessMaker to another, or between environments that include a development workspace (where all the processes are tested and created) and a production environment.

Requirements

The following requirements are needed in order to work with this feature.

  • ProcessMaker Enterprise Edition 3.0.1.8 or higher.

Licensing

To make sure that the license installed in ProcessMaker includes the Promotion Manager feature, go to Admin > Plugins > Enterprise Manager then select the Enterprise Features tab.

How the feature works

Users can select which process objects will be imported or exported. Process objects include: the Process Definition, Assignment Rules, Variables, Dynaforms, Input Documents, Output Documents, Triggers, Report Tables, Templates, Files, DB Connection, Permissions, Supervisors and Supervisors Objects.

However, user accounts and roles are not included. In any case, it is also possible to export all the process objects and the process diagram as a whole, for more information please visit the Importing and Exporting Projects page.

Selection of process objects to export

Use the Promotion Manager feature to export some process objects by following the next steps:

  • Go to the DESIGNER tab and select the process to export. After selecting it, the "Export" button will be enabled in the toolbar. Click on it and a menu with two options will be displayed. Select the Custom option to export the objects of a specific process.

  • The Export Process Objects dialog will be displayed to select the process objects that will be exported. Once selected, click on the Export button. A .pmx2 file will be created containing the selected objects. Take into consideration that the .pmx2 file must include all the process objects in order to create a new process.

  • The .pmx2 file will start to download automatically.

  • A process can also be exported by right-clicking the process and selecting the Custom option under the Export option as seen in the image below.

Exporting Process Objects from the Process Map

Process objects can also be exported from the Process Map by following the steps ahead:

  • Open a process by double-clicking on it to display it on the Process Map (A project can also be opened by clicking on the Edit option.)

  • Once the Process Map is opened, select the Export Process option of the top toolbar and click on the Custom option.

  • The Export Process Objects dialog will be displayed to select the process objects that will be included in the .pmx2 file.

The download of a .pmx2 file will start automatically. Save the file by following the procedure of the browser.
The exported .pmx2 file can then be imported into another ProcessMaker installation/workspace.

Importing Process Objects

Import the .pmx2 file by following the next steps:

  • Go to the Designer tab and select the Import button.

  • A new window within the Designer will open where the .pmx2 file to be uploaded must be selected. Click on the file icon to open the file navigator.

  • Select the .pmx2 file to be imported. Usually the file can be found in the Downloads folder (unless the browser is configured to store files in a different folder).
    Once the file is selected, click on Open.
  • The name of the file will be shown in the Import Process window, but it is not imported yet. Click on the Upload button to start selecting the process objects in the next window.

  • One of the following options are displayed depending if the process exists or not in the target workspace.

    Importing Process Objects to a New Process

    If the process that is being imported does not exist in the current workspace, a brand new process can be created if the .pmx2 file includes all the process objects.
    Only .pmx2 files that include all the process objects can be used to create a new process. In this case, the Promotion Manager Import Dialog will not be displayed.

    For this option a completely new process will be created with different UIDs for all the process objects. The name of the new process has the format "Copy of - Process_Name - Date, Time".

    If the exported .pmx2 file does not include all of the process objects, then the process can not be created and the following message displays:

    The option to create a completely new process is also available when the process already exists. Select the "Create complete new process" option in the window that is displayed after importing the .pmx2 file.

    Warning: ProcessMaker does NOT create new report tables if the report tables contained in the .pmx2 file already exist in the workspace. Therefore, if the user imports a .pmx2 file to create a copy of an existing process that includes existing report tables, an error message will be displayed since report tables can only be associated to one specific process. This is a known issue that will be fixed in upcoming versions of ProcessMaker.

    Importing Process Objects to an Existing Process

    If a process with the same UID in the current workspace already exists, the following window will appear:

    To update a current process, select the "Update the current process" option and the Import Process Objects dialog will be displayed in order to select the process objects that will be imported. This option detects if the selected file format supports selective import or not. If the selective import is supported by the .pmx2 file then the following dialog is display where users can select which of the process objects contained in the .pmx2 file will be imported:

    Except for the process definition object, each one of these objects has the following importation options:

    • Add to existing (merge): For this option, process objects will be compared and merged with the existing ones. New objects will be created and existing ones will not be replaced.

    • Replace all: This option means completely overwriting the existing process objects with the imported ones and new objects will be created.

    Examples of Importation

    The following table describes how the process objects are replaced or added to the target process. The process objects are represented as letters: A, B, C, D, E, F, G, H. A process object can be any process object described in this document.

    The following table describes the status of the process objects using the Replace All option:

    Replace All
    Original Process(.pmx2 file)Target ProcessProcess after changesDescription
    AANew process objects are created in the target process.
    A'AA'An existing process object is replaced with the new object version.
    C, D'DC, D'A combination of the previous rules. A new object is created and an existing one is replaced.
    F', GF, HF', G, H A combination of previous rules. Note that existing objects in target process that are not imported are not modified

    The following table describes the status of the process objects using the Add to existing option:

    Add to Existing (Merge)
    Original Process(.pmx2 file)Target ProcessProcess after changesDescription
    AANew process objects are created in the target process.
    A'AAExisting objects are not replaced in the target process.
    C, D'DC, DA combination of the previous rules. New objects are created and existing ones are not replaced.
    F', GF, HF, G, HNote that existing objects in target process are not modified.

    Promotion Manager Import Dialog

    This dialog is used to select the objects that will be imported to the process. The following process objects can be imported:

    • Process Definition
    • Assignment Rules
    • Variables
    • Dynaforms
    • Input Documents
    • Output Documents
    • Triggers
    • Report Tables
    • Templates
    • Files
    • DB Connections
    • Permissions
    • Supervisors
    • Supervisors Objects

    Take in consideration that elements not listed before will not be included. For instance, assigned users cannot be exported and PM tables have their own interface to be imported and exported so PM tables are not included in this option.

    The process objects are the lowest unit of configuration, therefore they are imported as units. The list of objects is a suggested order of import. The last imported object would refer to the previously imported object.

    Considerations When Importing Process Objects

    Importing a Process Definition

    When importing a Process Definition, "Replace all" is the only option available by default. The process definition replace all the diagram content with the imported content.

    A Process Definition includes the following items:

    BPMN elements:Task properties:
    TasksTasks Configuration
    GatewaysTask steps
    Start eventsSubprocess
    Intermediate eventsStart event properties
    End eventsWeb entries
    Flows
    Annotations
    Groups
    Data objects

    Process Definition Dependencies

    Take notice that Processes Definitions include references to other process objects. For this reason it is recommended to import them at the end, after all possible objects related were imported.

    Consider the following relations of a Process Definition with other process objects:

    Dependencies
    Task Groups Assignment Rules
    Step Trigger Triggers
    Case Tracker Dynaform
    Web Entry Dynaform
    Web Entry Event Dynaform
    Message Type Variable
    Message Type Definition Templates
    Email Event Templates
    ABE Templates and Dynaform
    Script task Triggers
    All task Steps
    Steps Dynaform
    Steps Input docs
    Steps Output docs
    Steps Triggers

    For example: If the process definition includes a step where an input document is related, then the input document should be imported first.

    Recommendations on Process Definitions

    Take in consideration the following cases:

    If a Process Definition refers to an non-existing process object, the reference will be removed. For example: if a non-existing Dynaform is referenced inside a task steps configuration, this reference will be removed from the steps configuration.

    Additionally, if there are cases currently running, and the process diagram is replaced, the following considerations must be taken care of:

    Importing Assignment Rules

    The assignment rules can be imported in the following ways:

    • Replace all: The assignment rules configuration is replaced by the imported information. All the current assigned users and groups will be removed and the imported groups will be inserted. Note that users are not exported, only groups will be created or assigned.

      .pmx2 File ConfigurationTarget Configuration:After migration:
      task1:
      • Assigned groups: Group1
      • Assignment type: Self service
      task 2:
      • assigned groups: Group2
      • Assignment type: Manual
      task1:
      • Assigned groups: Group3
      • Assignment type: ciclycal
      task 2:
      • assigned groups: Group4
      • Assignment type: Self service by value
      task1:
      • assigned groups: Group1
      • Assignment type: Self service
      task 2:
      • assigned groups: Group2
      • Assignment type: Manual

    • Add to existing (merge): The current assignment rules configuration is maintained. The new imported groups will be added to the configuration, assigned users and groups will be maintained. Note that assignment types can not be merged, so the current assignment type is maintained.

      .pmx2 File ConfigurationTarget Configuration:After migration:
      task1:
      • Assigned groups: Group1
      • Assignment type: Self service
      task 2:
      • assigned groups: Group2
      • Assignment type: Manual
      task1:
      • Assigned groups: Group3
      • Assignment type: Ciclycal
      task 2:
      • assigned groups: Group4
      • Assignment type: Self service by value
      task1:
      • assigned groups: Group1, Group3
      • Assignment type: Ciclycal
      task 2:
      • assigned groups: Group2, Group4
      • Assignment type: Self service by value

    Groups in tasks are compared based on their group names. If a group is referenced in the assignment rules of a task and is imported as a new group, this new group will be created empty (without users) in the current workspace. Keep in mind, that the change of the assignment type of a task could cause existing cases not to be found.

    Assignment Rules Dependencies

    The Assignment Rules object can include the following dependencies depending of its type:

    Dynaform Dependencies
    Assignment Rules → Groups
    Assignment Rules → Users
    Assignment Rules → Triggers

    Importing Dynaforms

    Dynaforms are compared with the imported ones based on their titles.

    Dynaforms Dependencies

    Dynaforms objects can include the following dependencies with other process objects:

    Dynaform Dependencies
    Dynaforms → Variables
    Dynaforms → Variables → Input Documents

    For example: If the Dynaform includes references to variables, these variables should be selected in the import process or imported before the Dynaform.

    Importing Report Tables

    Existing report tables are compared with the report tables that will be imported contained in the .pmx2 using their table names. The definition and data of each report table will be included in the importation process.

    Warning: ProcessMaker does NOT create new report tables if the report tables contained in the .pmx2 file already exist in the workspace. Therefore, if the user imports a .pmx2 file to create a copy of an existing process that includes existing report tables, an error message will be displayed since report tables can only be associated to one specific process. This is a known issue that will be fixed in upcoming versions of ProcessMaker.

    Importing DB Connections

    When importing DB Connections, the existing DB connections will be compared with the imported ones using their DB connection titles. In case of using external databases, if the server does not have the required libraries to support the external connections imported, then the DB connections will not work until the required libraries are installed.

    Importing Permissions

    When importing Permissions, the existing permissions will be compared with the imported ones using their names. For this, the permission name property must be created. If a group is used inside a permission and the group does not exist in the target workspace, it will be created as a new empty group (without users).

    Importing Supervisors

    When importing Supervisors, the existing supervisors will be compared with the imported supervisors using their names. If a group is selected as supervisor and it does not exists in the target workspace, it will be imported as a new empty group (without users).

    Importing Supervisors Objects

    The Supervisor Objects are references to Dynaforms, Input Documents and Output Documents. The supervisor can only manage the referenced objects. The existing supervisor objects are compared with the imported ones using their names.

    Importing Groups

    Groups are not imported directly. Take in notice that this functionality only imports groups which are referenced in any of the imported process objects. If the group referenced does not exists, a new group will be created. In any case, users belonging of these groups are not imported. Therefore, users should be created or assigned to the groups in the target workspace after the importing process is over.