Understanding SugarBPM Best Practices

Overview

SugarBPM is a powerful tool, and processes can get complicated quickly. This article outlines best practices for various aspects of SugarBPM, including design, maintenance, and scalability recommendations. The goal is to help Sugar administrators build efficient and reliable process definitions that support successful business use cases in Sugar.

Understanding Start Events

In most cases, a process definition begins with a single Start event. This is considered best practice to avoid creating a process that might become invalid due to multiple Start events evaluating as true at the same time.

However, there are specific scenarios where a single Start event limits the available "Applies To" options. In those cases, admins can use multiple Start events, as long as they are mutually exclusive and carefully designed.

When Multiple Start Events are Required

Multiple Start events are often needed in complex process definitions. An existing guide on multiple start events, including a helpful chart with good, acceptable, and bad examples can be found in the Adding Multiple Start Events section of the Process Definitions documentation in the Administration Guide.

We recommend the following best practices for using multiple Start events:

• Avoid repeating the same type of Start event within a process definition. Use logical operators (e.g., AND, OR) to combine conditions into a single Start event of the same type.
• Use parentheses to group conditions logically when constructing complex criteria.
• Consolidate multiple "New Records Only" Start events into one. This improves maintainability and reduces the risk of conflicting logic.

• Use Start events that apply to both new and updated records simultaneously, to eliminate the need for separate events in most circumstances.

Adding Controls to Prevent a Record From Triggering a SugarBPM Process Repeatedly

Sometimes, a single record might unintentionally trigger the same process multiple times. This happens when the Start event criteria remains true, and then an unrelated field on the record is updated, causing the process to fire again.

For example, if your Start event includes a condition such as "Status is New", the best practice is to immediately remove that condition once the process is triggered. This can be done by adding a Change Field action at the beginning of the process.

In this scenario, the first automated step would change the Status from "New" to "Assigned". This ensures the record no longer matches the Start event criteria and prevents the process from being retriggered unexpectedly.

Multiple SugarBPM Flows Triggering the Same Record

In SugarBPM, it is possible to create multiple process definitions with identical Start event criteria. As a result, each process definition will be triggered whenever a matching record is created or updated. In these cases, SugarBPM handles the flows in order of their creation date, from oldest to newest. This means all matching processes will be queued for execution, starting with the earliest one.

Triggering multiple SugarBPM flows simultaneously for the same record can significantly increase save times, leading to performance issues and a degraded user experience. To avoid long save times and system strain, consolidate multiple SugarBPM flows into a single process definition whenever possible. You can achieve this by using parallel gateways to handle the different execution paths that were previously defined in separate processes.

For example, consider three individual process definitions that share the same Start event criteria. All three would be triggered when a matching case record is created, resulting in three queued executions:

Instead, these can be combined into one unified process definition that uses diverging and converging parallel gateways to manage the individual paths. This approach improves efficiency, reduces load, and delivers a smoother user experience when saving records.

Understanding Diverging Gateways and Converging Gateways

Gateways in SugarBPM enable you to create multiple execution paths based on conditions evaluated from the primary record or related records.

When using diverging gateways, which split the process into separate branches, it is considered best practice to close each diverging branch with a corresponding converging gateway later in the process. This ensures a clean, structured flow and avoids leaving parallel branches open indefinitely, which could lead to process inconsistencies or unexpected behavior.

Inclusive Gateways

Inclusive gateways are divergent elements that evaluate conditions and direct the process flow through all paths where the criteria are met. This means one or more branches may be executed in parallel based on the defined logic. Each path within the gateway can have a unique set of criteria, allowing for flexible and dynamic branching.

You can also set up different combinations of criteria for each path:

Here are some best practices when designing these types of flows:

• Take note of the save time: Each path queries the database when the record is saved. More paths increase the evaluation time, adding milliseconds to the save action.
• Limit complexity: Design fewer than 15 possible paths per gateway, and thoroughly test all paths before deploying to production.
• Guarantee at least one path: Ensure that at least one path evaluates as true whenever the process definition is triggered.

It is common for unanticipated scenarios to appear after deployment. If a process is triggered but no path criteria are met, you can identify these cases in Admin > Process Management. They will appear as unassigned paths. You can see this in the example below, as noted by the three paths that are disabled and not taken.

In these cases, we recommend refining the Start event criteria to prevent records from unnecessarily entering the process and evaluating all paths without meeting any condition.

Designing for Flexibility and Maintenance

SugarBPM process definitions often need to evolve as business needs change. When designing a process definition, plan with the expectation that updates will be required over time. To support easier maintenance and change management, we recommend leveraging these easily configurable components:

• Round Robin
  

• Business Rules
  

• Email Templates
  

By using these elements, you can update logic or templates outside of the Visual Designer, and the changes take effect immediately, without needing to modify or redeploy the process definition itself.

A business rule can manage assignment logic for records in the same way a gateway with multiple paths would. This approach is typically faster, more efficient, and easier to maintain over time.

