Incoming Processing

Transcription

1 Incoming Processing Last updated on Monday, July 08, 2013 Copyright 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.

2 Table of Contents Incoming Processing 3 Entity Creation Rules 7 Configuring a Custom Mailbox 11 Tracking Your Work Using Indicators 16 Add Ticket Service (ATES) 17 Configuring the ATES Mailbox 19 Setting Up the Third Party Application Add Ticket 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 Service Processing Rules 28 Using Attachments with the Add Ticket Service 30 Using the Add Ticket Service API with Remote Monitoring Applications 31 Using Add Ticket Service with Managed Services Extensions 32 Index 35 Page 2 of 35

3 Incoming Processing Incoming Processing Incoming Processing converts s to Autotask entities. The Subject line is converted into the entity title, and the body is converted into the Description. Depending on information contained in the Subject line and the first line of the Body, s are converted to tickets, ticket notes, ticket time entries, project notes, task notes or task time entries. Refer to "How Autotask Processes s" on page 3 on how we determine what entity will be created from a given . The sender's (originator's) 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 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 parser, although we continue to support a number of partner integrations (refer to Autotask Integrations and Extensions). Licensing Basic Incoming Processing is available to all Autotask customers at no additional cost. Basic Incoming Processing includes: The Add Ticket Service (ATES) mailbox, which is already set up An option to configure one additional custom mailbox for creating tickets only Incoming s 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 Processing includes: The Add Ticket Service (ATES) mailbox, which is already set up An option to configure six additional custom mailboxes s 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 s Autotask uses information from the incoming to determine where the should go in the system. This Page 3 of 35

4 Incoming Processing information includes: The Subject line: Autotask checks for a matching ticket, project, or task number. The first line of the Body text: Autotask checks for indicators (for more information, refer to "Tracking Your Work Using Indicators" on page 16)....then Autotask will generate a: 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 -into-autotask process will occur. Page 4 of 35

5 Incoming Processing Customer sends an 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 arrives at the external mail server (for example, Gmail) which has been configured to automatically redirect (not forward!! Refer to this Microsoft article) s to the -processing mailbox you have specified in the Mailbox field in Autotask (as described in "Configuring a Custom Mailbox" on page 11). The arrives in your -processing mailbox and is parsed. (When you configure the -processing mailbox, you should also configure the success and failure notifications for the originator using an Incoming Notification template, as described in Managing Notification Templates.) If the originator's 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 originator's address is not in your Autotask database, but the domain (refer to NOTE below) of the address matches either that of an existing contact or an account's Web field, the originator will be added as a contact to that account. NOTE: "Domain" refers to the company's web address: If neither the address nor domain of the originator matches account information in Autotask, a Failure Notification will be sent to the 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 s" on page 3, above. EXAMPLE: A ticket is created from the information in the . The Subject (for example, Desktop Issues) becomes the Ticket Title. The Body text (for example, "After I updated my browser, my computer froze.") becomes the Ticket Description. A Success Notification with the ticket number of the newly created ticket in the Subject line is automatically sent to the 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 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 notification, the Ticket Number appears in the Subject line of the reply. Based on the -processing rules, an that includes a Ticket Number becomes a Ticket Note on the ticket with that number. In this way, the entire conversation is tracked in Autotask. Page 5 of 35

6 Incoming Processing Optionally, if this process has been followed, the Autotask technician can via this same 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 Indicators" on page 16. What about Add Ticket Service? Autotask continues to support the Add Ticket Service (ATES) for legacy users or those with special circumstances, such as remote-monitoring applications. ATES users should see "Add Ticket Service (ATES)" on page 17 and "Configuring the ATES Mailbox" on page 19. Configuration Overview The closed-loop 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 mailbox as your support mailbox, we recommend that you: Set up your support mailbox to automatically redirect (not forward!! Refer to this Microsoft article) s customer incoming messages to your Autotask incoming- mailbox. Page 6 of 35

7 Entity Creation Rules Entity Creation Rules Account and Contact Association When an Autotask entity is created from an incoming , we attempt to attribute the message to either a resource in your Autotask database, or a customer contact. The sender's (originator's) 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

