SugarBPM

Overview

SugarBPM™ enables administrators to streamline common business processes by managing approvals, sales processes, call triaging, and more. SugarBPM is an easy-to-use business process management (BPM) and workflow tool that adds advanced BPM functionality to Sugar.

The SugarBPM suite features an extensive toolbox of modules that provide the ability to easily create digital forms and map out robust workflows using a drag-and-drop interface.

Scope

This documentation only defines relevant BPM terminology and the concepts used specifically for SugarBPM modules. It is not intended for general BPM educational purposes, and should not be used as a complete BPM modeling resource.

The SugarBPM documentation contains the following pages:

Additionally, the Processes page of the Application Guide contains documentation for the user-facing elements of SugarBPM, and the Knowledge Base contains several business use-case tutorials on how to design some common processes for your organization.

Prerequisites

• Basic knowledge of process design is required.
• Basic knowledge of process standards such as BPMN is preferred. BPMN is a flowchart-based notation used to define business processes within an organization.
• You should know which business processes you want to automate in Sugar.

Core Concepts

A business process is a set of logically related tasks that are performed in order to achieve a specific organizational goal. It presents all of the tasks that must be completed in a simplified and streamlined format. SugarBPM empowers Sugar administrators to automate vital business processes for their organization. Some examples of business processes that can be automated using SugarBPM include invoice approvals, lead routing, customer service case routing, and automated reminders and escalations.

SugarBPM Modules

In order to seamlessly automate business processes, the SugarBPM suite leverages four interconnected process-related modules. The Process Business Rules module and the Process Email Templates module are used to create rules and email templates that will be referenced by records created in the Process Definitions module. Once a process definition has been created, it will generate a record in the Processes module each time the process definition is triggered.

The Process Business Rules, Process Email Templates, and Process Definitions modules can be viewed and configured by any system administrator user. In addition, regular users with a role that provides developer access to one or more modules for which a SugarBPM process can be triggered (e.g., Accounts module, Cases module) will be able to access all SugarBPM functions for those modules. For example, a regular user with developer access to the Accounts and Cases module can see the SugarBPM functions so that they can design process definitions, business rules, and email templates targeting the Accounts and Cases modules. Regular users without developer role permissions will only have access to the Processes module. For more information about roles, please review the Role Management documentation.

The following image illustrates the relationship between the SugarBPM modules:

The following table describes the four SugarBPM modules and their intended use. To learn more about any of the modules, click on the hyperlinked module name.

Note: We recommend reading this page in its entirety before moving on to other SugarBPM sections.

Basic Visual Notation Elements

SugarBPM depends on process definitions created by the administrator using a Visual Designer tool. When complete, the design will graphically display a collection of flow elements that connect with each other to define and regulate a business process in Sugar.

The following table defines the different types of flow elements that are available when creating a process definition in the Visual Designer.

Element	Symbol	Definition
Events		An Event is something that happens during the course of a business process. Events affect the flow of the Process and usually have a trigger and/or a result. They can start, interrupt, or end the flow of a process. An Event is represented by a circle in the Visual Designer.
Start Events		The Start event indicates where a process will begin. It defines the action that will trigger the Process. The Start event will always be triggered by a record in the Sugar module selected as the process definition's Target Module. Note: A process definition's target module will be the same module that is used for the Start event. A Start event is represented by a green circle on the Visual Designer canvas.
Intermediate Events		As the name suggests, Intermediate events occur after a process starts but before the process is complete. Intermediate events that are placed within the overall process flow represent things that happen during the normal operation of the process such as sending messages, receiving messages, or mandatory waiting periods. Intermediate events are represented by blue circles in the Visual Designer.
Activities		The only unit of work that may require a user response (opposed to automation) is an Activity. It is a moment within a flow where a user must decide if a circumstance is approved or rejected, or review a record that has been routed to them. Activities are represented by rounded-corner rectangles in the Visual Designer.
Actions		Actions are automated elements used to execute a business rule, create or update a Sugar record, or identify a process user. Actions are completed by the SugarBPM engine and do not require any human interaction to execute. Actions are represented by rounded-corner squares in the Visual Designer.
Gateways		Gateway elements are used to control the flow of a process via merging and splitting. When several activities may result in a common outcome, a gateway serves as a merging mechanism, or a "converging" element. When a single activity may result in several different outcomes, a gateway serves as a splitting mechanism, or a "diverging" element. A Gateway is represented by a diamond in the Visual Designer.
End Events		End events signal completion of a process. There are three end-event options: Do Nothing, Terminate Process, or Send Message. An End event is represented by a red circle in the Visual Designer.

