Incoming Email Processing Last updated on Monday, July 08, 2013 Copyright 2001-2013 Autotask. All Rights Reserved. Trademark Information All Autotask products are trademarks or registered trademarks of Autotask. All other brand and product names mentioned herein are trademarks or registered trademarks of their respective holders.
Table of Contents Incoming Email Processing 3 Entity Creation Rules 7 Configuring a Custom Mailbox 11 Tracking Your Work Using Email Indicators 16 Add Ticket Email Service (ATES) 17 Configuring the ATES Mailbox 19 Setting Up the Third Party Application Add Ticket Email Message 21 Formatting the Third Party Application Message Template 22 XML Token Message Sample 25 Creating a Contact in Autotask from Incoming Ticket Information 26 Add Ticket Email Service Processing Rules 28 Using Attachments with the Add Ticket Email Service 30 Using the Add Ticket Email Service API with Remote Monitoring Applications 31 Using Add Ticket Email Service with Managed Services Extensions 32 Index 35 Page 2 of 35
Incoming Email Processing Incoming Email Processing Incoming Email Processing converts emails to Autotask entities. The Subject line is converted into the entity title, and the email body is converted into the Description. Depending on information contained in the Subject line and the first line of the email Body, emails are converted to tickets, ticket notes, ticket time entries, project notes, task notes or task time entries. Refer to "How Autotask Processes Emails" on page 3 on how we determine what entity will be created from a given email. The sender's (originator's) email address determines which account and contact to attribute the item to, or which resource to attribute the item to. For detailed information on how the right account and contact are identified and how we prevent infinite loops, refer to "Entity Creation Rules" on page 7. Incoming Email Processing allows you to set up a "closed loop" of communications between your customer and resources (such as technicians) at your company. If all participants use "Reply" or "Forward", all communications are automatically carbon-copied to the customer ticket, project or task in Autotask. With this tool, tracking labor in Autotask can now be accomplished from a technician's mail client on a smart phone. Autotask customers no longer need an external email parser, although we continue to support a number of partner integrations (refer to Autotask Integrations and Extensions). Licensing Basic Incoming Email Processing is available to all Autotask customers at no additional cost. Basic Incoming Email Processing includes: The Add Ticket Email Service (ATES) mailbox, which is already set up An option to configure one additional custom mailbox for creating tickets only Incoming emails will be converted to tickets only; creation of Ticket Notes, Ticket Time Entries, Project Notes, Task Notes, and Task Time Entries is not available Advanced Incoming Email Processing includes: The Add Ticket Email Service (ATES) mailbox, which is already set up An option to configure six additional custom mailboxes Emails can be converted to Tickets, Ticket Notes, Ticket Time Entries, Project Notes, Task Notes, and Task Time Entries NOT E : To lice nse Adva nce d Incoming Ema il Proce ssing, cont a ct your Aut ot a sk sa le s re pre se nt a t ive. How Autotask Processes Emails Autotask uses information from the incoming email to determine where the email should go in the system. This Page 3 of 35
Incoming Email Processing information includes: The email Subject line: Autotask checks for a matching ticket, project, or task number. The first line of the email Body text: Autotask checks for indicators (for more information, refer to "Tracking Your Work Using Email Indicators" on page 16)....then Autotask will generate a: Email Subject line contains... Ticket Ticket Note Ticket Time Entry* Project Note Task Note Task Time Entry* Status Update * Role Update * No valid ticket, project, or task number Valid ticket number, no time entry indicator Valid ticket number and time entry indicator (#T=) Valid ticket number and status indicator (#S=) Valid ticket number and role indicator (#R=) Valid project number Valid task number, no time entry indicator Valid task number and time entry indicator (#T=) Valid task number and status indicator (#S=) Valid task number and role indicator (#R=) * Ticke t Time Ent ry, Ta sk Time Ent ry, St a t us Upda t e, a nd R ole Upda t e a re a pplica ble only t o t hose wit h a n Aut ot a sk 'Use r' lice nse. Overview of the Closed Loop Communication Flow After the configuration steps have been completed, the following email-into-autotask process will occur. Page 4 of 35
Incoming Email Processing Customer sends an email to the support address that you had supplied to them. For example, you have configured a Gmail account as 'support@abcservices.com' and given this to your customers as your 'support' address. The email arrives at the external mail server (for example, Gmail) which has been configured to automatically redirect (not forward!! Refer to this Microsoft article) emails to the email-processing mailbox you have specified in the Mailbox Email field in Autotask (as described in "Configuring a Custom Mailbox" on page 11). The email arrives in your email-processing mailbox and is parsed. (When you configure the email-processing mailbox, you should also configure the success and failure notifications for the email originator using an Incoming Email Notification template, as described in Managing Notification Templates.) If the email originator's email address matches an account contact or domain (refer to NOTE below) in your Autotask database, an Autotask ticket or note is created (as described in the Example below). If the email originator's email address is not in your Autotask database, but the domain (refer to NOTE below) of the email address matches either that of an existing contact or an account's Web field, the email originator will be added as a contact to that account. NOTE: "Domain" refers to the company's web address: If neither the email address nor domain of the email originator matches account information in Autotask, a Failure Notification will be sent to the email originator and any failure-notification recipients you have configured. NOTE: This will create a ticket under your company's Autotask account (account 0) and can be managed by your resources. For a more detailed look at Autotask actions, refer to the table in "How Autotask Processes Emails" on page 3, above. EXAMPLE: A ticket is created from the information in the email. The email Subject (for example, Desktop Issues) becomes the Ticket Title. The email Body text (for example, "After I updated my browser, my computer froze.") becomes the Ticket Description. A Success Notification email with the ticket number of the newly created ticket in the Subject line is automatically sent to the email originator using a pre-configured notification template. Optionally, Autotask (primary and/or secondary) resources can also be configured for notification in the notification template or a workflow rule. IMPORTANT: If the ticket sender is notified in this way, all subsequent communications on this topic will reference the ticket number. If Autotask workflow rules have been set up to assign that ticket to an Autotask resource, the email notification to that resource will also contain the ticket number in the Subject line. All subsequent communications between the resource and the customer will contain the ticket number and be added to the ticket as a note. When the customer replies to this email notification, the Ticket Number appears in the Subject line of the reply. Based on the email-processing rules, an email that includes a Ticket Number becomes a Ticket Note on the ticket with that number. In this way, the entire email conversation is tracked in Autotask. Page 5 of 35
Incoming Email Processing Optionally, if this process has been followed, the Autotask technician can via this same email thread: create Time Entries; update the Ticket Status; change the Role for the Time Entry; and close the Ticket. For more information on how the technician can do this, refer to "Tracking Your Work Using Email Indicators" on page 16. What about Add Ticket Email Service? Autotask continues to support the Add Ticket Email Service (ATES) for legacy users or those with special circumstances, such as remote-monitoring applications. ATES users should see "Add Ticket Email Service (ATES)" on page 17 and "Configuring the ATES Mailbox" on page 19. Configuration Overview The closed-loop email process requires you to: Configure your Autotask mailbox (refer to "Configuring a Custom Mailbox" on page 11) Establish your Workflow Rules (refer to Setting Workflow Rules and Notifications) Configure your Notification Templates (refer to Managing Notification Templates) Optionally, if you do not want to publish the Autotask Incoming Email mailbox as your support mailbox, we recommend that you: Set up your support mailbox to automatically redirect (not forward!! Refer to this Microsoft article) emails customer incoming messages to your Autotask incoming-email mailbox. Page 6 of 35
Entity Creation Rules Entity Creation Rules Account and Contact Association When an Autotask entity is created from an incoming email, we attempt to attribute the message to either a resource in your Autotask database, or a customer contact. The sender's (originator's) email address determines which account and contact to attribute the item to, or which resource to attribute the item to, according to the following rules: Page 7 of 35
Entity Creation Rules 1. We will search resources first. a. If we find one active matching resource, the item is attributed that resource. b. If more than one matching active resource is found, we will attribute the item to the first matching resource (this is a very unlikely case because it would mean that multiple resources in your database have the same email address). 2. If no resource match is found, we will search for a contact match. a. If we find a single matching active account that has a contact with the same domain as the originator's email address, but do not find a matching active contact, we will create a contact for that account. The contact will have the originator's email and "<unknown>" as their first and last name. All other fields will be blank, except for UDFs that have a default value. b. If we find multiple matching active accounts with the same domain as the originator's email address, but do not find a matching active contact, creation will fail (failure email will be sent). 3. If we cannot determine the account based on contact email addresses, or if multiple account matches are found, we will look next to the account's Web site field and attempt to find a match. a. If we find multiple matching active contacts, creation will fail, and a failure notification email will be sent. b. If we cannot find a matching active account or active contact, creation will fail and a failure notification email will be sent. c. Exception: for tickets, the ticket will get created for your Internal Account, with no contact. NOT E : The Account Type a nd 'Act ive ' st a t us of your Int e rna l Account do not a ffe ct Incoming Ema il Proce ssing t icke t cre a t ion rule s. 4. The contact must belong to the account the parent entity is associated with (in other words, John Smith at XYZ Company could not create a ticket note on a ticket associated with ABC Corporation). If the creation fails because this restriction is violated, a failure email will be sent. 5. Contact, Account, Resource must be active, or creation will fail. 6. Your database must be active and not in maintenance mode, or creation will fail. 7. For Kaseya tickets, we will determine the account using the string after the first period in the "machine.groupname.subgroupname". Kaseya tickets will not have a contact. They will have a creator of "Admin Autotask". Email Truncation To prevent the addition of a lot of repetitive information to Autotask, emails are truncated as follows: Page 8 of 35
Entity Creation Rules 1. Anything including and after the first character of the "[*** Please enter replies above this line ***]" string will be stripped. 2. We will remove any line that starts with: a. "From:" b. "To:" c. "CC:" d. "BCC:" e. "Subject:" f. Starts with "On" and ends with "wrote:" (this how Gmail presents headers) Message Count Limitation To ensure an acceptable response time for all users, Autotask has set an hourly limit on the number of incoming messages per customer. This limit is 1,000 messages per hour, but can be configured to a lower number for testing purposes. Once the threshold is reached, the 1,001st message will be bounced back to the originator with an appropriate message. Infinite Loop Prevention It is possible that Incoming Email Processing could result in an endless loop when auto-reply is turned on. To prevent that, we will not process (throw out) emails that contain the following strings in the Subject line: auto reply autoreply auto-reply automatic response automated response auto-response auto response out of office out-of-office maternity leave family leave T IP: You ma y wa nt t o configure your compa ny support ma ilbox so t ha t such e ma ils a re not re dire ct e d t o t he Aut ot a sk ma ilbox. Page 9 of 35
Entity Creation Rules Additionally, we will throw out any emails that have the same sender and subject, and at least three emails were received in the last 5 minutes. The first two emails will be processed. This applies to ticket, ticket note, project note, and task note. Ticket time entry and task time emails will never be thrown away. Page 10 of 35
Configuring a Custom Mailbox Configuring a Custom Mailbox IM PORT ANT : To e nsure prope r se t up of Incoming Ema il Proce ssing, you must log in using t he primar y domain for your Aut ot a sk da t a ba se. If you a re unsure of your Aut ot a sk da t a ba se primar y domain, cont a ct Aut ot a sk Cust ome r Support. To configure a mailbox for incoming email processing: 1. Go to Admin > AutotaskExtend > Tools > Incoming Email Processing. 2. Click New. 3. Complete the General tab. General tab Mailbox Name Active Mailbox Email Description The mailbox name that appears on the list of mailboxes on the Incoming Email Processing - Mailboxes page. Checked if Incoming Email Processing is enabled. The recipient email address for any emails that Autotask should convert to Autotask entities (tickets, task notes, etc.). NOTE: Autotask recommends that you give to your customer a 'friendly' email address (support@yourcompany.com) and configure your email server to redirect (not forward!! Refer to this Microsoft article) emails from that address to the Mailbox Email address. Attachments checkbox Kaseya Alert Handling checkbox (available only if Kaseya Extension is turned on) Select to have Autotask create attachments attached to the parent ticket, project, or task from images in the email body. Select to automatically create a ticket for the associated Autotask configuration item. To ensure this functionality, the email must contain a string formatted as "machinename.groupname.subgroupname". NOTE: Autotask recommends that you dedicate an email-processing mailbox to Kaseya, and not use that mailbox for any other purpose. 4. Click the Ticket tab. Populate the following fields to create Autotask tickets from emails without a valid ticket, project, or task number in the Subject line: Ticket tab Enabled checkbox Description Check to enable creation of tickets from emails sent to this mailbox. The Status, Priority, Queue, Source, and Due Date Offset fields become required and must be completed. NOTE: If you want the Incoming Email Processing service to create ticket notes, check Enable on the Ticket Note tab and configure the appropriate settings. Defaults Select the default values for tickets created by the service. Several fields are required. For more information on populating Ticket fields, refer to Creating Tickets and Configure service desk ticket due date and due time defaults. Page 11 of 35
Configuring a Custom Mailbox Failure and Success Notifications To kick off closed-loop email processing, email notifications can be sent to the email originator, internal resources, and other email recipients. IM PORT ANT NOT E : The t icke t, proje ct, or t a sk numbe r t ha t is in t he Subje ct line is crucia l t o e ma il-proce ssing communica t ions. Use F a ilure a nd Succe ss Not ifica t ions a nd one of t he not ifica t ion t e mpla t e s spe cifica lly de signe d for Incoming Ema il Proce ssing t o e nsure t ha t t his numbe r re ma ins pre se nt. Notification Template Pre-configured default Notification Templates specific to Incoming Email Processing are available from the Notification Template drop-down. Click the Edit (pencil) icon to edit a template. Click + to create your own template. You can edit them and add your own. Refer to Creating Notification Templates. NOTE: If a template is not selected, an email will not be sent to the email originator. NOT E : All cust ome rs ha ve a cce ss t o t he Ge ne ra l a nd Ticke t t a bs a nd ca n se t up one cust om ma ilbox in a ddit ion t o t he ATES ma ilbox. If you ha ve upgra de d t he e ma il-proce ssing se rvice, t he following t a bs will be a ct ive a nd you ca n conve rt e ma ils int o a ddit iona l Aut ot a sk e nt it ie s. 5. Click the Ticket Note tab. Populate the following fields to create Autotask tickets from emails with a valid ticket number in the Subject line: Ticket Note tab Enabled checkbox Defaults Failure and Success Notifications Description Check to enable creation of ticket notes from emails sent to this mailbox. Select the default values for ticket notes created by the service. The Note Type Defaults to Task Summary. You can select a different Note Type from the drop-down list. For more information on Note Types, refer to Adding System Note Types. If you select All Autotask Users in the Publish field, the note can be viewed by customer contacts you have given a Client Access Portal account and by Outsource module partners. Internal Users Only means the note can only be viewed by users in your Autotask database. If you select a Status, the ticket status is updated. To kick off closed-loop email processing, email notifications can be sent to the email originator, internal resources, and other email recipients. IM PORT ANT NOT E : The t icke t, proje ct, or t a sk numbe r t ha t is in t he Subje ct line is crucia l t o e ma il-proce ssing communica t ions. Use F a ilure a nd Succe ss Not ifica t ions a nd one of t he not ifica t ion t e mpla t e s spe cifica lly de signe d for Incoming Ema il Proce ssing t o e nsure t ha t t his numbe r re ma ins pre se nt. Notification Template Pre-configured default Notification Templates specific to Incoming Email Processing are available from the Notification Template drop-down. Click the Edit (pencil) icon to edit a template. Click + to create your own template. You can edit them and add your own. Refer to Creating Notification Templates. NOTE: If a template is not selected, an email will not be sent to the email originator. Page 12 of 35
Configuring a Custom Mailbox 6. Click the Ticket Time Entry tab. Populate the following fields to create a time entry from emails with a valid ticket number in the Subject line and a Time Entry Indicator (#T=) in the first line of the email body: Ticket Time Entry tab Enabled checkbox Defaults Failure and Success Notifications Description Check to enable creation of ticket time entries from emails sent to this mailbox. Select the default values for ticket time entries created by the service. You can specify the Ticket Status and the Work Type for the time entry. To kick off closed-loop email processing, email notifications can be sent to the email originator, internal resources, and other email recipients. IM PORT ANT NOT E : The t icke t, proje ct, or t a sk numbe r t ha t is in t he Subje ct line is crucia l t o e ma il-proce ssing communica t ions. Use F a ilure a nd Succe ss Not ifica t ions a nd one of t he not ifica t ion t e mpla t e s spe cifica lly de signe d for Incoming Ema il Proce ssing t o e nsure t ha t t his numbe r re ma ins pre se nt. Notification Template Pre-configured default Notification Templates specific to Incoming Email Processing are available from the Notification Template drop-down. Click the Edit (pencil) icon to edit a template. Click + to create your own template. You can edit them and add your own. Refer to Creating Notification Templates. NOTE: If a template is not selected, an email will not be sent to the email originator. 7. Click the Project Note tab. Populate the following fields to create a project note from emails with a valid project number in the Subject line: Project Note tab Enabled checkbox Defaults Failure and Success Notifications Description Check to enable creation of project notes from emails sent to this mailbox. Select the default values for project notes created by the service. You can specify the Note Type and the Publish option for the note. To kick off closed-loop email processing, email notifications can be sent to the email originator, internal resources, and other email recipients. IM PORT ANT NOT E : The t icke t, proje ct, or t a sk numbe r t ha t is in t he Subje ct line is crucia l t o e ma il-proce ssing communica t ions. Use F a ilure a nd Succe ss Not ifica t ions a nd one of t he not ifica t ion t e mpla t e s spe cifica lly de signe d for Incoming Ema il Proce ssing t o e nsure t ha t t his numbe r re ma ins pre se nt. Page 13 of 35
Configuring a Custom Mailbox Notification Template Pre-configured default Notification Templates specific to Incoming Email Processing are available from the Notification Template drop-down. Click the Edit (pencil) icon to edit a template. Click + to create your own template. You can edit them and add your own. Refer to Creating Notification Templates. NOTE: If a template is not selected, an email will not be sent to the email originator. 8. Click the Task Note tab. Populate the following fields to create Autotask tasks from emails with a valid task number in the Subject line: Task Note tab Enabled checkbox Defaults Failure and Success Notifications Description Check to enable creation of task notes from emails sent to this mailbox. Select the default values for ticket notes created by the service. The Note Type Defaults to Task Summary. You can select a different Note Type from the drop-down list. For more information on Note Types, refer to Adding System Note Types. If you select All Autotask Users in the Publish field, the note can be viewed by customer contacts you have given a Client Access Portal account and by Outsource module partners. Internal Project Team means the note can only be viewed by users in your Autotask database. If you select a Status, the task status is updated. To kick off closed-loop email processing, email notifications can be sent to the email originator, internal resources, and other email recipients. IM PORT ANT NOT E : The t icke t, proje ct, or t a sk numbe r t ha t is in t he Subje ct line is crucia l t o e ma il-proce ssing communica t ions. Use F a ilure a nd Succe ss Not ifica t ions a nd one of t he not ifica t ion t e mpla t e s spe cifica lly de signe d for Incoming Ema il Proce ssing t o e nsure t ha t t his numbe r re ma ins pre se nt. Notification Template Pre-configured default Notification Templates specific to Incoming Email Processing are available from the Notification Template drop-down. Click the Edit (pencil) icon to edit a template. Click + to create your own template. You can edit them and add your own. Refer to Creating Notification Templates. NOTE: If a template is not selected, an email will not be sent to the email originator. 9. Click the Task Time Entry tab. Populate the following fields to create a time entry from emails with a valid task number in the Subject line and a Time Entry Indicator (#T=) in the first line of the email body: Task Time Entry tab Enabled checkbox Defaults Description Check to enable creation of task time entries from emails sent to this mailbox. Select the default values for task time entries created by the service. You can specify the Status and the Work Type for the time entry. Page 14 of 35
Configuring a Custom Mailbox Failure and Success Notifications To kick off closed-loop email processing, email notifications can be sent to the email originator, internal resources, and other email recipients. IM PORT ANT NOT E : The t icke t, proje ct, or t a sk numbe r t ha t is in t he Subje ct line is crucia l t o e ma il-proce ssing communica t ions. Use F a ilure a nd Succe ss Not ifica t ions a nd one of t he not ifica t ion t e mpla t e s spe cifica lly de signe d for Incoming Ema il Proce ssing t o e nsure t ha t t his numbe r re ma ins pre se nt. Notification Template Pre-configured default Notification Templates specific to Incoming Email Processing are available from the Notification Template drop-down. Click the Edit (pencil) icon to edit a template. Click + to create your own template. You can edit them and add your own. Refer to Creating Notification Templates. NOTE: If a template is not selected, an email will not be sent to the email originator. 10. Click Save & Close. Page 15 of 35
Tracking Your Work Using Email Indicators Tracking Your Work Using Email Indicators Your company's resources and technicians can use Email Indicators to track ticket time, change the role rate for the time entry, and update the ticket status. Include any of the following indicators in the first line of the email Body to tell Autotask what action to take. #T= tells Autotask to add the email text as a time entry rather than a note. #R= changes the role rate to the one specified after the indicator (for ticket and task time entries). #S= changes the status of the ticket or task to the one specified after the indicator. NOT E : Do not put a ny ot he r t e xt in t he first line of t he e ma il body. Addit iona l informa t ion must be e nt e re d on t he line be low t he e ma il indica t ors, a s shown t he e xa mple be low. Email Indicators Examples The email example below will create a 30-minute time entry (#T=.5) on the ticket using the after-hours role rate (#R=After Hours Support), and complete the ticket (#S=Complete). #T=.5 #S=Complete #R=After Hours Support The example below uses the same email indicators, but the technician includes information to indicate that a site visit is necessary to prevent the situation arising again. Note that this is entered on the line below the email indicators. #T=.5 #S=Complete #R=After Hours Support Customer appreciated quick, temporary resolution; ticket closed. Site visit necessary to avoid re-occurrence. Email Indicators Notes Review the following notes to ensure that your email indicators are valid. Email indicators must appear with no other data on the first line of the body of the email. Additional information must be entered on the line below the email indicators. Multiple email indicators must be separated by a space. If you are specifying a Status or Role, be sure that it exists in your Autotask database. For a list of valid Statuses: Admin > Site Setup > Statuses For a list of valid Roles: Admin > Site Setup > Company Setup > Roles tab Page 16 of 35
Add Ticket Email Service (ATES) Add Ticket Email Service (ATES) The Add Ticket Email Service (ATES) integrates between Autotask and applications that generate email alerts, but require a generic email address. The database that creates the tickets is determined by an Autotask site-specific Service Provider ID and Service Provider Password which are appended to each message as an XML token. NOT E : ATES support s t he UTF -8 cha ra ct e r se t. IM PORT ANT : Do NO T se nd your spa m not ifica t ions t o a ddt icke t @aut ot a sk.ne t. High volume s of spa m not i- fica t ions ca n a ffe ct syst e m pe rforma nce. Service Provider ID and Password The Service Provider ID and Service Provider Password are unique Autotask site-specific values that Autotask generates for each customer. To view your ID and password, go to Admin > AutotaskExtend > Tools > Incoming Email Processing > Add Ticket Email Service (ATES) > General. All emails delivered to ATES must provide these values. Getting Started with Add Ticket Email Service Before you can begin creating Autotask tickets from incoming emails, you must set up both Autotask and the third party application that will generate the emails. If you are using a remote monitoring application with a custom Autotask integration or an Autotask Managed Services Extension, additional steps are required. To begin using ATES, complete the following setup: Configure the ATES Mailbox An Autotask Administrator must specify default ticket settings, notifications, and duplicate ticket handling preferences for automatically created tickets. Refer to "Configuring the ATES Mailbox" on page 19. Set Up the Email Templates in the third party application The incoming email must include a valid Autotask XML token at the end of the email body, per the ATES API specifications. Refer to "Setting Up the Third Party Application Add Ticket Email Message" on page 21. Set Up Third Party Remote Monitoring Specifications (when applicable) Third party remote monitoring services that have partnered with Autotask to provide a custom integration with ATES may require additional tasks to complete the ATES setup. For example, tasks that must be completed within the monitoring service application. Where available, Autotask Help provides information to assist with this setup. Page 17 of 35
Add Ticket Email Service (ATES) To see if additional information is available from Autotask, locate your monitoring service application in the table in Autotask Integrations and Extensions. If the integration application is not listed, or there is no documentation link, you must contact your monitoring service provider vendor. Add Custom Elements to the XML Token for Use with a Managed Service Extension (when applicable) If you are using an Autotask Managed Service Extension, you can add custom elements to the XML token to populate the Managed Service Extension UDFs with data from the incoming emails. Refer to "Using Add Ticket Email Service with Managed Services Extensions" on page 32. Page 18 of 35
Configuring the ATES Mailbox Configuring the ATES Mailbox IM PORT ANT : To e nsure t ha t you a re using t he corre ct Se rvice Provide r ID, you must log in using t he primar y domain for your Aut ot a sk da t a ba se. If you a re unsure of your Aut ot a sk da t a ba se primar y domain, cont a ct Aut ot a sk Cust ome r Support. To configure the ATES mailbox, complete the following steps: 1. Go to Admin > AutotaskExtend > Tools > Incoming Email Processing. 2. Click the Editicon (a pencil) to the left of the Add Ticket Email Service (ATES) mailbox. The ATES mailbox will open. NOT E : O nly t he Ge ne ra l a nd Ticke t t a bs a re e na ble d. 3. Complete the General and Ticket tabs using the information in the following table. General tab Mailbox Name Active Service Provider ID Service Provider Password Attachments checkbox Ticket tab Enabled checkbox Ticket Defaults Failure and Success Notifications Description The mailbox name is read-only: Add Ticket Email Service (ATES) Checked if ATES is enabled Read-only. The database's domain. Supplied by Autotask when ATES is enabled. Select to have Autotask create attachments attached to the parent ticket, project, or task from images in the email body. Description Check to turn on email processing for tickets. Select the default values for tickets created by the ATES service. Several fields are required. For more information on Ticket fields, refer to Creating Tickets and Configure service desk ticket due date and due time defaults. To kick off closed loop email processing, email notifications can be sent to the email originator, internal resources, and other recipients. Optionally, Send XML Notifications lets you send an XML-based message for automated processing, in addition to the default human-readable notification. NOTE: If you select this option, both types of notifications will be sent. Notification Template Pre-configured default Notification Templates specific to Incoming Email Processing are available from the Notification Template drop-down. - Click the Edit (pencil) icon to edit a template. - Click + to create your own template. Refer to Creating Notification Templates. NOTE: If a template is not selected, no email will be sent to the email originator. Page 19 of 35
Configuring the ATES Mailbox 4. Click Save & Close. Page 20 of 35
Setting Up the Third Party Application Add Ticket Email Message Setting Up the Third Party Application Add Ticket Email Message To ensure reliable creation of Autotask Tickets, third-party applications must append a properly populated and formatted XML token to the end of the email body. The email message is created by the third-party application from templates within that application. The Add Ticket Email Service (ATES) API uses the information in the XML token, along with the service information contained in the email, to create a Service Desk Ticket. NOT E : To a ut oma t ica lly cre a t e Aut ot a sk t icke t s using ATES, t hird-pa rt y a pplica t ions must submit e ma ils t o addtic ket@ auto task.net. For guidelines on setting up email messages and creating a properly populated and formatted XML token, including guidelines for footer information required by some managed-services provider software, refer to "Formatting the Third Party Application Message Template " on page 22. To view a sample XML message token, refer to " XML Token Message Sample" on page 25. For information on using custom elements in the XML token to populate Managed Services Extension UDFs, refer to "Using Add Ticket Email Service with Managed Services Extensions" on page 32. For information on using the Contact Name element in an incoming message to create a contact in Autotask, refer to "Creating a Contact in Autotask from Incoming Ticket Information" on page 26. For a description of how ATES processes incoming ticket information to associate emails with Autotask accounts and/or contacts, refer to "Add Ticket Email Service Processing Rules" on page 28. For information on using attachments with ATES, refer to "Using Attachments with the Add Ticket Email Service" on page 30. Page 21 of 35
Formatting the Third Party Application Message Template Formatting the Third Party Application Message Template To ensure reliable creation of Autotask tickets when using Add Ticket Email Service (ATES), the XML token appended to incoming email messages must include certain information that will be used: for authentication; to retrieve Autotask account information; and optionally to determine sub-issue type and the existence of a duplicate ticket. You must be sure that the service that generates the alert emails provides the necessary information in one of the formats described below. NOT E : The informa t ion in t his t opic a ssume s a ba sic fa milia rit y wit h XML a nd wit h your t hird pa rt y a pplica t ion's me ssa ge t e mpla t e. To learn more about how ATES processes incoming messages, refer to "Add Ticket Email Service Processing Rules" on page 28. Formatting the XML Token and Email Message NOT E : Aut ot a sk re comme nds using t he pla in-t e xt forma t. All third-party applications must submit emails to addticket@autotask.net. ATES uses the email Subject as the title for the new Ticket in Autotask, and the email body above the XML token for the ticket description. Because Autotask tickets require a title, if the incoming email does not include a Subject, the ticket title will be "New Ticket - <Date/Time>". The XML token can be submitted as a continuous string at the end of the email body, or formatted so that each element has its own line, as shown in the Sample Message XML that appears in " XML Token Message Sample" on page 25. Outside of the actual data values, there should be no unnecessary white space. Option 1 for Appending the XML Token This option is supported if the monitoring application provides a free-form alert notification definition that the user defines and if the free-form area supports a mix of literals and variables: Paste the XML token into that free-form area Place the "Customer name" variable inside the "Customer name" attribute value NOT E : The va lue s in t he "Cust ome r na me " a t t ribut e must ma t ch a n Account Na me in Aut ot a sk. Option 2 for Appending the XML Token The monitoring application may provide specific options for integration with Autotask. These applications, like Level Platforms Managed Workplace, provide configuration options that simplify this integration effort. For additional information regarding third-party application settings, check the documentation links provided in the Page 22 of 35
Formatting the Third Party Application Message Template table in the introductory topic Integrating with Remote Monitoring Applications, or contact your third-party application provider. For additional information about ATES and Autotask Managed Services Extensions, refer to "Using Add Ticket Email Service with Managed Services Extensions" on page 32. If your third-party application generates an Autotask footer, refer to the guidelines in "Company Name and Sub-issue Values in the Autotask Footer" on page 24, below. List of XML Elements The following table lists the XML elements to include in the XML token. It indicates the element type and describes the element value. For information on positioning the XML, refer to "Formatting the XML Token and Email Message" on page 22, above. NOT E : Some e le me nt s a re a lwa ys re quire d, whe re a s ot he rs a re re quire d a s not e d. Element Name Required Element Type Value Autotask Yes Container No additional value is required. ID Yes Data (String) PW Yes Data (String) Service Provider ID: This fixed literal value is provided by Autotask. You can find it in the ATES setup window in the Admin module. Service Provider Password: This fixed literal value is provided by Autotask. You can find it in the ATES setup window in the Admin module. Customer Yes, if no Email value is provided* Data (String) Customer Name of Service Provider s Customer: This variable value is provided by the Service Provider. For proper Ticket creation, the value must map exactly to an Autotask Account Name. Email Yes, if no Customer value is provided* Data (String) Email Address of Service Provider s Customer: This variable value is provided by the Service Provider. For proper Ticket creation, the value must map exactly to an Autotask Contact Email Address or domain of the value must map exactly to the domain of an Account Web Address. Contact No, but recommended when using an Autotask workflow rule to notify contacts Data (String) When included, if no contact is associated with the matching Autotask account, the Service attempts to create a contact in Autotask using name information parsed from the incoming email From: address. SubIssue No Data (String) TicketNumber No Data (String) Sub-Issue Type: This variable value is provided by the Service Provider. For proper Ticket creation, the value must map exactly to an Autotask Sub-Issue. Ticket Number: Use this element to create a duplicate ticket for an existing Ticket in Autotask. *XML can contain a Customer value and an Email value. It must contain at least one of those values. NOT E : Aut ot a sk Ma na ge d Se rvice Ext e nsions re quire a ddit iona l e le me nt s. F or a list of t he se e le me nt s, re fe r t o "Using Add Ticke t Ema il Se rvice wit h Ma na ge d Se rvice s Ext e nsions" on pa ge 32. Page 23 of 35
Formatting the Third Party Application Message Template XML Special Characters XML predefines the following five entity references for special characters that would otherwise be interpreted as part of markup language. Character Name Entity Reference Character Reference Numeric Reference Ampersand & & & #38; Left angle bracket < < < Right angle bracket > > > Straight quotation mark " " ' Apostrophe ' ' " To use these characters, you must escape them using the Entity Reference. Company Name and Sub-issue Values in the Autotask Footer The Autotask Footer generated by some MSP software contains values for Company Name and Sub-Issue. When configuring email alerts, follow these guidelines: The customer s 'Customer Name' value in your monitoring software must exactly match the customer s Autotask 'Account Name.' When you add or set up a new customer in your monitoring software, we suggest that you send a test notification to ensure that the names match and that this process is operating properly. The Sub-Issue value is the problem type identified by your monitoring software. This is an optional value but, if you want Autotask to track sub-issues, you must configure your Autotask Sub-Issue type values to match your monitoring problem type. Page 24 of 35
XML Token Message Sample XML Token Message Sample This sample code illustrates the use of XML token elements in messages used with ATES. For additional information on the message template formatting and XML elements, refer to "Formatting the Third Party Application Message Template " on page 22. Sample Message XML This sample XML token message data uses the ATES XML elements and formatting: <Autotask> <ID name="acmemsp.com"/> <PW name="zzz3zz/2z1zzzzzz0zoz9z=="/> <Customer name="msps Customer Incorporated"/> <Email name="jdoe@mspcinc.com"/> <Contact name="fred Jones"/> <SubIssue name="hardware"/> </Autotask> Sample Message XML for Duplicate Ticket This sample message illustrates data that will be processed as a duplicate for an existing ticket: <Autotask> <ID name="acmemsp.com"/> <PW name="zzz3zz/2z1zzzzzz0zoz9z=="/> <TicketNumber>T20060213.0045</TicketNumber> </Autotask> Page 25 of 35
Creating a Contact in Autotask from Incoming Ticket Information Creating a Contact in Autotask from Incoming Ticket Information When the Add Ticket Email Service (ATES) processes an incoming email message it compares the incoming Customer information to your Autotask Accounts. If ATES identifies an Autotask Account that corresponds to the incoming XML Customer information, but cannot find a matching Contact in the Account information, and the XML does not include the Contact element, the Service does not assign a Contact to the Ticket. A message is added to the Ticket indicating that no match was found for the contact email address submitted with the alert email. If the incoming XML includes the Contact element, the Web Services attempt to add a Contact using the incoming Contact element information. NOT E : The Cont a ct e le me nt is not re quire d but st rongly re comme nde d for use rs who wa nt t o use Aut o- t a sk workflow rule s t o se t up a syst e m t o not ify cont a ct s a t t icke t cre a t ion. The following is the contact element tag: <Contact name="firstname Lastname"/> For an example of an XML token that includes the Contact name tag, refer to " XML Token Message Sample" on page 25. Parsing the Contact Element Content The content can be parsed from the From: name of the incoming email. For example, if using Email2DB to forward alerts to the Service, the following tag can be inserted between the Autotask opening and closing tags in the Plain Text Body field under %msg_body% <Contact name="%msg_fromname"/> What Happens When the XML Contains a Contact Name Value If the XML contains the optional Contact name value, the following occurs: The service attempts to match the Customer name and Email name values to an Autotask Account and Contact as outlined in the procedures above. If a matching Account is found for the Customer name value, but no matching contact is found for the account, the Service attempts to create a contact in Autotask. The following fields are completed based on information parsed from the incoming email: First Name, Last Name, Account, and Email Address If no value is available for any field, the value is set to unknown. User-defined Fields are populated as follows: Page 26 of 35
Creating a Contact in Autotask from Incoming Ticket Information All UDFs will be left null, unless they are required or have a default value. UDFs with a default value will inherit the default value. Required UDFs that do not have a default value will inherit the following value, based on field type: -- Date: today's date -- String: "unknown" -- Numeric: "0" LIST type UDFs that are required but have no default value specified will use the first value in the list. Page 27 of 35
Add Ticket Email Service Processing Rules Add Ticket Email Service Processing Rules When an alert email is received at addticket@autotask.net, the Add Ticket Email Service (ATES) uses the service information in the alert, along with the information in the appended XML token, to create a Service Desk Ticket. The Service uses the Customer name and Email values to retrieve Autotask Account information. When an account is matched, but no matching contact is found for the Account, if the XML token includes the Contact Name tag (<Contact name="firstname lastname"/>), the Autotask Web Services API attempts to create the contact in Autotask. This is especially useful if your system uses an Autotask workflow rule to notify the contact when a ticket is created. Refer to "Creating a Contact in Autotask from Incoming Ticket Information" on page 26. NOT E : ATES use s t he e ma il Subje ct a s t he Tit le for t he ne w t icke t in Aut ot a sk, a nd t he e ma il Body a bove t he XML t oke n for t he t icke t De script ion. Be ca use Aut ot a sk t icke t s re quire a t it le, if t he Subje ct line for t he incoming t icke t is e mpt y, t he t icke t t it le will be "Ne w Ticke t - <Da t e / Time >", wit h t he t ime zone a nd da t e /t ime forma t honoring t he de fa ult loca t ion pre fe re nce s. Matching Customer Name and Email Name Values If the XML token contains a Customer name value without an Email name value, the Service searches Autotask Account Names for an exact match to the Customer name element value. If an exact match is found, the Service assigns the ticket to that Account. If no match is found, the Service assigns the ticket to Account ID: 0 (usually assigned to your own company). A message is added to the ticket Description indicating failure to find a match for the submitted Customer name. If the XML contains an Email name value without a Customer name value, the Service searches all Autotask Contact Email Addresses for an exact match to the Email name element value. NOT E : If t he re is more t ha n one ma t ch, a s wit h pa re nt -child a ccount s wit h t he sa me e ma il a ddre ss, t he Se rvice a ssigns t he t icke t t o Account ID: 0 a nd a me ssa ge is a dde d t o t he t icke t De script ion indica t ing t ha t t he e ma il a ddre ss be longs t o mult iple cust ome r a ccount s. If an exact match is found, the Service determines the Autotask Account associated with the Contact Email Address and then assigns that Account ID and ticket Contact to the ticket. If no match is found, and there is no Customer name value, the Service parses the email address to determine the domain name and attempts to match the domain name to an Account Web address. If a match is found for the domain name, the Service assigns the corresponding Account ID to the ticket and includes a message indicating that the Account was determined by the domain name of the submitted email, but no contact was found. If no match is found for the domain name, the Service assigns the ticket to Account ID: 0 (usually assigned to your own company). A message is added to the ticket Description indicating failure to find a match for the submitted email address. If the XML contains a Customer name value and an Email name value, the Service first searches Autotask Account Names for an exact match to the Customer name value. Page 28 of 35
Add Ticket Email Service Processing Rules If no match is found for the Customer name value, the Service assigns the ticket to Account ID: 0 (usually assigned to your own company) and the Service ignores the Email value. A message is added to the ticket Description indicating that no match for the Customer value was found. If a match is found for the Customer value, the Service assigns that Account ID to the ticket. The Service then attempts to match the email value with an email address for a Contact for the Account. If a match is found, that Contact is assigned to the ticket. If no match is found, and the email does not include a Contact name value, the Service does not assign a Contact to the ticket. A message is added to the ticket indicating that no match was found for the contact email address. If no match is found but the XML includes a Contact name value, the Service attempts to create a contact in Autotask and that Contact is assigned to the account. Refer to details under "Creating a Contact in Autotask from Incoming Ticket Information" on page 26. If the XML contains the optional Sub-Issue value, the following occurs: The Service searches for exact match for the Sub-Issue element value in the Autotask Sub-Issues list. If an exact match is found, the Service assigns that Sub-Issue to the ticket. If a match is not found, no Sub-Issue is assigned to the ticket and a message is added to the ticket Description indicating that no match was found for the submitted Sub-Issue value. If the XML contains a Device ID value that maps to a Configuration Item but the Customer name value does not map to the Account that the Configuration Item is associated with, the following occurs: If the Customer name value does not map to any Autotask Account, the ticket is created for the Account that the Configuration Item is associated with. If the Customer name value maps to an Account that is different from the Configuration Item's associated Account, then the ticket is created for the Account that matches the Customer name value and a note is added to the description indicating that a Device ID was specified, but could not be mapped. Page 29 of 35
Using Attachments with the Add Ticket Email Service Using Attachments with the Add Ticket Email Service Add Ticket Email Service (ATES) can accept attachment files and attach those files to the automatically created ticket. No special configuration is required. The file size for uploaded attachments in Autotask is limited to 10 MB: 5 MB for ATES and 4 MB for pictures (the.net default). Autotask will upload all file formats except: ade, adp, app, asp, aspx, bas, bat, cer, chm, class, cmd, cnt, com, cpl, crt, csh, cshtml, der, exe, fon, fxp, gadget, hlp, hpj, hta, inf, ini, ins, isp, its, iw, js, jse, ksh, lnk, mad, maf, mag, mam, maq, mar, mas, mat, mau, mav, maw, mda, mde, mdt, mdw, mdz, msc, msh, msh1, msh1xml, msh2, msh2xml, mshxml, msi, msp, mst, ops, osd, pcd, php, pif, plg, prf, prg, ps1, ps1xml, ps2, ps2xml, psc1, psc2, pst, reg, scf, scr, sct, shb, shs, tmp, url, vb, vbe, vbp, vbs, vsmacros, vsw, ws, wsc, wsf, wsh, xnk. Page 30 of 35
Using the Add Ticket Email Service API with Remote Monitoring Applications Using the Add Ticket Email Service API with Remote Monitoring Applications Several third-party application vendors provide monitoring system alerts that are compatible with the Autotask Add Ticket Email Service (ATES). User-configurable email alert templates, provided by the vendor, allow the Service Provider to include Autotask XML token information in the system alerts. The XML token contains key information and security authentication. When ATES processes incoming emails, the email subject line becomes the ticket title and the email body becomes the ticket details in Autotask. Only emails with valid Autotask token information will be processed. NOT E : Ema il a le rt s dire ct e d t o ATES must be se nt t o addtic ket@auto task.net. Before ATES can successfully process incoming messages, you must complete any setup required by the third party monitoring service vendor and complete the ATES setup in Autotask. Specifying Add Ticket Email Service Settings in Autotask To use Add Ticket Email Service with third-party applications, an administrator must set up ATES and message template. Refer to "Add Ticket Email Service (ATES)" on page 17. Vendor-specific Configuration Some third party vendors have provided user-configurable email alert templates or other features for use with ATES. Autotask Help provides additional vendor specific information and instructions where available. In most cases, we provide links to the vendor documentation or web site. To access vendor information for integrations with ATES, locate your vendor in the table in Autotask Integrations and Extensions. If the integration application is not listed, or there is no documentation link, you must contact your monitoring service application vendor. Page 31 of 35
Using Add Ticket Email Service with Managed Services Extensions Using Add Ticket Email Service with Managed Services Extensions Managed Services Extensions allow Autotask users to use Autotask Device Discovery and the Configuration Item Discovery Wizard to import device information directly from third-party remote monitoring and managedservices applications. These applications can also use the Autotask Web Services API or Add Ticket Email Service (ATES) to automate ticket creation and to handle multiple alerts. For additional information on the Autotask Managed Services Extensions and Device Discovery and Configuration Item Discover Wizard, refer to Managed Services Extensions. Using Custom XML Token Elements with Managed Services Extensions When the Managed Services Extensions are activated, Autotask automatically creates several User-defined Fields (UDFs). The UDFs accept data that maps the monitoring service customer, alert, ticket, and device information to Autotask Accounts, Tickets, and Configuration Items. When integrating with the Add Ticket Email Service, the Managed Services Extension appends an XML token, used by ATES, to their alert emails. The elements in the ATES XML token can provide data that corresponds to the Autotask UDFs. The Add Ticket Email Service then uses the data to compare incoming alerts to existing tickets. For additional information on how Add Ticket Email Service processes incoming emails, refer to "Add Ticket Email Service Processing Rules" on page 28. User-defined Fields for Managed Services Extensions The labels for the Managed Services Extension UDFs include the name of the application associated with the extension, for example, Managed Workplace Device ID or Kaseya Ticket ID. The UDFs correspond to Add Ticket Email Service token elements described below in "XML Token Elements for Use with Managed Services Extensions " on page 33. For information on accessing and managing Managed Services Extension UDFs, refer to Device Discovery User-defined Fields (UDFs). Autotask creates at least two, and up to four, of the following UDFs for each extension. [Partner Application Name] Customer ID (Account UDF): Accepts a partner Customer ID that maps to an Autotask Account entity [Partner Application Name] Device ID (Configuration Item UDF): Accepts a partner Device or Machine ID that maps to an Autotask Configuration Item entity [Partner Application Name] Alert ID (Service Desk Ticket UDF): Accepts a partner alert ID that maps to an Autotask Ticket entity [Partner Application Name] Ticket ID (Service Desk Ticket UDF): Accepts a partner Ticket number that maps to an Autotask Ticket entity Page 32 of 35
Using Add Ticket Email Service with Managed Services Extensions The following table describes the UDF types created in Autotask by the Managed Services Extensions and their relationship to the XML elements used in the Add Ticket Email Service. For details about the UDFs created by a specific Managed Services Extension, refer to the documentation specific to that extension. This Autotask UDF Maps these monitoring service entity types To this Autotask entity type Used with these ATES elements Account UDF: [Partner Application Name] Customer ID Customer ID Site ID Machine Group ID Account Entity <CustomerID source= [Partner Application Name] name= [value] /> Configuration Item UDF: [Partner Application Name] Device ID Device ID Machine Configuration Item Entity <DeviceID source= [Partner Application Name] name= [value] /> Service Desk Ticket UDF: [Partner Application Name] Alert ID Alert ID Alarm ID Ticket Entity <AlertID source= [Partner Application Name] name= [value] /> Service Desk Ticket UDF: [Partner Application Name] Ticket ID Ticket Number Ticket Entity <TicketID source= [Partner Application Name] name= [value] /> XML Token Elements for Use with Managed Services Extensions The third party monitoring application can include the following elements in the ATES XML token to provide data for the Managed Services Extension UDFs. Element Name Required Element Type Element Value CustomerID No Data (String) DeviceID No Data (String) AlertID No Data (String) TicketID No Data (String) Customer ID: This element is used to send a site identifier. ATES will look for the Autotask Account that is mapped (via the UDF labeled [Partner Application Name] Customer ID) to the specified customer id and attach this account to the ticket. Device ID: This element is used to send a device identifier. If provided, ATES will look for the Autotask Configuration Item that is mapped (via the UDF labeled [Partner Application Name] Device ID) to the device id and attach this Configuration Item to the ticket. Alert ID: This element is used to send an alert identifier. If provided, ATES will update a Ticket UDF with this alert value. The corresponding ticket UDF is labeled [Partner Application Name] Alert ID. Ticket ID: This element is used to send a ticket ID generated by the monitoring service. When an alert identifier is not available, this element can be used to define a duplicate ticket for multiple alert handling. Some monitoring services also use it to enable round trip ticket closure. The corresponding ticket UDF is labeled [Partner Application Name] Ticket ID. NOT E : F or e a ch of t he a bove XML e le me nt s, t he pa rt ne r a pplica t ion (for e xa mple, Ma na ge d Se rvice s, N-ce n- t ra l, or Ka se ya ) must spe cify a source a t t ribut e va lue t ha t indica t e s t he pa rt ne r a pplica t ion na me. This va lue is use d t o const ruct t he corre sponding UDF. Page 33 of 35
Using Add Ticket Email Service with Managed Services Extensions Sample Message XML The following is sample message data that includes a site id and device id from a monitoring notification: <Autotask> <ID name="acmemsp.com"/> <PW name="zzz3zz/2z1zzzzzz0zoz9z=="/> <CustomerID source="xyz Monitoring Application" name="100"/> <DeviceID source="xyz Monitoring Application" name="123"/> <AlertID source="xyz Monitoring Application" name="8932"/> </Autotask> Page 34 of 35
Index: Add Ticket Email Service Incoming Email Processing Index Add Ticket Email Service 17 attachments and 30 creating contact from ticket 26 formatting the message template 22 processing rules 28 setting up message templates 21 using with Managed Services Extensions 32 using with remote monitoring 31 XML message sample 25 Email Parser 3 Incoming Email Processing 3 configuring 11, 19 entity creation rules 7 indicators 16 Page 35 of 35