Incoming Processing

(1)

Incoming Email

Processing

Last updated on Monday, July 08, 2013

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.

(2)

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.

l 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 3on how we determine what entity will be created from a given email.

l 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.

l Incoming Email Processing allows you to set up a "closed loop" of communications between your cus-tomer and resources (such as technicians) at your company. If all participants use "Reply" or "For-ward", 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 part-ner integrations (refer to Autotask Integrations and Extensions).

Licensing

BasicIncoming Email Processing is available to all Autotask customers at no additional cost. Basic Incoming Email Processing includes:

l The Add Ticket Email Service (ATES) mailbox, which is already set up

l An option to configureoneadditional custom mailbox for creating tickets only

l 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

AdvancedIncoming Email Processing includes:

l The Add Ticket Email Service (ATES) mailbox, which is already set up l An option to configuresixadditional custom mailboxes

l Emails can be converted to Tickets, Ticket Notes, Ticket Time Entries, Project Notes, Task Notes, and Task Time Entries

NOT E :To lic e n s e Ad va n c e d In c o m in g Em a il P r o c e s s in g , c o n t a c t yo u r Au t o t a s k s a le s r e p r e s e n t a t ive .

How Autotask Processes Emails

(4)

information includes:

l The emailSubjectline: Autotask checks for a matching ticket, project, or task number.

l The first line of the emailBodytext: Autotask checks for indicators (for more information, refer to "Tracking Your Work Using Email Indicators" on page 16).

Email Subject line contains...

...then Autotask will generate a:

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

indi-cator (#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=)

•

*Tic ke t Tim e En t r y, Ta s k Tim e En t r y, S t a t u s Up d a t e , a n d R o le Up d a t e a r e a p p lic a b le o n ly t o t h o s e w it h a n Au t o t a s k 'Us e r ' lic e n s e .

Overview of the Closed Loop Communication Flow

(5)

Customer sends an email to the support address that you had supplied to them.

For example, you have configured a Gmail account as '[email protected]' 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 automaticallyredirect(not for-ward!! Refer to thisMicrosoft article) emails to the email-processing mailbox you have specified in theMailbox Emailfield 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 tem-plate, as described inManaging Notification Templates.)

• If the email originator's email address matches an account contact or domain (refer to NOTE below) in your Autotask data-base, an Autotask ticket or note is created (as described in theExamplebelow).

• 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'sWebfield, 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 Noti-fication will be sent to the email originator and any failure-notiNoti-fication 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 emailSubject(for example, Desktop Issues) becomes the Ticket Title.