Basic Steps to Automate a Business Process

It is important to understand how all of the modules and elements of the SugarBPM suite will work together. Here is the best-practice chronology of the overall procedure for automating business processes in Sugar using SugarBPM:

1. Create a SugarBPM Dashboard: Before using SugarBPM for the first time, create a new dashboard specific to SugarBPM for easy, one-stop access to all automated business processes and their components.
2. Create and Configure a Process Business Rule: (optional) Create at least one Process Business Rule that will be used in a process definition. For example, automated lead assignments might require a process business rule to define which lead source values will be assigned to which user.
3. Create and Configure a Process Email Template: (optional) Prepare at least one Process Email Template for processes that require alerts or notifications.
4. Create and Configure a Process Definition: Using the Process Designer canvas, create the visual design of the overall business process that you want to automate. The process definition may make use of Process Business Rules and Process Email Templates created in previous steps.
5. Process Management: With all of the SugarBPM modules now working in harmony, administrators can navigate to the Process Management page to monitor process status, reassign or cancel an in-progress process, or repair processes in an error state. Users can monitor the Processes dashlet for activities that are queued or awaiting feedback.

Creating a SugarBPM Dashboard

Before getting started, we recommend that the administrator user creates a SugarBPM-specific dashboard on their home page. This will allow the administrator to easily manage Process Definitions and their supporting modules all in one place. Regular users who may be engaged in running processes should place the Processes dashlet on their home pages to stay abreast of activities requiring their attention.

Processes Dashlet

This is the only SugarBPM dashlet available to regular users. It is important for all users who may be engaged in a process to place this dashlet on their home screens. Open, running processes and self-service processes waiting to be acted upon by the logged-in user will be listed in this dashlet.

Note: Users (including administrators) will see only the processes that immediately require their attention.

To add a Processes dashlet, please refer to the Dashboards and Dashlets documentation, choosing "Processes" from the Add a Dashlet page.

After saving the dashlet and its containing dashboard, the dashlet will offer several process-specific management tools:

• Current: Click on this button to view all processes that are running within the expected timeframe.
• Overdue: Click on this button to view all processes that have a due date in the past. The label "Overdue" and the due date will be displayed adjacent to the process description.
• My Processes: View this tab to view the running processes upon which the logged-in user must act. Self-Service processes are not displayed here.
• To execute a Process from the dashlet, click on the name of the process. Please note that admin users cannot see processes running for other users via the dashlet. To access the system's exhaustive list of running and completed processes, refer to the Process Management section of this documentation.
• Self Service Processes: View this tab to view only the running processes in the queue to be claimed by a user. Self-Service processes are configured inside the User Activity element settings of the related process definition.
• Process Description: Running processes are displayed in list view format with descriptive fields including the unique process number, the name of the affected Sugar record, the process title, the responsible user's name, and the label of the relevant process step.
• Due Date: When a due date exists it will appear adjacent to the process description.

Process Definitions Dashlet

You must be an administrator user to add this dashlet to your home page. To add a Process Definitions dashlet, please refer to the Adding Dashlets section of the Dashboards and Dashlets documentation, choosing "Process Definitions" from the Add a Dashlet page.

After saving the dashlet and its containing dashboard, the dashlet will offer several SugarBPM-specific administration tools:

• Actions Menu: Click on the plus (+) icon to access the "Create Process Definitions" and "Import Process Definitions" options. Please note that imports for this module must have a .bpm file extension.
  
