Formatting the application message template
In generic Incoming Email Processing, every Autotask customer has their own unique mailbox address. But all applications from all customers that use ATES to send data to Autotask so a ticket can be created use the same email address: addticket@autotask.net (for customers in the UK data center, addticket@uk.autotask.net and customers in the German datacenter, addticket@eu.autotask.net).
What allows Autotask to identify which customer Autotask instance the email message is intended for is the XML token that is a part of each email. It contains not only the data elements that identify the customer Autotask instance, but also information that lets us create a valid ticket from the message.
Adding the token to a message template
NOTE We assume a basic familiarity with XML and with your third party application's message template.
Free-form alert notification
If the monitoring application provides a free-form alert notification definition and if the free-form area supports a mix of literals and variables, you simply paste the XML token into that free-form area and place the "Customer name" variable inside the "Customer name" attribute value.
- 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.
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>
This sample message illustrates data that will be processed as a duplicate of an existing ticket:
<Autotask><ID name="acmemsp.com"/><PW name="zzZ3zZ/2Z1ZzzZZZ0zoZ9z=="/><TicketNumber>T20060213.0045</TicketNumber></Autotask>
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 & & & Left angle bracket < < < Right angle bracket > > > Straight quotation mark " " " Apostrophe ' ' ' To use these characters, you must escape them using the Entity Reference.
- Outside of the actual data values, there should be no unnecessary white space.
- If possible, the 3rd party message should use plain text format.
3rd party configuration page
Monitoring applications may provide configuration options that simplify the integration effort. For additional information regarding third-party application settings, check the documentation links provided in the table in the introductory topic Remote monitoring & management (RMM) extensions, or contact your third-party application provider.
The Autotask Footer generated by some MSP software contains values for Organization Your Autotask instance may be configured to use one of the following terms instead: Account, Business Unit, Client Company, Customer, Site. Name and Sub-issue Type. When configuring email alerts, follow these guidelines:
- The customer’s 'Customer Name' value in your monitoring software must exactly match the customer’s Autotask 'Organization 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 Type value is the problem type identified by your monitoring software. This is an optional value but, if you want Autotask to track sub-issue types, you must configure your Autotask Sub-issue Type values to match your monitoring problem type.
NOTE Autotask Managed Service Extensions require additional elements. For a list of these elements, refer to Using Add Ticket Email Service with managed services extensions.
How the email message is parsed
| Element Name | Required | Element Type | Value |
|---|---|---|---|
| Subject line | No | n/a | The subject line becomes the title of the ticket that is created. Because Autotask tickets require a title, if the incoming email does not include a Subject, the ticket title will be "New Ticket - <Date/Time>". |
| Email Body | Technically no | n/a | The email body above the XML token becomes the ticket description. |
| XML Token | |||
| Autotask | Yes | Container | No additional value is required. |
| ID | Yes | Data (String) | Your Service Provider ID. This fixed literal value identifies your Autotask instance as the one to create the ticket in, and is provided by Autotask. You can find it in the ATES setup window in the Admin module. You can locate it here:  > Admin > Automation > Email Notifications & Surveys > Incoming Email Processing > edit Add Ticket Email Service Mailbox. |
| PW | Yes | Data (String) | Your Service Provider Password. This fixed literal value is provided by Autotask, and is found right below the Service Provider ID. |
| Customer | Yes, if no Email value is provided* | Data (String) | This is the Customer Name of your customer. This variable value is provided by the Service Provider. For proper ticket creation, customer names in your 3rd party application and Autotask must match exactly. |
| Yes, if no Customer value is provided* | Data (String) | Email Address of your 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 Organization Web Address. | |
| Contact | No, but recommended when using Autotask workflow rules to notify contacts | Data (String) | When included, if no contact is associated with the matching Autotask organization, the Service attempts to create a contact in Autotask using name information parsed from the incoming email From: address. |
| SubIssue | 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 Type. |
| TicketNumber | No | Data (String) | Ticket Number: Use this element to create a ticket note instead of a duplicate ticket in Autotask. |
NOTE *XML can contain a Customer value and an Email value. It must contain at least one of those values.
Add Ticket Email Service (ATES) can accept attachment files and attach those files to the automatically created ticket. No special configuration is required.
To learn more about how ATES processes incoming messages, refer to Adding Ticket Email Service processing rules.
