BMC Helix ITSM

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

BMC Helix ITSM Configuring OAuth 2.0

BMC Helix ITSM API Documentation Link

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

Configuring OAuth 2.0: 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.

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.

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.

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.

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.

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.

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

Docs powered by Archbee