Troubleshooting Issues with the TeamDynamix Email Service

Summary

This article is intended to help troubleshoot issues with the TeamDynamix Email Service.

Troubleshooting Resources

In the TDAdmin application there are two types of monitors:

1. The Email Replies monitor. This monitor scans for reply tokens and creates comments on work items. The logs for this monitor are found under TDAdmin > Email > Email Replies > Logs
2. The ticket creating Email Monitor. This monitor scans the desired inbox and creates tickets based on a customizable set of rules. You can have as many of these monitors as you would like and they are configurable within each ticketing application. You can access the logs for these monitors under Ticketing Applications > Select Application > Email Monitors > Select Monitor > Logs

Troubleshooting Tips for Email Settings

These tips apply to the Details tab of an inbox configuration.

1. Review the logs of the email monitor and see if there are any errors
   • Check the Logs tab for the most recent log items. If your monitor was disabled look at the messages that precede the disable log entry to see what exactly went wrong. 
   • Invalid logins will be logged in the logs tab.
   • Valid logins will not be logged in this tab because it would clutter up quickly.
   • If you see no invalid logins after receiving errors, there is most likely an issue connecting to TeamDynamix
2. Ensure that the Client Secret in your mail system is still valid and has not expired
3. Press the Save button on the email monitors configuration page to see if any additional errors arise

Common Error List

1. Profile Could Not Be Activated: Could not connect to server. Please check to make sure the credentials, server name, and port are correct
2. Invalid TD user login credentials. Please verify that the username and password are correct and that the user has access to TDNext
3. Could not find or access folder
4. Email Monitor does not have any rules defined
    

Could not connect to server

This error is most likely going to be due to the token generation on the email authentication account. To resolve this, you'll need to do the following:

1. Sign in to TDAdmin
2. Locate the auth accounts page for the account in question
3. Click to Edit the Oauth auth account in question
4. Before progressing, go to O365.com or gmail.com (depending on the OAuth account type)
5. sign in then sign out of O365/Gmail, then you can close the tab when complete
6. Click the generate token button in the TDadmin tab. When you click the generate tokens button, a login window should populate where you should be signing in with the actual mailbox that is being monitored.
7. Sign in to the O365/Gmail page with the credentials of that mailbox and accept the prompted permissions
8. Save the auth account's page
9. Ensure the monitor is set to use the desired Oauth 2.0 account, enable the monitor, and save

If at any point during this process you receive a warning similar to that shown below, the client secret in your mail system has expired and a new one needs to be generated. 

{
  "error": "invalid_client",
  "error_description": "12345: The provided client secret keys for app 'ID' are expired,
  "error_codes": [
    Error code
  ],
  "timestamp": "Time Here",
  "trace_id": "ID here",
  "correlation_id": "ID Here",
  "error_uri": "URL Here"
}

At this point, you would need to log into your Azure/G Cloud system, generate a new secret for your TDX app, and update all email authentication accounts to use the new secret.

Invalid TDUser Credentials 

This error indicates that the TD Username credentials listed on the email monitor are incorrect. To resolve this, please follow the steps below:

1. Sign in to TDAdmin
2. Locate the Email Monitor in question
3. Take note of which account is being used in the TD Username field
4. Go to TDAdmin > Users & Roles > Users > Select the TD Username in question
5. Be sure that the account is not locked and if it is, unlock the account
6. On the Authentication tab of the user record, ensure that the "This person is exempt from password expiration" setting is enabled if desired
7. To reset the password, go to the general tab of the user record and click Actions > Reset Password
   • If the password to this account is reset, you will need to update the TD User on all email monitors that use this account
8. Go back to the email monitor in question and use the "Click to update existing password" link to insert the new TD Username credentials
9. Enable the monitor, and save
    

Could not find or access folder

This error indicates that either the Monitored, Processed, or Unsuccessful folder names are incorrect. Please log into the mailbox in question and ensure that the folder names match what is listed in TDX.  
 

Email Monitor does not have any rules defined

1. Sign in to TDAdmin
2. Go to Applications > Ticket App > Email > Email Monitor > Select Monitor > Rules tab
3. Ensure that there is at least one active email monitor rule

These tips apply to the Rules tab of a ticket creating Email Monitor:

1. Ensure that the rules under the Rules tab are ordered in the desired hierarchy. Tickets are created based on the first rule an email matches.
2. Ensure that there is a rule for all cases. You might consider having a blank rule subject as the last rule to catch any messages that do not match any rules. Any emails that do not match any rules will be moved out of the processed folder.
3. Ensure you only have one ticket monitor monitoring a single folder in an inbox. If two monitors are monitoring the same folder in the same inbox this will lead to a race condition between the monitors and a ticket will be created by the monitor that gets to it first.