Ticket

IMPORTANT  The SOAP API entered a limited enhancement phase in Q4 2020. Access to version 1.6 will be deactivated.

This entity describes an Autotask Ticket. Tickets define service requests within the Autotask system. Autotask users manage Tickets through a number of modules including Service Desk, Home, CRM, and Contracts. They can click New Ticket on the Autotask interface sub-navigation menu to open the New Ticket window.

Entity details

You can also retrieve this information with the Web Services API call The getEntityInfo() SOAP API call.

Entity Name: Ticket
Can Create:
Can Update:
Can Query:
Can Delete:  
Can Have UDFs:

Although you can query this entity, it contains one or more fields that are not queryable. If you attempt to query these fields, you will receive an error message.

  • CreatorType
  • LastActivityPersonType

NOTE   Although the Autotask interface now allows multiple resources on a ticket, the current versions of the Web Services API do not support this feature. Web Services is, however, aware of and will check existing multiple resources on a ticket and will not allow any resource to be assigned as primary resource if that resource is already a secondary resource.

Conditions and requirements

General

  • This entity will be read-only if the module with which it is associated is not active. For more information, refer to Activations.
  • The Web Services API stores and returns all time data in Coordinated Universal Time (UTC).
  • The Ticket entity can have no more than 300 UDFs. Refer to UserDefinedFieldDefinition.
  • A Resource + Role combination assigned to a ticket must be associated with at least one Service Desk Queue.
  • The API can complete a ticket that has one or more incomplete 'Important' Checklist items. There is no warning.
  • With the granular ticket security features implemented in the 2016.1 release, the API Ticket entity will respect the View, Add, and Edit permissions assigned to the logged in end user, EXCEPT the API will not respect the 'Mine + Accounts' setting. 'Mine + Accounts' will be treated as 'None.' For more information on granular ticket security, refer to the Online Help topic: Create or edit a custom security level.
  • Update() is allowed on a Ticket with an inactive attribute value if that value is not being changed. A new inactive attribute value cannot be assigned.
  • Three read only fields, MonitorID, MonitorTypeID, and RMMAlertID are currently available for use by the Autotask RMM integration only.

IMPORTANT  When the API receives a request to update a field that contains Rich Text, the API will update the text-only version of the field and overwrite the data in the Rich Text field with plain text. All text formatting and images will be lost. Refer to The Rich Text editor to learn more.

Contact impersonation validation rules for creating entities

  1. The API user security level has access to contact impersonation for tickets.
  2. The ticket must be associated to either the contact's account or any of its child accounts.
  3. The contact is active.
  4. The contact's account is active.

NOTE  If the API user does not have the Contacts impersonation option enabled, it will be unable to specify custom values for the AttachedByContactID and the CreatedByContactID fields. Any entities or attachments that the account creates will be attributed to "API User." Refer to Web Services API security settings.

Special field attributes

Field Conditions and Requirements
AccountID

Ticket.AccountID cannot be changed if the ticket has an associated and posted TimeEntry, TicketCost, or Expense.

If the ticket has no associated posted items and Ticket.AccountID is changed, any associated (non-posted) Contract, TimeEntries, or TicketCosts are set to Null, along with any Service or ServiceBundle items associated with the TimeEntries or TicketCosts. ExpenseItem.AccountID is updated and ExpenseItem.ProjectID, ExpenseItem.TaskID, or ExpenseItem.TicketID is set to Null.

AllocationCodeID

AllocationCodeID is required on create() and update() if your company has enabled the Autotask system setting that requires a Work Type on a Ticket.

The AllocationCodeID field must reference a Work Type allocation code.

AssignedResourceRoleID

 

Autotask now allows Role to be inactivated.

  • You can update an existing Ticket that has a Resource + Role combination that uses an inactive role.
  • An attempt to create a Ticket using a Resource + Role combination with an inactive Role will trigger an error.
ChangeApprovalBoard ChangeApprovalBoard must reference an active Change Approval Board.
ChangeApprovalStatus

ChangeApprovalStatus can only be set to Requested or Assigned. All other statuses, Not Assigned, Partially Approved, Approved, or Rejected can only be set by the system.

  • If ChangeApprovalStatus = Assigned, user can change it to Requested (only).
  • If ChangeApprovalStatus = Requested, user can change it to Assigned (only)
ChangeApprovalType

If a value is not provided for ChangeApprovalType:

  • If the ticket type = Change Request, then ChangeApprovalType is set to the default value.
  • If the ticket type is not = Change Request and a current ChangeApprovalType value exists on the entity, then the field is cleared. This allows the field to be cleared for tickets that are not Change Request type tickets.
  • Otherwise, do nothing.
