Workflow Notification Email Troubleshooting

Hello GP Community!

We wanted to setup this article to compile solutions to common problems relating to email notification issues being seen with the new Workflow functionality in Microsoft Dynamics GP.

This blog will mostly cover Workflow email notification topics and issues but may include some other Workflow topics also.

I. Test Emails

The first question when troubleshooting any type of Workflow email notifications not being sent/received issue, is to determine whether or not the test emails from the Workflow Setup window (Administration > Setup > System > Workflow Setup) are able to be sent and received.

 This will help to determine if the issue is Dynamics GP system related (SQL stored procedure/CLR assemblies, message template, Active Directory query related) or SMTP related.

 From the Workflow Setup window, click on the Test E-Mail menu button which will open an email box which has a subject line and body that you can manually enter an email address to send the test email to. The recommendation is to send the test email to yourself or to an email address you’ve verified is working and receiving email.

--If the test emails are being received, but workflow approvers, alternate final approvers, workflow submitters and/or workflow managers are not receiving the email notifications they should be receiving, then skip to Section III below.

--If the test emails are not being received, then continue with the following troubleshooting items under Section II below.

II. SMTP Server Connectivity Related Issues

This section covers troubleshooting SMTP server connectivity relates issues, starting with steps that can be performed quickly.
If you are not receiving the test email when using the Test E-mail button in the Workflow Setup window, this is a good place to start.

• Password Length
  The Workflow Setup window’s email password fields, all the way to Microsoft Dynamics GP/18.2.xxxx, have a 15-character limit. Confirm that the SMTP email password length being used is 15 characters or less and if necessary shorten the length of the password to meet the 15 character constraint.

• SMTP Authentication Type
  Make sure the correct SMTP authentication is selected in Workflow Setup.
  
  In most cases, This should be set to Basic Authentication which will allow you to enter a dedicated user credential used to authenticate against the SMTP server. Verify that this email account and password exists and is valid on your environment.

• Multi-Factor Authentication (MFA)
• Workflow email functionality is not designed to handle multi-factor or dual authentication when sending emails out. Usually we would require the usage of App Passwords, but the password field in the Workflow Setup window only allows 15 characters and most App Passwords are 16 characters or longer, thus they won't fit, and won't authenticate, so the email will fail to send out.

• Server Name
  Confirm that the server name entered in the Workflow Setup window is the correct SMTP server name and its IP address is resolvable.

For example, an O365 SMTP server name is usually smtp.office365.com, while an Outlook.com server name is usually smtp-mail.outlook.com

A good test for this is to attempt to ping the SMTP server name, allowing us to check the IP address resolution and basic connectivity:

**Note: The ping test should be performed on the SQL server hosting the Dynamics GP data.

1. Press the key combination ?Win  +  R  to open the Run 
2. Type in cmd into the Open text box and press OK. This will open a new command prompt window.

3. Type in ping -4 <server name> and press the Enter 

This is an example of a ping performed on a server call smtp-mail.outlook.com.

     As you can see the server name resolves to the IP address 52.96.79.162 and also received four reply to the ping. This is a good indication of a valid server name and that it is reachable from the current server/workstation.

     In contrary, below is the result when an invalid/unresolvable address is entered. This would indicate that the server name entered is either invalid or an issue with your environment's network name resolution (DNS server related issue).

     If you receive a result such as the one below, indicating a 100% loss of packet (highlighted in green). It typically indicates no issue with the server name (since it still resolves the IP address) but it indicates a connectivity issue possibly relating to firewall.

• Port Number – Both O365 and Outlook.com use port 587 by default, but the SMTP server you’re using may be different, so verify this.

• SSL/TLS Encryption
  This server requires a secure connection (SSL) should be checked if the SMTP server supports/requires SSL/TLS encryption.
  
  Typically, servers that utilize port 587 require SSL/TLS encryption, however this is not always the case. There are servers that do support SSL/TLS encryption on port 25 and servers that allows non SSL/TLS encrypted connection on port 587.
  
  For example, Microsoft's Office 365 SMTP server supports (and highly advises) enabling SSL/TLS encryption regardless if using port 25 or 587.

• Server Connectivity/Firewall
  Dynamics GP utilizes stored procedures and CLR assemblies on the SQL server to transmit workflow notification emails to the SMTP server. This means all SMTP traffic is originating from the SQL server instead of the workstation/server the Dynamics GP client is installed and running from.
  
  If the ping test indicates that the server name's IP address is being resolved correctly but is losing 100% of the packets, there is a good chance that either the firewall on the SQL server or something on the environment is block SMTP traffic.
  
  The quickest way to check if the issue is due to the windows firewall (or in some case antivirus software) is to disable windows firewall and any antivirus software on the SQL server.
  Keep in mind that disabling the window firewall is a temporary solution, and should be re-enable with the proper exception on production environments.

• SMTP Email Address’ Sent folder

Another test is to verify whether Microsoft Dynamics GP is sending out the workflow emails or not, is to look in the ‘Sent’ folder of the email address specified in the Workflow Setup window’s SMTP configuration.

