TOPdesk

TOPdesk’s Enterprise Service Management software (ESM) lets your service teams join forces and process requests from a single platform.
This integration was integrated and tested with 10.08.008-on-premises-release3-build2 for Linux x86 64-bit of TOPdesk.

Use cases

1. Get, update, and create TOPdesk incidents, as well as (de-)escalate, (un)archive or upload files to the incidents.
2. Fetch newly created TOPdesk incidents.
3. Get information about branches, persons and operators.

Configure TOPdesk on Cortex XSOAR

1. Navigate to Settings > Integrations > Servers & Services.
2. Search for TOPdesk.

3. Click Add instance to create and configure a new integration instance.

   Parameter	Description	Required
   Server URL (e.g., https://topdesk.mydomain/tas/)	The server url.	True
   Username	See section about auth details below	True
   Password	See section about auth details below	True
   Fetch incidents		False
   Maximum number of incidents per fetch		False
   First fetch time (<number> <time unit>, e.g., 12 hours, 7 days, 3 months, 1 year)		False
   Default Incident Caller ID	The default caller ID which is added when creating new TOPdesk incidents and no explicit caller ID is provided. See See Finding the Default Incident Caller ID.	False
   The query to use when fetching incidents	Getting incidents with new style FIQL query is available only from TOPdeskRestAPI version 3.4.0. For earlier versions this field will be used as additional inline params as supported.	False
   Incident type	Use TOPdesk Incident for some predefined layouts	False
   Trust any certificate (not secure)		False
   Use system proxy settings		False

4. Click Test to validate the URLs, token, and connection.

Auth Details

Person and operator are TOPdesk’s user types. Each user type has a different set of actions that he is allowed to perform.
For example, a person can only update incidents he created, while an operator can update a wider range of incidents.

In general, if an account is able to preform the requested command in TOPdesk’s UI, it should be able to preform it using this integration.
Make sure you use the right account for your needs and that the account used has all the required permissions.

Setup TOPdesk’s application password

1. Login to TOPdesk with the designated account.
2. In TOPdesk, click Open user menu (top right side of the front page) > Choose My settings
3. At the bottom of the page should be an Application passwords section. You can view all application passwords that are configured for the logged in account.
4. At the bottom right corner, click Add.
5. A window should open requesting a name for the application. Choose any convenient name (e.g., XSOAR-key) and click Create.
6. The application password should be shown - copy it to a safe location. This is the password that will be used for the integration in XSOAR.
7. Once copied for further usage you can click Close.

Configure Username and Password

Username: Use the account username from which the application password was generated. (Not the key name)

Password: Use the application password generated in step 6 of the Setup TOPdesk’s application password procedure.

Troubleshooting

Make sure the application password is not expired by logging in TOPdesk and viewing it as described in step 3 of the Setup TOPdesk’s application password procedure.

Finding the Default Incident Caller ID

The TOPdesk incident caller is the TOPdesk person who requested a specific TOPdesk incident and is the contact person for all activities related to this incident.
To find the incident caller ID which should be used as the default caller when creating a new TOPdesk incident, first configure the integration instance without providing the Default Incident Caller ID. Then run the command !topdesk-persons-list in the Playground - War Room.
You will receive a list of people and their IDs. Copy the ID of the desired person and edit the integration instance to set the Default Incident Caller ID.

Incident Mirroring

You can enable incident mirroring between Cortex XSOAR incidents and TOPdesk incidents.

To setup the mirroring follow these instructions:

1. Navigate to Settings > Integrations > Servers & Services.
2. Search for TOPdesk and select your integration instance.
3. Enable Fetches incidents.
4. In the Mirroring Direction integration parameter, select in which direction the incidents should be mirrored:
   • Incoming - Any changes in TOPdesk incidents (processingStatus, priority, urgency, impact) will be reflected in Cortex XSOAR incidents.
   • Outgoing - Any changes in Cortex XSOAR incidents will be reflected in TOPdesk incidents (processingStatus, priority, urgency, impact).
   • Incoming And Outgoing - Changes in Cortex XSOAR incidents and TOPdesk incidents will be reflected in both directions.
   • None - Turns off incident mirroring.
5. The Comment Entry Tag, Work Note Entry Tag and File Entry Tag integration parameters can be used to specify which comments and attachments should be mirrored to TOPdesk. When the tag Comment Entry Tag is used, the comment is visible to the operator and the person. If the tag Work Note Entry Tag is used, the comment is only visible to the operator and the tag File Entry Tag is used to mirror files from Cortex XSOAR to TOPdesk.
6. Optional: Check the Close Mirrored XSOAR Incident integration parameter to close the Cortex XSOAR incident when the corresponding incident is closed in TOPdesk.
7. Optional: Check the Close Mirrored TOPdesk Incident integration parameter to close the TOPdesk incident when the corresponding Cortex XSOAR incident is closed.

Newly fetched incidents will be mirrored in the chosen direction. However, this selection does not affect existing incidents.

Important Notes
To ensure the mirroring works as expected, mappers are required, both for incoming and outgoing, to map the expected fields in Cortex XSOAR and TOPdesk.

FIQL query

A few implemented commands can get a query as a parameter. A partial list of these commands:

• topdesk-incidents-list
• topdesk-branches-list
• topdesk-persons-list
• topdesk-operators-list

While the new versions of TOPdesk all use the new FIQL query format, older versions use limited inline parameters for filters in the requests.
Specifically there are 2 versions being used:

TOPdeskRestAPI

Implements: topdesk-incidents-list

Supports FIQL query version 3.3.0 and higher.

Conveniently, TOPdeskRestAPI also provides an endpoint revealing the API version.
Therefore, once the integration is configured, it automatically translates FIQL query to
inline parameters and vice versa depending on the TOPdesk version.

SupportingFilesAPI

Implements: topdesk-branches-list, topdesk-persons-list, topdesk-operators-list

Supports FIQL query version 1.38.0 and higher.

Unlike TOPdeskRestAPI, SupportingFilesAPI does not currently provide an endpoint revealing the API version.
Therefore, this integration only supports SupportingFilesAPI version 1.38.0 and higher.

Commands

You can execute these commands from the Cortex XSOAR CLI, as part of an automation, or in a playbook.
After you successfully execute a command, a DBot message appears in the War Room with the command details.

topdesk-subcategories-list

Get list of subcategories.

Permissions

Operator: 1st/2nd line incident permissions; Category/Branch/Operator filters apply.

Person: Unrestricted access.

Base Command

topdesk-subcategories-list

Input

Context Output

Command Example

#### Context Example

```json
{
    "TOPdesk": {
        "Subcategories": [
            {
                "Category": {
                    "Id": "some-category-id-1",
                    "Name": "User Security"
                },
                "Id": "some-subcategory-id-1",
                "Name": "Endpoint Security"
            },
            {
                "Category": {
                    "Id": "some-category-id-1",
                    "Name": "User Security"
                },
                "Id": "some-subcategory-id-2",
                "Name": "Mobile Threat Prevention"
            }
        ]
    }
}

Human Readable Output

TOPdesk subcategories

Id	Name	CategoryId	CategoryName
some-subcategory-id-1	Endpoint Security	some-category-id	User Security
some-subcategory-id-2	Mobile Threat Prevention	some-category-id	User Security

topdesk-categories-list

Get list of categories.

Permissions

Operator: With 1st/2nd line incident permission; Category/Branch/Operator filters apply

Person: Unrestricted access

Base Command

topdesk-categories-list

Input

Context Output

Command Example

#### Context Example

```json
{
    "TOPdesk": {
        "Category": [
            {
                "Id": "some-category-id-1",
                "Name": "User Security"
            },
            {
                "Id": "some-category-id-2",
                "Name": "Network Security"
            }
        ]
    }
}

Human Readable Output

TOPdesk categories

Id	Name
some-category-id-1	User Security
some-category-id-2	Network Security

topdesk-entry-types-list

Get list of entry types.

Permissions

Operator: With 1st/2nd line incident permission; Category/Branch/Operator filters apply

Person: No access

Base Command

topdesk-entry-types-list

Input

Context Output

Command Example

#### Context Example

```json
{
    "TOPdesk": {
        "EntryType": [
            {
                "Id": "some-entry-type-id-1",
                "Name": "Self Service Desk"
            },
            {
                "Id": "some-entry-type-id-2",
                "Name": "Telephone"
            }
        ]
    }
}

Human Readable Output

TOPdesk entry types

Id	Name
some-entry-type-id-1	Self Service Desk
some-entry-type-id-2	Telephone

topdesk-call-types-list

Get list of entry types.

Permissions

Operator: With 1st/2nd line incident permission; Category/Branch/Operator filters apply

Person: Unrestricted access

Base Command

topdesk-call-types-list

Input

Context Output

Command Example

#### Context Example

```json
{
    "TOPdesk": {
        "CallType": [
            {
                "Id": "some-call-type-id-1",
                "Name": "Request for Information"
            },
            {
                "Id": "some-call-type-id-2",
                "Name": "Problem"
            }
        ]
    }
}

Human Readable Output

TOPdesk call types

Id	Name
some-call-type-id-1	Request for Information
some-call-type-id-2	Problem

topdesk-deescalation-reasons-list

Get list of deescalation reasons.

Permissions

Operator: With 1st and 2nd line incident write permission; Feature must be enabled.

Person: No access

Base Command

topdesk-deescalation-reasons-list

Input

Context Output

Command Example

#### Context Example

```json
{
    "TOPdesk": {
        "DeescalationReason": [
            {
                "Id": "some-deescalation-reason-id-1",
                "Name": "Resolves after reset"
            },
            {
                "Id": "some-deescalation-reason-id-2",
                "Name": "Workaround exists"
            }
        ]
    }
}

Human Readable Output

Id	Name
some-deescalation-reason-id-1	Resolves after reset
some-deescalation-reason-id-2	Workaround exists

topdesk-escalation-reasons-list

Get list of escalation reasons.

Permissions

Operator: With 1st line incident write permission and write permission for escalating incidents

Person: No access

Base Command

topdesk-escalation-reasons-list

Input

Context Output

Command Example

#### Context Example

```json
{
    "TOPdesk": {
        "EscalationReason": [
            {
                "Id": "some-escalation-reason-id-1",
                "Name": "Call from president"
            },
            {
                "Id": "some-escalation-reason-id-2",
                "Name": "Money is being lost"
            }
        ]
    }
}

Human Readable Output

TOPdesk escalation reasons

Id	Name
some-escalation-reason-id-1	Call from president
some-escalation-reason-id-2	Money is being lost

topdesk-archiving-reasons-list

Get list of archiving reasons.

Permissions

Operator: Incident write permission and archiving permission; Category/Branch/Operator filters apply;

Person: No access

Base Command

topdesk-archiving-reasons-list

Input

Context Output

Command Example

#### Context Example

```json
{
    "TOPdesk": {
        "ArchiveReason": [
            {
                "Id": "some-archive-reason-id-1",
                "Name": "No longer valid"
            },
            {
                "Id": "some-archive-reason-id-2",
                "Name": "No longer employed"
            }
        ]
    }
}

Human Readable Output

TOPdesk archiving reasons

Id	Name
some-archive-reason-id-1	No longer valid
some-archive-reason-id-2	No longer employed

topdesk-persons-list

Get list of persons.

Permissions

Operator: With read permission on persons; Branch filters apply

Visible fields in response: all

Person: Only accessible when phonebook is enabled.

Visible fields in response: id, dynamicName, phoneNumber, mobileNumber, fax, email, jobTitle, department, department.id, department.name, city, departmentFree, branch, branch.id, branch.name, location, location.id, location.branch, location.branch.id, location.branch.name, location.name, location.room

Base Command

topdesk-persons-list

Input

Context Output

Command Example

#### Context Example

```json
{
    "TOPdesk": {
        "Person": [
            {
                "AttentionComment": "",
                "AuthorizeAll": false,
                "AuthorizeBranch": false,
                "AuthorizeBudgetHolder": false,
                "AuthorizeDepartment": false,
                "AuthorizeSubsidiaryBranches": false,
                "BirthName": "",
                "Branch": {
                    "ClientReferenceNumber": "1337",
                    "ExtraA": {
                        "Id": "some-extra-id",
                        "Name": "Building in progress"
                    },
                    "Id": "some-branch-id-1",
                    "Name": "HQ",
                    "TimeZone": ""
                },
                "City": "",
                "ClientReferenceNumber": "1337",
                "CreationDate": "2020-12-21T09:16:34.000+0000",
                "Creator": {
                    "Id": "some-admin-id",
                    "Name": "TOPdesk Admin"
                },
                "DynamicName": "Xsoar - User - A",
                "Email": "",
                "EmployeeNumber": "",
                "Fax": "",
                "FirstInitials": "",
                "FirstName": "Xsoar -",
                "Gender": "UNDEFINED",
                "HasAttention": false,
                "Id": "some-user-id-a",
                "IsManager": false,
                "JobTitle": "",
                "Language": {
                    "Id": "some-eng-lng-id",
                    "Name": "ENG"
                },
                "MainframeLoginName": "",
                "MobileNumber": "",
                "ModificationDate": "2020-12-21T09:20:53.000+0000",
                "Modifier": {
                    "Id": "some-admin-id",
                    "Name": "TOPdesk Admin"
                },
                "NetworkLoginName": "",
                "OptionalFields1": {
                    "Text1": "",
                    "Text2": "",
                    "Text3": "",
                    "Text4": "",
                    "Text5": ""
                },
                "OptionalFields2": {
                    "Text1": "",
                    "Text2": "",
                    "Text3": "",
                    "Text4": "",
                    "Text5": ""
                },
                "PhoneNumber": "",
                "Prefixes": "",
                "ShowAllBranches": false,
                "ShowBranch": true,
                "ShowBudgetholder": false,
                "ShowDepartment": false,
                "ShowSubsidiaries": false,
                "Status": "person",
                "SurName": "User - A",
                "TasLoginName": "xsoar-user-a",
                "Title": ""
            }
        ]
    }
}

Human Readable Output

TOPdesk persons

Id	Name	BranchName
some-user-id-a	Xsoar - User - A	XSoar - Customer - A
some-user-id-b	Xsoar - User - B	Xsoar - Customer - B

topdesk-operators-list

Get list of operators.

Permissions

Operator: With read permission on operators; Branch/Operator filters apply

Person: No access

Base Command

topdesk-operators-list

Input

Context Output

Command Example

#### Context Example

```json
{
    "TOPdesk": {
        "Operator": {
            "AccountManager": false,
            "BirthName": "",
            "Branch": {
                "ClientReferenceNumber": "1337",
                "ExtraA": {
                    "Id": "some-extra-id",
                    "Name": "Building in progress"
                },
                "Id": "some-branch-id-1",
                "Name": "HQ",
                "TimeZone": ""
            },
            "ChangeActivitiesOperator": false,
            "ChangeCoordinator": false,
            "Comments": "",
            "ContractManager": false,
            "CreationDate": "2020-12-21T09:24:35.000+0000",
            "Creator": {
                "Id": "some-admin-id",
                "Name": "TOPdesk Admin"
            },
            "DynamicName": "Xsoar - Operator",
            "Email": "xsoar-dev@example.com",
            "EmployeeNumber": "",
            "ExchangeAccount": "xsoar-dev@example.com",
            "ExtensiveChangeOperator": false,
            "ExternalHelpDeskParty": false,
            "FaxNumber": "",
            "FirstLineCallOperator": true,
            "FirstName": "Xsoar -",
            "Gender": "UNDEFINED",
            "HasAttention": false,
            "Id": "some-operator-id",
            "Initials": "",
            "Installer": false,
            "JobTitle": "",
            "KnowledgeBaseManager": false,
            "Language": {
                "Id": "some-eng-lng-id",
                "Name": "ENG"
            },
            "LoginName": "XSOAR-OPERATOR",
            "LoginPermission": true,
            "MainframeLoginName": "",
            "MobileNumber": "",
            "ModificationDate": "2020-12-21T09:24:35.000+0000",
            "Modifier": {
                "Id": "some-admin-id",
                "Name": "TOPdesk Admin"
            },
            "NetworkLoginName": "",
            "OperationsManager": false,
            "OperationsOperator": false,
            "OptionalFields1": {
                "Text1": "",
                "Text2": "",
                "Text3": "",
                "Text4": "",
                "Text5": ""
            },
            "OptionalFields2": {
                "Text1": "",
                "Text2": "",
                "Text3": "",
                "Text4": "",
                "Text5": ""
            },
            "PlanningActivityManager": false,
            "Prefixes": "",
            "PrincipalId": "some-principal-id",
            "ProblemManager": false,
            "ProblemOperator": false,
            "ProjectActiviesOperator": false,
            "ProjectCoordinator": false,
            "RequestForChangeOperator": false,
            "ReservationsOperator": false,
            "ScenarioManager": false,
            "SecondLineCallOperator": true,
            "ServiceOperator": false,
            "SimpleChangeOperator": false,
            "Status": "operator",
            "StockManager": false,
            "SurName": "Operator",
            "Telephone": "",
            "Title": ""
        }
    }
}

Human Readable Output

TOPdesk operators

Id	Name	BranchName
some-operator-id	Xsoar - Operator	HQ

topdesk-branches-list

Get list of branches.

Permissions

Operator: Branch filters apply

Person: Only accessible when branches are editable in the SSP. Returns only ID and name.

Base Command

topdesk-branches-list

Input

Context Output

Command Example

!topdesk-branches-list start=5

Context Example

{
    "TOPdesk": {
        "Branch": [
          {
            "Id": "some-branch-id",
            "Status": "Active",
            "Name": "HeadQuarters",
            "Specification": "string",
            "ClientReferenceNumber": "string",
            "TimeZone": "string",
            "ExtraA": {
              "Id": "some-id-76",
              "Name": "string"
            },
            "ExtraB": {
              "Id": "some-id-98",
              "Name": "string"
            },
            "Phone": "1337",
            "Fax": "string",
            "Address": {
              "Country": {
                "Id": "some-id-78",
                "Name": "string"
              },
              "Street": "Featherstone Street",
              "Number": "49",
              "County": "Greater London",
              "City": "London",
              "Postcode": "EC1Y 8SY",
              "AddressMemo": "49 Featherstone Street\nLONDON\nEC1Y 8SY\nUNITED KINGDOM",
              "AddressType": "GB"
            },
            "Email": "string",
            "Website": "some-domain.com",
            "PostalAddress": {
              "Country": {
                "Id": "some-id-56",
                "Name": "string"
              },
              "Street": "Featherstone Street",
              "Number": "49",
              "County": "Greater London",
              "City": "London",
              "Postcode": "EC1Y 8SY",
              "AddressMemo": "49 Featherstone Street\nLONDON\nEC1Y 8SY\nUNITED KINGDOM",
              "AddressType": "GB"
            },
            "BranchType": "string",
            "HeadBranch": {
              "Id": "some-id-45",
              "Name": "string"
            },
            "MembershipNumber": "string",
            "AccountManager": {
              "Id": "some-id-45",
              "Name": "string"
            },
            "Contact": {
              "Id": "some-id-34",
              "Name": "string"
            },
            "VatNumber": "string",
            "SurfaceArea": 0,
            "Volume": 0,
            "Attention": {
              "Id": "some-id-23",
              "Name": "string"
            },
            "AttentionComment": "string",
            "AdditionalInfo": "string",
            "ServiceWindowOption": "string",
            "ServiceWindow": {
              "Id": "some-id-12",
              "Name": "string"
            },
            "RealEstate": {
              "RegistryReference": "string",
              "OwnerName": "string",
              "OwnerMobile": "string",
              "OwnerTelephone": "string",
              "OwnerEmail": "string",
              "DesignatedUse": {
                "Id": "some-id-99",
                "Name": "string"
              },
              "ListedBuilding": {
                "Id": "some-id-88",
                "Name": "string"
              },
              "ConstructionYear": 0,
              "AcquisitionYear": 0,
              "AcquisitionPrice": 0,
              "EnergyPerformance": {
                "Id": "some-id-77",
                "Name": "string"
              },
              "EnergyPerformanceMeasurementDate": "2021-03-24T12:39:50.643Z",
              "EnvironmentalImpact": {
                "Id": "some-id-66",
                "Name": "string"
              },
              "EnvironmentalImpactMeasurementDate": "2021-03-24T12:39:50.643Z",
              "BuildingLevelEPC": {
                "Id": "some-id-55",
                "Name": "string"
              },
              "TotalAcquisitionCost": 0,
              "PropertyValuation": 0,
              "ResidualValue": 0,
              "AnnualDepreciation": 0,
              "DepreciationPeriod": 0,
              "LiquidationValue": 0,
              "LiquidationValueSurveyDate": "2021-03-24T12:39:50.643Z",
              "LandValue": 0,
              "LandValueSurveyDate": "2021-03-24T12:39:50.643Z",
              "MarketValue": 0,
              "MarketValueSurveyDate": "2021-03-24T12:39:50.643Z",
              "RentalValue": 0,
              "RentalValueSurveyDate": "2021-03-24T12:39:50.643Z",
              "RebuildingValue": 0,
              "RebuildingValueSurveyDate": "2021-03-24T12:39:50.643Z"
            },
            "OptionalFields1": {
              "Boolean1": true,
              "Boolean2": true,
              "Boolean3": true,
              "Boolean4": true,
              "Boolean5": true,
              "Number1": 0,
              "Number2": 0,
              "Number3": 0,
              "Number4": 0,
              "Number5": 0,
              "Date1": "2021-03-24T12:39:50.643Z",
              "Date2": "2021-03-24T12:39:50.643Z",
              "Date3": "2021-03-24T12:39:50.643Z",
              "Date4": "2021-03-24T12:39:50.643Z",
              "Date5": "2021-03-24T12:39:50.643Z",
              "Text1": "string",
              "Text2": "string",
              "Text3": "string",
              "Text4": "string",
              "Text5": "string",
              "Memo1": "string",
              "Memo2": "string",
              "Memo3": "string",
              "Memo4": "string",
              "Memo5": "string",
              "Searchlist1": {
                "Id": "some-id-55",
                "Name": "string"
              },
              "Searchlist2": {
                "Id": "some-id-44",
                "Name": "string"
              },
              "Searchlist3": {
                "Id": "some-id-33",
                "Name": "string"
              },
              "Searchlist4": {
                "Id": "some-id-22",
                "Name": "string"
              },
              "searchlist5": {
                "Id": "some-id-11",
                "Name": "string"
              }
            },
            "optionalFields2": {
              "Boolean1": true,
              "Boolean2": true,
              "Boolean3": true,
              "Boolean4": true,
              "Boolean5": true,
              "Number1": 0,
              "Number2": 0,
              "Number3": 0,
              "Number4": 0,
              "Number5": 0,
              "Date1": "2021-03-24T12:39:50.643Z",
              "Date2": "2021-03-24T12:39:50.643Z",
              "Date3": "2021-03-24T12:39:50.643Z",
              "Date4": "2021-03-24T12:39:50.643Z",
              "Date5": "2021-03-24T12:39:50.643Z",
              "Text1": "string",
              "Text2": "string",
              "Text3": "string",
              "Text4": "string",
              "Text5": "string",
              "Memo1": "string",
              "Memo2": "string",
              "Memo3": "string",
              "Memo4": "string",
              "Memo5": "string",
              "Searchlist1": {
                "Id": "some-id-6",
                "Name": "string"
              },
              "Searchlist2": {
                "Id": "some-id-5",
                "Name": "string"
              },
              "Searchlist3": {
                "Id": "some-id-4",
                "Name": "string"
              },
              "Searchlist4": {
                "Id": "some-id-3",
                "Name": "string"
              },
              "searchlist5": {
                "Id": "some-id-2",
                "Name": "string"
              }
            },
            "Notes": "string",
            "Creator": {
              "Id": "some-id-1",
              "name": "string"
            },
            "CreationDate": "2021-03-24T12:39:50.644Z",
            "Modifier": {
              "Id": "some-id",
              "Name": "string"
            },
            "ModificationDate": "2021-03-24T12:39:50.644Z",
            "HasAttention": true
          }
        ]
    }
}

Human Readable Output

TOPdesk branches

Id	Status	Name	Phone	Website	Address
some-branch-id	Active	HeadQuarters	1337	some-domain.com	49 Featherstone Street\nLONDON\nEC1Y 8SY\nUNITED KINGDOM

topdesk-incidents-list

Get list of incidents.

Permissions

Operator: With read permission on 1st/2nd line incident; Category/Branch/Operator filters apply

Person: Accessible; Person visibility settings apply

Base Command

topdesk-incidents-list

Input

Context Output

Command Example

#### Context Example

```json
{
    "TOPdesk": {
        "Incident": [
            {
                "Action": "/tas/api/incidents/id/some-id/actions",
                "Attachments": "/tas/api/incidents/id/some-id/attachments",
                "BriefDescription": "",
                "CallDate": "2021-03-24T08:15:13.867+0000",
                "Caller": {
                    "DynamicName": "some-caller"
                },
                "Closed": false,
                "Completed": false,
                "CreationDate": "2021-03-24T08:15:13.867+0000",
                "Creator": {
                    "Id": "some-id-1",
                    "Name": "Xsoar - Operator"
                },
                "ExternalNumber": "",
                "Id": "some-id",
                "MajorCall": false,
                "ModificationDate": "2021-03-24T08:15:13.000+0000",
                "Modifier": {
                    "Id": "some-id-1",
                    "Name": "Xsoar - Operator"
                },
                "Monitored": false,
                "Number": "XSOAR-1337",
                "OnHold": false,
                "OptionalFields1": {
                    "Searchlist1": {
                        "Id": "some-id-3",
                        "Name": "Some Search Name"
                    },
                    "Searchlist3": {
                        "Id": "some-id-4",
                        "Name": "Some Other Search Name"
                    },
                    "Text1": "",
                    "Text2": "",
                    "Text3": "",
                    "Text4": "",
                    "Text5": ""
                },
                "OptionalFields2": {
                    "Text1": "",
                    "Text2": "",
                    "Text3": "",
                    "Text4": "",
                    "Text5": ""
                },
                "ProcessingStatus": {
                    "Id": "some-processing-status-id",
                    "Name": "Logged"
                },
                "PublishToSsd": false,
                "Requests": "/tas/api/incidents/id/some-id/requests",
                "Responded": false,
                "Status": "firstLine"
            }
        ]
    }
}

Human Readable Output

TOPdesk incidents

Id	Number	Line	CallerName	Status
some-id	XSOAR-1337	firstLine	some-caller	Logged

topdesk-incident-actions

List all actions for specific incident

Permissions

Operator: With read permission on 1st/2nd line incident; Category/Branch/Operator filters apply

Persons: Accessible; Person visibility settings apply

Base Command

topdesk-incident-actions-list

Input

Context Output

topdesk-incident-create

Create an incident in TOPdesk.

The command first uses the callerLookup option and tries to attach an existing user to the caller field of the incident.
If the callerLookup shows up empty, the command will create an incident with an unregistered caller with a name as provided in the caller option.

Permissions

Operator: With create permission on 1st/2nd line incident, partials require 2nd line create permission

Person: Can only create first line incidents for himself. Only the following fields can be set depending on the setting for the new call form:

• request
• briefDescription
• callType
• category
• subcategory
• object
• location
• operatorGroup

Base Command

topdesk-incident-create

Input

Context Output

Command Example

!topdesk-incident-create caller=some-caller

Context Example

{
    "TOPdesk": {
        "Incident": [
            {
                "Action": "/tas/api/incidents/id/some-id/actions",
                "Attachments": "/tas/api/incidents/id/some-id/attachments",
                "BriefDescription": "",
                "CallDate": "2021-03-24T08:15:13.867+0000",
                "Caller": {
                    "DynamicName": "some-caller"
                },
                "Closed": false,
                "Completed": false,
                "CreationDate": "2021-03-24T08:15:13.867+0000",
                "Creator": {
                    "Id": "some-id-1",
                    "Name": "Xsoar - Operator"
                },
                "ExternalNumber": "",
                "Id": "some-id",
                "MajorCall": false,
                "ModificationDate": "2021-03-24T08:15:13.000+0000",
                "Modifier": {
                    "Id": "some-id-1",
                    "Name": "Xsoar - Operator"
                },
                "Monitored": false,
                "Number": "XSOAR-1337",
                "OnHold": false,
                "OptionalFields1": {
                    "Searchlist1": {
                        "Id": "some-id-3",
                        "Name": "Some Search Name"
                    },
                    "Searchlist3": {
                        "Id": "some-id-4",
                        "Name": "Some Other Search Name"
                    },
                    "Text1": "",
                    "Text2": "",
                    "Text3": "",
                    "Text4": "",
                    "Text5": ""
                },
                "OptionalFields2": {
                    "Text1": "",
                    "Text2": "",
                    "Text3": "",
                    "Text4": "",
                    "Text5": ""
                },
                "ProcessingStatus": {
                    "Id": "some-processing-status-id",
                    "Name": "Logged"
                },
                "PublishToSsd": false,
                "Requests": "/tas/api/incidents/id/some-id/requests",
                "Responded": false,
                "Status": "firstLine"
            }
        ]
    }
}

Human Readable Output

TOPdesk incidents

Id	Number	Line	CallerName	Status
some-id	XSOAR-1337	firstLine	some-caller	Logged

topdesk-incident-update

Update an incident in TOPdesk.

Permissions

Operator: With edit permission on 1st/2nd line incident; Category/Branch/Operator filters apply

Person: Accessible; Person visibility settings apply.
Depending on settings, the following fields can be updated:

• action
• closed
• feedbackRating
• feedbackMessage

Base Command

topdesk-incident-update

Input

Context Output

Command Example

!topdesk-incident-update description=some-updated-description number=XSOAR-1337

Context Example

{
    "TOPdesk": {
        "Incident": [
            {
                "Action": "/tas/api/incidents/id/some-id/actions",
                "Attachments": "/tas/api/incidents/id/some-id/attachments",
                "BriefDescription": "some-updated-description",
                "CallDate": "2021-03-24T08:15:13.867+0000",
                "Caller": {
                    "DynamicName": "some-caller"
                },
                "Closed": false,
                "Completed": false,
                "CreationDate": "2021-03-24T08:15:13.867+0000",
                "Creator": {
                    "Id": "some-id-1",
                    "Name": "Xsoar - Operator"
                },
                "ExternalNumber": "",
                "Id": "some-id",
                "MajorCall": false,
                "ModificationDate": "2021-03-24T08:15:13.000+0000",
                "Modifier": {
                    "Id": "some-id-1",
                    "Name": "Xsoar - Operator"
                },
                "Monitored": false,
                "Number": "XSOAR-1337",
                "OnHold": false,
                "OptionalFields1": {
                    "Searchlist1": {
                        "Id": "some-id-3",
                        "Name": "Some Search Name"
                    },
                    "Searchlist3": {
                        "Id": "some-id-4",
                        "Name": "Some Other Search Name"
                    },
                    "Text1": "",
                    "Text2": "",
                    "Text3": "",
                    "Text4": "",
                    "Text5": ""
                },
                "OptionalFields2": {
                    "Text1": "",
                    "Text2": "",
                    "Text3": "",
                    "Text4": "",
                    "Text5": ""
                },
                "ProcessingStatus": {
                    "Id": "some-processing-status-id",
                    "Name": "Logged"
                },
                "PublishToSsd": false,
                "Requests": "/tas/api/incidents/id/some-id/requests",
                "Responded": false,
                "Status": "firstLine"
            }
        ]
    }
}

Human Readable Output

TOPdesk incidents

Id	Number	Line	CallerName	Status
some-id	XSOAR-1337	firstLine	some-caller	Logged

topdesk-incident-escalate

Escalate an incident in TOPdesk.

Permissions

Operator: With 1st line incident write permission and write permission for escalating incidents; Category/Branch/Operator filters apply

Person: No access

Base Command

topdesk-incident-escalate

Input

Context Output

Command Example

!topdesk-incident-escalate number=XSOAR-1337 escalate_reason_id=some-escalation-id-1

Context Example

{
    "TOPdesk": {
        "Incident": [
            {
                "Action": "/tas/api/incidents/id/some-id/actions",
                "Attachments": "/tas/api/incidents/id/some-id/attachments",
                "BriefDescription": "some-updated-description",
                "CallDate": "2021-03-24T08:15:13.867+0000",
                "Caller": {
                    "DynamicName": "some-caller"
                },
                "Closed": false,
                "Completed": false,
                "CreationDate": "2021-03-24T08:15:13.867+0000",
                "Creator": {
                    "Id": "some-id-1",
                    "Name": "Xsoar - Operator"
                },
                "ExternalNumber": "",
                "Id": "some-id",
                "MajorCall": false,
                "ModificationDate": "2021-03-24T08:15:13.000+0000",
                "Modifier": {
                    "Id": "some-id-1",
                    "Name": "Xsoar - Operator"
                },
                "Monitored": false,
                "Number": "XSOAR-1337",
                "OnHold": false,
                "OptionalFields1": {
                    "Searchlist1": {
                        "Id": "some-id-3",
                        "Name": "Some Search Name"
                    },
                    "Searchlist3": {
                        "Id": "some-id-4",
                        "Name": "Some Other Search Name"
                    },
                    "Text1": "",
                    "Text2": "",
                    "Text3": "",
                    "Text4": "",
                    "Text5": ""
                },
                "OptionalFields2": {
                    "Text1": "",
                    "Text2": "",
                    "Text3": "",
                    "Text4": "",
                    "Text5": ""
                },
                "ProcessingStatus": {
                    "Id": "some-processing-status-id",
                    "Name": "Logged"
                },
                "PublishToSsd": false,
                "Requests": "/tas/api/incidents/id/some-id/requests",
                "Responded": false,
                "Status": "secondLine"
            }
        ]
    }
}