For example, the above screenshot shows the simplicity and configurability of using a business rule as opposed to the attempt at using a complicated process below to accomplish the same thing.

Editing Existing Process Definitions

There will be times when updates to the original process flow or its components are necessary. To ensure stability and rollback capability, follow these best practices.

Consider Active Processes

Before making changes to a process definition, there may be processes already in progress (i.e., in-flight). If you modify any elements that a record is expected to pass through, or alter related components connected to the active path, the ongoing process is automatically canceled by the system.

Disable and Back Up the Original Process Definition

Before making any changes to a process definition, always disable it and create a copy. The copy allows you to revert to a stable version if unexpected issues arise during or after the modification.

Create Incrementing Versions of Process Definitions

To avoid disrupting active flows, create a new version of the process definition rather than editing the existing one.

For example, consider this process definition that does not include an event-based gateway:

If you need to add a gateway after the first related record, doing so in the original design would disrupt the active process. Instead, create a new version of the process definition with the updated logic. This allows in-progress flows in Version 1 to finish without interruption, while new records follow Version 2.

If you modify the design of an enabled process definition, any processes already in progress will immediately adopt the new flow, which leads to unexpected results or logic errors.

To prevent this, always disable the process definition before making design changes. Disabling ensures that in-flight processes continue on the original flow without being interrupted or canceled. Once the definition is re-enabled, any incomplete flows will then continue under the updated logic.

Recommended Steps to Add a Gateway

1. Export the original process definition and re-import it. This ensures you have a clean working copy without altering the active version.
2. In the original process, modify the Start event so it no longer triggers for new records (e.g., add a hidden field via Studio and exclude it in the Start criteria).
3. Make the necessary changes to the new version, including the new gateway, outside of peak business hours.
4. Keep both versions enabled temporarily. This allows for existing in-flight records to complete using the original version while new records follow the new version.
5. Once all records tied to the original version have finished processing, you can safely disable the original definition.

Validating Triggered Process Definitions by a Specific Record

During testing, it is easy to use the Process Management module to see which process definitions have been triggered. However, in complex scenarios or troubleshooting, administrators may need to verify which SugarBPM flows were triggered for a specific record.

To do this, we recommend using Advanced Reports to run a custom SQL query to trace the relationship between the record and its associated process flows.

First, obtain the record ID from the record that triggered the process (e.g., the note's record ID, the case's record ID). You can get this in the URL of the record within Sugar:

Next, plug this record ID into the following query, which returns the names of the process definitions that were triggered for a specific record:

    SELECT 
    pmse_bpm_flow.pro_id, 
    pmse_bpm_flow.cas_id, 
    pmse_bpmn_process.name AS ProcessName, 
    pmse_bpm_flow.cas_flow_status AS Status
FROM pmse_bpm_flow 
INNER JOIN pmse_bpmn_process 
    ON pmse_bpm_flow.pro_id = pmse_bpmn_process.id 
WHERE cas_sugar_object_id = 'RECORD-ID-HERE-b198-02812091b24a';

It is also important to monitor the number of in-flight processes within the instance. There are active SugarBPM flows that wait for an external event (e.g., user action, a timer, a message event) to continue execution. It is recommended to keep the number of concurrent in-flight processes below 10,000 to ensure good system performance.

Use the following queries in Advanced Reports to check active or waiting processes.

    -- Count of processes waiting for an event
SELECT COUNT(cas_flow_status) 
FROM pmse_bpm_flow 
WHERE cas_flow_status = "WAITING";

    -- Breakdown of process statuses
SELECT cas_status, COUNT(1) 
FROM pmse_inbox 
WHERE deleted = 0 
GROUP BY cas_status;

Understanding SugarBPM Performance

In some cases, users may report that saving a record takes longer than expected, sometimes more than ten seconds, or that overall system performance feels slow. A common cause is a process definition that executes too many actions immediately upon the first save. The best practice is to analyze the timing of the initial trigger, especially when numerous automated actions are involved, since save time is directly impacted by the number of elements that must run before the flow pauses or ends.

Consider a support center scenario where creating a new case record also triggers ten related task records. While these tasks are important for follow-up, they are not immediately required by the agent handling the call. If all ten tasks are generated during the initial save, the agent may face a delay of up to 15 seconds before the case saves and the case number appears. This slows the user experience and reduces system responsiveness during peak usage.

To improve performance in this scenario, a one-minute timer is added immediately after the process is triggered. This allows the Case record to save almost instantly, so the agent can quickly view and share the case number with the customer. Once the timer expires, the process resumes in the background, creating the related records without delaying the initial save.

A process enters a waiting state when it includes one of the following elements:

• Receive Message event
• Wait event

To ensure system performance, it is recommended to keep the number of simultaneous waiting flows below 10,000. You can estimate this threshold by considering:

• The average duration of each process
• The number of processes triggered per day