Datto Autotask PSA

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:

D3 SOAR	V14.0.214.0+
Category	Case Management
Deployment Options	Option II, Option IV

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#***KN0$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.
1. General
  1. Provide the user's First Name, Last Name and Email Address.
  2. Select the Security Level as API User (system) from the options available. See System Security Levels for more information.
  3. Select the Primary Internal Location.
2. Credentials
  1. Generate a key by clicking Generate Key. This key will be used as the username to connect with D3 SOAR.
  2. Generate a secret by clicking Generate Secret. This secret will be used as the password to connect with D3 SOAR.
  3. Copy and save both the username (key) and password (secret) for later use.
3. API Tracking Identifier.
  1. Select Integration Vendor.
  2. 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.
4. Line of Business
  1. 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.
5. 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.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type Datto Autotask PSA in the search box to find the integration, then click it to select it.
4. 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.
1. Connection Name: The desired name for the connection.
2. 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.
3. 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.
4. 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.
5. Description (Optional): Add your desired description for the connection.
6. Configure User Permissions: Defines which users have access to the connection.
7. Active: Check the tick box to ensure the connection is available for use.
8. 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.
9. 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.
10. 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.
1. 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.
2. Click OK to close the alert window.
3. 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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "itemId": **
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "TicketID": "\"***\"",
    "NoteID": "\"***\""
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

AddedNoteCount