8 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 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 address, but do not find a matching active contact, we will create a contact for that account. The contact will have the originator's 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 address, but do not find a matching active contact, creation will fail (failure will be sent). 3. If we cannot determine the account based on contact 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 will be sent. b. If we cannot find a matching active account or active contact, creation will fail and a failure notification 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 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". Truncation To prevent the addition of a lot of repetitive information to Autotask, s are truncated as follows: Page 8 of 35

9 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 Processing could result in an endless loop when auto-reply is turned on. To prevent that, we will not process (throw out) s 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

10 Entity Creation Rules Additionally, we will throw out any s that have the same sender and subject, and at least three s were received in the last 5 minutes. The first two s will be processed. This applies to ticket, ticket note, project note, and task note. Ticket time entry and task time s will never be thrown away. Page 10 of 35

11 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 processing: 1. Go to Admin > AutotaskExtend > Tools > Incoming Processing. 2. Click New. 3. Complete the General tab. General tab Mailbox Name Active Mailbox Description The mailbox name that appears on the list of mailboxes on the Incoming Processing - Mailboxes page. Checked if Incoming Processing is enabled. The recipient address for any s that Autotask should convert to Autotask entities (tickets, task notes, etc.). NOTE: Autotask recommends that you give to your customer a 'friendly' address ([email protected]) and configure your server to redirect (not forward!! Refer to this Microsoft article) s from that address to the Mailbox 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 body. Select to automatically create a ticket for the associated Autotask configuration item. To ensure this functionality, the must contain a string formatted as "machinename.groupname.subgroupname". NOTE: Autotask recommends that you dedicate an -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 s without a valid ticket, project, or task number in the Subject line: Ticket tab Enabled checkbox Description Check to enable creation of tickets from s 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 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

12 Configuring a Custom Mailbox Failure and Success Notifications To kick off closed-loop processing, notifications can be sent to the originator, internal resources, and other 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 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 will not be sent to the 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 s 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 s 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 processing, notifications can be sent to the originator, internal resources, and other 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 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 will not be sent to the originator. Page 12 of 35