ChangeInfoFields ChangeInfoFields are available regardless of whether they are Active or Inactive.
ContactID

For the ContactID field, Contact.AccountID must = Ticket.AccountID or the ParentAccountID of Ticket.AccountID.

update() is allowed on a Ticket with an inactive ContactID value if that value is not being changed, or if a new active value is assigned. A new inactive ContactID value cannot be assigned on create() or update().

If the ticket category = 'RMA', and no value is supplied for the Contact field, it will be set to the contact of the supplied asset.

ContractID

If a ticket is created or updated with a sub-issue type that is excluded from the associated contract, the ticket's ContractID will be updated to that of the exclusion contract, if it exists. If it does not exist, the ContractID will be set to null.

CreatorResourceID CreatorResourceID can return a ContactID. CreatorType specifies whether the CreatorResourceID refers to a Resource or a Contact.

Description

When you use the API to update this field, the REST API will return the text-only version of its content. If you send the content back, the Rich Text and all images that it contains will be lost. You cannot use the API to create items that contain Rich Text, but you can add Rich Text later via a supported method.

To learn more, refer to The Rich Text editor.

DueDateTime

This field is required unless the supplied ticket category or the user's default ticket category has both the Due Date and Due Time configured.

If the ticket category has only the due date or only the due time configured, then the API Ticket.DueDateTime will be required, and not supplying a value will return an error message.

If the ticket is created from a Datto RMM alert and the Autotask ticket category has a Due Date and Time configured, then we will clear the DueDateTime field on the alert supplied by Datto RMM, and apply the default from the Autotask ticket category.

InstalledProductID

On create(), if InstalledProductID is populated, the InstalledProduct.AccountID must = Ticket.AccountID

On update(), InstalledProduct.ID cannot be updated to an InstalledProduct where InstalledProduct.AccountID ≠ Ticket.AccountID.

If the ticket category = 'RMA', the InstalledProductID is required. That InstalledProduct must also reference a Product that is EligibleForRma.

NOTE  If the InstalledProduct value is not being updated, and for some reason it is already associated with an Account that is different from the Ticket Account, the update() will not fail.

IssueType, SubIssueType

 

IssueType and SubIssueType are never required in the API. They are required in the UI only if the system setting 'Require Issue and Sub-Issue on tickets' is enabled.

SubIssueType is associated with an Issue and the available SubIssueType picklist items are specific to the associated IssueType. When a SubIssueType value is provided, the associated IssueType value must also be provided.

LastActivityPersonType LastActivityPersonType values indicating whether the initiator of the last activity was a resource or a contact. This field is not filterable for tickets in the API.

LastTrackedModificationDateTime

Tracks updates to any field except changes to the LastActivityDate, LastCustomerNotificationDateTime, LastCustomerVisibleActivityDateTime. UDF changes are included in the criteria for updating LastTrackedModificationDate.

OpportunityID For the OpportunityID field, Opportunity.AccountID must = Ticket.AccountID.
Priority

On create(), Priority must be an active priority.

If the current priority is inactive, update() is allowed if the Priority value is not changed, or if Priority is changed to an active value.

ProblemTicketID ProblemTicketID cannot = TicketID of a ticket that is already associated with a ProblemTicketID; that is, an incident ticket already associated with a problem ticket cannot become a problem ticket.
ProjectID ProjectID must be associated with the same Account as the Ticket (Ticket.AccountID).
QueueID

QueueID requirement - The ticket's category (Ticket.TicketCategory) will determine whether or not Ticket.QueueID is required, based on the category's 'Queue is Required' setting. If QueueID does not meet the requirement specified by the associated ticket category's 'Queue is Required' setting, as listed below, an error will occur.

  • If setting equals 'Always', the API will always require the QueueID value.
  • If setting equals 'Never' then the API will not require the QueueID value.
  • If setting equals 'RequiredWhenPrimaryResourceIdBlank', then the API will produce an error when both the QueueID and ResourceID fields are empty.
RMAStatus

This field is editable for tickets whose ticket category is 'RMA.' ◦

  • Attempting to edit this field on a ticket with a different ticket category will result in the supplied value being ignored.
  • If a ticket is created with the 'RMA' ticket category via the API and no value is supplied for this field, the ticket category default value for the field will be used.

RMAType

This field is editable for tickets whose ticket category is 'RMA.'

  • Attempting to edit this field on a ticket with a different ticket category will result in the supplied value being ignored.