1

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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "item": {
        "id": ***,
        "apiVendorID": **,
        "assignedResourceID": null,
        "assignedResourceRoleID": null,
        "billingCodeID": ***,
        "changeApprovalBoard": null,
        "changeApprovalStatus": null,
        "changeApprovalType": null,
        "changeInfoField1": "",
        "changeInfoField2": "",
        "changeInfoField3": "",
        "changeInfoField4": "",
        "changeInfoField5": "",
        "companyID": **,
        "companyLocationID": **,
        "completedByResourceID": ***,
        "completedDate": "2022-06-06T16:29:43.103Z",
        "configurationItemID": null,
        "contactID": null,
        "contractID": null,
        "contractServiceBundleID": null,
        "contractServiceID": null,
        "createDate": "2021-09-10T21:23:41.773Z",
        "createdByContactID": null,
        "creatorResourceID": **,
        "creatorType": 1,
        "currentServiceThermometerRating": null,
        "description": "update an existing ticket",
        "dueDateTime": "2021-09-10T18:00:00Z",
        "estimatedHours": 3.5,
        "externalID": "",
        "firstResponseAssignedResourceID": null,
        "firstResponseDateTime": "2021-09-10T23:33:43.87Z",
        "firstResponseDueDateTime": null,
        "firstResponseInitiatingResourceID": null,
        "hoursToBeScheduled": 0,
        "impersonatorCreatorResourceID": null,
        "isAssignedToComanaged": false,
        "issueType": 13,
        "isVisibleToComanaged": false,
        "lastActivityDate": "2022-06-07T23:09:51.98Z",
        "lastActivityPersonType": 1,
        "lastActivityResourceID": ***,
        "lastCustomerNotificationDateTime": null,
        "lastCustomerVisibleActivityDateTime": null,
        "lastTrackedModificationDateTime": "2022-04-07T00:57:15.88Z",
        "monitorID": null,
        "monitorTypeID": null,
        "opportunityID": null,
        "organizationalLevelAssociationID": null,
        "previousServiceThermometerRating": null,
        "priority": 1,
        "problemTicketId": null,
        "projectID": null,
        "purchaseOrderNumber": "",
        "queueID": ***,
        "resolution": "",
        "resolutionPlanDateTime": "2021-09-10T23:33:43.87Z",
        "resolutionPlanDueDateTime": null,
        "resolvedDateTime": "2021-09-10T23:33:43.87Z",
        "resolvedDueDateTime": null,
        "rmaStatus": null,
        "rmaType": null,
        "rmmAlertID": null,
        "serviceLevelAgreementHasBeenMet": null,
        "serviceLevelAgreementID": null,
        "serviceLevelAgreementPausedNextEventHours": null,
        "serviceThermometerTemperature": null,
        "source": -1,
        "status": 5,
        "subIssueType": **,
        "ticketCategory": **,
        "ticketNumber": "T**.**",
        "ticketType": 1,
        "title": "Ticket creation with API for unicorn co",
        "userDefinedFields": []
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "TicketID": "\"**\"",
    "TicketNumber": "\"\\\"T***.**\\\"\"",
    "Status": "\"5\""
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

item

{'id': **, 'apiVendorID': **, 'assignedResourceID': None, 'assignedResourceRoleID': None, 'billingCodeID': **, 'changeApprovalBoard': None, 'changeApprovalStatus': None, 'changeApprovalType': None, 'changeInfoField1': '', 'changeInfoField2': '', 'changeInfoField3': '', 'changeInfoField4': '', 'changeInfoField5': '', 'companyID': **, 'companyLocationID': **, 'completedByResourceID': **, 'completedDate': '2022-06-06T16:29:43.103Z', 'configurationItemID': None, 'contactID': None, 'contractID': None, 'contractServiceBundleID': None, 'contractServiceID': None, 'createDate': '2021-09-10T21:23:41.773Z', 'createdByContactID': None, 'creatorResourceID': **, 'creatorType': 1, 'currentServiceThermometerRating': None, 'description': 'update an existing ticket', 'dueDateTime': '2021-09-10T18:00:00Z', 'estimatedHours': 3.5, 'externalID': '', 'firstResponseAssignedResourceID': None, 'firstResponseDateTime': '2021-09-10T23:33:43.87Z', 'firstResponseDueDateTime': None, 'firstResponseInitiatingResourceID': None, 'hoursToBeScheduled': 0.0, 'impersonatorCreatorResourceID': None, 'isAssignedToComanaged': False, 'issueType': 13, 'isVisibleToComanaged': False, 'lastActivityDate': '2022-06-07T23:09:51.98Z', 'lastActivityPersonType': 1, 'lastActivityResourceID': **, 'lastCustomerNotificationDateTime': None, 'lastCustomerVisibleActivityDateTime': None, 'lastTrackedModificationDateTime': '2022-04-07T00:57:15.88Z', 'monitorID': None, 'monitorTypeID': None, 'opportunityID': None, 'organizationalLevelAssociationID': None, 'previousServiceThermometerRating': None, 'priority': 1, 'problemTicketId': None, 'projectID': None, 'purchaseOrderNumber': '', 'queueID': **, 'resolution': '', 'resolutionPlanDateTime': '2021-09-10T23:33:43.87Z', 'resolutionPlanDueDateTime': None, 'resolvedDateTime': '2021-09-10T23:33:43.87Z', 'resolvedDueDateTime': None, 'rmaStatus': None, 'rmaType': None, 'rmmAlertID': None, 'serviceLevelAgreementHasBeenMet': None, 'serviceLevelAgreementID': None, 'serviceLevelAgreementPausedNextEventHours': None, 'serviceThermometerTemperature': None, 'source': -1, 'status': 5, 'subIssueType': **, 'ticketCategory': 3, 'ticketNumber': 'T**.**', 'ticketType': 1, 'title': 'Ticket creation with API for unicorn co', 'userDefinedFields': []}

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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "item": {
        "id": ***,
        "apiVendorID": ***,
        "assignedResourceID": null,
        "assignedResourceRoleID": null,
        "billingCodeID": ***,
        "changeApprovalBoard": null,
        "changeApprovalStatus": null,
        "changeApprovalType": null,
        "changeInfoField1": "",
        "changeInfoField2": "",
        "changeInfoField3": "",
        "changeInfoField4": "",
        "changeInfoField5": "",
        "companyID": ***,
        "companyLocationID": ***,
        "completedByResourceID": null,
        "completedDate": null,
        "configurationItemID": null,
        "contactID": null,
        "contractID": null,
        "contractServiceBundleID": null,
        "contractServiceID": null,
        "createDate": "2021-09-10T21:23:41.773Z",
        "createdByContactID": null,
        "creatorResourceID": ***,
        "creatorType": 1,
        "currentServiceThermometerRating": null,
        "description": "update an existing ticket",
        "dueDateTime": "2021-09-10T18:00:00Z",
        "estimatedHours": 3.5,
        "externalID": "",
        "firstResponseAssignedResourceID": null,
        "firstResponseDateTime": "2021-09-10T23:33:43.87Z",
        "firstResponseDueDateTime": null,
        "firstResponseInitiatingResourceID": null,
        "hoursToBeScheduled": 3.5,
        "impersonatorCreatorResourceID": null,
        "isAssignedToComanaged": false,
        "issueType": 13,
        "isVisibleToComanaged": false,
        "lastActivityDate": "2022-04-07T01:09:44.047Z",
        "lastActivityPersonType": 1,
        "lastActivityResourceID": ***,
        "lastCustomerNotificationDateTime": null,
        "lastCustomerVisibleActivityDateTime": null,
        "lastTrackedModificationDateTime": "2022-04-07T00:57:15.88Z",
        "monitorID": null,
        "monitorTypeID": null,
        "opportunityID": null,
        "organizationalLevelAssociationID": null,
        "previousServiceThermometerRating": null,
        "priority": 1,
        "problemTicketId": null,
        "projectID": null,
        "purchaseOrderNumber": "",
        "queueID": 29682833,
        "resolution": "",
        "resolutionPlanDateTime": "2021-09-10T23:33:43.87Z",
        "resolutionPlanDueDateTime": null,
        "resolvedDateTime": "2021-09-10T23:33:43.87Z",
        "resolvedDueDateTime": null,
        "rmaStatus": null,
        "rmaType": null,
        "rmmAlertID": null,
        "serviceLevelAgreementHasBeenMet": null,
        "serviceLevelAgreementID": null,
        "serviceLevelAgreementPausedNextEventHours": null,
        "serviceThermometerTemperature": null,
        "source": -1,
        "status": 1,
        "subIssueType": 156,
        "ticketCategory": 3,
        "ticketNumber": "T20210910.0003",
        "ticketType": 1,
        "title": "Ticket creation with API for unicorn co",
        "userDefinedFields": []
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "TicketID": "\"**\"",
    "TicketNumber": "\"\\\"T***.**\\\"\""
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

item

{'id': **, 'apiVendorID': **, 'assignedResourceID': None, 'assignedResourceRoleID': None, 'billingCodeID': **, 'changeApprovalBoard': None, 'changeApprovalStatus': None, 'changeApprovalType': None, 'changeInfoField1': '', 'changeInfoField2': '', 'changeInfoField3': '', 'changeInfoField4': '', 'changeInfoField5': '', 'companyID': **, 'companyLocationID': **, 'completedByResourceID': None, 'completedDate': None, 'configurationItemID': None, 'contactID': None, 'contractID': None, 'contractServiceBundleID': None, 'contractServiceID': None, 'createDate': '2021-09-10T21:23:41.773Z', 'createdByContactID': None, 'creatorResourceID': **, 'creatorType': 1, 'currentServiceThermometerRating': None, 'description': 'update an existing ticket', 'dueDateTime': '2021-09-10T18:00:00Z', 'estimatedHours': 3.5, 'externalID': '', 'firstResponseAssignedResourceID': None, 'firstResponseDateTime': '2021-09-10T23:33:43.87Z', 'firstResponseDueDateTime': None, 'firstResponseInitiatingResourceID': None, 'hoursToBeScheduled': 3.5, 'impersonatorCreatorResourceID': None, 'isAssignedToComanaged': False, 'issueType': 13, 'isVisibleToComanaged': False, 'lastActivityDate': '2022-04-07T01:09:44.047Z', 'lastActivityPersonType': 1, 'lastActivityResourceID': **, 'lastCustomerNotificationDateTime': None, 'lastCustomerVisibleActivityDateTime': None, 'lastTrackedModificationDateTime': '2022-04-07T00:57:15.88Z', 'monitorID': None, 'monitorTypeID': None, 'opportunityID': None, 'organizationalLevelAssociationID': None, 'previousServiceThermometerRating': None, 'priority': 1, 'problemTicketId': None, 'projectID': None, 'purchaseOrderNumber': '', 'queueID': **, 'resolution': '', 'resolutionPlanDateTime': '2021-09-10T23:33:43.87Z', 'resolutionPlanDueDateTime': None, 'resolvedDateTime': '2021-09-10T23:33:43.87Z', 'resolvedDueDateTime': None, 'rmaStatus': None, 'rmaType': None, 'rmmAlertID': None, 'serviceLevelAgreementHasBeenMet': None, 'serviceLevelAgreementID': None, 'serviceLevelAgreementPausedNextEventHours': None, 'serviceThermometerTemperature': None, 'source': -1, 'status': 1, 'subIssueType': 156, 'ticketCategory': 3, 'ticketNumber': 'T**.**', 'ticketType': 1, 'title': 'Ticket creation with API for unicorn co', 'userDefinedFields': []}

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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "itemId": **
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "TimeEntryId": "\"**\""
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

itemId

***

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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "entityName": "timeentries",
    "entityID": ***,
    "deletedAttachmentIDs": [
        ***,
        ***
    ],
    "errors": [
        {
            "entityName": "timeentries",
            "entityID": **,
            "attachmentID": ***,
            "failedAction": "Delete attachment Failed.",
            "statusCode": 500,
            "reason": "Internal Server Error",
            "message": {
                "errors": [
                    "Invalid attachment id (***). Attachment does not exist."
                ]
            }
        }
    ]
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

DeletedCount

2

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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "itemId": ***
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "TimeEntryIDs": "\"[ ***]\""
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

itemId

**

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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "items": [
        {
            "id": ***,
            "additionalAddressInformation": "",
            "address1": "DT vancouver",
            "address2": null,
            "alternatePhone1": "",
            "alternatePhone2": "",
            "apiVendorID": ***,
            "assetValue": null,
            "billToCompanyLocationID": null,
            "billToAdditionalAddressInformation": "",
            "billingAddress1": "DT vancouver",
            "billingAddress2": "",
            "billToAddressToUse": 1,
            "billToAttention": "",
            "billToCity": "Vancouver",
            "billToCountryID": **,
            "billToState": "",
            "billToZipCode": "",
            "city": "Vancouver",
            "classification": null,
            "companyCategoryID": 1,
            "companyName": "Unicorn Co",
            "companyNumber": "",
            "companyType": 1,
            "competitorID": null,
            "countryID": ***,
            "createDate": "2021-08-04T00:20:00.397Z",
            "createdByResourceID": ***,
            "currencyID": 1,
            "fax": "",
            "impersonatorCreatorResourceID": null,
            "invoiceEmailMessageID": 1,
            "invoiceMethod": null,
            "invoiceNonContractItemsToParentCompany": null,
            "invoiceTemplateID": ***,
            "isActive": true,
            "isClientPortalActive": true,
            "isEnabledForComanaged": false,
            "isTaskFireActive": false,
            "isTaxExempt": false,
            "lastActivityDate": "2021-08-04T19:52:58.86Z",
            "lastTrackedModifiedDateTime": "2021-08-04T00:20:00.397Z",
            "marketSegmentID": null,
            "ownerResourceID": **,
            "parentCompanyID": null,
            "phone": "***",
            "postalCode": "",
            "purchaseOrderTemplateID": null,
            "quoteEmailMessageID": 2,
            "quoteTemplateID": 1,
            "sicCode": "",
            "state": "",
            "stockMarket": "",
            "stockSymbol": "",
            "surveyCompanyRating": null,
            "taxID": "",
            "taxRegionID": null,
            "territoryID": null,
            "webAddress": null,
            "userDefinedFields": []
        }
    ],
    "pageDetails": {
        "count": 3,
        "requestCount": 500,
        "prevPageUrl": null,
        "nextPageUrl": null
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "CompanyIDs": "\"[ ***]\"",
    "CompanyNames": "\"[ \\\"Unicorn Co\\\" ]\"",
    "Phones": "\"[ \\\"***\\\" ]\"",
    "CreateDate": "\"[ \\\"2021-08-04 00:20:00\\\" ]\""
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

items

{'id': ***, 'additionalAddressInformation': '', 'address1': 'DT vancouver', 'address2': None, 'alternatePhone1': '', 'alternatePhone2': '', 'apiVendorID': ***, 'assetValue': None, 'billToCompanyLocationID': None, 'billToAdditionalAddressInformation': '', 'billingAddress1': 'DT vancouver', 'billingAddress2': '', 'billToAddressToUse': 1, 'billToAttention': '', 'billToCity': 'Vancouver', 'billToCountryID': ***, 'billToState': '', 'billToZipCode': '', 'city': 'Vancouver', 'classification': None, 'companyCategoryID': 1, 'companyName': 'Unicorn Co', 'companyNumber': '', 'companyType': 1, 'competitorID': None, 'countryID': **, 'createDate': '2021-08-04T00:20:00.397Z', 'createdByResourceID': ***, 'currencyID': 1, 'fax': '', 'impersonatorCreatorResourceID': None, 'invoiceEmailMessageID': 1, 'invoiceMethod': None, 'invoiceNonContractItemsToParentCompany': None, 'invoiceTemplateID': ***, 'isActive': True, 'isClientPortalActive': True, 'isEnabledForComanaged': False, 'isTaskFireActive': False, 'isTaxExempt': False, 'lastActivityDate': '2021-08-04T19:52:58.86Z', 'lastTrackedModifiedDateTime': '2021-08-04T00:20:00.397Z', 'marketSegmentID': None, 'ownerResourceID': **, 'parentCompanyID': None, 'phone': '***', 'postalCode': '', 'purchaseOrderTemplateID': None, 'quoteEmailMessageID': 2, 'quoteTemplateID': 1, 'sicCode': '', 'state': '', 'stockMarket': '', 'stockSymbol': '', 'surveyCompanyRating': None, 'taxID': '', 'taxRegionID': None, 'territoryID': None, 'webAddress': None, 'userDefinedFields': []}

pageDetails

{'count': 3, 'requestCount': 500, 'prevPageUrl': None, 'nextPageUrl': None}

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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "fields": [
        {
            "name": "territoryID",
            "dataType": "integer",
            "length": 0,
            "isRequired": false,
            "isReadOnly": false,
            "isQueryable": true,
            "isReference": false,
            "referenceEntityType": "",
            "isPickList": true,
            "picklistValues": [
                {
                    "value": "***",
                    "label": "Southeast",
                    "isDefaultValue": false,
                    "sortOrder": 0,
                    "parentValue": "",
                    "isActive": true,
                    "isSystem": false
                },
                {
                    "value": "**",
                    "label": "Northeast",
                    "isDefaultValue": false,
                    "sortOrder": 1,
                    "parentValue": "",
                    "isActive": true,
                    "isSystem": false
                }
            ],
            "picklistParentValueField": "",
            "isSupportedWebhookField": true
        }
    ]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

fields

{'name': 'territoryID', 'dataType': 'integer', 'length': 0, 'isRequired': False, 'isReadOnly': False, 'isQueryable': True, 'isReference': False, 'referenceEntityType': '', 'isPickList': True, 'picklistValues': [{'value': '***', 'label': 'Southeast', 'isDefaultValue': False, 'sortOrder': 0, 'parentValue': '', 'isActive': True, 'isSystem': False}, {'value': '***', 'label': 'Northeast', 'isDefaultValue': False, 'sortOrder': 1, 'parentValue': '', 'isActive': True, 'isSystem': False}], 'picklistParentValueField': '', 'isSupportedWebhookField': True}

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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "item": {
            "id": ***,
            "apiVendorID": ***,
            "assignedResourceID": null,
            "assignedResourceRoleID": null,
            "billingCodeID": ***,
            "changeApprovalBoard": null,
            "changeApprovalStatus": null,
            "changeApprovalType": null,
            "changeInfoField1": "",
            "changeInfoField2": "",
            "changeInfoField3": "",
            "changeInfoField4": "",
            "changeInfoField5": "",
            "companyID": ***,
            "companyLocationID": **,
            "completedByResourceID": **,
            "completedDate": "2022-06-06T16:29:43.103Z",
            "configurationItemID": null,
            "contactID": null,
            "contractID": null,
            "contractServiceBundleID": null,
            "contractServiceID": null,
            "createDate": "2021-09-10T21:23:41.773Z",
            "createdByContactID": null,
            "creatorResourceID": ***,
            "creatorType": 1,
            "currentServiceThermometerRating": null,
            "description": "update an existing ticket",
            "dueDateTime": "2021-09-10T18:00:00Z",
            "estimatedHours": 3.5,
            "externalID": "",
            "firstResponseAssignedResourceID": null,
            "firstResponseDateTime": "2021-09-10T23:33:43.87Z",
            "firstResponseDueDateTime": null,
            "firstResponseInitiatingResourceID": null,
            "hoursToBeScheduled": 0,
            "impersonatorCreatorResourceID": null,
            "isAssignedToComanaged": false,
            "issueType": 13,
            "isVisibleToComanaged": false,
            "lastActivityDate": "2022-06-07T23:09:51.98Z",
            "lastActivityPersonType": 1,
            "lastActivityResourceID": ***,
            "lastCustomerNotificationDateTime": null,
            "lastCustomerVisibleActivityDateTime": null,
            "lastTrackedModificationDateTime": "2022-04-07T00:57:15.88Z",
            "monitorID": null,
            "monitorTypeID": null,
            "opportunityID": null,
            "organizationalLevelAssociationID": null,
            "previousServiceThermometerRating": null,
            "priority": 1,
            "problemTicketId": null,
            "projectID": null,
            "purchaseOrderNumber": "",
            "queueID": ***,
            "resolution": "",
            "resolutionPlanDateTime": "2021-09-10T23:33:43.87Z",
            "resolutionPlanDueDateTime": null,
            "resolvedDateTime": "2021-09-10T23:33:43.87Z",
            "resolvedDueDateTime": null,
            "rmaStatus": null,
            "rmaType": null,
            "rmmAlertID": null,
            "serviceLevelAgreementHasBeenMet": null,
            "serviceLevelAgreementID": null,
            "serviceLevelAgreementPausedNextEventHours": null,
            "serviceThermometerTemperature": null,
            "source": -1,
            "status": 5,
            "subIssueType": 156,
            "ticketCategory": 3,
            "ticketNumber": "T***.***",
            "ticketType": 1,
            "title": "Ticket creation with API for unicorn co",
            "userDefinedFields": []
        }
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "TicketIDs": "\"[\\\"***\\\", \\\"**\\\"]\"",
    "TicketNumbers": "\"[\\\"T2***\\\", \\\"T2***\\\"]\"",
    "Statuses": "\"[ 5, 5 ]\""
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

ITEM
{'id': ***}

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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "item": {
            "id": ***,
            "billingApprovalDateTime": null,
            "billingApprovalLevelMostRecent": 0,
            "billingApprovalResourceID": null,
            "billingCodeID": **,
            "contractID": null,
            "contractServiceBundleID": null,
            "contractServiceID": null,
            "createDateTime": "2021-08-05T23:11:02.747Z",
            "creatorUserID": **,
            "dateWorked": "2021-08-07T00:00:00Z",
            "endDateTime": null,
            "hoursToBill": 5.5,
            "hoursWorked": 5.5,
            "impersonatorCreatorResourceID": null,
            "impersonatorUpdaterResourceID": null,
            "internalBillingCodeID": ***,
            "internalNotes": null,
            "isNonBillable": true,
            "lastModifiedDateTime": "2021-08-05T23:38:58.5Z",
            "lastModifiedUserID": ***,
            "offsetHours": 0,
            "resourceID": ***,
            "roleID": ***,
            "showOnInvoice": false,
            "startDateTime": null,
            "summaryNotes": "test summary",
            "taskID": ***,
            "ticketID": null,
            "timeEntryType": 6
        }
    }
]

Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

D3 customizes the Context Data by extracting the data from path $.item in API returned JSON.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE

[
    {
        "id": **,
        "billingApprovalDateTime": null,
        "billingApprovalLevelMostRecent": 0,
        "billingApprovalResourceID": null,
        "billingCodeID": **,
        "contractID": null,
        "contractServiceBundleID": null,
        "contractServiceID": null,
        "createDateTime": "2021-08-09T19:09:59.207Z",
        "creatorUserID": ***,
        "dateWorked": "2021-08-03T00:00:00Z",
        "endDateTime": null,
        "hoursToBill": 6,
        "hoursWorked": 6,
        "impersonatorCreatorResourceID": null,
        "impersonatorUpdaterResourceID": null,
        "internalBillingCodeID": ***,
        "internalNotes": null,
        "isNonBillable": true,
        "lastModifiedDateTime": "2021-08-09T19:09:59.207Z",
        "lastModifiedUserID": ***,
        "offsetHours": 0,
        "resourceID": ***,
        "roleID": ***,
        "showOnInvoice": false,
        "startDateTime": null,
        "summaryNotes": "test python create time entry",
        "taskID": ***,
        "ticketID": null,
        "timeEntryType": 6
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "BillingCodeIDs": "\"[ ***]\"",
    "CreateDateTime": "\"[ \\\"2021-08-05 23:11:02\\\" ]\"",
    "DateWorked": "\"[ \\\"2021-08-07T00:00:00Z\\\" ]\"",
    "HoursToBill": "\"[ 5.5 ]\"",
    "HoursWorked": "\"[ 5.5 ]\"",
    "ResourceIDs": "\"[ *** ]\"",
    "RoleIDs": "\"[ ***]\"",
    "SummaryNotes": "\"[ \\\"Test Summary\\\" ]\"",
    "TaskIDs": "\"[ *** ]\"",
    "TimeEntryTypes": "\"[ 6 ]\"",
    "TimeEntryIDs": "\"[ *** ]\""
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

ID	BILLINGAPPROVALDATETIME	BILLINGAPPROVALLEVELMOSTRECENT	BILLINGAPPROVALRESOURCEID	BILLINGCODEID	CONTRACTID	CONTRACTSERVICEBUNDLEID	CONTRACTSERVICEID	CREATEDATETIME	CREATORUSERID	DATEWORKED	ENDDATETIME	HOURSTOBILL	HOURSWORKED	IMPERSONATORCREATORRESOURCEID	IMPERSONATORUPDATERRESOURCEID	INTERNALBILLINGCODEID	INTERNALNOTES	ISNONBILLABLE	LASTMODIFIEDDATETIME	LASTMODIFIEDUSERID	OFFSETHOURS	RESOURCEID	ROLEID	SHOWONINVOICE	STARTDATETIME	SUMMARYNOTES	TASKID	TICKETID	TIMEENTRYTYPE
**	None	0	None	***	None	None	None	2021-08-09T19:09:59.207Z	***	2021-08-03T00:00:00Z	None	6.0	6.0	None	None	***	None	True	2021-08-09T19:09:59.207Z	***	0.0	***	***	False	None	test python create time entry	***	None	6

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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "items": [
        {
            "id": ***,
            "assignedResourceID": **,
            "assignedResourceRoleID": ***,
            "billingCodeID": ***,
            "canClientPortalUserCompleteTask": false,
            "companyLocationID": null,
            "completedByResourceID": null,
            "completedByType": null,
            "completedDateTime": null,
            "createDateTime": "2012-06-18T16:50:32Z",
            "creatorResourceID": 4,
            "creatorType": 1,
            "departmentID": ***,
            "description": "   Modify code",
            "endDateTime": "2012-09-13T00:00:00Z",
            "estimatedHours": 2,
            "externalID": "",
            "hoursToBeScheduled": -5,
            "isTaskBillable": false,
            "isVisibleInClientPortal": true,
            "lastActivityDateTime": "2021-08-06T00:20:58.943Z",
            "lastActivityPersonType": 1,
            "lastActivityResourceID": ***,
            "phaseID": ***,
            "priority": 0,
            "priorityLabel": null,
            "projectID": ***,
            "purchaseOrderNumber": "",
            "remainingHours": 0,
            "startDateTime": "2012-09-10T00:00:00Z",
            "status": 11,
            "taskCategoryID":**,
            "taskNumber": "***",
            "taskType": 1,
            "title": "   Modify code",
            "userDefinedFields": [],
            "attachments": [
                {
                    "id": ***,
                    "attachDate": "2021-08-06T00:51:52.473Z",
                    "attachedByContactID": null,
                    "attachedByResourceID": ***,
                    "attachmentType": "FILE_ATTACHMENT",
                    "contentType": "image/jpeg",
                    "creatorType": 1,
                    "fileSize": 3840,
                    "fullPath": "***.jpg",
                    "impersonatorCreatorResourceID": null,
                    "opportunityID": null,
                    "parentAttachmentID": null,
                    "parentID": ***,
                    "publish": 1,
                    "taskID": **,
                    "taskNoteID": null,
                    "timeEntryID": null,
                    "title": "blue jay logo",
                    "data": null
                }
            ]
        }
    ],
    "pageDetails": {
        "count": 1,
        "requestCount": 200,
        "prevPageUrl": null,
        "nextPageUrl": null
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "EntityName": "\"timeentries\"",
    "EntityIDs": "\"[ ***, **]\"",
    "EntityNumbers": "\"[ \\\"***\\\", \\\"***\\\" ]\""
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

EntityCount

2

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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "items": [
        {
            "id": ***,
            "billingApprovalDateTime": null,
            "billingApprovalLevelMostRecent": 0,
            "billingApprovalResourceID": null,
            "billingCodeID": ***,
            "contractID": null,
            "contractServiceBundleID": null,
            "contractServiceID": null,
            "createDateTime": "2021-08-05T00:55:11.68Z",
            "creatorUserID": **,
            "dateWorked": "2021-08-05T00:00:00Z",
            "endDateTime": null,
            "hoursToBill": 6,
            "hoursWorked": 6,
            "impersonatorCreatorResourceID": null,
            "impersonatorUpdaterResourceID": null,
            "internalBillingCodeID": ***,
            "internalNotes": null,
            "isNonBillable": true,
            "lastModifiedDateTime": "2021-08-05T00:55:11.68Z",
            "lastModifiedUserID": ***,
            "offsetHours": 0,
            "resourceID": **,
            "roleID": ***,
            "showOnInvoice": false,
            "startDateTime": null,
            "summaryNotes": "test summary",
            "taskID": ***,
            "ticketID": null,
            "timeEntryType": 10
        },
        {
            "id": ***,
            "billingApprovalDateTime": null,
            "billingApprovalLevelMostRecent": 0,
            "billingApprovalResourceID": null,
            "billingCodeID": ***,
            "contractID": null,
            "contractServiceBundleID": null,
            "contractServiceID": null,
            "createDateTime": "2021-08-05T00:58:40.303Z",
            "creatorUserID": ***,
            "dateWorked": "2021-08-05T00:00:00Z",
            "endDateTime": null,
            "hoursToBill": 6,
            "hoursWorked": 6,
            "impersonatorCreatorResourceID": null,
            "impersonatorUpdaterResourceID": null,
            "internalBillingCodeID": ***,
            "internalNotes": null,
            "isNonBillable": true,
            "lastModifiedDateTime": "2021-08-05T00:58:40.32Z",
            "lastModifiedUserID": ***,
            "offsetHours": 0,
            "resourceID": ***,
            "roleID": ***,
            "showOnInvoice": false,
            "startDateTime": null,
            "summaryNotes": "test summary",
            "taskID": ***,
            "ticketID": null,
            "timeEntryType": 10
        }
    ],
    "pageDetails": {
        "count": 2,
        "requestCount": 100,
        "prevPageUrl": null,
        "nextPageUrl": null
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "BillingCodeIDs": "\"[ ***]\"",
    "CreateDateTime": "\"[ \\\"2021-08-05 23:11:02\\\" ]\"",
    "DateWorked": "\"[ \\\"2021-08-07 00:00:00\\\" ]\"",
    "HoursToBill": "\"[ 5.5 ]\"",
    "HoursWorked": "\"[ 5.5 ]\"",
    "ResourceIDs": "\"[ ***]\"",
    "RoleIDs": "\"[ ***]\"",
    "SummaryNotes": "\"[ \\\"Test Summary\\\" ]\"",
    "TaskIDs": "\"[ **8]\"",
    "TimeEntryTypes": "\"[ 10 ]\""
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

items

{'id': ***, 'billingApprovalDateTime': None, 'billingApprovalLevelMostRecent': 0, 'billingApprovalResourceID': None, 'billingCodeID': ***, 'contractID': None, 'contractServiceBundleID': None, 'contractServiceID': None, 'createDateTime': '2021-08-05T00:55:11.68Z', 'creatorUserID': ***, 'dateWorked': '2021-08-05T00:00:00Z', 'endDateTime': None, 'hoursToBill': 6, 'hoursWorked': 6, 'impersonatorCreatorResourceID': None, 'impersonatorUpdaterResourceID': None, 'internalBillingCodeID': ***, 'internalNotes': None, 'isNonBillable': True, 'lastModifiedDateTime': '2021-08-05T00:55:11.68Z', 'lastModifiedUserID': ***, 'offsetHours': 0, 'resourceID': ***, 'roleID': ***, 'showOnInvoice': False, 'startDateTime': None, 'summaryNotes': 'test summary', 'taskID': ***, 'ticketID': None, 'timeEntryType': 10}
{'id': 35, 'billingApprovalDateTime': None, 'billingApprovalLevelMostRecent': 0, 'billingApprovalResourceID': None, 'billingCodeID': ***, 'contractID': None, 'contractServiceBundleID': None, 'contractServiceID': None, 'createDateTime': '2021-08-05T00:58:40.303Z', 'creatorUserID': ***, 'dateWorked': '2021-08-05T00:00:00Z', 'endDateTime': None, 'hoursToBill': 6, 'hoursWorked': 6, 'impersonatorCreatorResourceID': None, 'impersonatorUpdaterResourceID': None, 'internalBillingCodeID': 29683311, 'internalNotes': None, 'isNonBillable': True, 'lastModifiedDateTime': '2021-08-05T00:58:40.32Z', 'lastModifiedUserID': ***, 'offsetHours': 0, 'resourceID': ***, 'roleID': ***, 'showOnInvoice': False, 'startDateTime': None, 'summaryNotes': 'test summary', 'taskID': **, 'ticketID': None, 'timeEntryType': 10}

pageDetails

{'count': 2, 'requestCount': 100, 'prevPageUrl': None, 'nextPageUrl': None}

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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "item": {
        "id": ***,
        "apiVendorID": ***,
        "assignedResourceID": null,
        "assignedResourceRoleID": null,
        "billingCodeID": ***,
        "changeApprovalBoard": null,
        "changeApprovalStatus": null,
        "changeApprovalType": null,
        "changeInfoField1": "",
        "changeInfoField2": "",
        "changeInfoField3": "",
        "changeInfoField4": "",
        "changeInfoField5": "",
        "companyID": ***,
        "companyLocationID": ***,
        "completedByResourceID": ***,
        "completedDate": "2022-06-06T16:29:43.103Z",
        "configurationItemID": null,
        "contactID": null,
        "contractID": null,
        "contractServiceBundleID": null,
        "contractServiceID": null,
        "createDate": "2021-09-10T21:23:41.773Z",
        "createdByContactID": null,
        "creatorResourceID": ***,
        "creatorType": 1,
        "currentServiceThermometerRating": null,
        "description": "update an existing ticket",
        "dueDateTime": "2021-09-10T18:00:00Z",
        "estimatedHours": 3.5,
        "externalID": "",
        "firstResponseAssignedResourceID": null,
        "firstResponseDateTime": "2021-09-10T23:33:43.87Z",
        "firstResponseDueDateTime": null,
        "firstResponseInitiatingResourceID": null,
        "hoursToBeScheduled": 0,
        "impersonatorCreatorResourceID": null,
        "isAssignedToComanaged": false,
        "issueType": 13,
        "isVisibleToComanaged": false,
        "lastActivityDate": "2022-06-06T16:29:43.103Z",
        "lastActivityPersonType": 1,
        "lastActivityResourceID": ***,
        "lastCustomerNotificationDateTime": null,
        "lastCustomerVisibleActivityDateTime": null,
        "lastTrackedModificationDateTime": "2022-04-07T00:57:15.88Z",
        "monitorID": null,
        "monitorTypeID": null,
        "opportunityID": null,
        "organizationalLevelAssociationID": null,
        "previousServiceThermometerRating": null,
        "priority": 1,
        "problemTicketId": null,
        "projectID": null,
        "purchaseOrderNumber": "",
        "queueID": ***,
        "resolution": "",
        "resolutionPlanDateTime": "2021-09-10T23:33:43.87Z",
        "resolutionPlanDueDateTime": null,
        "resolvedDateTime": "2021-09-10T23:33:43.87Z",
        "resolvedDueDateTime": null,
        "rmaStatus": null,
        "rmaType": null,
        "rmmAlertID": null,
        "serviceLevelAgreementHasBeenMet": null,
        "serviceLevelAgreementID": null,
        "serviceLevelAgreementPausedNextEventHours": null,
        "serviceThermometerTemperature": null,
        "source": -1,
        "status": 5,
        "subIssueType": ***,
        "ticketCategory": 3,
        "ticketNumber": "T***",
        "ticketType": 1,
        "title": "Ticket creation with API for unicorn co",
        "userDefinedFields": []
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "TicketID": "\"***\"",
    "TicketNumber": "\"\\\"T***\\\"\"",
    "Status": "\"5\""
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

item

{'id': **, 'apiVendorID': ***, 'assignedResourceID': None, 'assignedResourceRoleID': None, 'billingCodeID': ***, 'changeApprovalBoard': None, 'changeApprovalStatus': None, 'changeApprovalType': None, 'changeInfoField1': '', 'changeInfoField2': '', 'changeInfoField3': '', 'changeInfoField4': '', 'changeInfoField5': '', 'companyID': **, 'companyLocationID': ***, 'completedByResourceID': ***, 'completedDate': '2022-06-06T16:29:43.103Z', 'configurationItemID': None, 'contactID': None, 'contractID': None, 'contractServiceBundleID': None, 'contractServiceID': None, 'createDate': '2021-09-10T21:23:41.773Z', 'createdByContactID': None, 'creatorResourceID': **, 'creatorType': 1, 'currentServiceThermometerRating': None, 'description': 'update an existing ticket', 'dueDateTime': '2021-09-10T18:00:00Z', 'estimatedHours': 3.5, 'externalID': '', 'firstResponseAssignedResourceID': None, 'firstResponseDateTime': '2021-09-10T23:33:43.87Z', 'firstResponseDueDateTime': None, 'firstResponseInitiatingResourceID': None, 'hoursToBeScheduled': 0.0, 'impersonatorCreatorResourceID': None, 'isAssignedToComanaged': False, 'issueType': 13, 'isVisibleToComanaged': False, 'lastActivityDate': '2022-06-06T16:29:43.103Z', 'lastActivityPersonType': 1, 'lastActivityResourceID': ***, 'lastCustomerNotificationDateTime': None, 'lastCustomerVisibleActivityDateTime': None, 'lastTrackedModificationDateTime': '2022-04-07T00:57:15.88Z', 'monitorID': None, 'monitorTypeID': None, 'opportunityID': None, 'organizationalLevelAssociationID': None, 'previousServiceThermometerRating': None, 'priority': 1, 'problemTicketId': None, 'projectID': None, 'purchaseOrderNumber': '', 'queueID': **, 'resolution': '', 'resolutionPlanDateTime': '2021-09-10T23:33:43.87Z', 'resolutionPlanDueDateTime': None, 'resolvedDateTime': '2021-09-10T23:33:43.87Z', 'resolvedDueDateTime': None, 'rmaStatus': None, 'rmaType': None, 'rmmAlertID': None, 'serviceLevelAgreementHasBeenMet': None, 'serviceLevelAgreementID': None, 'serviceLevelAgreementPausedNextEventHours': None, 'serviceThermometerTemperature': None, 'source': -1, 'status': 5, 'subIssueType': 156, 'ticketCategory': 3, 'ticketNumber': '**', 'ticketType': 1, 'title': 'Ticket creation with API for unicorn co', 'userDefinedFields': []}

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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "itemId": ***
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

itemId

***

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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "itemId": ***
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "AttachmentID": "\"***\""
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

itemId

***

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

Return Data

Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

SAMPLE DATA

CODE

Successful

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.