Ignoring Weekends During Wait Events in SugarBPM

Overview

This article explains how to use SugarBPM to automate a business process after a certain number of business days have passed, excluding Saturdays and Sundays, if your Sugar instance does not have business centers. If you are using Sugar 12.0 or higher, it is recommended to use business centers as they can accomplish the same task with minimal configuration. Refer to the Business Center Management documentation for more information. 

Use Case

When a case's status changes to "Pending Input", we will send the case's assigned user an email reminder three business days later. For example, if the status change occurs on a Friday, the process definition will ignore the weekend and send the email reminder the following Wednesday. To use an interval other than three business days, refer to the table in the Application section for the appropriate values to use in the gateway and Wait events in this article.

Prerequisites

• You must be an administrator or have developer-level role access in Sugar to create and manage SugarBPM records and to create custom fields as required by this article.
• Before performing the steps in this article, it is recommended that you have a basic understanding and knowledge of SugarBPM and be familiar with creating fields in Studio.
• Schedulers, specifically the SugarBPM™ scheduler, must be running.
• Sugar must be configured to send outbound emails via Admin > Email Settings.

For more information on any of these items, please refer to the User Management, Role Management, SugarBPM, Studio, Schedulers, or Email documentation.

Steps to Complete

The following sections cover how to create a process email template for the reminder alert, a calculated field that determines what the current day of the week is, and the process definition that determines how long to wait based on the current day.

Creating a Process Email Template

First, create a process email template that will determine the layout of the reminder email that the process sends to the assigned user. Use the following steps to create the email template:

1. Create a new process email template record according to the Process Email Templates documentation. Name the record "Pending Input 3-day Reminder" and set the Target Module field to "Cases".
   
2. Click the Save & Design button to design the template content.
3. Enter a Subject line and message as desired. It is recommended to use content variables via the Fields Selector tool to reference specific case information in the email.
   
4. Click "Save & Exit" to preserve the changes in the template.
   

Now, proceed to the next section to create the custom field that determines which day of the week it is.

Creating a Custom Field

Create a custom Integer-type field in the Cases module called "thisday" that has a calculated value of dayofweek(today()). This will return the current day of the week as an integer value from 1 to 7 where 1 equals Monday, 2 equals Tuesday, and so on. When a record is updated, the custom field will calculate the current day's number. Refer to the Sugar Logic help articles for details and examples of using calculated fields.

Now, proceed to the next section to create the process definition that will wait three days before sending the case reminder email that you created earlier.

Creating a Process Definition

Use the following steps to create a case-reminder process definition:

1. Create a new process definition record according to the Process Definitions documentation. Name the record "3-day Cases Reminder" and set the Target Module as "Cases". Click "Save & Design" to continue to the Visual Designer canvas.
2. Drag two Start events onto the canvas and name them "New Pending Input case" and "Case changes to Pending Input".
   
3. Right-click the "New Pending Input case" Start event and select "Settings" to set its criteria. Configure it to apply to new records with the Status field set to "Pending Input".
   
4. Right-click the "Case changes to Pending Input" Start event and configure it to apply to all updates to records where the Status field changes to "Pending Input".
   
5. If a new case has a status of "Pending Input" or an existing case's status changes to "Pending Input", the process is triggered. It must then determine the current day's "thisday" value and wait for the appropriate number of days before sending a reminder message. This requires one Exclusive gateway connected to three Wait events. Add these elements to the canvas and connect the two Start events to the gateway ("Evaluate 'thisday'") and then, one by one, connect the gateway to each Wait event.
   
   Note: If you are building this functionality into a larger process, make sure that the evaluation of "thisday" occurs on the same day that the process begins.
6. Label the Wait events "Wait 3 days", "Wait 4 days", and "Wait 5 days". Or, if you are using an interval other than the three business days used in this article, refer to the table in the Application section for the appropriate values to use in the gateway and Wait events.
7. Right-click each Wait event and click "Settings". Set each element's duration to the corresponding number of days. For example, for the Wait event labeled "Wait 3 days", set the duration to 3 days.
   
8. Right-click on the gateway and set its default flow to "Wait 5 days". Since this is the default option, you do not need to set any criteria for that element in the next step of configuring the gateway. For more information on setting the default sequence flow, refer to the Process Definitions documentation.
   
