Troubleshooting Workflow Alert Emails Failing to Send

Overview

Sugar workflows can be used to send emails when certain conditions are met. If it appears that your workflows are failing to deliver email alert messages, you should confirm that the email template, workflow definition, schedulers, and system email settings are properly configured. This article covers how to troubleshoot workflow email alert issues in these areas of Sugar. 

Each user's license type (e.g., Sugar Serve, Sugar Sell Premier) determines what functionality is available as described in the License Types matrix.

Prerequisites

You must be an administrator user or have developer-level role access to view and manage the Workflows, Schedulers, and Email Settings sections of the Admin panel. For more information on workflows, please refer to the Workflow Management documentation. For more information on configuring the scheduler and system email settings, please refer to the Schedulers and Email documentation.

Symptom

Your Sugar instance contains one or more workflow definitions that should generate an email alert. When the workflow conditions are met, however, the intended recipient does not receive an email as expected.

Resolution

If you experience issues with your workflow email alert, try troubleshooting the following areas in the Sugar application.

Workflow Alert Email Template

Sugar's core product includes several places where email templates can be created for different purposes, but the Workflows module requires email alert messages to be created via the Workflow Definitions > Alert Email Templates module. Confirm that the email template for your workflow was created in this location. If it was created in the wrong place, the workflow definition would not have found it, and the workflow definition would, therefore, be incomplete. For instructions on how to create an alert email template, please refer to Creating an Alert Email Template for Workflows article.

Workflow Definition Configuration

At the definition level, there could be errors with the workflow's status, recipients, or conditions.

Verifying the Workflow's Active Status

In a workflow definition, if the Status field is not set to "Active", then the definition will not run. Use the following steps to verify the workflow definition's settings:

1. Navigate to Admin > Workflow Management and select the workflow in question from the Workflow Definitions list view. 
2. Edit the record and verify the Status field is set to "Active." 
   
3. Click "Save" to finalize any changes.

Verifying Other Workflow Configurations

There are two additional fields available when editing a workflow which may affect the its ability to send email alerts. First, check the Applies to field. If it is set to "New Records Only" or "Updated Records Only", the workflow will not fire on updated records or new records, respectively. Next, ensure the Processing Order is set correctly for your use case. For example, if you have an action to relate a user to the target record and an alert to email that user, ensure "Actions then Alerts" is selected so that the user will be in place before the workflow attempts to send the email.

Verifying the Recipient List

Workflow email alerts must relate to one or more recipients. Use the following steps to confirm the message's recipients:

1. Navigate to the detail view of the workflow definition and click on "Recipients" next to the broken alert event in the Alerts subpanel.
   
2. On the next page, confirm that there is at least one complete line within the Alert Recipient List subpanel, as shown in the following image. 
   
3. If this section is empty, click the Create button to specify the email recipient(s).
4. If the subpanel is correctly populated, verify the validity of the recipients' email addresses in Sugar.

Verifying the Workflow's Conditions

If workflow email alerts are not sending, it could mean there is an issue with your workflow conditions. Review the conditions of your workflow to ensure they are configured correctly. You can also recreate the workflow, including its conditions, in order to ensure all of the conditions are still valid. Be sure to do this without using the Copy function on the original workflow.

Scheduler Job Not Running

In order for a time-elapsed workflow to execute, schedulers, specifically the Process Workflow Tasks scheduler, must be running in Sugar. Use the following steps to verify the settings for the scheduler record:

1. Navigate to the Admin > Scheduler and select "Process Workflow Tasks" from the list view.
   
2. Verify that the Status field is set to "Active." If the scheduler is inactive, click "Edit" and set the field to "Active."
3. Also, verify that the Interval field is set to a valid running time. This determines how frequently the server will check for queued workflow tasks. 
   
4. Click "Save" to finalize any changes.
5. After saving or canceling the edit, check the Job Log at the bottom of the scheduler's detail view. You should see regular and up-to-date entries of when the scheduler last completed.

If there are no entries or no recent entries, ensure that cron is running on your instance using the Troubleshooting Cron and Schedulers article. Sugar instances hosted on Sugar's cloud service have the cron scheduler set up automatically, but it must be configured for On-Site Sugar instances. For more information on schedulers, please refer to the Schedulers section of the Sugar Knowledge Base.

Email Settings Configuration

In order to send email alerts from your Sugar instance, you must have the system's main email settings configured. Use the following steps to verify the main email settings for your instance:

1. Navigate to Admin > Email Settings.  
2. If the outgoing mail has not yet been configured, select one of the default SMTP email providers or fill in the SMTP fields according to your organization's provider.
3. Once the fields have been completed, click "Send Test Email" to confirm that the settings are correct. 
   

If the settings are correct, the specified email address will receive an email confirmation. For more information on setting up your system email settings, please refer to the Testing Outbound Email Using Sugar article. 

Summary

Once the administrator has correctly checked and validated all of the areas discussed in this article, email alerts should send successfully. However, if the email alerts still do not send as expected, please file a case with SugarCRM Support for further assistance.