If the workflow emails are not showing in the Sent folder, then it may be an issue of the emails not being sent out from Dynamics GP and that needs to be addressed.

If the workflow emails are showing in the Sent folder, but the workflow users are not receiving them, then you would need to look at what may be keeping the emails from receiving those domain users.

**NOTE: It’s not uncommon for SMTP/Workflow emails to end up in a user’s Junk or Spam folder, so be sure to verify the emails aren’t showing there and the user just not realizing it.

• EXEC wfDeployClrAssemblies

Run this script against the DYNAMICS/system database for Microsoft Dynamics GP, as it will drop and re-create the assemblies, functions, and stored procedures used by Workflow, including the SendWorkflowAssignmentEmail, SendWorkflowCompletionEmail and TestEmail stored procedures.

• O365/Exchange Online accounts used for SMTP

If using an O365 email account credentials to send emails out from, via the Workflow Setup window, there are a couple of requirements that must be met:

--‘Basic’ Authentication must be enabled on the O365 account/Exchange Online environment along with the default ‘Modern’ authentication.

--Multi-Factor Authentication (MFA) – The Workflow Setup window isn’t setup to work with MFA nor the App Passwords that are used as an alternative when MFA is enabled.

    A reason for this is that the Password fields in the Workflow Setup window only allow 15 characters, and App Passwords are normally more than 16 characters.

    Workflow also doesn’t know how to handle the second level of authentication that MFA uses, whether it be entering a code sent to your cell phone or something else.

    ***NOTE: This issue with having Multi-Factor Authentication (MFA) enabled is true also for non-O365 email accounts used for the SMTP configuration in Workflow Setup to send emails through.

• Outlook.com test account

We’ve found that testing the Workflow Setup / Test Email with a non-O365 Outlookcom account that you create anew, or have already is a good test, especially when ruling out an O365 account from being the cause of test emails not working.

     1. Create an Outlook.com email account at Outlook.com by signing up and creating the new email address

     2. Login to this new email address account, otherwise you won’t be able to send emails through it.

     3. Use the SMTP information for this new Outlook.com account in the Workflow Setup window, such as this example that has worked:

          --E-Mail Address: WorkflowEmailTest@Outlook.com

          --Display Name: Test Workflow

          --Server: smtp-mail.outlook.com

          --Port: 587

          --Mark the option of ‘This server requires a secure connection (SSL)’.

      4. Under the ‘SMTP Authentication’ section of the Workflow Setup window, mark the ‘Basic Authentication’ option, and then enter the required information:

         --E-Mail Address: WorkflowEmailTest@Outlook.com

        --Password: (enter the password for this new Outlook.com email address)

        --Confirm Password: (re-enter the password for this new Outlook.com email address)

      5. Click OK to save changes and then re-open the Workflow Setup window and click the ‘Test E-Mail’ button to attempt to send a test email to yourself at your own email address, to confirm whether or not you receive the notification.

• TLS 1.0 Protocol

The TLS 1.0 Protocol must be enabled both on the SQL Server that is holding the databases for Microsoft Dynamics GP as well as the SMTP server specified for use in the Workflow Setup window to send Workflow test and regular email notifications through.

 III. Email Message Related Issues

This section covers troubleshooting email recipient related issues, starting with steps that can be performed quickly.

If you are receiving the test email when using the Test E-mail button in the Workflow Setup window but are not receiving the notification emails from Workflow, this is a good place to start.

• Recipient Email Address
  The recipient email address is retrieved from the user's Active Directory profile. In most environments that have Microsoft Exchange integration, the email address value for a user is populated automatically.

However, in some cases the email address property for a user may not be populated.

You will need access to the Domain Controller or a workstation with the Active Directory Users and Computers management tool.

To check for the recipient email address, follow the step below:

1. Open Active Directory Users and Computer.
2. Navigate through the organizational unit (OUs) and find the recipient user. Right-click the user and select 
3. The user property should open with the General tab selected. The E-mail property is located towards the bottom of the window.
   Make sure that the value in the E-mail field has the correct email address.

• Email Message Type

In some cases, the email message type for the message template utilized for generating workflow notification email is set to the wrong value on the SY04901 table. To check current values in the SY04901 table, run the following query against the GP company database(s).

           SELECT Email_Message_Type, * FROM SY04901

In most cases all canned message templates should have an email message type of 2, except for WF ACTION COMPLETE* which should have an email message type of 3.

• SQL Server service account

The new Workflow feature uses the SQL Server service account, of the SQL Server instance the Microsoft Dynamics GP databases are held on, to query Active Directory to validate all domain users entered into the Workflow Maintenance window as an approver, alternate final approver, workflow manager, workflow submitter/originator, etc.

 This is also how Workflow determines the email address to send the email notifications to for these Workflow users, as mentioned above under ‘Recipient Email Address’.

 If you find that a workflow approver or user is not receiving the email notifications they should be receiving, it may be a case where the SQL Server account isn’t able to query and validate the domain user account in Active Directory or the user doesn’t have a valid email address specified in their AD user properties, if at all.