• My Process Definitions: Click on this button to list all process definitions created by the current admin user.
• All Process Definitions: Click on this button to list all process definitions created by any admin user.
• Enabled: View this tab to view a list of process definitions that are currently enabled in the system.
• Disabled: View this tab to view a list of process definitions that are currently disabled in the system. Disabling a process definition will prevent it from triggering new processes. Any running processes related to the disabled process definition will pause in an In-Progress state until the process definition is re-enabled.
• Process Definition Shortcut Buttons
  • Design: Click on this icon to edit the process definition via the Visual Designer.
    
  • Delete: Click on this icon to delete the adjacent process definition. A confirmation message will appear on the top of the screen; click "Confirm" to delete the process definition or click "Cancel" to close the message without deleting.
    
  • Export: Click on this icon to export the process definition to a .bpm file.
    
  • Disable/Enable: Click on this icon to disable an active process definition or to enable an inactive one. Disabled process definitions will be listed in the "Disabled" tab.
  • All process definitions are disabled by default and must be enabled by an administrator. For more information, please refer to Enabling Process Definitions.
  • Disabling a process definition will prevent it from triggering new processes. Any running processes related to the disabled process definition will pause in an In-Progress state until the process definition is re-enabled.
    
  • Description: Click this icon to open a blue alert window that displays the admin-specified description of the process definition. To close the description dialogue, click on the x in the corner of the message.

Process Email Templates Dashlet

You must be an administrator user to add this dashlet to your home page. To add a Process Email Templates dashlet, please refer to the Adding Dashlets section of the Dashboards and Dashlets documentation, choosing "Process Email Templates" from the Add a Dashlet page.

After saving the dashlet and its containing dashboard, the dashlet will offer several SugarBPM-specific administration tools:

• Actions Menu: Click on the plus (+) icon to access the "Create Process Email Template" shortcut.
  
• My Process Email Templates: Click on this button to list all email templates created by the current admin user.
• All Process Email Templates: Click on this button to list all email templates created by any admin user.
• Process Email Template Shortcut Buttons
  • Edit: Click on this icon to edit the template record from record view. It is then possible to access the template designer from the record view.
    
  • Delete: Click on this icon to delete the adjacent email template. A confirmation message will appear on the top of the screen; click "Confirm" to delete the email template or click "Cancel" to close the message without deleting.
    
  • Export: Click on this icon to export the process email template to a .pet file.
    
  • Description: Click this icon to open a blue alert window that displays the admin-specified description of the process email template. To close the description dialogue, click on the X in the corner of the message.
    

Process Business Rules Dashlet

You must be an administrator user to add this dashlet to your home page. To add a Process Business Rules dashlet, please refer to the Adding Dashlets section of the Dashboards and Dashlets documentation, choosing "Process Business Rules" from the Add a Dashlet page.

After saving the dashlet and its containing dashboard, the dashlet will offer several SugarBPM-specific administration tools:

• Actions Menu: Click on the plus (+) icon to access the "Create Process Business Rule" shortcut.
  
• My Process Business Rules: Click on this button to view business rules created by the logged-in admin user.
• All Process Business Rules: Click on this button to view business rules created by any admin user.
• Business Rules Shortcut Buttons
  
  • Edit: Click on this icon to edit the rule configuration from the Business Rules Builder interface.
    
  • Delete: Click on this option to delete the adjacent business rule. A confirmation message will appear on the top of the screen; click "Confirm" to delete the process business rule or click "Cancel" to close the message without deleting.
    
  • Export: Click on this icon to export the process business rule to a .pbr file.
    
  • Description: Click this icon to open a blue alert window that displays the admin-specified description of the process business rule. To close the description dialogue, click on the X in the corner of the message.

Process Management List View

For processes, the admin user is restricted to the same access as a regular user in the Processes module. This means that in Processes list view and the Processes dashlet, the admin user will not see processes unless they have participated in that process or they are expected to participate in it.

The exhaustive list of open and completed processes is accessible only via the admin's Process Management page. This page can be accessed from either of the following two places in Sugar:

• Admin > SugarBPM™ > Process Management.
• The Processes module tab's actions menu:
  

The following columns are available from the Process Management page:

• Process Number: Similar to a case number, this is a unique auto-increment number assigned to the process in the order it was triggered by the SugarBPM. This field is not related to the Sugar system ID field.
• Process Definition Name: The name of the originating process definition that triggered the process.
• Record Name: The related Sugar module record to which the process applies.
• Run Order: The order in which running processes targeting the same module are executed. This value is set on the process definition and is optional; processes with a blank run order are run last. In the case of a tie, processes are run oldest to newest by their process definition's Date Created field.
• Date Created: The date and time that the process was triggered.
• Assigned To: The user who is assigned to the Sugar record that triggered the process's Start event.
• Process User: The user who is responsible for executing the current activity in a running process if a Route or Approval activity is running.
• Process Owner: The administrator who created the process definition (not necessarily affiliated with the running process).
• Status
  • Completed: The process has successfully reached an end event and is no longer running.
  • Cancelled: An administrator user has chosen to cancel this process.
  • In Progress: The process is currently open and running.
  • Terminated: The record that triggered the process has been deleted or merged.
  • Error: The process has encountered a configuration problem and is paused.