• The emailBodytext (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.

(6)

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 theAdd 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 17and"Configuring the ATES Mailbox" on page 19.

Configuration Overview

The closed-loop email process requires you to:

l Configure your Autotask mailbox (refer to "Configuring a Custom Mailbox" on page 11) l Establish your Workflow Rules (refer to Setting Workflow Rules and Notifications) l 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 rec-ommend that you:

l Set up your support mailbox to automaticallyredirect(not forward!! Refer to thisMicrosoft article) emails customer incoming messages to your Autotask incoming-email mailbox.

(7)

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 deter-mines which account and contact to attribute the item to, or which resource to attribute the item to, according to the following rules:

(8)

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 match-ing 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 con-tact for that account. The concon-tact 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 fail-ure notification email will be sent.

c. Exception: for tickets, the ticket will get created for your Internal Account, with no con-tact.

NOT E :Th e Ac c o u n t Typ e a n d 'Ac t ive ' s t a t u s o f yo u r In t e r n a l Ac c o u n t d o n o t a ffe c t In c o m in g Em a il P r o c e s s in g t ic ke t c r e a t io n r u le 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 cre-ation 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

(9)

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 incom-ing 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:

l auto reply l autoreply l auto-reply l automatic response l automated response l auto-response l auto response l out of office l out-of-office l maternity leave l family leave

T IP: Yo u m a y w a n t t o c o n fig u r e yo u r c o m p a n y s u p p o r t m a ilb o x s o t h a t s u c h e m a ils a r e n o t r e d ir e c t e d t o t h e Au t o t a s k m a ilb o x.

(10)

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.

(11)

Configuring a Custom Mailbox

IM POR T ANT :To e n s u r e p r o p e r s e t u p o f In c o m in g Em a il P r o c e s s in g , yo u m u s t lo g in u s in g t h ep r imar y d o mainfo r yo u r Au t o t a s k d a t a b a s e .

If yo u a r e u n s u r e o f yo u r Au t o t a s k d a t a b a s ep r imar y d o main, c o n t a c t Au t o t a s kCu s t o m e r S u p p o r t. To configure a mailbox for incoming email processing:

1. Go toAdmin > AutotaskExtend > Tools > Incoming Email Processing. 2. ClickNew.

3. Complete theGeneraltab.

General tab Description

Mailbox Name The mailbox name that appears on the list of mailboxes on theIncoming Email Processing - Mail-boxespage.

Active Checked if Incoming Email Processing is enabled.

Mailbox Email The recipient email address for any emails that Autotask should convert to Autotask entities (tick-ets, task notes, etc.).

NOTE:Autotask recommends that you give to your customer a 'friendly' email address ([email protected]) and configure your email server toredirect(not forward!! Refer to this

Microsoft article) emails from that address to theMailbox Emailaddress.

Attachments checkbox Select to have Autotask create attachments—attached to the parent ticket, project, or task— from images in the email body.

Kaseya Alert Handling check-box (available only if Kaseya Extension is turned on)

Select to automatically create a ticket for the associated Autotask configuration item. To ensure this functionality, the email must contain a string formatted as

"machine-name.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 theTickettab. Populate the following fields to create Autotask tickets from emails without a valid ticket, project, or task number in the Subject line:

Ticket tab Description

Enabled checkbox

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 pop-ulating Ticket fields, refer toCreating TicketsandConfigure service desk ticket due date and due time defaults.

(12)

Failure and Success Noti-fications

To kick off closed-loop email processing, email notifications can be sent to the email originator, internal resources, and other email recipients.

IM POR T ANT NOT E :Th e t ic ke t , p r o je c t , o r t a s k n u m b e r t h a t is in t h e S u b je c t lin e is c r u -c ia l t o e m a il- p r o -c e s s in g -c o m m u n i-c a t io n s . Us e F a ilu r e a n d S u -c -c e s s No t ifi-c a t io n s a n d o n e o f t h e n o t ific a t io n t e m p la t e s s p e c ific a lly d e s ig n e d fo r In c o m in g Em a il P r o c e s s in g t o e n s u r e t h a t t h is n u m b e r r e m a in s p r e s e n t .

Notification Template

Pre-configured default Notification Templates—specific to Incoming Email Processing—are available from the Noti-fication 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 toCreating Notification Templates.

NOTE:If a template is not selected, an email will not be sent to the email originator.

NOT E :All c u s t o m e r s h a ve a c c e s s t o t h e Ge n e r a l a n d Tic ke t t a b s a n d c a n s e t u p o n e c u s t o m m a ilb o x in a d d i-t io n i-t o i-t h e ATES m a ilb o x. If yo u h a ve u p g r a d e d i-t h e e m a il- p r o c e s s in g s e r vic e , i-t h e fo llo w in g i-t a b s w ill b e a c i-t ive a n d yo u c a n c o n ve r t e m a ils in t o a d d it io n a l Au t o t a s k e n t it ie s .

5. Click theTicket Note tab. Populate the following fields to create Autotask tickets from emails with a valid ticket number in the Subject line:

Ticket Note

tab Description

Enabled checkbox

Check to enable creation of ticket notes from emails sent to this mailbox.

Defaults Select the default values for ticket notes created by the service. The Note Type Defaults toTask Summary. You can select a different Note Type from the drop-down list. For more information on Note Types, refer toAdding System Note Types.

If you selectAll Autotask Usersin 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 Onlymeans the note can only be viewed by users in your Autotask database.

If you select a Status, the ticket status is updated. Failure and

Success Noti-fications

(13)

6. Click theTicket 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 Description Enabled

checkbox

Check to enable creation of ticket time entries from emails sent to this mailbox.

Defaults 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.

7. Click theProject 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 Description Enabled

checkbox

Check to enable creation of project notes from emails sent to this mailbox.

Defaults Select the default values for project notes created by the service. You can specify the Note Type and the Publish option for the note.

(14)

8. Click theTask Note tab. Populate the following fields to create Autotask tasks from emails with a valid task number in the Subject line:

Task Note

tab Description

Enabled checkbox

Check to enable creation of task notes from emails sent to this mailbox.

Defaults Select the default values for ticket notes created by the service. The Note Type Defaults toTask Summary. You can select a different Note Type from the drop-down list. For more information on Note Types, refer toAdding System Note Types.

If you selectAll Autotask Usersin 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 Teammeans the note can only be viewed by users in your Autotask database.

If you select a Status, the task status is updated. Failure and

9. Click theTask 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 Description

Enabled checkbox

Check to enable creation of task time entries from emails sent to this mailbox.

Defaults 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.

(15)

NOTE:If a template is not selected, an email will not be sent to the email originator. 10. ClickSave & Close.

(16)

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 emailBodyto tell Autotask what action to take. l #T=tells Autotask to add the email text as a time entry rather than a note.

l #R=changes the role rate to the one specified after the indicator (for ticket and task time entries). l #S=changes the status of the ticket or task to the one specified after the indicator.

NOT E :Do n o t p u t a n y o t h e r t e xt in t h e fir s t lin e o f t h e e m a il b o d y. Ad d it io n a l in fo r m a t io n m u s t b e e n t e r e d o n t h e lin e b e lo w t h e e m a il in d ic a t o r s , a s s h o w n t h e e xa m p le b e lo w .

Email Indicators Examples

The email example below will create a 30-minutetime entry(#T=.5) on the ticket using the after-hours

role rate(#R=After Hours Support), andcompletethe 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.

l 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.

l Multiple email indicators must be separated by a space.

l If you are specifying a Status or Role, be sure that it exists in your Autotask database. l For a list of valid Statuses:Admin > Site Setup > Statuses

(17)

Add Ticket Email Service (ATES)

TheAdd 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 Serv-ice Provider Password which are appended to each message as an XML token.

NOT E :ATES s u p p o r t s t h e UTF - 8 c h a r a c t e r s e t .

IM POR T ANT :Do NO T s e n d yo u r s p a m n o t ific a t io n s t o a d d t ic ke t @ a u t o t a s k.n e t . Hig h vo lu m e s o f s p a m n o t i-fic a t io n s c a n a ffe c t s ys t e m p e r fo r m a n c e .

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 toAdmin > AutotaskExtend > Tools > Incoming Email Proc-essing > 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 cus-tom Autotask integration or an Autotask Managed Services Extension, additional steps are required.

To begin using ATES, complete the following setup: l Configure the ATES Mailbox

An Autotask Administrator must specify default ticket settings, notifications, and duplicate ticket han-dling preferences for automatically created tickets. Refer to"Configuring the ATES Mailbox" on page 19. l 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.

l Set Up Third Party Remote Monitoring Specifications(when applicable)

Third party remote monitoring services that have partnered with Autotask to provide a custom inte-gration 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.

(18)

Add Ticket Email Service (ATES)

To see if additional information is available from Autotask, locate your monitoring service application in the table inAutotask Integrations and Extensions. If the integration application is not listed, or there is no documentation link, you must contact your monitoring service provider vendor.

l 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.

(19)

Configuring the ATES Mailbox

IM POR T ANT :To e n s u r e t h a t yo u a r e u s in g t h e c o r r e c t S e r vic e P r o vid e r ID, yo u m u s t lo g in u s in g t h ep r i-mar y d o mainfo r yo u r Au t o t a s k d a t a b a s e .

If yo u a r e u n s u r e o f yo u r Au t o t a s k d a t a b a s ep r imar y d o main, c o n t a c t Au t o t a s kCu s t o m e r S u p p o r t. To configure the ATES mailbox, complete the following steps:

1. Go toAdmin > AutotaskExtend > Tools > Incoming Email Processing.

2. Click theEditicon (a pencil) to the left of theAdd Ticket Email Service (ATES)mailbox. The ATES mailbox will open.

NOT E :O n ly t h e Ge n e r a l a n d Tic ke t t a b s a r e e n a b le d .

3. Complete theGeneralandTickettabs using the information in the following table. General tab Description

Mailbox Name

The mailbox name is read-only: Add Ticket Email Service (ATES)

Active Checked if ATES is enabled Service

Pro-vider ID

Read-only. The database's domain.

Service Pro-vider Pass-word

Supplied by Autotask when ATES is enabled.

Attachments checkbox

Select to have Autotask create attachments—attached to the parent ticket, project, or task—from images in the email body.

Ticket tab Description

Enabled checkbox

Check to turn on email processing for tickets.

Ticket Defaults

Select the default values for tickets created by the ATES service. Several fields are required. For more information on Ticket fields, refer toCreating TicketsandConfigure service desk ticket due date and due time defaults. Failure and

To kick off closed loop email processing, email notifications can be sent to the email originator, internal resources, and other recipients. Optionally,Send XML Notificationslets 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

- Click the Edit (pencil) icon to edit a template. - Click + to create your own template. Refer toCreating Notification Templates.

(20)

Configuring the ATES Mailbox

(21)

Setting Up the Third Party Application Add Ticket Email Message

Setting Up the Third Party Application Add Ticket Email

Mes-sage

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. TheAdd 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 u t o m a t ic a lly c r e a t e Au t o t a s k t ic ke t s u s in g ATES , t h ir d - p a r t y a p p lic a t io n s m u s t s u b m it e m a ils t o ad d tic ket@ au to task.n et.

l 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 soft-ware, refer to"Formatting the Third Party Application Message Template " on page 22.

l To view a sample XML message token, refer to" XML Token Message Sample" on page 25.

l 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.

l For information on using the Contact Name element in an incoming message to create a contact in Auto-task, refer to"Creating a Contact in Autotask from Incoming Ticket Information" on page 26.

l 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.

l For information on using attachments with ATES, refer to"Using Attachments with the Add Ticket Email Service" on page 30.

(22)

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 dupli-cate 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 :Th e in fo r m a t io n in t h is t o p ic a s s u m e s a b a s ic fa m ilia r it y w it h XML a n d w it h yo u r t h ir d p a r t y a p p li-c a t io n 's m e s s a g e t e m p la 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 :Au t o t a s k r e c o m m e n d s u s in g t h e p la in - t e xt fo r m a t .

l All third-party applications must submit emails to[email protected].

l 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>".

l 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.

l 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:

l Paste the XML token into that free-form area

l Place the "Customer name" variable inside the "Customer name" attribute value NOT E :Th e va lu e s in t h e "Cu s t o m e r n a m e " a t t r ib u t e m u s t m a t c h a n Ac c o u n t Na m e in Au t o t a s k.

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

(23)

table in the introductory topicIntegrating with Remote Monitoring Applications, or contact your third-party appli-cation 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 :S o m e e le m e n t s a r e a lw a ys r e q u ir e d , w h e r e a s o t h e r s a r e r e q u ir e d a s n o t e d . Element

Name Required

Element

Type Value

Autotask Yes Container No additional value is required.

ID 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.

PW Yes Data

(String)

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)

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.

TicketNumber No Data

(String)

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 :Au t o t a s k Ma n a g e d S e r vic e Ext e n s io n s r e q u ir e a d d it io n a l e le m e n t s . F o r a lis t o f t h e s e e le m e n t s , r e fe r t o "Us in g Ad d Tic ke t Em a il S e r vic e w it h Ma n a g e d S e r vic e s Ext e n s io n s " o n p a g e 3 2.

(24)

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 < < &#60;

Right angle bracket > > >

Straight quotation mark " " '

Apostrophe ' ' "

To use these characters, you must escape them using theEntity 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:

l 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 sug-gest that you send a test notification to ensure that the names match and that this process is operating properly.

l 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.

(25)

XML Token Message Sample

This sample code illustrates the use of XML token elements in messages used with ATES. For additional infor-mation on the message template formatting and XML elements, refer to "Formatting the Third Party Appli-cation 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"/>

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"/>

(26)

Creating a Contact in Autotask from Incoming Ticket Information

Creating a Contact in Autotask from Incoming Ticket

Infor-mation

When theAdd Ticket Email Service(ATES) processes an incoming email message it compares the incom-ing Customer information to your Autotask Accounts.

l 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 ele-ment, 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 sub-mitted with the alert email.

l If the incoming XML includes the Contact element, the Web Services attempt to add a Contact using the incoming Contact element information.

NOT E :Th e Co n t a c t e le m e n t is n o t r e q u ir e d b u t s t r o n g ly r e c o m m e n d e d fo r u s e r s w h o w a n t t o u s e Au t o -t a s k w o r kflo w r u le s -t o s e -t u p a s ys -t e m -t o n o -t ify c o n -t a c -t s a -t -t ic ke -t c r e a -t io n .

The following is thecontact 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%

What Happens When the XML Contains a Contact Name Value

If the XML contains the optional Contact name value, the following occurs:

l 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

l If no value is available for any field, the value is set to unknown. l User-defined Fields are populated as follows:

(27)

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"

(28)

Add Ticket Email Service Processing Rules

When an alert email is received at [email protected], theAdd 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 Infor-mation" on page 26.

NOT E :ATES u s e s t h e e m a il S u b je c t a s t h e Tit le fo r t h e n e w t ic ke t in Au t o t a s k, a n d t h e e m a il Bo d y a b o ve t h e XML t o ke n fo r t h e t ic ke t De s c r ip t io n . Be c a u s e Au t o t a s k t ic ke t s r e q u ir e a t it le , if t h e S u b je c t lin e fo r t h e in c o m in g t ic ke t is e m p t y, t h e t ic ke t t it le w ill b e "Ne w Tic ke t < Da t e / Tim e > ", w it h t h e t im e z o n e a n d d a t e /t im e fo r -m a t h o n o r in g t h e d e fa u lt lo c a t io n p r e fe r e n c e 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.

l If an exact match is found, the Service assigns the ticket to that Account.

l If no match is found, the Service assigns the ticket to Account ID: 0 (usually assigned to your own com-pany). 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 h e r e is m o r e t h a n o n e m a t c h , a s w it h p a r e n t - c h ild a c c o u n t s w it h t h e s a m e e m a il a d d r e s s , t h e S e r v-ic e a s s ig n s t h e t v-ic ke t t o Ac c o u n t ID: 0 a n d a m e s s a g e is a d d e d t o t h e t v-ic ke t De s c r ip t io n in d v-ic a t in g t h a t t h e e m a il a d d r e s s b e lo n g s t o m u lt ip le c u s t o m e r a c c o u n t s .

l 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.

l 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 sub-mitted 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 containsa Customer name value and an Email name value, the Service first searches Auto-task Account Names for an exact match to the Customer name value.

(29)

Add Ticket Email Service Processing Rules

l 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.

l If a match is found for the Customer value, the Service assigns that Account ID to the ticket.

l 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 con-tact in Autotask and that Concon-tact 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 theoptional Sub-Issue value, the following occurs:

The Service searches for exact match for the Sub-Issue element value in the Autotask Sub-Issues list. l If an exact match is found, the Service assigns that Sub-Issue to the ticket.

l 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 aDevice IDvalue that maps to a Configuration Item but theCustomername value does not map to the Account that the Configuration Item is associated with, the following occurs:

l If the Customer name valuedoes not map to any Autotask Account, the ticket is created for the Account that the Configuration Item is associated with.

l If the Customer name valuemaps 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.

(30)

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 to10 MB:5 MB for ATESand4 MB for pictures(the .net default).

Autotask will upload all file formatsexcept: 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.

(31)

Using the Add Ticket Email Service API with Remote Monitoring Applications

Using the Add Ticket Email Service API with Remote

Mon-itoring 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 :Em a il a le r t s d ir e c t e d t o ATES m u s t b e s e n t t oad d tic ket@ au to task.n et.

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 inAutotask Inte-grations and Extensions. If the integration application is not listed, or there is no documentation link, you must contact your monitoring service application vendor.

(32)

Using Add Ticket Email Service with Managed Services Extensions

Using Add Ticket Email Service with Managed Services

Exten-sions

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 managed-services applications. These applications can also use the Autotask Web Services API orAdd 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 Con-figuration 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 severalUser-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 tick-ets.

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.

l [Partner Application Name] Customer ID(Account UDF): Accepts a partner Customer ID that maps to an Autotask Account entity

l [Partner Application Name] Device ID(Configuration Item UDF): Accepts a partner Device or Machine ID that maps to an Autotask Configuration Item entity

l [Partner Application Name] Alert ID(Service Desk Ticket UDF): Accepts a partner alert ID that maps to an Autotask Ticket entity

l [Partner Application Name] Ticket ID(Service Desk Ticket UDF): Accepts a partner Ticket number that maps to an Autotask Ticket entity

(33)

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] Cus-tomer ID

Customer ID Site ID

Machine Group ID

Account Entity <CustomerID source=”[Partner Appli-cation 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)

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 cus-tomer id and attach this account to the ticket.

DeviceID No Data

(String)

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.

AlertID No Data

(String)

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.

TicketID No Data

(String)

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 han-dling. 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 o r e a c h o f t h e a b o ve XML e le m e n t s , t h e p a r t n e r a p p lic a t io n (fo r e xa m p le , Ma n a g e d S e r vic e s , N c e n -t r a l, o r Ka s e ya ) m u s -t s p e c ify a s o u r c e a -t -t r ib u -t e va lu e -t h a -t in d ic a -t e s -t h e p a r -t n e r a p p lic a -t io n n a m e . Th is va lu e is u s e d t o c o n s t r u c t t h e c o r r e s p o n d in g UDF .

(34)

Sample Message XML

The following is sample message data that includes a site id and device id from a monitoring notification: <Autotask>

(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

Incoming Processing

Incoming Email

Processing

Table of Contents

Incoming Email Processing

Licensing

How Autotask Processes Emails

•

•

•

•

•

•

•

•

•

•

•

Overview of the Closed Loop Communication Flow

What about Add Ticket Email Service?

Configuration Overview

Entity Creation Rules

Account and Contact Association

Email Truncation

Message Count Limitation

Infinite Loop Prevention

Configuring a Custom Mailbox

Tracking Your Work Using Email Indicators

Email Indicators Examples

Email Indicators Notes

Add Ticket Email Service (ATES)

Service Provider ID and Password

Getting Started with Add Ticket Email Service

Configuring the ATES Mailbox

Setting Up the Third Party Application Add Ticket Email

Mes-sage

Formatting the Third Party Application Message Template

Formatting the XML Token and Email Message

Option 1 for Appending the XML Token

Option 2 for Appending the XML Token

List of XML Elements

XML Special Characters

Company Name and Sub-issue Values in the Autotask Footer

XML Token Message Sample

Sample Message XML

Sample Message XML for Duplicate Ticket

Creating a Contact in Autotask from Incoming Ticket

Infor-mation

Parsing the Contact Element Content

What Happens When the XML Contains a Contact Name Value

Add Ticket Email Service Processing Rules

Matching Customer Name and Email Name Values

Using Attachments with the Add Ticket Email Service

Using the Add Ticket Email Service API with Remote

Mon-itoring Applications

Specifying Add Ticket Email Service Settings in Autotask

Vendor-specific Configuration

Using Add Ticket Email Service with Managed Services

Exten-sions

Using Custom XML Token Elements with Managed Services Extensions

User-defined Fields for Managed Services Extensions

XML Token Elements for Use with Managed Services Extensions

Sample Message XML

Index