13 Configuring a Custom Mailbox 6. Click the Ticket Time Entry tab. Populate the following fields to create a time entry from s with a valid ticket number in the Subject line and a Time Entry Indicator (#T=) in the first line of the body: Ticket Time Entry tab Enabled checkbox Defaults Failure and Success Notifications Description Check to enable creation of ticket time entries from s 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 processing, notifications can be sent to the originator, internal resources, and other 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 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 will not be sent to the originator. 7. Click the Project Note tab. Populate the following fields to create a project note from s 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 s 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 processing, notifications can be sent to the originator, internal resources, and other 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

14 Configuring a Custom Mailbox Notification Template Pre-configured default Notification Templates specific to Incoming 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 will not be sent to the originator. 8. Click the Task Note tab. Populate the following fields to create Autotask tasks from s 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 s 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 processing, notifications can be sent to the originator, internal resources, and other 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 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 will not be sent to the originator. 9. Click the Task Time Entry tab. Populate the following fields to create a time entry from s with a valid task number in the Subject line and a Time Entry Indicator (#T=) in the first line of the body: Task Time Entry tab Enabled checkbox Defaults Description Check to enable creation of task time entries from s 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

15 Configuring a Custom Mailbox Failure and Success Notifications To kick off closed-loop processing, notifications can be sent to the originator, internal resources, and other 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 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 will not be sent to the originator. 10. Click Save & Close. Page 15 of 35

16 Tracking Your Work Using Indicators Tracking Your Work Using Indicators Your company's resources and technicians can use 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 Body to tell Autotask what action to take. #T= tells Autotask to add the 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. Indicators Examples The 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 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 indicators. #T=.5 #S=Complete #R=After Hours Support Customer appreciated quick, temporary resolution; ticket closed. Site visit necessary to avoid re-occurrence. Indicators Notes Review the following notes to ensure that your indicators are valid. indicators must appear with no other data on the first line of the body of the . Additional information must be entered on the line below the indicators. Multiple 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

17 Add Ticket Service (ATES) Add Ticket Service (ATES) The Add Ticket Service (ATES) integrates between Autotask and applications that generate alerts, but require a generic 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 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 Processing > Add Ticket Service (ATES) > General. All s delivered to ATES must provide these values. Getting Started with Add Ticket Service Before you can begin creating Autotask tickets from incoming s, you must set up both Autotask and the third party application that will generate the s. 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 Templates in the third party application The incoming must include a valid Autotask XML token at the end of the body, per the ATES API specifications. Refer to "Setting Up the Third Party Application Add Ticket 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

18 Add Ticket 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 s. Refer to "Using Add Ticket Service with Managed Services Extensions" on page 32. Page 18 of 35

19 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 Processing. 2. Click the Editicon (a pencil) to the left of the Add Ticket 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 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 body. Description Check to turn on 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 processing, notifications can be sent to the 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 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 will be sent to the originator. Page 19 of 35

20 Configuring the ATES Mailbox 4. Click Save & Close. Page 20 of 35

21 Setting Up the Third Party Application Add Ticket Message Setting Up the Third Party Application Add Ticket 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 body. The message is created by the third-party application from templates within that application. The Add Ticket Service (ATES) API uses the information in the XML token, along with the service information contained in the , 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 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 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 s with Autotask accounts and/or contacts, refer to "Add Ticket Service Processing Rules" on page 28. For information on using attachments with ATES, refer to "Using Attachments with the Add Ticket Service" on page 30. Page 21 of 35

22 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 Service (ATES), the XML token appended to incoming 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 s 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 Service Processing Rules" on page 28. Formatting the XML Token and 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 s to [email protected]. ATES uses the Subject as the title for the new Ticket in Autotask, and the body above the XML token for the ticket description. Because Autotask tickets require a title, if the incoming 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 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

23 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 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 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 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. Yes, if no Customer value is provided* Data (String) 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 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 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 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

24 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 < < &#60; Right angle bracket > > > Straight quotation mark " " &#39; Apostrophe &apos; ' " 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 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

25 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"/> < <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>T </TicketNumber> </Autotask> Page 25 of 35

26 Creating a Contact in Autotask from Incoming Ticket Information Creating a Contact in Autotask from Incoming Ticket Information When the Add Ticket Service (ATES) processes an incoming 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 address submitted with the alert . 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 . For example, if using 2DB 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 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 First Name, Last Name, Account, and 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

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" LIST type UDFs that are required but have no default value specified will use the first value in the list. Page 27 of 35

28 Add Ticket Service Processing Rules Add Ticket Service Processing Rules When an alert is received at the Add Ticket 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 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 Name Values If the XML token contains a Customer name value without an 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 name value without a Customer name value, the Service searches all Autotask Contact Addresses for an exact match to the 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 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 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 , 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 address. If the XML contains a Customer name value and an name value, the Service first searches Autotask Account Names for an exact match to the Customer name value. Page 28 of 35

29 Add Ticket 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 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 value with an 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 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 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

30 Using Attachments with the Add Ticket Service Using Attachments with the Add Ticket Service Add Ticket 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

31 Using the Add Ticket Service API with Remote Monitoring Applications Using the Add Ticket Service API with Remote Monitoring Applications Several third-party application vendors provide monitoring system alerts that are compatible with the Autotask Add Ticket Service (ATES). User-configurable 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 s, the subject line becomes the ticket title and the body becomes the ticket details in Autotask. Only s 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 Service Settings in Autotask To use Add Ticket Service with third-party applications, an administrator must set up ATES and message template. Refer to "Add Ticket Service (ATES)" on page 17. Vendor-specific Configuration Some third party vendors have provided user-configurable 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

32 Using Add Ticket Service with Managed Services Extensions Using Add Ticket 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 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 Service, the Managed Services Extension appends an XML token, used by ATES, to their alert s. The elements in the ATES XML token can provide data that corresponds to the Autotask UDFs. The Add Ticket Service then uses the data to compare incoming alerts to existing tickets. For additional information on how Add Ticket Service processes incoming s, refer to "Add Ticket 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 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

33 Using Add Ticket 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 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

34 Using Add Ticket 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

35 Index: Add Ticket Service Incoming Processing Index Add Ticket 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 Parser 3 Incoming Processing 3 configuring 11, 19 entity creation rules 7 indicators 16 Page 35 of 35