Triggering on “To” and “From” Field Values in SugarBPM

    Overview

    This article covers how to use SugarBPM to trigger a process or a step in a process based on a field changing from one value to another specified value. This is useful in a variety of situations where certain “From” or “To” values for a field have special significance in your business flows.

    Note: SugarBPM™ was known as Advanced Workflow prior to Sugar 9.x and is not available on the Professional edition of Sugar. This article pertains to Sugar versions 7.6.x through 7.10.x. As of the Winter ’18 release of Sugar (a.k.a 7.11.x), comparative operators are built into Start events and Receive Message events to enable “a field changes to/from” functionality in process definitions.

    Use Case

    As an example, we will automate a business process that begins when the Status field on a dead lead is changed. We look at two ways to manage dead leads that users later re-open. The first uses a simple Receive Message event to wait until a lead’s status changes from “Dead” to “Recycled”. This method is sufficient for a disciplined sales force that is not likely to select any other lead status. The second uses a business rule to consider every potential change that a user may make to a dead lead’s status and to react uniquely to each.

    Prerequisites

    • You must be an administrator or have developer-level role access to create and manage SugarBPM records.
    • Schedulers, specifically the SugarBPM™ Scheduled Job, must be running.
    • Before performing the steps in this article, you should have a basic understanding and knowledge of SugarBPM.

    Steps to Complete

    Sugar can easily recognize the beginning, or “from” value of a field via the conditions set on a process definition’s event element. For “a field changes to/from” functionality, administrators should include a subsequent event to define the “to” value. In simple use cases, the Receive Message event should suffice. More complex business processes may require a link to a process business rule. This article explains both scenarios so that you can choose the option most suited to your needs.

    Defining “To” and “From” Field Values Using a Receive Message Event

    This section’s example uses a Receive Message event to listen for a specific change to a given field. The Start event contains the “from” condition, so a process will start watching a lead when its status changes to “Dead”. If the lead ever changes from “Dead” to “Recycled,” the process will react, in this case, by updating the lead’s description. A status change to any other value will simply end the process which allows a new process to commence if the lead ever changes to “Dead” again.

    Use the following steps to create a process definition that uses a Receive Message event to wait for a lead’s status to change from “Dead” to “Recycled”:

    1. Create a new process definition record. Name the record “Dead lead recycled” and set the Target Module as “Leads”. Please refer to the Process Definitions documentation.
    2. Click “Save & Design” to continue to the Visual Designer canvas.
    3. Drag a Start event onto the canvas.
    4. Right-click the Start event and then select “Settings” to configure the Start event criteria.
    5. Using the “Applies to” dropdown menu, specify when the process definition should activate. For this use case, select “Updated Records Only (All Updates)” so that the process begins every time a lead’s Status field changes to “Dead”.
    6. Click inside the Criteria box to add conditions for when the process definition should activate. For this use case, create a Module Field Evaluation where the lead’s Status field is “Dead”, as shown here:
    7. Save the Start event’s Settings window and then drag a Receive Message event onto the canvas. Drag a connector to this event from the Start event.
    8. Right-click the Receive Message event and then select “Settings”.
    9. Click inside the Criteria box to add conditions for when the process definition should resume. For this use case, create a Module Field Evaluation where the lead’s Status field is “Recycled”, as shown here:
    10. Save the event’s Settings window and then drag an action element onto the canvas.
    11. Drag a connector to the Action element from the Receive Message event and then configure the action:
      • Right-click on the action element and select “Change Fields”.
      • Right-click on the Change Fields action again and select “Settings”.
      • Click inside the checkbox next to “Description” to enable editing in the field.
      • Type a message inside the Description field to explain that someone has revived this lead, such as, “Restored from dead!”.
    12. Save the Action and then drag an End event onto the canvas. Drag a connector from the Action element to the End event. There is no need to configure the End event’s settings for this process definition.
    13. Save and enable the process definition.
      • Note: New process definitions are set to “Disabled” by default as a preventative feature to ensure a process instance is not triggered inadvertently during the design phase. After fully configuring the design, exit the Visual Designer and set the process definition to “Enabled” via the Process Definitions dashlet or list view. For more information, please refer to the Process Definitions documentation.
    14. Finally, test the process definition:
      • Find an open lead and change the status to “Dead”. On save, confirm that a process begins in the Process Management list by navigating to https://yoursugarinstance.com/#pmse_Inbox/layout/casesList:
      • Return to the lead and edit the lead’s status to “Recycled”. View the lead’s Description field and confirm it displays the message specified in step 11 above:

    Downloads

    The process definition record created in this article is provided here for your convenience. Always review the settings of imported SugarBPM files to confirm that they are configured as expected. Please follow these general steps to use the sample file in your instance:

    1. Download the process definition file in .bpm format here: Download Link
    2. Import the downloaded .bpm file to the Process Definitions module as explained in the Exporting and Importing a Process Definition article.
    3. Open the process definition in design view.
    4. Confirm that each element’s settings are configured as expected and appropriate for your use case.
    5. Save and then enable the process definition for testing.

    New process definitions are set to “Disabled” by default. This is a preventative feature that ensures a process instance is not triggered inadvertently during the design phase. After the design is fully configured, exit the Visual Designer and set the process definition to “Enabled” via the Process Definitions dashlet or list view. For more information, please refer to the Process Definitions documentation.

    Defining “To” and “From” Field Values Using a Process Business Rule

    This section’s example depends on a process business rule to specify different behavior for each potential “to” scenario. Like the previous example, the Start event contains the “from” condition, so a process will start watching a lead when its status changes to “Dead”. If the lead ever changes status again, the process will react uniquely based on which status the user selects.

    Use the following steps to create a process business rule and a related process definition that wait for a lead’s status to change from “Dead” to any other value:

    1. Create a new process business rule record. Name the record “Lead status from-to” and set the Target Module as “Leads”. Please refer to the Process Business Rules documentation for complete steps to create a new business rule record.
    2. Click “Save & Design” to view the Business Rules Builder.
    3. Each row of the decision table represents a separate rule. Begin entering rules for the value of each lead status according to the following steps:
      • Click inside the cell in the first row under “Conditions”.
      • From the dropdown, select “Status”.
      • Click inside the leftmost cell under “Status” and select “==”.
      • Click on the Conditions box under the Status header and then select any Status value that is not “Dead”.
      • Click on the plus sign next to the Status header to create additional rows for each remaining lead status, saving as you go.
    4. Specify the required return value for each condition by clicking inside the row’s corresponding Return cell. Select “Constants” then click on “String, Number, and Boolean”. Indicate whether each row is an open or closed status according to your organization. For example, type “open” (without the quotes) to indicate that the Recycled status is an open state. Click the Add String button to populate the Return value. Do this for each respective row, clicking the Save button after each entry.
      • Note: It is important that the Dead status condition exists as the final row of the rule set because the business rule operates in a “single-hit” fashion. This means that each row will be evaluated independently in descending order. When a rule in the rule set evaluates as true, the evaluation process stops and that row’s conclusions are executed. Therefore, the fall-back condition that the lead’s status remains “Dead” should be the last row considered in this business rule.
    5. Now, add a second Conclusions column by clicking the plus sign next to the Conclusions header. Configure this column as follows:
      • Click inside the blank header cell to the right of the Return column.
      • From the dropdown, select “Description”.
      • Click inside the cell below the Description header and enter a description to explain that this lead has been changed from “Dead” to the row’s status. For example, if a lead record changes from “Dead” to “Assigned”, you may want the description to read, “re-assigned”.
      • Continue entering and saving unique descriptions for any Status value that is not considered closed:
    6. Click “Save & Exit” to save the process business rule and then navigate to the Process Definitions module.
    7. Create a new process definition record. Name the record “Dead lead status change” and set the Target Module as “Leads”. Please refer to the Process Definitions documentation for complete steps to create a new process definition record.
    8. Click “Save & Design” to continue to the Visual Designer canvas.
    9. Drag a Start event onto the canvas.
    10. Right-click the Start event and then select “Settings”.
    11. Using the “Applies to” dropdown menu, determine when the process definition should activate. For this use case, select “Updated Records Only (All Updates)” so that the process begins every time a lead’s Status field changes to “Dead”.
    12. Click inside the Criteria box to add conditions for when the process definition should activate. For this use case, create a Module Field Evaluation where the lead’s Status field is “Dead”, as shown here:
    13. Save the Start event’s Settings window and then drag a Receive Message event onto the canvas. Drag a connector to this event from the Start event.
    14. Right-click the Receive Message event and then select “Settings”.
    15. Click inside the Criteria box to add conditions for when the process definition should resume. For this use case, create a Module Field Evaluation where the lead’s Status field is no longer “Dead”, as shown here:
    16. Save the event’s Settings window and then drag an action element onto the canvas.
    17. Drag a connector to the action element from the Receive Message event and then configure the action:
      • Right-click on the action element and select “Business Rule”.
      • Right-click on the Business Rule action again and select “Settings”.
      • In the pop-up window, select the rule created in the steps above in this section:
    18. Save the action’s settings and then drag an End event onto the canvas. Drag a connector from the action element to the End event. There is no need to configure the End event’s settings for this process definition.
    19. Save and enable the process definition.
      • Note: New process definitions are set to “Disabled” by default as a preventative feature to ensure a process instance is not triggered inadvertently during the design phase. After fully configuring the design, exit the Visual Designer and set the process definition to “Enabled” via the Process Definitions dashlet or list view. For more information, please refer to the Process Definitions documentation.
    20. Finally, test the process definition:
      • Find an open lead and change its Status field to “Dead”. On save, confirm that a process begins in the Process Management list:
      • Return to the lead and edit the lead’s status to any other value. View the lead’s Description field and confirm it displays the message specified in the related business rule:
      • Change the lead’s status back to “Dead” and confirm that a new process appears in the Process Management list.
      • Continue changing the lead’s status from “Dead” to every other value and observe the behavior. A new process should run every time the lead’s status returns to “Dead” and conclude when the dead lead’s status changes to any other value (e.g. Assigned).

    Downloads

    The two module records created in this section are provided here for your convenience. Please choose the appropriate files according to your Sugar version. While these records are importable to their respective modules, keep in mind the following:

    • A process definition (.bpm) file that contains a reference to an email template or business rule should be imported after those related records have been created in or imported to the instance.
    • You must re-configure the settings for the Business Rule action before enabling the process definition.
    • Always review the settings of imported SugarBPM files to confirm that they are configured as expected.
    • Process definition files may import in a “Disabled” state. Please enable the process definition after confirming its elements’ settings.
    Process Business Rule File Process Definition File
    .pbr .bpm
    in SugarBPM

    Reach out to us for help