ServiceLevelAgreementID

The ticket SLA is defaulted in using the following logic:

  1. Check the asset. If the asset is associated to an SLA, then use that ID.

  2. If there is no Asset SLA, then check the Contract Service or Bundle SLA. If the Contract Service or Bundle is associated to an SLA, then use that ID.

  3. If there is no Contract Service or Bundle SLA, then check the Contract. If the Contract is associated to an SLA, then use that ID.

  4. If no asset or contract SLA, then check the Ticket Category. If the ticket category is associated to an SLA, then use that ID.

ServiceLevelAgreementPausedNextEventHours ServiceLevelAgreementPausedNextEventHours (read only) is calculated as the time differential between the most recent time the ticket status changed to Waiting Customer and the time of the next SLA target. Calculated in hours only. Field is cleared when ticket comes out of Waiting Customer status and is recalculated every time ticket goes back into Waiting Customer status.
Source Ticket.Source is not required; however, in the UI the Source field defaults to 'Other', so for tickets created through the UI, the value for Ticket.Source is never Null. If no value is provided for Ticket.Source when a ticket is created via the API, the default Source value is returned on update. For additional information, refer to SOAP API best practices.
Ticket.AccountID If Ticket.AccountID is updated then Ticket.AccountPhysicalLocation must have AccountID = Ticket.AccountID.
TicketCategory

The Ticket entity will support the Ticket Category:

  • If no TicketCategory is passed in, the API will use the logged in resource's default category; if the resource does not have a default category, the API will use the Company's system default ticket category.
  • TicketCategory default values will be applied unless another value is passed in.
  • Ticket cannot be created with an inactive TicketCategory.
  • On update, a TicketCategory cannot be updated to another TicketCategory that is inactive.
  • In Picklist, an inactive TicketCategory displays in italic text.
  • The API does not respect the TicketCategory's 'required' and 'available list item' settings, with the exception of the 'Queue is Required' setting.
  • When a ticket category is applied and it changes the value of ChangeApprovalType, the field will be updated even if the ticket type does not = ChangeApproval.
  • While this is not possible in the UI, in the API, you can create tickets with a ticket category of 'API.'
  • The following fields are not editable when ticket category is RMA: AccountID, InstalledProductID, TicketType.

TicketNumber

  • On create(), you can specify a ticket number prefix for this resource.
  • The prefix must follow the format 'TYYYYMMDD.' For example, 'T20200615.'
  • The 'YYYYMMDD' value must be a date less than or equal to today's date.

  • If the API receives an invalid prefix, it will automatically generate one and assign it to the resource.
  • You cannot change a resource's ticket number prefix once created.
  • Autotask will automatically assign the record number that follows the prefix. For example, 'T20200615.0674.'

TicketType
  • Tickets with no TicketType specified are set automatically to Service Request.
  • Tickets where Type = Service Request cannot be associated with a ProblemTicket ID. If TicketType = Service Request and the ticket also specifies a ProblemTicketID, the ticket type is updated to Service Request. An error message indicates that Service Request tickets cannot be associated with a problem ticket.
  • TicketType must = Incident before the ticket can be associated with a ProblemTicketID.
  • If TicketType = Problem and incidents are associated with the ticket, TicketType cannot be changed to Incident or Service Request until the incidents are disassociated from the ticket.
  • You cannot create a ticket with TicketType = Problem and specify a ProblemTicket ID or specify ProblemTicketID for an existing Ticket with TicketType=Problem; that is, a ticket that is already a problem ticket cannot become an incident to another problem ticket.
  • If TicketType = ChangeRequest, ProblemTicketID cannot have a value.
  • If a ticket has TicketType not equal to 'Change Request' and it has data in one or more the fields that are exclusive to Change Request tickets, then the ticket can be saved. Although the data will remain intact and will be reportable, it will not be viewable in the ticket in Autotask. This includes the following fields: ChangeApprovalBoard, ChangeApprovalType, ChangeApprovalStatus, ChangeInfoField1, ChangeInfoField2, ChangeInfoField3, ChangeInfoField4, ChangeInfoField5.
  • The ChangeManagement module must be enabled to create a new ticket with TicketType = Change Request. Any existing Change Request tickets can be edited. Other fields related to change request will accept values when Change Management is not enabled, but that data will not be available through the UI.
  • If the ticket catgeory = 'RMA', the TicketType is set to 'Change Request', regardless of the value that is supplied.

Field definitions

