Exporting and Importing a Process Definition


    Administrators can export process definitions created via SugarBPM and import them into the same or another qualified Sugar instance. This article covers best practices for exporting and importing process definition records.

    Note: SugarBPM™ was known as Advanced Workflow prior to Sugar 9.x and is not available on the Professional edition of Sugar.

    Version Compatibility

    This article pertains to process definition files exported from Sugar 8.0.x and lower. As of Sugar 8.1.x, exported process definitions will package their related business rules and email templates inside the .bpm file, making it easy to upload all related records in one step. The following list explains important compatibility rules for importing and exporting process definitions for the various versions of Sugar.

    As a byproduct of continuously improving the SugarBPM functionality, the following compatibility rules apply when importing SugarBPM records:

    • Sugar 9.0.0 and higher : Process definitions exported from Sugar 9.0.0 and higher will import to Sugar versions 9.0.0 and higher with all related process business rules and process email templates packaged together in the .bpm file. The components do not need to be imported as separate records as explained in this article. Any Gateway criteria will also carry over, assuming any business rules, email templates, and custom modules, fields, and relationships are available in both databases.
    • Sugar 8.1.0 – 8.3.x : Process definitions exported from Sugar 8.1.0 and higher will import to Sugar versions 8.1.0 and higher with any related process business rules and process email templates packaged together and do not need to be imported as separate records as explained in this article. However, any Gateway criteria for imported process definitions must be re-configured upon import in order for the process definition to run correctly.
    • Sugar 8.0.0 and lower : Process definitions must be exported and imported as separate files for any process business rules or email templates as explained in this article. Please refer to the Steps to Complete for more information.

    For more information on the import capabilities for your version of Sugar, please refer to the SugarBPM documentation. 

    Use Case

    SugarBPM’s import capability is useful for sharing process definitions between Sugar instances. For example, it is recommended to create and test process definitions in a non-production instance before importing and activating them in a live Sugar instance. Another good use of the import functionality is duplicating a process definition that you plan to tweak for a different business process. Unlike standard Sugar modules, the Process Definitions module does not offer a “Duplicate” option. Instead, administrators can export and then import a process definition as a new record then edit the new record to accommodate a unique business process.

    For this article, we will export a process definition from a Sugar sandbox (Sugar 8.0.x or lower) and then import it to a live, production Sugar instance. The process definition targets the Accounts module and relates to one process email template record and no process business rules. 


    • You must be an administrator or have developer-level role access to import and export SugarBPM records. For more information, please refer to the Role Management and User Management documentation.
    • Process definitions that have a locked field inside a field group cannot be imported. If you have a locked field inside a field group (e.g. the Country field is locked in the Billing Address field group), you must first unlock the individual fields that are part of the grouped field in the instance you are importing to, then import the .bpm file, and then re-lock the grouped field after import.

    Steps to Complete

    Before importing a process definition, your Sugar instance must already contain any Process Email Templates and Process Business Rules module records that are used by the process definition. If you are importing to the same Sugar instance from which the process definition originated, the related records may already be there and do not need to be re-imported. For imports between two different Sugar instances, follow these steps to export the files, upload any collateral records, and then finally upload the process definition record into Sugar.

    Note: These steps pertain to process definition files exported from Sugar 8.0.x and lower. Files exported from Sugar version or earlier cannot be imported to Sugar instances running or later.

    1. Navigate to the Process Email Templates module in the sandbox.
    2. Find or search for the template in the list view and then select “Export” from the record’s list view Actions menu:
    3. Read the warning message and click “Confirm” to begin downloading the template file to your computer in the .pet file format, which is specific to process email templates.
    4. Navigate to the Process Email Templates module in the production Sugar instance and select “Import Process Email Templates” from the module tab’s menu.
    5. Click the “Choose File” button and select the .pet file that you downloaded from the sandbox in step 3.
    6. Click the Import button, read the warning message, and click confirm to begin uploading the template file to the production instance’s Process Email Templates module.
    7. When complete, view the imported template record’s layout to confirm that the import was a success.
      Note: If your use case involves additional email templates or business rules, repeat steps 1-7 for each of these records before importing the process definition’s .bpm.
    8. Once the email template has been imported into the production environment, you may import the related process definition record. Repeat steps 1-7 using the Process Definitions module to export and import the process definition’s .bpm file.
    9. Once all of the records are uploaded to the live Sugar instance, review the process definition’s design and settings to be sure everything transferred over as expected. In some Sugar versions, the references to related business rules and email templates are not automatically re-established during the imported process definition. Re-establish these connections in the appropriate Action element(s).
    10. Finally, activate the process definition in the live Sugar instance and immediately test its behavior. To activate it, set the process definition to “Enabled” via the Process Definitions list view or dashlet.

      Be sure to deactivate the process definition before making any subsequent changes to the process design. For more information, please refer to the Process Definitions documentation.
    in SugarBPM

    Reach out to us for help