# Integrate OpManager with TOPdesk

Integrating OpManager with TOPdesk enables seamless incident management by automatically logging network alerts as incidents in TOPdesk. This guide walks you through the integration steps to create, update, close, and reopen incidents from OpManager into TOPdesk using APIs.

OpManager can be integrated with TOPdesk using the **custom integration** option.

**Steps to perform in OpManager**

- [Configure TOPdesk in OpManager](https://www.manageengine.com/network-monitoring/help/configure-opm-topdesk.html#configuring-topdesk-settings-in-opmanager)
  1. [Create an Incident](https://www.manageengine.com/network-monitoring/help/configure-opm-topdesk.html#create-incident)
  2. [Test and Manage Integration](https://www.manageengine.com/network-monitoring/help/configure-opm-topdesk.html#test-integration)
     1. [Update Incident Status](https://www.manageengine.com/network-monitoring/help/configure-opm-topdesk.html#update-incident-status)
     2. [Close an Incident](https://www.manageengine.com/network-monitoring/help/configure-opm-topdesk.html#close-incident)
     3. [Reopen an Incident](https://www.manageengine.com/network-monitoring/help/configure-opm-topdesk.html#reopen-incident)
     4. [Associate a Notification Profile](https://www.manageengine.com/network-monitoring/help/configure-opm-topdesk.html#notification-profile)

## Configure TOPdesk in OpManager

1. Click on **Settings**, navigate to **General Settings**, click on **Integrations**.
2. On the Integrations page, click on **Add Custom Integration Profile** or **New Custom Integration**.
3. Proceed to fill the following details:
   - **Integration Name**
   - **Description**
   - **Integration Type** (e.g., Incident Management)
   - **Create and Manage Incident** (API, payload, headers, etc.)

## Create an Incident

**Method:** POST

**API Endpoint:** `https://<Instance base URL>/tas/api/incidents`

**Payload Type:** JSON

**Data Type:** Raw

**Request Body:**

```json
{
  "briefDescription": "$stringseverity - $displayName",
  "request": "alert: $message",
  "action": "Category: $category - $displayName - $strModTime",
  "status": "secondLine",
  "callerLookup": {
    "networkLoginName": "<User_Name>"
  },
  "category": {
    "id": "c8322xacsaxx87877aaszaxsa908c"
  },
  "subcategory": {
    "id": "7f9436c6dsafcdws8i878swqw25"
  },
  "processingStatus": {
    "id": "325o908dfcsdfdcsd0114ebf7e891"
  }
}
```

**Note:** Replace `<User_Name>` with the TOPdesk login username and `<Instance base URL>` with instance ID. Ensure a valid **processingStatus.id** is provided to define the incident's initial status. Payload varies based on user requirements. Refer to [category](https://developers.topdesk.com/explorer/index.html?page=incident#/general/get_incidents_categories), [sub-category](https://developers.topdesk.com/explorer/index.html?page=incident#/general/get_incidents_subcategories), and [processing status](https://developers.topdesk.com/explorer/index.html?page=incident#/general/get_incidents_statuses) to get the corresponding IDs used in the incident payload.

![opmanager-topdesk-create-incident](https://www.manageengine.com/network-monitoring/help/images/topdesk-opm-1.png)

## Test the Integration

Click **"Test Action"** to verify the request. Once successful, click **"Manage Incident"** to retrieve the unique value from the response (e.g., the incident number). This unique identifier is used to manage the specific incident.

![opmanager-topdesk-manage-incident](https://www.manageengine.com/network-monitoring/help/images/topdesk-opm-2.png)

## Update Incident Status

**Method:** POST

**API Endpoint:** `https://<Instance base URL>/tas/api/incidents/number/$.number`

**Payload Type:** JSON

**Data Type:** Raw

**Request Body:**

```json
{
  "briefDescription": "$stringseverity - $displayName",
  "request": "alert: $message",
  "action": "Category: $category - $displayName - $strModTime",
  "status": "secondLine",
  "callerLookup": {
    "networkLoginName": "<User_Name>"
  },
  "category": {
    "id": "c8322080-94f2-4680-9b4d-527f7d2e7cac"
  },
  "subcategory": {
    "id": "7f9436c6-98c6-4c7scscr4-9d-d0a9ae3f9055"
  },
  "processingStatus": {
    "id": "325ded26-refe55657-tgr54c3-0114ebf7e891"
  }
}
```

**Note:** Replace `<User_Name>` with the actual TOPdesk login username and `<Instance base URL>` with instance ID. The request body should match the creation payload, but with an updated **processingStatus.id** to reflect a new status (e.g., “In Progress”, “Assigned”). This transitions the incident to the appropriate workflow state. Payload varies based on user requirements. Refer to [category](https://developers.topdesk.com/explorer/index.html?page=incident#/general/get_incidents_categories), [sub-category](https://developers.topdesk.com/explorer/index.html?page=incident#/general/get_incidents_subcategories), and [processing status](https://developers.topdesk.com/explorer/index.html?page=incident#/general/get_incidents_statuses) to get the corresponding IDs used in the incident payload.

![opmanager-topdesk-update-incident](https://www.manageengine.com/network-monitoring/help/images/topdesk-opm-3.png)

## Close an Incident

Closing an incident uses the same **POST** method and URL format as updating. The key change is setting **processingStatus.id** to a value that maps to a "Closed" or "Resolved" status in your TOPdesk system. This action marks the incident as resolved and completes the tracking lifecycle in the helpdesk.

**Method:** POST

**API Endpoint:** `https://<Instance base URL>/tas/api/incidents/number/$.number`

**Payload Type:** JSON

**Data Type:** Raw

**Request Body:**

```json
{
  "briefDescription": "$stringseverity - $displayName",
  "request": "alert: $message",
  "action": "Category: $category - $displayName - $strModTime",
  "status": "secondLine",
  "callerLookup": {
    "networkLoginName": "<User_Name>"
  },
  "category": {
    "id": "c8322xacsaxx87877aaszaxsa908c"
  },
  "subcategory": {
    "id": "7f9436c6dsafcdws8i878swqw25"
  },
  "processingStatus": {
    "id": "325o908dfcsdfdcsd0114ebf7e891"
  }
}
```

**Note:** Replace `<User_Name>` with your TOPdesk login user name and `<Instance base URL>` with instance ID. Payload varies based on user requirements. Refer to [category](https://developers.topdesk.com/explorer/index.html?page=incident#/general/get_incidents_categories), [sub-category](https://developers.topdesk.com/explorer/index.html?page=incident#/general/get_incidents_subcategories), and [processing status](https://developers.topdesk.com/explorer/index.html?page=incident#/general/get_incidents_statuses) to get the corresponding IDs used in the incident payload.

![opmanager-topdesk-close-incident](https://www.manageengine.com/network-monitoring/help/images/topdesk-opm-4.png)

## Reopen an Incident

To reopen a closed incident, send a **POST** request to the same incident URL. The request must contain a **processingStatus.id** corresponding to an “Open” or “In Progress” status. This allows the incident to be reopened and further actions to be taken.

Note that this is only applicable for reopening an incident. This is not applicable if you **Create a new incident**.

**Method:** POST

**API Endpoint:** `https://<Instance base URL>/tas/api/incidents/number/$.number`

**Payload Type:** JSON

**Data Type:** Raw

**Request Body:**

```json
{
  "briefDescription": "$stringseverity - $displayName",
  "request": "alert: $message",
  "action": "Category: $category - $displayName - $strModTime",
  "status": "secondLine",
  "callerLookup": {
    "networkLoginName": "<User_Name>"
  },
  "category": {
    "id": "c83225fdfre-94f2-4911-9b4d-527f7d2e7cac"
  },
  "subcategory": {
    "id": "7f9436c45775-8c6-4c71-af9d-d0a9ae3f9055"
  },
  "processingStatus": {
    "id": "325ded26-849e-4c954354-4c6-0114ebf7e891"
  }
}
```

**Note:** Replace `<User_Name>` with your TOPdesk login user name and `<Instance base URL>` with instance ID. Payload varies based on user requirements. Refer to [category](https://developers.topdesk.com/explorer/index.html?page=incident#/general/get_incidents_categories), [sub-category](https://developers.topdesk.com/explorer/index.html?page=incident#/general/get_incidents_subcategories), and [processing status](https://developers.topdesk.com/explorer/index.html?page=incident#/general/get_incidents_statuses) to get the corresponding IDs used in the incident payload.

![opmanager-topdesk-reopen-incident](https://www.manageengine.com/network-monitoring/help/images/topdesk-opm-5.png)

- Click **Save** to finalize the configuration.
- Click **Configure Now** under "Associate Notification Profile".

![opmanager-topdesk-associate-notification-profile](https://www.manageengine.com/network-monitoring/help/images/opm-associate-notification-profile.png)

- Select **Custom_Integration** and choose the "TopDesk" profile.
- Learn more about configuring [criteria](https://www.manageengine.com/network-monitoring/help/configuring-notifications.html#criteria-notifications), [devices](https://www.manageengine.com/network-monitoring/help/configuring-notifications.html#select-devices), and [time window](https://www.manageengine.com/network-monitoring/help/configuring-notifications.html#applying-time-window) in notification profiles [here](https://www.manageengine.com/network-monitoring/help/configuring-notifications.html?custom_integration_topdesk).
- Click **Save**.

Refer to the steps below to **configure multiple notification profiles**.

## Associate a Notification Profile

Follow the steps below to configure the notification profile:

1. Go to **Settings** → **Notifications** → **Notification Profiles** → **Add**
2. Select **Custom_Integration** and choose the profile named "TopDesk".

![opmanager-topdesk-custom-integration](https://www.manageengine.com/network-monitoring/help/images/topdesk-opm-8.png)

3. Learn more about configuring [criteria](https://www.manageengine.com/network-monitoring/help/configuring-notifications.html#criteria-notifications), [devices](https://www.manageengine.com/network-monitoring/help/configuring-notifications.html#select-devices), and [time window](https://www.manageengine.com/network-monitoring/help/configuring-notifications.html#applying-time-window) in notification profiles [here](https://www.manageengine.com/network-monitoring/help/configuring-notifications.html?custom_integration_topdesk).
4. Click **Save**.

## Verifying the Integration

Trigger a real-time alert in OpManager. Then, log in to your TOPdesk interface to verify the alert has been logged as an incident.

[Know more about the integrations offered by OpManager](https://www.manageengine.com/network-monitoring/integration.html?custom_integration_topdesk)

[Know more about dynamic variables used in request body](https://www.manageengine.com/network-monitoring/help/workflow-variables.html?custom_integration_topdesk)