Record Actions Menu

The Record Actions menu to the right of each record's Preview button allows users to view vital process information, re-direct processes, and navigate to the process execution screen directly from the list view.

Preview

Administrators can view the progression of a process within the overall flow directly from the Processes list view by clicking the Preview icon to the far right of each process list row. A color-coded representation of the process' design layout will display to the right of the list view providing key information regarding the stages that have already been completed, the current stage of the process, and the stages that have yet to execute.

The executed and in-progress stages of the process will be displayed in color, while skipped or not-yet-executed stages will be presented in a grayed-out style.

Note: To view the process design layout in more detail, simply click on the preview image to open a full-sized version of the flow in a new browser tab.

On the upper right of the intelligence pane, there is a Left and Right arrow button that allows you to scroll through the list view's current search results by previewing the next or previous record. To close the preview, simply click the "X" on the upper right of the intelligence pane.

Searching Processes

The Process Management list view includes a module search to help you locate running, completed, and incomplete processes easily and effectively. Once the search is performed, the relevant results will be displayed in the list view below.

Unlike the standard Sugar filter, the Process Management search bar will query all Process fields by default with the exception of "Record Name", which is technically a field from a related module. Furthermore, Sugar automatically assumes a wildcard character (%) at both the beginning and the end of your search phrase for processes. This means that, for example, a search for "error" will return processes named "Approve Error Resolution" as well as processes that are in an "Error" status.

The search also provides a Filter option that can be used in combination with the open Search box to narrow your search further using the available options as follows:

• All: Returns all processes.
• Processes Completed: Returns only processes with a status of "Completed".
• Processes Terminated: Returns only processes with a status of "Terminated".
• Processes In Progress: Returns only processes with a status of "In Progress".
• Processes Cancelled: Returns only processes with a status of "Cancelled".
• Processes Error: Returns only processes with a status of "Error".

When you choose a filter, Sugar will return processes that match both the selected filter and any name provided in the "Search..." bar in the filtered list view results. For example, if you select "Processes Completed" in the Filter options and enter a search query, Sugar will only return processes that contain a match to the search query and have a Completed status. To see all processes, simply select "All" in the filter and remove any text from the search bar. You can also click the X that appears within the search bar. When you run a search using a saved filter, the search will not be preserved when you navigate away from the module. Returning to the Process Management page will automatically display all unfiltered results.

Unattended Processes

An unattended process is a running process instance that has been interrupted because an activity is dependent upon the response of an inactive or deleted user. If an activity is encountered within a process, and the activity's process user record's status is "Deleted" or "Inactive" or its employee status is "Not Active", the process will be considered unattended. The activity cannot be completed unless the administrator designates a new process user.

Note: While an unattended process will also appear in the Process Management list, its status will remain "In Progress" and will not indicate that it is in an unattended state.

The list of unattended processes is accessible via the admin's Unattended Processes page. This page can only be accessed from the Processes module tab's actions menu:

To select a new process user for an unattended process, follow these steps:

1. From the Unattended Processes list view, expand the actions menu for the row that contains the unattended process.
2. Click on "Select New Process User".
   
3. After a brief pause, the Select New Process User drawer will appear.
   
4. Find and select the name of the new process user and then click Done.

The updated process should no longer be visible in the Unattended Processes list, and the new process user will see the activity in their Processes dashlet and list view.

Terminated vs. Cancelled Processes

SugarBPM automatically terminates a process when the record related to the process' Start event is deleted. The associated process will be removed from the Processes dashlet and the process record will display "Terminated" in the Status column of the Process Management list view. Processes may also be terminated as a result of meeting conditions specified in the Process Termination settings. For more information, please refer to the Process Definitions documentation.

Cancelled processes, on the other hand, have been intentionally stopped by the administrator. The associated process will be removed from the Processes dashlet and the process record will display "Cancelled" in the Status column of the Process Management list view.

Importing and Exporting SugarBPM Module Records

