Troubleshooting On-Save Legacy Workflows
Overview
Sugar's Workflow functionality allows administrators to configure cause-and-effect actions across multiple Sugar modules. On-save workflows produce alerts and/or actions when specified conditions are met at the time the record is saved. However, there are times when a workflow does not produce the expected result. This article is not an exhaustive list of possibilities as to why the workflow did not function as expected, but seeks to help you initially troubleshoot and further understand the issue at hand.
For more information about workflows, please refer to the Workflow Management documentation.
Each user's license type (e.g., Sugar Serve, Sugar Sell Premier) determines what functionality is available as described in the License Types matrix.
Symptoms
After setting up an on-save workflow, the alerts or actions do not trigger when the conditions are met upon a record save.
Resolution
Troubleshooting Workflow Fields
The Workflow module contains several pieces of information that serve both functional and organizational purposes in workflows. The following items may be influencing your workflow's ability to produce the desired result:
- Execution Occurs : Determines when and how workflows are triggered
- Target Module : The Sugar module whose save triggers the workflow
- Processing Order : Determines whether any alerts will fire before or after any actions are executed
- Status : Determines whether the workflow is actively functioning or not
- Applies To : Specified which types save records will trigger the workflow
- Conditions : Conditions which be met in order for the workflow to trigger
- Alerts : When a workflow triggers, emails which are sent to a specified list of recipients
- Actions : When a workflow triggers, actions which are executed on the target or a related module
Execution Occurs
For on-save workflows, the Execution Occurs field needs to be set to "When record saved". If this is set to "After Time Elapses", you may not be getting the results you expect. If this is erroneously set, click the Edit button in the top right corner, select "When record saved", and save.
Target Module
"Target Module" is the module in which the save must be made in order to trigger the workflow. If the workflow is expected to trigger when contact records are saved, but "Target Module" is set to "Accounts", you may not be getting the results you expect. If this is erroneously set to the wrong target module, click the Edit button in the top right corner, select the intended module, and save.
Note: The Target Module field cannot be edited once conditions, alerts, or actions have been set up on the workflow. If the target module needs to be changed, you must delete the workflow and create a new one with the desired settings.
Processing Order
If your workflow is going to include both email alerts and workflow actions, select which of the two you would like to happen first. This should not effect whether or not the workflow triggers, but may impact the field data that appears in the received alert.
Status
When this is set to "Inactive", the workflow will not process. If you have a workflow that is not firing, ensure that the status is set to "Active".
Applies To
This field indicates if this workflow is going to fire on all saves, only when a new record is created, or only when an existing record is updated. If the workflow is being triggered when it is not expected, or if it is not being triggered every time it is expected, the workflow's Applies To field may not be set right. Ensure that this field reflects the intention of the workflow.
Note: If "New Records Only" is selected, the workflow will only fire when the record's Date Created matches the current time. It is not based on any other fields or statuses indicating that it is a new record.
Troubleshooting Conditions
Workflow conditions can evaluate one or more fields on the target or related module. All conditions must be simultaneously met in order for the workflow to trigger. There are various issues that can arise depending on how your workflow conditions are defined.
Field Changes Versus Field Contains
When defining a condition, there are two very similar definitions that can be easily confused. Among other possibilities, a workflow can be triggered "when a field in the target module changes to or from a specified value" or "when a field in the target module contains a specified value". The important distinction here is whether or not the defined value has changed during the save event that triggers the workflow. If the condition is "when a field in the target module changes to or from a specified value", this workflow will only be triggered when the value in this field is being changed in the triggering save event. However, if the condition is "when a field in the target module contains a specified value", the workflow will be triggered whether the field was just changed to the defined value or if it was already that value and was not changed.
For example, if the workflow is expected to fire when the State field changes to "Iowa", for example, but it is firing every time the record is saved and the State field has been "Iowa" for months, ensure that the workflow's condition is using "when a field in the target module changes to or from a specified value".
If your workflow is not firing when expected or is unexpectedly firing, ensure that the conditions being used accurately reflect your intentions.
Field Content Integrity
When defining specific values for a condition, particularly for text or currency fields, for example, it is very important to avoid typos or unintended characters in both the field data and the workflow definition. It is also important that your workflow definition reflects the data that is being recorded in the record. For example, if the workflow definition is to trigger when the State field contains "IA", but users have entered "Iowa" into this field, then saving this record will not meet this condition, and the workflow will not be triggered.
Confirm data integrity by carefully comparing the field content in sample records with the data defined in the condition of the workflow to ensure a perfect match.
Field Confusion
Two fields in the same module can have identical or similar labels. This can create confusion when selecting the field in the process of defining a condition. If there are two fields with identical or similar labels, ensure that the field in the condition is the intended field. Changing the label of one of these fields via Studio > {Module Name} > Fields is one of the simplest ways of distinguishing them.
Contradicting Conditions
When more than one condition is defined for a workflow, all conditions must be true during the single save event in order to trigger the workflow. It is possible to create two or more conditions that can never be true at the same time. For example, there can be two conditions on the same field, with one looking for the value to be one string, and the other looking for the value to be a different string.
In the below example, a record's Type field cannot change to "Analyst" and contain "Competitor" because if it changed to "Analyst", then it contains "Analyst". These would therefore be contradictory conditions, causing this workflow not to fire.
Conditions for Fields in a Related Module
In addition to all of the above concerns, conditions that evaluate related records may be prevented from behaving as expected if there is more than one relationship between the two modules. In this case, please ensure with testing that you are specifying the correct relationship. Additionally, ensure that you are not confusing a relationship with a custom relate field. You must specific the correct link in order to have your workflow behave as desired.
Conditions and the Actions of Other Workflows
An instance can have more than one workflow affecting the same module and, therefore, the same records. The same save event can trigger multiple workflows, and the actions of one can affect whether or not the conditions of another workflow are met. Workflow sequence determines the order in which multiple workflows are triggered on the same save event. Subsequent workflows will be affected by the actions taken by previous workflows, but the converse is not true.
Troubleshooting Actions
Workflow actions can modify fields within the target module or fields in modules related to the target module. They can also create new records in related modules. Workflows can have one or more actions that are automatically performed when the workflow is triggered. There are various issues that can arise depending on how your workflow's actions are defined.
Field Confusion
Two fields in the same module can have identical or similar labels. This can create confusion when selecting the field in the process of defining an action. If there are two fields with identical or similar labels, ensure that the field in the action is the intended field. Changing the label of one of these fields via Studio > {Module Name} > Fields is one of the simplest ways of distinguishing them.
Two Actions Affecting One Field
A workflow's actions happen in a series, so if there are two actions that modify a field, only the last action's result will be reflected in the field after the save is complete. If you have an action that sets a field's value but this field does not contain that value after it is saved, ensure that no other actions in this workflow are setting this field to a different value.
Actions of Multiple Workflows
An instance can have more than one workflow affecting the same module and, therefore, the same records. The same save event can trigger multiple workflows, and the actions of one workflow can override the results of the actions of another. Workflow sequence determines the order in which multiple workflows are triggered on the same save event. A given field will only reflect the changes produced by the last action triggered to affect that field. All previous changes will be overwritten.
Actions Affecting Fields in a Related Module
In addition to all of the above concerns, actions that affect related records may be prevented from behaving as expected if there is more than one relationship between the two modules. In this case, please ensure with testing that you are specifying the correct relationship. Additionally, ensure that you are not confusing a relationship with a custom relate field. You must specific the correct link in each action in order to have your workflow behave as desired.
Troubleshooting Alerts
Workflow actions can send email alerts, and there are various issues that can arise that affect a workflow's ability to correctly execute its alerts.
Outbound Email Settings
If the outbound email settings defined in Admin > Email Settings are not configured correctly, then workflows will be unable to send workflow alert emails. Confirm that this outbound account is able to send email from Sugar before continuing to troubleshoot workflow alert issues. For more information, please refer to the Email documentation.
Recipient Lists
The recipient list for the alert template can be populated with users, recipients (e.g. Contacts, Accounts, Leads, etc), or members of teams or roles within your instance. Alerts being received by these recipients depends on the email address field being populated correctly for the desired related records. To rule out whether one of these relationships could be causing the issue, temporarily set the recipient list to send only to a specified user with a known, good email address. If that user does not receive the email, the issue is likely elsewhere.
Alert Templates
Template Availability in Workflow
A workflow can only utilize templates that are created for that same target module as the workflow itself. When an alert template is first created, a module needs to be selected. Therefore, a Contacts module alert template will not be available to a workflow with Accounts as its target module. Ensure that the template you are looking for is in the same module as the workflow you are troubleshooting.
Invalid Values
If a variable that is expected to show the value of a field in a related module is displaying "Invalid Value" in a received email, ensure that records are related using the intended relationship, especially if there is more than one relationship in place between the two modules or if custom relate-type fields are being used in the record view that do not represent a relationship between the records.
For example, if a Contacts module workflow alert has a variable for the related account's name but the Contact record is not related to an account via the relationship specified in the alert template, then that variable will print "Invalid Value" in the received email.
Field Confusion
Two fields in the same module can have identical or similar labels or similar database names. This can create confusion when selecting the field in the process of defining an alert template. If there are two fields with identical or similar labels or similar database names, ensure that the field variable in the alert is the intended field. Changing the label of one of these fields via Studio > {Module Name} > Fields is one of the simplest ways of distinguishing them.
New Value Versus Old Value
A variable for inserting the value of the contact's Name field after the save action is complete is:
{::future::Contacts::full_name::}
A variable for inserting the previous value of the contact's Name field prior to the same event is:
{::past::Contacts::full_name::}
An "old" value variable will be blank for all new records created in Sugar because this record did not previously exist, so the field contained no data.
Additional Help
If the above areas did not reveal or resolve the issue you are experiencing, please reach out to others for additional assistance. There is an active community at sugarclub.sugarcrm.com. There may be a discussion of a similar issue there, or you can start a discussion on the topic. You can also file a case in order to have SugarCRM Support assist you in troubleshooting your workflow.
