---
title: BMC Helix ITSM
slug: connectors/bmc-helix-itsm
docTags: 
createdAt: 2026-06-09T16:30:25.364Z
---

The BMC Helix ITSM connector facilitates the automation of IT service management tasks such as incident creation, problem recording, and change request management.

BMC Helix ITSM is a cutting-edge IT service management solution that streamlines incident, problem, and change management processes. This connector enables Swimlane Turbine users to automate ITSM workflows, such as creating and updating incidents, problems, and changes directly within BMC Helix ITSM. By integrating with BMC Helix ITSM, users can enhance their incident response capabilities, reduce manual efforts, and accelerate resolution times, all while maintaining a centralized view of ITSM activities.

### Limitations

With BMC Helix Single Sign-On, your end users can present credentials for authentication only once in a multi software environment. Administrators enable single sign-on experience for applications, configure authentication methods, and review audit records.

### Supported Version

It supports the 21.3 version of BMC Helix Single Sign-On.

### Additional Docs

- [BMC Helix ITSM Authentication Link](https://docs.bmc.com/docs/is221/using-authorization-rest-apis-to-consume-bmc-helix-single-sign-on-1039590021.html)
- [BMC Helix ITSM Configuring OAuth 2.0](https://docs.bmc.com/docs/rsso/213/configuring-oauth-2-0-1198861985.html)
- [BMC Helix ITSM API Documentation Link](https://docs.bmc.com/docs/itsm221/integrating-third-party-applications-with-bmc-helix-itsm-by-using-the-simplified-rest-api-1053748396.html)

## Configuration

### Prerequisites

To effectively utilize the BMC Helix ITSM connector with Swimlane Turbine, ensure you have the following prerequisites:

- Custom authentication configured with the necessary parameters:
  - URL: Endpoint for BMC Helix ITSM API access

## Authentication Methods

### OAuth2 access token authentication with these parameter

- URL: The endpoint for the BMC Helix ITSM API services.
- Access Token: Token used to authenticate API requests.

### OAuth2 refresh token authentication with these parameters

- URL: The endpoint for the BMC Helix ITSM API services.
- Client ID: The client ID must correspond to the client ID specified in the registeredclient table.
- Client Secret: The client secret  must correspond to the redirect URI specified in the registeredclient table.
- Refresh Token: A token used to obtain a new access token when the current one expires.

**Setup Instructions**

**Document References:**

- OAuth2.0 login document reference: [https://docs.bmc.com/docs/is221/using-authorization-rest-apis-to-consume-bmc-helix-single-sign-on-1039590021.html](https://docs.bmc.com/docs/is221/using-authorization-rest-apis-to-consume-bmc-helix-single-sign-on-1039590021.html)
- Configuring OAuth 2.0: [https://docs.bmc.com/docs/rsso/213/configuring-oauth-2-0-1198861985.html](https://docs.bmc.com/docs/rsso/213/configuring-oauth-2-0-1198861985.html)

## Capabilities

- Create a Change
- Create a Problem
- Create an Incident
- Retrieve Incident Details Based on Search Criteria
- Retrieve Incident Details Based on the Incident ID
- Update the Details of an Incident

### Create a Change

Create a change in BMC Helix ITSM. It's used to create the BMC Helix ITSM tickets.

BMC Helix ITSM's documentation for this action can be found [here](https://docs.bmc.com/docs/itsm221/example-of-using-the-simplified-rest-api-to-create-a-ticket-1117623801.html).

### Create a Problem

Create a Problem in BMC Helix ITSM. It's used to create the BMC Helix ITSM tickets.

BMC Helix ITSM's documentation for this action can be found [here](https://docs.bmc.com/docs/itsm221/example-of-using-the-simplified-rest-api-to-create-a-ticket-1117623801.html).

### Create an Incident

Create an Incident in BMC Helix ITSM. It's used to create the BMC Helix ITSM tickets.

BMC Helix ITSM's documentation for this action can be found [here](https://docs.bmc.com/docs/itsm221/example-of-using-the-simplified-rest-api-to-create-a-ticket-1117623801.html).

### Retrieve Incident Details Based on Search Criteria

Retrieve detailed information on incidents in BMC Helix ITSM using specified search criteria.

BMC Helix ITSM's documentation for this action can be found [here](https://docs.bmc.com/docs/itsm213/example-of-using-the-simplified-rest-api-to-search-and-update-an-incident-1030556758.html).

### Retrieve Incident Details Based on the Incident ID

Retrieve detailed information for a specific incident in BMC Helix ITSM using the provided incident ID.

BMC Helix ITSM's documentation for this action can be found [here](https://docs.bmc.com/docs/itsm213/example-of-using-the-simplified-rest-api-to-search-and-update-an-incident-1030556758.html).

### Update the Details of an Incident

Updates an incident's details in BMC Helix ITSM using the specified incident ID and provided data.

BMC Helix ITSM's documentation for this action can be found [here](https://docs.bmc.com/docs/itsm213/example-of-using-the-simplified-rest-api-to-search-and-update-an-incident-1030556758.html).

## Notes

- The Swimlane team will provide a Python script and instructions on how to use the script to generate the Access Token and Refresh Token using Oauth2.0.

# Configurations

## BMC Helix ITSM Custom Authentication

BMC Helix ITSM custom authentication using Access Token or Client Credentials.

### Configuration Parameters

| **Parameter**  | **Description**                                                                                 | **Type** | **Required** |
| -------------- | ----------------------------------------------------------------------------------------------- | -------- | ------------ |
| url            | A URL to the target host.                                                                       | string   | Required     |
| access\_token  | The Access token.                                                                               | string   | Optional     |
| client\_id     | The client ID must correspond to the client ID specified in the registeredclient table.         | string   | Optional     |
| client\_secret | The client secret  must correspond to the redirect URI specified in the registeredclient table. | string   | Optional     |
| refresh\_token | The Refresh token.                                                                              | string   | Optional     |
| verify\_ssl    | Verify SSL certificate                                                                          | boolean  | Optional     |
| http\_proxy    | A proxy to route requests through.                                                              | string   | Optional     |

# Actions

## Create a Change

Creates a new change request in BMC Helix ITSM with the provided headers and JSON body content.

### Endpoint

- **URL:** `/api/com.bmc.dsm.itsm.itsm-rest-api/v2/change`
- **Method:** `POST`

### Input

| **Argument Name**              | **Type** | **Required** | **Description**                                   |
| ------------------------------ | -------- | ------------ | ------------------------------------------------- |
| `headers`                      | object   | Required     | HTTP headers for the request                      |
| `headers.X-Requested-By`       | string   | Required     | The header value should be XMLHttpRequest.        |
| `summary`                      | string   | Optional     | The summary of the change.                        |
| `impact`                       | number   | Optional     | The impact of the change.                         |
| `urgency`                      | number   | Optional     | The urgency of the change.                        |
| `status`                       | number   | Optional     | The status of the change.                         |
| `locationCompany`              | string   | Optional     | The location company of the change.               |
| `requestedFor`                 | object   | Optional     | Parameter for Create a Change                     |
| `requestedFor.loginId`         | string   | Optional     | The Login ID of the requested for.                |
| `coordinatorGroupId`           | string   | Optional     | The coordinator group ID of the change.           |
| `coordinatorGroup`             | string   | Optional     | The coordinator group of the change.              |
| `coordinatorGroupOrganization` | string   | Optional     | The coordinator group organization of the change. |
| `coordinatorGroupCompany`      | string   | Optional     | The coordinator group company of the change.      |

### Input Example

`{"json_body":{"summary":"Change the printer","impact":4000,"urgency":1000,"status":1,"locationCompany":"Petramco","requestedFor":{"loginId":"PetramcoAllTicketMaster"},"coordinatorGroupId":"SGP000000000213","coordinatorGroup":"Petramco Support Group1","coordinatorGroupOrganization":"Petramco Support Org1","coordinatorGroupCompany":"Petramco"},"headers":{"X-Requested-By":"XMLHttpRequest"}}`

### Output

| **Parameter** | **Type** | **Description**                  |
| ------------- | -------- | -------------------------------- |
| `status_code` | number   | HTTP status code of the response |
| `reason`      | string   | Response reason phrase           |

### Output Example

`{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Thu, 16 Jan 2024 20:37:23 GMT"},"reason":"OK","json_body":{}}`

## Create a Problem

Initiates the creation of a problem record in BMC Helix ITSM using specified headers and JSON body content.

### Endpoint

- **URL:** `/api/com.bmc.dsm.itsm.itsm-rest-api/v2/problem`
- **Method:** `POST`

### Input

| **Argument Name**        | **Type** | **Required** | **Description**                            |
| ------------------------ | -------- | ------------ | ------------------------------------------ |
| `headers`                | object   | Required     | HTTP headers for the request               |
| `headers.X-Requested-By` | string   | Required     | The header value should be XMLHttpRequest. |
| `summary`                | string   | Optional     | Summary of the problem.                    |
| `description`            | string   | Optional     | Description of the problem.                |
| `impact`                 | number   | Optional     | Impact of the problem.                     |
| `urgency`                | number   | Optional     | Urgency of the problem.                    |
| `siteId`                 | string   | Optional     | Site ID of the problem.                    |
| `site`                   | string   | Optional     | Site of the problem.                       |
| `siteGroup`              | string   | Optional     | Site Group of the problem.                 |
| `siteRegion`             | string   | Optional     | Site Region of the problem.                |
| `company`                | string   | Optional     | Company of the problem.                    |

### Input Example

`{"json_body":{"summary":"Sample problem is created","description":"This is sample problem to test create problem api","impact":4000,"urgency":4000,"siteId":"STE_SOLN0002846","site":"Headquarters, Building 1.31","siteGroup":"United States","siteRegion":"Americas","company":"Calbro Services"},"headers":{"X-Requested-By":"XMLHttpRequest"}}`

### Output

| **Parameter** | **Type** | **Description**                  |
| ------------- | -------- | -------------------------------- |
| `status_code` | number   | HTTP status code of the response |
| `reason`      | string   | Response reason phrase           |

### Output Example

`{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Thu, 16 Jan 2024 20:37:23 GMT"},"reason":"OK","json_body":{}}`

## Create an Incident

Initiates the creation of an incident in BMC Helix ITSM using the provided JSON body details.

### Endpoint

- **URL:** `/api/com.bmc.dsm.itsm.itsm-rest-api/v2/incident`
- **Method:** `POST`

### Input

| **Argument Name**             | **Type** | **Required** | **Description**                                |
| ----------------------------- | -------- | ------------ | ---------------------------------------------- |
| `summary`                     | string   | Optional     | Summary of the incident.                       |
| `impact`                      | number   | Optional     | Impact of the incident.                        |
| `priority`                    | number   | Optional     | Priority of the incident.                      |
| `urgency`                     | number   | Optional     | Urgency of the incident.                       |
| `incidentType`                | number   | Optional     | Type of the incident.                          |
| `assigneeGroupId`             | string   | Optional     | Assignee group ID of the incident.             |
| `assigneeGroup`               | string   | Optional     | Assignee group of the incident.                |
| `assigneeSupportCompany`      | string   | Optional     | Assignee support company of the incident.      |
| `assigneeSupportOrganization` | string   | Optional     | Assignee support organization of the incident. |
| `customer`                    | object   | Optional     | Customer of the incident.                      |
| `customer.loginId`            | string   | Optional     | Login ID of the customer.                      |

### Input Example

`{"json_body":{"summary":"Printer is not working","impact":2000,"priority":2,"urgency":4000,"incidentType":0,"assigneeGroupId":"SGP000000000010","assigneeGroup":"Frontoffice Support","assigneeSupportCompany":"Calbro Services","assigneeSupportOrganization":"IT Support","customer":{"loginId":"Allen"}}}`

### Output

| **Parameter** | **Type** | **Description**                  |
| ------------- | -------- | -------------------------------- |
| `status_code` | number   | HTTP status code of the response |
| `reason`      | string   | Response reason phrase           |

### Output Example

`{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Thu, 16 Jan 2024 20:37:23 GMT"},"reason":"OK","json_body":{}}`

## Retrieve Incident Details Based on Search Criteria

Retrieve detailed incident information from BMC Helix ITSM based on user-defined search criteria.

### Endpoint

- **URL:** `/api/com.bmc.dsm.itsm.itsm-rest-api/incident/search`
- **Method:** `POST`

### Input

| **Argument Name**            | **Type** | **Required** | **Description**                             |
| ---------------------------- | -------- | ------------ | ------------------------------------------- |
| `parameters.filter`          | string   | Optional     | Filter incidents by group.                  |
| `limit`                      | number   | Optional     | Maximum number of incidents to return.      |
| `offset`                     | number   | Optional     | Starting point for the incident list.       |
| `sortBy`                     | array    | Optional     | Sort the incidents by field and order.      |
| `sortBy.field`               | string   | Optional     | Field to sort by.                           |
| `sortBy.order`               | string   | Optional     | Order of the sort.                          |
| `fields`                     | array    | Optional     | Fields to return in the response.           |
| `criteria`                   | object   | Optional     | Criteria to filter the incidents.           |
| `criteria.bindingExpression` | string   | Optional     | Binding expression to use for the criteria. |
| `criteria.conditions`        | string   | Optional     | Conditions to filter the incidents.         |

### Input Example

`{"parameters":{"filter":"My Group"},"json_body":{"limit":10,"offset":10,"sortBy":[{"field":"priority","order":"desc"}],"fields":"['id','status']","criteria":{"bindingExpression":"AND","conditions":"{\r\n              \"fieldName\": \"status\",\r\n              \"operation\": \"eq\",\r\n              \"fieldValue\": \"27000\"\r\n          },\r\n          {\r\n              \"fieldName\": \"assignee\",\r\n              \"operation\": \"eq\",\r\n              \"fieldValue\": \"Allen Allbrook\"\r\n          }"}}}`

### Output

| **Parameter** | **Type** | **Description**                  |
| ------------- | -------- | -------------------------------- |
| `status_code` | number   | HTTP status code of the response |
| `reason`      | string   | Response reason phrase           |

### Output Example

`{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Thu, 16 Jan 2024 20:37:23 GMT"},"reason":"OK","json_body":{}}`

## Retrieve Incident Details Based on the Incident ID

Retrieve detailed information for a specific incident in BMC Helix ITSM using the provided incident ID.

### Endpoint

- **URL:** `/api/com.bmc.dsm.itsm.itsm-rest-api/incident/{{incident_id}}`
- **Method:** `GET`

### Input

| **Argument Name**             | **Type** | **Required** | **Description** |
| ----------------------------- | -------- | ------------ | --------------- |
| `path_parameters.incident_id` | string   | Required     | Incident ID.    |

### Input Example

`{"path_parameters":{"incident_id":"INC000000000102"}}`

### Output

| **Parameter** | **Type** | **Description**                  |
| ------------- | -------- | -------------------------------- |
| `status_code` | number   | HTTP status code of the response |
| `reason`      | string   | Response reason phrase           |

### Output Example

`{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Thu, 16 Jan 2024 20:37:23 GMT"},"reason":"OK","json_body":{}}`

## Update the Details of an Incident

Updates an incident's details in BMC Helix ITSM using the specified incident ID and provided data.

### Endpoint

- **URL:** `/api/com.bmc.dsm.itsm.itsm-rest-api/incident/{{incident_id}}`
- **Method:** `PATCH`

### Input

| **Argument Name**                   | **Type** | **Required** | **Description**                                 |
| ----------------------------------- | -------- | ------------ | ----------------------------------------------- |
| `path_parameters.incident_id`       | string   | Required     | The ID of the incident to be updated.           |
| `id`                                | string   | Optional     | Unique identifier for the item.                 |
| `guid`                              | string   | Optional     | Unique identifier for the item.                 |
| `instanceId`                        | string   | Optional     | Unique identifier for the Instance.             |
| `summary`                           | string   | Optional     | Brief description of the item.                  |
| `description`                       | string   | Optional     | Detailed description of the item.               |
| `locationCompany`                   | string   | Optional     | Company where the item is located.              |
| `createDate`                        | string   | Optional     | Date when the item was created.                 |
| `modifiedDate`                      | string   | Optional     | Date when the item was last modified.           |
| `type`                              | number   | Optional     | Type of the item.                               |
| `status`                            | number   | Optional     | Status of the item.                             |
| `statusReason`                      | number   | Optional     | Reason for the status of the item.              |
| `resolutionNote`                    | string   | Optional     | Note for the resolution of the item.            |
| `priority`                          | number   | Optional     | Priority of the item.                           |
| `impact`                            | number   | Optional     | Impact of the item.                             |
| `urgency`                           | number   | Optional     | Urgency of the item.                            |
| `customer`                          | object   | Optional     | Parameter for Update the Details of an Incident |
| `customer.loginId`                  | string   | Optional     | Login ID of the customer.                       |
| `customer.firstName`                | string   | Optional     | First name of the customer.                     |
| `customer.lastName`                 | string   | Optional     | Last name of the customer.                      |
| `customer.fullName`                 | string   | Optional     | Full name of the customer.                      |
| `customer.company`                  | string   | Optional     | Company of the customer.                        |
| `customer.permission`               | array    | Optional     | Permissions of the customer.                    |
| `customer.assigneeSupportGroups`    | array    | Optional     | Parameter for Update the Details of an Incident |
| `customer.assigneeSupportGroups.id` | string   | Optional     | ID of the group.                                |

### Input Example

`{"path_parameters":{"incident_id":"INC000000000102"}}`

### Output

| **Parameter** | **Type** | **Description**                  |
| ------------- | -------- | -------------------------------- |
| `status_code` | number   | HTTP status code of the response |
| `reason`      | string   | Response reason phrase           |

### Output Example

`{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Thu, 16 Jan 2024 20:37:23 GMT"},"reason":"OK","json_body":{}}`

# Response Headers

| **Header**     | **Description**                                       | **Example**                   |
| -------------- | ----------------------------------------------------- | ----------------------------- |
| content-length | The length of the response body in bytes              | 140                           |
| content-type   | The media type of the resource                        | application/json              |
| Date           | The date and time at which the message was originated | Thu, 16 Jan 2024 20:37:23 GMT |