**NOTE: If approvers are having workflows assigned to them for approval, that would prove that their AD account can be validated by the SQL service account, but maybe a valid email address isn’t specified in that user’s AD properties.

• Spam Filtering
  Check for any spam filter at the email client, server and network firewall level.

• EXEC wfDeployClrAssemblies

Run this script against the DYNAMICS/system database for Microsoft Dynamics GP, as it will drop and re-create the assemblies, functions, and stored procedures used by Workflow, including the SendWorkflowAssignmentEmail, SendWorkflowCompletionEmail and TestEmail stored procedures.

• Workflow Maintenance

On the Workflow approval steps, make sure the ‘Send Message’ option is marked to have an email sent out to the approver(s) when a workflow requires approval based on that step’s conditions.

As well, verify the Message ID that is specified as the email template to be sent out to approvers on that Workflow step, is valid. If a custom Message ID, try the default Message ID for that specific Workflow type and see if that makes any difference.

• Workflow Assignment

Verify the Workflow document or task is assigned to the approver(s) expecting to receive an email notification stating the assignment. Look at the Workflow history, approval steps and conditions and even WFI tables to verify what approver(s) the Workflow document or task is being assigned to for approval, if approval is needed.

• Microsoft Dynamics GP code/files

Along with stored procedures and other objects in the databases for Dynamics GP, email functionality is also using DLL and other files within the Microsoft Dynamics GP installation directory.

Verify whether or not the Workflow email notifications are not reaching the approvers and/or other Workflow users, from more than one Microsoft Dynamics GP instance if not different machines, to rule that out.

• TLS 1.0 Protocol

The TLS 1.0 Protocol must be enabled both on the SQL Server that is holding the databases for Microsoft Dynamics GP as well as the SMTP server specified for use in the Workflow Setup window to send Workflow test and regular email notifications through.

 IV. NetMon/WireShark Logging Steps

     ***NOTE: Run this logging from the SQL Server that holds the databases for Microsoft Dynamics GP***

 1. If you need to download Network Monitor 3.4, you can do so from this site::

                     https://www.microsoft.com/en-US/download/details.aspx?id=4865

 2. Launch Netmon in an elevated status by choosing ‘Run As Administrator’

 3. NetMon opens with all network adapters displayed. Select the network adapters where you want to capture traffic, click 'New Capture' and then click 'Start'.

 4. Reproduce the issue with theWorkflow test email failing, and you'll see the NetMon grab the packets on the wire.

 5. Select 'Stop' and go to File > Save As to save the results, which by default is a .cap file.

 ***NOTE: You can also use WireShark to capture a log of the Workflow emails not working as this application is similar to NetMon.

 V. Workflow Logging

 If there is an error or issue within the Workflow Engine itself for Microsoft Dynamics GP, one or both of the following logs will be generated, which may help in troubleshooting why email functionality for Workflow is not working:

 > DynamicsGP_WorkflowGP.log > This log is created on the local workstation or server that Microsoft Dynamics GP is installed onto, under the Windows account path of the user logged in, i.e. C:\Users\<UserID>\AppData\Local\Temp\

 > DynamicsGP_WorkflowGP.WorkflowEngine.log  > This log is created on the SQL Server, where the databases for Microsoft Dynamics GP are held, under the path for the domain account running the SQL Server service, i.e. C:\Users\MSSQLSERVER\AppData\Local\Temp\

**NOTE: The Event Viewer logs on both the Microsoft Dynamics GP and SQL Server machines may also hold error/warning information that can help troubleshoot why email functionality is not working in Microsoft Dynamics GP/Workflow, so look at them if experiencing these type of issues.

VI. Miscellaneous Issues

This section covers all other troubleshooting steps.

• Workflow Condition
  If the test email is working correctly and still notification email is not being sent correctly after all troubleshooting, another possible cause may be the workflow condition itself. Specially the table joins in the workflow condition.
  
  Even if the workflow step has not condition the table joins would still affect the notification email, since it is used to fill in the email templates.
  1. Open DEX.INI and add the following line (If the line already exists, make sure to change the value to TRUE).
     
     QueryDesignerAllFunctionality=TRUE
  2. Open the Dynamics GP client and navigate to the Workflow Management window.
  3. Navigate to the workflow step in question. If the step is set to Action is always required for this step, change it to Action is required only when the following condition is met temporarily to get access to the Workflow Condition Editor 
  4. Open the Workflow Condition Editor window and click the Run Query 
     
     This will run the query executed by workflow; since the window limits the number or results returned in this window, copy the query from the T-SQL field and execute it from SQL Server Management Studio for the full result.
     
     If the result returned does not include the workflow item submitted, it indicated and issue with the workflow condition/table joins.

Hopefully this blog will help with your Workflow Email troubleshooting in Microsoft Dynamics GP, regardless of what is being seen. At the least, we wanted to put all of the information out here so that you have the basic troubleshooting that we would provide and then if you exhaust all of this information, at least we've gotten through the basic setup so should know what the potential cause of the issue is, then can proceed with that.

Thank you!