Field Name Label Datatype Read Only Is Required Reference Name Picklist
AccountID {LT:Account} integer   Account  
AccountPhysicalLocationID Account Physical Location ID integer     AccountPhysicalLocation  

AEMAlertID

AEM Alert ID

string (50)

 

 

 

 

AllocationCodeID Allocation Code Name integer     AllocationCode  
ApiVendorID API Vendor ID integer    
AssignedResourceID Resource integer     Resource  
AssignedResourceRoleID Resource Role Name integer     Role  
BusinessDivisionSubdivisionID Business Division Subdivision ID integer     Ticket  
ChangeApprovalBoard Change Approval Board ID integer      
ChangeApprovalStatus Change Approval Status integer      
ChangeApprovalType Change Approval Type integer      
ChangeInfoField1 Change Info Field 1 string (8000)        
ChangeInfoField2 Change Info Field 2 string (8000)        
ChangeInfoField3 Change Info Field 3 string (8000)        
ChangeInfoField4 Change Info Field 4 string (8000)        
ChangeInfoField5 Change Info Field 5 string (8000)        
CompletedByResourceID Ticket Completed By integer   Resource  
CompletedDate Ticket Date Completed by Complete Project Wizard datetime      
ContactID Ticket Contact integer     Contact  
ContractID Contract integer     Contract  
ContractServiceBundleID Contract Service Bundle ID long     ContractServiceBundle  
ContractServiceID Contract Service ID long     ContractService  
CreateDate Ticket Creation Date datetime      

CreatedByContactID

Created by Contact ID

integer

 

 

Contact

 

CreatorResourceID Ticket Creator integer   Resource  
CreatorType Creator Type integer    
CurrentServiceThermometerRating Current Service Thermometer Rating integer    
Description Ticket Description string (8000)        
DueDateTime Ticket End Date datetime      
EstimatedHours Ticket Estimated Hours double        
ExternalID Ticket External ID string (50)        
FirstResponseAssignedResourceID First Response Assigned Resource ID integer      
FirstResponseDateTime First Response Date Time datetime      
FirstResponseDueDateTime First Response Due Date Time datetime      
FirstResponseInitiatingResourceID First Response Initiating Resource ID integer      
HoursToBeScheduled Hours To Be Scheduled decimal      
id Ticket ID long    
ImpersonatorCreatorResourceID Impersonator Creator Resource ID integer   Resource

 

InstalledProductID {LT:InstalledProduct} integer     InstalledProduct  
IssueType Ticket Issue integer      
LastActivityDate Ticket Last Activity Date datetime      
LastActivityPersonType Last Activity Person Type integer    
LastActivityResourceID Last Activity ResourceID integer   Resource  
LastCustomerNotificationDateTime Last Customer Notification DateTime datetime      
LastCustomerVisibleActivityDateTime Last Customer Visible Activity DateTime datetime      
LastTrackedModificationDateTime Last Tracked Modification Date Time datetime      
MonitorID
(Datto RMM integration only)
Monitor ID integer      
MonitorTypeID
(Datto RMM integration only)
Monitor Type ID integer      
OpportunityId Opportunity ID integer     Opportunity  
PreviousServiceThermometerRating Previous Service Thermometer Rating integer    
Priority Ticket Priority integer    
ProblemTicketId Problem Ticket ID integer     Ticket  
ProjectID Project ID integer     Project  
PurchaseOrderNumber Purchase Order Number string (50)        
QueueID Ticket Department Name OR Ticket Queue Name integer      
Resolution Resolution string (32000)        
ResolutionPlanDateTime Resolution Plan Date Time datetime      
ResolutionPlanDueDateTime Resolution Plan Due Date Time datetime      
ResolvedDateTime Resolved Date Time datetime      
ResolvedDueDateTime Resolved Due Date Time datetime      
RMAStatus RMA Status integer      

RMAType

RMA Type

integer

 

 

 

RMMAlertID
(Datto RMM integration only)
RMM Alert ID string
(50)
     
ServiceLevelAgreementHasBeenMet Has Met SLA boolean      
ServiceLevelAgreementID Service Level Agreement ID integer      
ServiceLevelAgreementPausedNextEventHours Service Level Agreement Paused Next Event Hours decimal      
ServiceThermometerTemperature Service Thermometer Temperature integer      
Source Ticket Source integer      
Status Ticket Status integer    
SubIssueType Ticket Subissue Type integer      
TicketCategory Ticket Category integer      
TicketNumber Ticket Number string (50)        
TicketType Ticket Type integer      
Title Ticket Title string (255)