SugarBPM supports import/export functionality for records in all modules except the Processes module, which only contains running instances of process definitions. To import records into the Process Definitions, Process Email Templates, or Process Business Rules modules, the import file must be formatted as the appropriate proprietary file type, as shown in the table below.

Note: The .bpm file type is a package that may include email templates and business rules that are related to the process definition. Process email templates and process business rules, when exported or imported on their own, will have the .pet and .pbr file extensions, respectively. More information is available in the Exporting and Importing SugarBPM Records sections below.

Due to the proprietary nature of the SugarBPM file types, only files that have been exported from a Sugar instance can be imported into a Sugar instance. For example, an administrator may choose to design process definitions in a sandbox or development instance before moving them to a production environment. For this, the process definitions would be exported from the dev instance as .bpm files and then imported into the production instance's Process Definitions module.

Exporting SugarBPM Records

Exported SugarBPM records will automatically download as the appropriate file type. If a process definition uses any email templates or business rules, then the related records will automatically be included as part of the exported process definition's .bpm file. Any tags applied to the SugarBPM records in the .bpm file will also be retained. The user who later imports the process definition will be prompted to decide which supporting files they want to import with the process definition. The process definition and related email template(s) and business rule(s) will be created in their respective modules. More information is available in the Importing SugarBPM Records section below.

SugarBPM module records can be exported from any of the following locations:

• The record's list view actions menu:
  
• The record's record view actions menu:
  
• The dashlet's Export button adjacent to the record:
  

Importing SugarBPM Records

You can import a business rule (.pbr), an email template (.pet), or a process definition (.bpm) that has been exported from another Sugar instance. Most often, this action is performed between a production and development instance for testing or debugging.

Note: By default, Sugar will automatically validate imported process definitions, but you may disable this feature via Admin > System Settings.

After exporting a SugarBPM module record, it can be imported via the option in one of the following menus:

• The Actions menu on the module's dashlet:
  
• The module tab's Actions menu:
  

When importing a process definition record, if the .bpm file was exported with related email templates and business rules, you will see a list of those records and be given the option to import them as well. Select the checkbox next to the record type (e.g., Business Rules) to import all of the records in that category. To select related records individually, enable only the checkboxes next to those records. 

Click "Import" when you are ready to continue. The process definition and any related email template(s) and business rule(s) will be created in their respective modules and retain their settings and field values, including record-level tags. Please note that the systems that you are exporting and importing between should be clones so that any custom fields, modules, or relationships used by the SugarBPM records can be found.

SugarBPM Settings

To configure SugarBPM settings such as auto-save and auto-validation intervals, navigate to Admin > System Settings and find the SugarBPM™ panel. For more information on the system configuration options for SugarBPM, please refer to the System documentation.

SugarBPM Log Viewer

Administrators and developers can gain insight into the performance of the SugarBPM engine by viewing the SugarBPM log. To access the SugarBPM Log Viewer, navigate to the Admin page and click on "Log Viewer" under the SugarBPM panel.

There are two options on the SugarBPM Log Viewer page:

• Refresh: Refreshes the log view, loading the last records.
• Clear: Permanently deletes all log history. This cannot be undone.

The log level is set to Critical, which is equivalent to Sugar's Fatal log level and starts recording events as soon as SugarBPM has been installed. A developer can update the system config.php to change SugarBPM settings including "logger_level" and "error_timeout". Changes that are made to config.php are honored in real-time. For more information, please refer to the Core Settings documentation in the Developer Guide.

SugarBPM Scheduler

Schedulers in Sugar automate the execution of system processes. Schedulers are available only to administrative users and can be accessed by navigating to Admin > Schedulers. SugarBPM Scheduled Job is responsible for processes associated with SugarBPM. It is active and runs as often as possible by default. The SugarBPM Scheduled Job will check for any active, time-based process events (e.g., Wait events, Receive Message events, and Send Message events) in a pending state. If any processes meet this criterion, the scheduler will ensure that the process flow continues.

For more information about Sugar schedulers, please refer to the Schedulers documentation. For more information on troubleshooting the SugarBPM Scheduled Job, please refer to the Troubleshooting Wait Events in SugarBPM article.

Note: Process events processed by this scheduler will be run by the admin user (user id = '1') in Process History unless the admin user is disabled.

SugarBPM Excluded Fields