Datto Autotask PSA
LAST UPDATED: 05/30/2024
Overview
Datto's Autotask PSA is a cloud-based professional services automation platform which provides a singular view of the entire business and enables MSPs to centralize business operations.
D3 SOAR is providing REST operations to function with Datto Autotask PSA.
For example, you can use Datto AutoTask as the support ticketing system and the solution to track billable and non-billable time to jobs. You can also use it to schedule recurring activities that occur daily, weekly, monthly, quarterly, or annually. Additionally, the customizable dashboards allow you to keep a handle on your workload.
Datto Autotask PSA is available for use in:
Known Limitations
The API size limit for individual attachment files is 6 to 7 MB, with a maximum of 10,000,000 bytes within a five-minute period. If your integration exceeds either of these limits, you'll receive an error message indicating the condition. If the integration exceeds 10,000,000 bytes within a five-minute span, the API will also stop accepting attachment creation calls for five minutes.
To ensure an acceptable response time for all REST API users and prevent inadvertent coding errors from crippling the system, Autotask PSA sets a limit of 10,000 on the number of external requests allowed per hour between an individual database and the API.
On query, Autotask PSA returns no more than 500 records per entity at once, sorted by internal ID.
You can include up to 500 OR conditions in a single call to the API.
Please refer to the REST API supportability and query thresholds for detailed information.
Connection
To connect Datto Autotask PSA from D3 SOAR, please follow this part to collect the required information below:
Parameter | Description | Example |
Username | The account user name to authenticate the connection. | test@example.com |
Password | The password to authenticate the connection. | H#****K*N0$bj@G6S3~*****~$ |
API Version | The version of the API to use for the connection. | v1.0 |
Reader Note
The prerequisite to establishing a working integration connection is a configured Datto Autotask PSA account. Additionally, an API user must be created for the purpose of establishing the connection. Ensure the user is active and not locked.
Permission Requirements
Each endpoint in the Datto Autotask PSA API requires a certain permission scope. The following scopes are required scopes for each command in this integration:
You'll need to use the API User (API-only) or API User (system) Can't Read Costs security level to access the REST API. It provides full system administrator access to Autotask PSA modules, features, and data via the Autotask REST API, with no access to the Autotask UI.
Reader Note
Two similar but different default system security levels are available for API user accounts:
API User (system) - Use this system security level for resources and integration partners who will work with integrations via the API and do not need to access Autotask PSA via the UI. The API User (system) security level grants full access to all Autotask PSA data, including internal costs, for the roles to which it belongs.
API User (system) Can't Read Costs - If you need to grant API User access to an integration partner, but you prefer that they not have the ability to view your internal cost data, select this security level. The API User (system) Can’t Read Costs role has to access all data for the roles to which it belongs, but calls to Query will return no data for cost fields. The API will also ignore calls to Update cost fields.
Please refer to Defining an API User and System Security Levels for more API permission details.
Configuring Datto Autotask PSA to Work with D3 SOAR
Log in to Datto Autotask PSA at https://webservices2.autotask.net.
Hover over the hamburger menu icon located near the top left corner and select Admin > Account Settings & Users.
Under the Account Settings & Users tab, open the Resources/Users (HR) section.
Select Resources/Users.
Click on the arrow beside the + New button and select New API User.
Add a new API user.
General
Provide the user's First Name, Last Name and Email Address.
Select the Security Level as API User (system) from the options available. See System Security Levels for more information.
Select the Primary Internal Location.
Credentials
Generate a key by clicking Generate Key. This key will be used as the username to connect with D3 SOAR.
Generate a secret by clicking Generate Secret. This secret will be used as the password to connect with D3 SOAR.
Copy and save both the username (key) and password (secret) for later use.
API Tracking Identifier.
Select Integration Vendor.
Select "D3 Security - Security" as the integration vendor.
Note: When using REST API with API-only users, it is necessary to provide a tracking identifier. As such, the API Tracking Identifier section must be completed when creating an API user account. Please note that the tracking identifier cannot be modified once the API user is created. For more information, see REST API Security and Authentication.
Line of Business
Select "General > IT Services" and "General". Select the right Line of Business pairings for this user and click the right arrow. The pairings will move to the Associated tab.
To complete the process, click Save & Close.
Reader Note
For more information about the creating and managing API users, see Adding or editing an API user.
Configuring D3 SOAR to Work with Datto Autotask PSA
Log in to D3 SOAR.
Find the Datto Autotask PSA integration.
Navigate to Configuration on the top header menu.
Click on the Integration icon on the left sidebar.
Type Datto Autotask PSA in the search box to find the integration, then click it to select it.
Click + Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Datto Autotask PSA.
Connection Name: The desired name for the connection.
Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.
Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
Description (Optional): Add your desired description for the connection.
Configure User Permissions: Defines which users have access to the connection.
Active: Check the tick box to ensure the connection is available for use.
System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
1. Input your Username. This is the key generated from Datto Autotask PSA. See step 6b of Configuring Datto Autotask PSA to Work with D3 SOAR for more information.
2. Input your Password. This is the secret generated from Datto Autotask PSA. See step 6b of Configuring Datto Autotask PSA to Work with D3 SOAR for more information.
3. Input your API Version. The default value is v1.0.Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Please refer to the password vault connection guide if needed.
Connection Health Check: Updates the connection status you have created. A connection health check is done by scheduling the Test Connection command of this integration. This can only be done when the connection is active.
To set up a connection health check, check the Connection Health Check tickbox. You can customize the interval (minutes) for scheduling the health check. An email notification can be set up after a specified number of failed connection attempts.
Test the connection.
Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green checkmark appear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.
Click OK to close the alert window.
Click + Add to create and add the configured connection.
Commands
Datto Autotask PSA includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, you can execute these commands independently for playbook troubleshooting.
Integration API Note
For more information about the Datto Autotask PSA API, please refer to General information about Autotask APIs and Swagger for Autotask PSA.
Reader Note
Certain permissions are required for each command. Please refer to the Permission Requirements and Configuring Datto Autotask PSA to Work with D3 SOAR for details.
Add Ticket Note
Adds a new note to the specified ticket.
Reader Note
Ticket ID is a required parameter to run this command.
Run the List Entities command with selection of "Tickets" in the Entity Name field. Ticket IDs can be obtained from the returned raw data at the path $.items[*].id.
Input
Input Parameter | Required/Optional | Description | Example |
Ticket ID | Required | The ID of the ticket to add a note. Ticket ID can be obtained using the List Entities command with selection of "Tickets" in the Entity Name field. | *** |
Note Title | Required | The title for the ticket note. | Test |
Note Description | Required | The description for the ticket note. | internal note. |
Publish Type | Optional | The publication type of the note. The available publication types are All Autotask Users - 1, Internal Project Team - 2 and Internal & Co-Managed - 4. | Internal Project Team - 2 |
Note Type | Optional | The type of note (i.e., Task Summary - 1, Task Detail - 2 and Task Notes - 3) being created. | Task Summary - 1 |
Output
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Add Ticket Note failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Datto Autotask PSA portal. Refer to the HTTP Status Code Registry for details. | Status Code: 500. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Ticket does not exist or is invalid. |
Error Sample Data Add Ticket Note failed. Status Code: 500. Message: Ticket does not exist or is invalid. |
Close Ticket
Closes ticket(s) in Datto Autotask PSA.
Reader Note
Ticket ID or Ticket Number is a required parameter to run this command.
Run the List Entities command with the Entity Name parameter set to "Tickets" to obtain Ticket IDs. Ticket IDs can be obtained from the returned raw data at the path $.items[*].id.
Ticket numbers can be obtained from the Datto Autotask PSA platform or with the List Entities command with the Entity Name parameter set to "Tickets".
Input
Input Parameter | Required/Optional | Description | Example |
Ticket ID Or Number | Required | The ID or ticket number of the ticket to close. Ticket IDs can be obtained using the List Entities command with selection of "Tickets" in the Entity Name field. Ticket numbers can be obtained from the Datto Autotask PSA platform or with the List Entities command with selection of "Tickets" in the Entity Name field. | "T**.**" (Ticket Number) "***" (Ticket ID) |
Output
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Close Ticket failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Datto Autotask PSA portal. Refer to the HTTP Status Code Registry for details. | Status Code: 404. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: The provided ticket id or number can not be found. |
Error Sample Data Close Ticket failed. Status Code: 404. Message: The provided ticket id or number can not be found. |
Create Ticket
Creates a ticket in Datto Autotask PSA.
Reader Note
Company ID is a required parameter to run this command.
Run the Get Company By Name command to obtain Company ID. Company IDs can be obtained from the returned raw data at the path $.items[*].id.
Input parameter Additional Settings is optional to input for this command.
Run the Get Entity Information command to view the list of picklist field names and values.
Input
Input Parameter | Required/Optional | Description | Example |
Title | Required | The title of the ticket. | Test Ticket |
Description | Optional | The description for the ticket. | Create a sample ticket |
Company ID | Required | The company ID associated with the ticket. Company IDs can be obtained using the Get Company By Name command. | *** |
Priority | Required | The priority level of the ticket. The built-in priority levels are Critical, High, Medium and Low. | High |
Status | Required | The status of the ticket. The built-in statuses are New, Complete, and Waiting Customer. | New |
Queue | Required | The queue for the ticket. The built-in queues are Client Portal, Post Sale, and Monitoring Alert. | Client Portal |
Work Type | Optional | The work type of the ticket, mapped to the allocation code. The available work types can be viewed from the Datto Autotask PSA platform. | IT:Emergency (Non-Billable) |
Service Level Agreement | Optional | The service level agreement associated with the ticket. The built-in SLAs are IT:Basic SLA, IT:Premium SLA, and SW: Internal Support SLA. | IT:Basic SLA |
Ticket Category | Optional | The category of the ticket. The built-in categories Standard (non-editable), AEM Alert, Standard, Datto Alert and RMA. The default value is Standard. | AEM Alert |
Ticket Type | Optional | The type of ticket being created. The built-in ticket types are Service Request, Incident, Problem, Change Request and Alert. The default value is Service Request. | Alert |
Source | Optional | The source of ticket information. The built-in sources are Insourced, Client Portal, Internal, Phone, Email, Web Portal, In Person/Onsite and Monitoring Alert. | |
Additional Settings | Optional | The JSON object containing the additional fields and values of the ticket. You can view the list of picklist field names and values using the Get Entity Information command. | { "billingCodeID": ***, "contractID": *** } |
Output
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Create Ticket failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Datto Autotask PSA portal. Refer to the HTTP Status Code Registry for details. | Status Code: 403. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Local variable 'resultData' referenced before assignment. |
Error Sample Data Create Ticket failed. Status Code: 403. Message: Local variable 'resultData' referenced before assignment. |
Create Time Entry
Creates a time entry in Datto Autotask PSA.
Reader Note
Resource ID is a required parameter to run this command.
You can obtain resource IDs from the Datto Autotask PSA platform by navigating to ADMIN > Account Settings & Users > Resources/Users.
At least one of the Task Number Or ID or the Ticket Number Or ID parameters must be defined.
You can obtain the Task Number or ID from the Datto Autotask PSA platform by navigating to DASHBOARD > Project Manager - Tasks.
Run the List Entities command with the Entity Name parameter set to "Tickets" to obtain Ticket IDs. Ticket IDs can be obtained from the returned raw data at the path $.items[*].id. Ticket numbers can be obtained from the Datto Autotask PSA platform or with the List Entities command with the Entity Name parameter set to "Tickets".
Input parameter Additional Settings is optional to input for this command.
Run the Get Entity Information command to view the list of picklist field names and values.
When the Ticket ID parameter is defined, the Start Time and End Time parameters must also be defined.
When the Start Time parameter is not defined, the Date Worked parameter must be defined.
Input
Input Parameter | Required/Optional | Description | Example |
Resource ID | Required | The unique ID of the resource (i.e. employees, contractors, or consultants) associated with the time entry. Resource IDs can be obtained from the Datto Autotask PSA platform by navigating to ADMIN > Account Settings & Users > Resources/Users. | *** |
Task Number Or ID | Optional | The unique ID or number of the time entry's corresponding task. At least one of the Task Number Or ID or Ticket Number Or ID parameters must be defined. Tasks are linked to a specific project and outline the required work. The task number can be obtained from the Datto Autotask PSA platform by navigating to DASHBOARD > Project Manager - Tasks. | T***.*** |
Billing Code | Required | The code representing the category of billing items associated with the time entry. The built-in billing codes are Work Types, Material, Internal Time, Expense Categories, Recurring Contract Service, and Milestone. Users have the option to create their own billing codes. Billing codes can be obtained from the Datto Autotask PSA platform by navigating to ADMIN > Features & Settings > FINANCE, ACCOUNTING, INVOICING > BILLING CODES. | SW:Project (Non-Billable) |
Date Worked | Optional | The date for the work to be completed. This parameter is required when the Start Time parameter is not defined. | 2021-08-07 00:00:00 |
Hours Worked | Optional | The amount of hours for the work to be completed. If this parameter is not defined, the value will be the difference between the start and end times (i.e., Hours Worked = Start Time - End Time). | 4.00 |
Summary Notes | Required | The summary notes for the time entry. | Test Summary |
Ticket Number Or ID | Optional | The unique ID or number of the time entry's corresponding ticket. At least one of the Task Number Or ID or Ticket Number Or ID parameters must be defined. If you are creating a time entry for a ticket, both the Start Time and End Time input parameters are required, and the time duration between these two values cannot exceed 24 hours. Ticket IDs can be obtained using the List Entities command with selection of "Tickets" in the Entity Name field. Ticket numbers can be obtained from the Datto Autotask PSA platform or with the List Entities command with selection of "Tickets" in the Entity Name field. | *** |
Start Time | Optional | The start time of the time entry. This parameter is required when you are creating a time entry for a ticket. The time duration between the start time and end time values cannot exceed 24 hours. | 2022-04-01 15:45:00 |
End Time | Optional | The end time of the time entry. This parameter is required when you are creating a time entry for a ticket. The time duration between the start time and end time values cannot exceed 24 hours. | 2022-04-01 16:45:00 |
Additional Settings | Optional | The JSON object containing the additional fields and values of the time entry. You can view the list of picklist field names and values using the Get Entity Information command. | { "contractID": ***, "internalNotes": "internalNotes1" } |
Output
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Create Time Entry failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Datto Autotask PSA portal. Refer to the HTTP Status Code Registry for details. | Status Code: 500. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Must have at least one of TimeEntry. |
Error Sample Data Create Time Entry failed. Status Code: 500. Message: Must have at least one of TimeEntry. |
Delete Attachments
Delete attachments matching the specified criteria.
Reader Note
Entity ID and Attachment IDs are required parameters to run this command.
Run the List Entities command to obtain Entity ID. Entity IDs can be obtained from the returned raw data at the path $.items[*].id.
Run the List Entities command with the Include Attachments parameter set to True to obtain Attachment IDs. Attachment IDs can be obtained from the returned raw data at the path $.items[*].id.
Alert
The input Entity ID must match its corresponding Entity Name. For example, if the Entity Name is "Task," the Entity ID should be a task entity ID. An error message indicating an "Invalid ParentType/ParentID combination" will be returned if a mismatch occurs.
By default, the Entity Name is "Tickets." If you leave the Entity Name or Custom Entity Name parameter blank, you can only input a ticket entity ID.
It is recommended first to use the List Entities command to identify your desired Entity Name and corresponding Entity ID pair, then input them into this command.
Input
Input Parameter | Required/Optional | Description | Example |
Entity Name | Optional | The entity name to filter the entities to delete attachments. The available options are Tasks, Tickets and Time Entries. This parameter will be omitted when the Custom Entity Name parameter is defined. The default value of this parameter is Tickets. | Tickets |
Custom Entity Name | Optional | The additional entity name (not listed in the previous parameter) to filter the entities to delete attachments. Some examples of custom entity names are companies and services. | companies |
Entity ID | Required | The ID of the entity to delete attachments. Entity IDs can be found using the List Entities command. | *** |
Attachment IDs | Required | The IDs of the attachments to delete. Attachment IDs can be obtained using the List Entities command with the Include Attachments parameter set to True. | [ ***, ***] |
Output
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Delete Attachments failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Datto Autotask PSA portal. Refer to the HTTP Status Code Registry for details. | Status Code: 500. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Invalid attachment id (*). Attachment does not exist. |
Error Sample Data Delete Attachments failed. Status Code: 500. Message: Invalid attachment id (*). Attachment does not exist. |
Delete Time Entries
Deletes the specified time entries in Datto Autotask PSA.
Reader Note
The parameter Time Entry IDs is required to run this command.
Run the List Entities command with Time Entries selected for the Entity Name parameter to obtain Time Entry ID. Time Entry IDs can be obtained from the returned raw data at the path $.items[*].id.
Input
Input Parameter | Required/Optional | Description | Example |
Time Entry IDs | Required | The IDs of the time entries to delete. Entity IDs can be found using the List Entities command with "Time Entries" selected for the Entity Name parameter. | [ ***, ***] |
Output
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Delete Time Entries failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Datto Autotask PSA portal. Refer to the HTTP Status Code Registry for details. | Status Code: 500. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: You do not have permission to delete time entries that you did not create. |
Error Sample Data Delete Time Entries failed. Status Code: 500. Message: You do not have permission to delete time entries that you did not create. |
Get Company By Name
Returns details about a company based on its name.
Input
Input Parameter | Required/Optional | Description | Example |
Company Name | Required | The name of the company to retrieve details. | Unicorn |
Is Exact Match | Optional | The option to perform the search for an exact match, when set to True. A search using partial match will be performed when this parameter is set to False. | False |
Output
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Get Company By Name failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Datto Autotask PSA portal. Refer to the HTTP Status Code Registry for details. | Status Code: 401. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Unauthorized. Please check your connector parameters. |
Error Sample Data Get Company By Name failed. Status Code: 401. Message: Unauthorized. Please check your connector parameters. |
Get Entity Information
Returns field information for the selected entity.
Input
Input Parameter | Required/Optional | Description | Example |
Entity Name | Optional | The name of the entity to retrieve information from. The available options are Tasks, Tickets and Time Entries. This parameter will be omitted when the Custom Entity Name parameter is defined. | Tickets |
Custom Entity Name | Optional | The additional entity name (not listed in the previous parameter) to filter the entities to return information from. Some examples of custom entity names are companies and services. | companies |
Output
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Get Entity Information failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Datto Autotask PSA portal. Refer to the HTTP Status Code Registry for details. | Status Code: 404. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Incorrect Entity Name provided. |
Error Sample Data Get Entity Information failed. Status Code: 404. Message: Incorrect Entity Name provided. |
Get Tickets
Returns details on the specified ticket(s).
Reader Note
The parameter Ticket IDs is required to run this command.
Run the List Entities command with the Entity Name parameter set to "Tickets" to obtain Ticket IDs. Ticket IDs can be obtained from the returned raw data at the path $.items[*].id.
Input
Input Parameter | Required/Optional | Description | Example |
Ticket IDs | Required | The IDs of the tickets to retrieve details. Ticket IDs can be obtained using the List Entities command with selection of "Tickets" in the Entity Name field. | [ "***", "***" ] |
Output
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Get Tickets failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Datto Autotask PSA portal. Refer to the HTTP Status Code Registry for details. | Status Code: 404. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Not Found. The resource you are looking for might have been removed, had its name changed, or is temporarily unavailable. |
Error Sample Data Get Tickets failed. Status Code: 404. Message: Not Found. The resource you are looking for might have been removed, had its name changed, or is temporarily unavailable. |
Get Time Entries
Returns details on the specified time entries.
Reader Note
The parameter Time Entry IDs is required to run this command.
Run the List Entities command with the Entity Name parameter set to "Time Entries" to obtain Time Entry IDs. Time Entry IDs can be obtained from the returned raw data at the path $.items[*].id.
Input
Input Parameter | Required/Optional | Description | Example |
Time Entry IDs | Required | The IDs of the time entries to retrieve. Time Entry IDs can be obtained using the List Entities command with the Entity Name parameter set to "Time Entries". | [ ** ] |
Output
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Get Time Entries failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Datto Autotask PSA portal. Refer to the HTTP Status Code Registry for details. | Status Code: 401. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: 'timeEntryIDs' is not valid json input. |
Error Sample Data Get Time Entries failed. Status Code: 401. Message: 'timeEntryIDs' is not valid json input. |
List Entities
Retrieves entities (tasks, tickets, time entries etc.) based on the given search conditions.
Input
Input Parameter | Required/Optional | Description | Example |
Entity Name | Optional | The name of the entity to return. The available options are Tasks, Tickets and Time Entries. This parameter will be omitted when the Custom Entity Name parameter is defined. | Tickets |
Custom Entity Name | Optional | The additional entity name (not listed in the previous parameter) to filter the entities to return. Some examples of custom entity names are companies and services. | companies |
Filter | Required | The query statement to filter the returned entities. The filter can be defined with D3's simple Lucene query syntax or the Datto Autotask query syntax, as a JSON object. The queryable fields can be obtained using the Get Entity Info command. Lucene Query Syntax: Defined with a series of field-operator-value tuples (e.g. "(resourceId eq 29683994) AND (summaryNotes contains \"test_summary\") AND (hoursWorked eq 6.00)"), where the values may include special characters that must be enclosed in double quotations. For the list of available operators, see Making basic query calls to the REST API. Datto Autotask Syntax: Defined with a JSON array containing filter conditions objects, each containing three key-value pairs specifying the operation to perform, the field to perform the operation on, and the value to use for the operation. For more information, see Making basic query calls to the REST API from Datto's documentation. | (resourceId eq ***) AND (summaryNotes contains \"test_summary\") AND (hoursWorked eq 6.00) |
Limit | Optional | The maximum number of entity records to return. When the input value is 0, a negative number, or not defined, the command will return the 500 results matching the search conditions. | 20 |
Include Attachments | Optional | The option to include attachments of the returned entities, when set to True. If False is selected, only the entity information will be returned.The default setting is False. | True |
Output
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | List Entities failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Datto Autotask PSA portal. Refer to the HTTP Status Code Registry for details. | Status Code: 404. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Wrong syntax is used. |
Error Sample Data List Entities failed. Status Code: 404. Message: Wrong syntax is used. |
Query Time Entries
Searches time entries with the specified criteria.
Input
Input Parameter | Required/Optional | Description | Example |
Filter | Required | The query statement to filter the returned time entries. The filter can be defined with D3's simple Lucene query syntax or the Datto Autotask query syntax, as a JSON object. The queryable fields can be obtained using the Get Entity Info command. Lucene Query Syntax: Defined with a series of field-operator-value tuples (e.g. "resourceId=29683994 summaryNotes="test summary" hoursWorked=6.00 "), where the values may include special characters that must be enclosed in double quotations. For the list of available operators, see Making basic query calls to the REST API. Datto Autotask Syntax: Defined with a JSON array containing filter conditions objects, each containing three key-value pairs specifying the operation to perform, the field to perform the operation on, and the value to use for the operation. For more information, see Making basic query calls to the REST API from Datto's documentation. | resourceId=***summaryNotes="test summary" hoursWorked=6.00 |
Limit | Optional | The maximum number of time entries to return. | 20 |
Output
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Query Time Entries failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Datto Autotask PSA portal. Refer to the HTTP Status Code Registry for details. | Status Code: 500. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Conversion failed when converting the varchar value '****' to data timeEntryType int. |
Error Sample Data Query Time Entries failed. Status Code: 500. Message: Conversion failed when converting the varchar value '****' to data timeEntryType int. |
Update Ticket
Updates ticket(s) in Datto Autotask PSA.
Reader Note
Ticket ID or Ticket Number is a required parameter to run this command.
Run the List Entities command with the Entity Name parameter set to "Tickets" to obtain Ticket IDs. Ticket IDs can be obtained from the returned raw data at the path $.items[*].id.
Ticket numbers can be obtained from the Datto Autotask PSA platform or with the List Entities command with the Entity Name parameter set to "Tickets".
Input
Input Parameter | Required/Optional | Description | Example |
Ticket ID Or Number | Required | The ID or ticket number of the ticket to update. Ticket IDs can be obtained using the List Entities command with selection of "Tickets" in the Entity Name field. Ticket numbers can be obtained from the Datto Autotask PSA platform or with the List Entities command with selection of "Tickets" in the Entity Name field. | "T***" (Ticket Number) "**" (Ticket ID) |
Title | Required | The updated title of the ticket. | Update a ticket |
Description | Optional | The updated description for the ticket. | Update a ticket |
Priority | Optional | The updated priority level of the ticket. The built-in priority levels are Critical, High, Medium and Low. | High |
Status | Optional | The updated status of the ticket. The built-in statuses are New, Complete, and Waiting Customer. | New |
Queue | Required | The queue for the ticket. The built-in queues are Client Portal, Post Sale, and Monitoring Alert. | Client Portal |
Billing Code | Optional | The code representing the category of billing items associated with the time entry. The built-in billing codes are Work Types, Material, Internal Time, Expense Categories, Recurring Contract Service, and Milestone. Users have the option to create their own billing codes. Billing codes can be obtained from the Datto Autotask PSA platform by navigating to ADMIN > Features & Settings > FINANCE, ACCOUNTING, INVOICING > BILLING CODES. | SW:Project (Non-Billable) |
Contact Email | Optional | The email address to reach the contact person. | "test@example.com" |
Due Date | Optional | The due date of the ticket. | 2021-09-10 18:00:05 |
Additional Settings | Optional | The updated additional fields and values of the ticket. The additional settings can be defined with D3's simple Lucene query syntax, the Datto Autotask query syntax, as a JSON object.You can view the list of picklist field names and values using the Get Entity Information command. Lucene Query Syntax: Defined with a series of field-operator-value tuples (e.g. "ticketCategory= 3 subIssueType= 156 estimatedHours= 3.5"), where the values may include special characters that must be enclosed in double quotations. For the list of available operators, see Making basic query calls to the REST API. Datto Autotask Syntax: Defined with a JSON array containing filter conditions objects, each containing three key-value pairs specifying the operation to perform, the field to perform the operation on, and the value to use for the operation. For more information, see Making basic query calls to the REST API from Datto's documentation. | Lucene Query Syntax: ticketCategory=3 subIssueType=156 estimatedHours= 3.5 Datto Autotask Syntax: { "billingCodeID": **, "contractID": *** } |
Output
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Update Ticket failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Datto Autotask PSA portal. Refer to the HTTP Status Code Registry for details. | Status Code: 500. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: No matching records found. Please verify the id and/or parentId supplied in the endpoint URL. |
Error Sample Data Update Ticket failed. Status Code: 500. Message: No matching records found. Please verify the id and/or parentId supplied in the endpoint URL. |
Update Time Entry By ID
Updates the specified time entries.
Reader Note
Time Entry ID and Resource ID are required parameters to run this command.
Run the List Entities command with Time Entries selected for the Entity Name parameter to obtain Time Entry IDs. Time Entry IDs can be obtained from the returned raw data at the path $.items[*].id.
Resource IDs can be obtained from the Datto Autotask PSA platform by navigating to ADMIN > Account Settings & Users > Resources/Users.
Input parameter Additional Settings is optional to input for this command.
Run the Get Entity Information command to view the list of picklist field names and values.
Input
Input Parameter | Required/Optional | Description | Example |
Time Entry ID | Required | The ID of the time entry to update. Time Entry IDs can be obtained using the List Entities command with "Time Entries" selected for the Entity Name parameter. | ** |
Resource ID | Required | The unique ID of the resource (i.e. employees, contractors, or consultants) associated with the time entry. Resource IDs can be obtained from the Datto Autotask PSA platform by navigating to ADMIN > Account Settings & Users > Resources/Users. | *** |
Billing Code | Optional | The code representing the category of billing items associated with the time entry. The built-in billing codes are Work Types, Material, Internal Time, Expense Categories, Recurring Contract Service, and Milestone. Users have the option to create their own billing codes. Billing codes can be obtained from the Datto Autotask PSA platform by navigating to ADMIN > Features & Settings > FINANCE, ACCOUNTING, INVOICING > BILLING CODES. | SW:Project (Non-Billable) |
Date Worked | Optional | The date for the work to be completed. | 2021-08-07 00:00:00 |
Hours Worked | Optional | The amount of hours for the work to be completed. Note: This value should be less than 24 hours. | 4.00 |
Summary Notes | Optional | The summary notes for the time entry. | Test Summary |
Additional Settings | Optional | The JSON object containing the additional fields and values of the time entry. You can view the list of picklist field names and values using the Get Entity Information command. | { "contractID": **, "internalNotes": "internalNotes1" } |
Output
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Update Time Entry By ID failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Datto Autotask PSA portal. Refer to the HTTP Status Code Registry for details. | Status Code: 500. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Resource does not exist or is invalid. |
Error Sample Data Update Time Entry By ID failed. Status Code: 500. Message: Resource does not exist or is invalid. |
Upload Attachment
Uploads an attachment to a specified entry (tasks, tickets, time entries etc.)
Reader Note
Entity ID is a required parameter to run this command.
Run the List Entities command to obtain Entity ID. Entity IDs can be obtained from the returned raw data at the path $.items[*].id.
Alert
The input Entity ID must match its corresponding Entity Name. For example, if the Entity Name is "Task," the Entity ID should be a task entity ID. An error message indicating an "Invalid ParentType/ParentID combination" will be returned if a mismatch occurs.
By default, the Entity Name is "Tickets." If you leave the Entity Name or Custom Entity Name parameter blank, you can only input a ticket entity ID.
It is recommended first to use the List Entities command to identify your desired Entity Name and corresponding Entity ID pair, then input them into this command.
It is not recommended to use the Test Command feature with the Submit Sample Files command as it is designed for dynamic input files in Playbooks, Incident Attachments, and Artifact Attachments. There is a simple workaround to test the command:
In D3 SOAR, navigate to Configuration on the top bar menu.
Click Utility Commands on the left sidebar menu.
Use the search box to find and select the Create a File from input Text Array command.
Select the Test tab, then input the required information for the parameters. Click Test Command.
A D3 File ID will appear in the output data after the file has been successfully created.
(Note: The D3 File Source of the created file will be Playbook File)
Input
Input Parameter | Required/Optional | Description | Example |
Entity Name | Optional | The name of the parent entity to upload the attachment to. The available options are Tasks, Tickets, Time Entries, and Others. This parameter will be omitted when the Custom Entity Name parameter is defined. The default value of this parameter is Tickets. | Tickets |
Entity ID | Required | The ID of the entity to upload the attachment. Entity IDs can be found using the List Entities command. Note: Your input Entity ID must match the Entity Name. | *** |
Custom Entity Name | Optional | The additional entity name (not listed in the previous parameter) to filter the entities to delete attachments. If this parameter has been defined, it will omit the value you input in the Entity Name parameter. Some examples of custom entity names are companies and services. | companies |
Title | Required | The title of the attachment object. | Test text to a ticket. |
File Name | Required | The file name or the full file link of the attachment file. | Test text to a ticket |
Attachment Type | Required | The attachment type of the attachment file. Note: If you choose the "File Attachment" option, File ID and File Source parameters must be defined. | File Attachment |
File ID | Optional | The file path of the file source. The options for file paths are: Incident Attachment: Incident.file.file ID Playbook File: Task output Artifact File: Incident.Events.file.file ID. | [ "***" ] |
File Source | Optional | The file source of the file to send. The options for file sources are: Incident Attachment File: Manually uploaded file from Incident Playbook File: Output from another Task Artifact File: Ingested Artifact in an Event. | Playbook File |
Output
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Upload Attachment failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Datto Autotask PSA portal. Refer to the HTTP Status Code Registry for details. | Status Code: 404. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: The specified File does not have file data. |
Error Sample Data Upload Attachment failed. Status Code: 404. Message: The specified File does not have file data. |
Test Connection
Allows you to perform a health check on an integration connection. You can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.
Input
N/A
Output
Error Handling
If the Return Data is failed, an Error tab will appear in the Test Result window.
The error tab contains the responses from the third-party API calls including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Test Connection failed. Failed to check the connector. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Datto Autotask PSA portal. Refer to the HTTP Status Code Registry for details. | Status Code: 401. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Unauthorized, Please check your Username, Password and API version. |
Error Sample Data Test Connection failed. Failed to check the connector. Status Code: 401. Message: Unauthorized, Please check your Username, Password and API version. |