9. Right-click on the gateway again and click on "Settings". Set the criteria as follows:
   • Wait 3 days : thisday is equal to 1 OR thisday is equal to 2 OR thisday is equal to 7
   • Wait 4 days : thisday is equal to 6
   • If "thisday" is equal to 3, 4, or 5, then the default flow will occur (Wait 5 days). For alternative wait periods, please refer to the Application section to configure the criteria appropriately.
   
10. Before sending the message, we need to make sure the case status is still "Pending Input". If it is, then we can send the message. If not, then no reminder is needed and the process can end. To perform this evaluation, add another Exclusive gateway to the canvas and pull connectors from each of the three Wait events (e.g. Wait 3 days) to the new gateway ("check for status change") as follows:
    
11. Place two End events to the right of the second gateway ("check for status change") and pull connectors from the gateway to these elements. Label one of the End events "Send Message".
    
12. Right-click on the End event labeled "Send Message", then click "Result" and select "Send Message".
    
13. Right-click again on the End event labeled "Send Message" and select "Settings". Choose the process email template you created earlier and select who the sender of the email should be (e.g. System Email). Then, set the message recipient to the user who is assigned to the case record.
    
14. Finally, configure the second gateway's criteria.
    • Right-click on the gateway and set its default flow to "Send Message". Since this is the default option, you will not need to set any criteria for that element in the next step of configuring the gateway.
    • Right-click on the gateway again and click "Settings". Set the criteria for the remaining End event to "Status is not equal to Pending Input".
      
15. 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. For more information on enabling process definitions, please refer to the Process Definitions documentation.
16. Lastly, test the process definition using each of the Start events. For testing purposes, change the duration for all three Wait events to 1 minute.
17. First, test the "New Pending Input case" Start event:
    
    • Create a new case record assigned to yourself with the Status field set to "Pending Input". Confirm that a process begins in the Process Management list. For details on accessing the Process Management list view, refer to the SugarBPM documentation.
    • Click on the preview button next to the test process and confirm that the correct Wait event has been reached. It will have a glowing red halo in the preview image as follows:
      Note: Your results may vary based on which day of the week you are testing and how you have configured your wait periods.
      
    • Wait several minutes and then refresh the Process Management list view. Click on the preview button again and confirm that the Send Message End event occurred and the process is in a Completed status.
      
      Note: Though we set the wait durations to one minute for testing, it may take a few extra minutes for the Wait event to expire depending on the frequency at which cron runs in your instance, which determines the maximum frequency that schedulers can run. SugarCloud is configured to run cron approximately every five to seven minutes. If your process has not resumed after seven minutes of waiting, please refer to the Troubleshooting Wait Events in Process Definitions article.
18. Second, test the "Case changes to Pending Input" Start event:
    • Update an existing case and set its Status field to "Pending Input". Confirm that a process begins in the Process Management list.
    • Click the preview button next to the test process and confirm that the correct Wait event has been reached.
    • Wait several minutes and then refresh the Process Management list view. Click on the preview button again and confirm that the Send Message End event occurred and the process is in a Completed status.
19. Check your email for the reminder messages from each of the test processes. If you have received the messages as expected, return to the process definition and revert the durations for all three Wait events to their proper settings. If you have not received the messages as expected, please check the configuration of all of the process definition elements and refer to the following articles for troubleshooting help:
    • Troubleshooting a Blank Process Email Template
    • Troubleshooting Wait Events in Process Definitions

Application

If your use case requires a duration that is longer or shorter than three business days, the following table translates the number of wait days required to ignore weekends for up to ten business days. To use the reference table, simply find the row that matches your timespan and then configure the three Wait events (Steps 6 and 7), the gateway's default flow (Step 8), and the gateway settings (Step 9) accordingly. Please note that the Wait event configured as the default flow will occur when the other criteria are not met, so you will not need to set any criteria for the default Wait events. For more information on setting the default sequence flow, please refer to the Process Definitions documentation.

Note: As a reminder, "thisday" is the field we created for the Cases module that calculates the current day of the week as an integer value from 1 to 7 where 1 represents Monday, 2 represents Tuesday, and so on.

¹ The Wait event configured as the default flow will occur when the other criteria are not met, so you do not need to set any criteria for the default Wait events in your process definition's design.

Downloads

The SugarBPM and process email template files created in this article are provided here for your convenience. While these files are importable, keep in mind the following:

• You must manually create the calculated field in your instance and configure the imported process definition to refer to this field.
• If on Sugar 8.x, you must re-configure the settings for the Send Message End event.
• You must thoroughly review the settings of all 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.