BMC Helix ITSM connector powered by MuleSoft

The BMC Helix ITSM connector, powered by MuleSoft provides a connection between the MuleSoft connector engine and BMC Helix ITSM. Use the connector to configure activities for the connection that can be used as a source or target within operations defined for the connection. You can perform get, create, search, and update BMC Helix ITSM records and forms by using the connector.

Before you begin

Make sure you have the following subscriptions, applications, and access to set up and use the integration:

• Permissions to create and modify cases in BMC Helix ITSM
• Anypoint Studio version 7.8.0 is installed

Supported product versions

Configuring the BMC Helix ITSM connector for MuleSoft in Anypoint Studio

Use Anypoint Studio to configure the connector and then publish it in the cloud platform for distribution. You can design and update your application, properties, and configuration files for the connector.

Complete the following procedures to configure the connector in Anypoint Studio:

1. Create a MuleSoft project and add the connector to the project
2. Create the files required for the connector configuration
3. Configure the connector

After you complete the configuration, you define a workflow and add the following operations:

Task 1: To create a MuleSoft project and add the connector to the project 

1. Log in to Anypoint Studio.
2. Select File > New > Mule Project.
3. Enter a name for your project and click Finished. 
   To populate the XML code with the connector's name space and schema location, and required dependencies to the project's pom.xml file, add the connector to your project.
4. In the Mule Palette view, click (X) Search in Exchange.
5. In the Add Dependencies to Project dialog box, enter BMC Helix ITSM in the search field.

6. From the Available Modules list, select BMC Helix ITSM Connector - Mule 4, and click Add >.

7. Click Finish.

   Important

   You must add the connector to each project you create. Adding the connector to a project does not make it available to other projects in Anypoint Studio.

8. On the Package Explorer tab, open the pom.xml for your project and verify that the following dependency is included in the file:

   <dependency>
   	<groupId>org.mule.bmc.connector</groupId>
   	<artifactId>bmc-helix-itsm-connector</artifactId>
   	<version>1.0.0</version>
   	<classifier>mule-plugin</classifier>
   </dependency>  

   The BMC Helix ITSM connector is listed in the Mule Palette for your project.

9. To save your updates, click the Save icon on the application toolbar.

Task 2: To create the files required for the connector configuration 

1. Create a properties file for the project. 

   1. Right-click the src/main/resources branch and select New > File.
   2. Enter a name for the file; for example: project.properties.
   3. Enter the following variable values in the file and save it: 

      • hostURL—Enter the URL of the BMC Helix ITSM instance; for example, https://hostname-dsom-platform.trybmc.com/.

      • userName—Enter the name of the user who has permissions to create or modify the case. For example, aUser@bmc.com.

      • password—Enter the password for the user name entered.

      These variables are used to configure your connector.
2. Create a configuration file to define the connector configuration:
   1. Right-click the src/main/mule branch and select New > Mule Configuration File.
   2. In the General Information dialog box, enter config.xml in the Name and click Finish.
   3. Click Global Elements and then click Create.
   4. Select Global Configurations > Configuration Properties.
   5. On the General tab, select the project.properties file created in the previous step and then click OK.
3. To save your updates, click the Save icon on the application toolbar.

Task 3: To configure the connector 

1. From the Package Explorer pane, double-click the <projectName>.xml file.
2. To run the workflow when specific conditions are met, configure HTTP Listener as the source: 
   

   1. From the Mule Palette, select HTTP > Listener. 

   2. Select the Listener element, and add the following details: 

      Field name	Actions
      Display name	Enter a short display name for the source.
      Connector configuration	Click the + sign to add the connector configuration and add the following details: Name—Enter a name for the configuration. Protocol—Select HTTP or HTTPS. Host—Select the default value. Port—For HTTP, enter 8081 and for HTTPS, enter 8082. Important: If the selected port is in use, enter a different value. Base path—Enter a path for the flow. Listener interceptors—Select None.

   3. To verify the configuration values, click Test Connection. 

3. Define the connector configuration.
   1. From the Mule Palette, select BMC Helix ITSM, and drag a BMC Helix ITSM activity to the Message Flow tab. 
   2. On the Message Flow tab, select a BMC Helix ITSM operation.

   3. To define the connector configuration, click the + icon for Connector configuration in the Basic Settings section.

   4. Enter the following variables defined in the project.properties file in Task 2:

      Important

      Create a properties file for the proxy configuration and add the variable values instead of the actual values.

      Field name	Value
      Name	Name for the connector configuration.
      General tab
      Host URL	${hostURL}
      User Name	${userName}
      Password	${password}
      Proxy Config
      Host	URL of the proxy server
      Port	Port number for the proxy server
      Username	User name to connect to the proxy server
      Password	User's password to connect to the proxy server
      NTLM Domain	Domain name of the NT LAN Manager (NTLM) active directory server

   5. To verify the configuration values, click Test Connection. 

   6. Click OK.
   7. To save your updates, click the Save icon on the application toolbar.
   After you configure the connector, this configuration is used for all the BMC Helix ITSM operations in your flow. After you set up the project configuration files and the details for the BMC Helix ITSM connector for MuleSoft, you can create flows between BMC Helix ITSM and other applications.

A typical flow requires the source configuration, for example HTTP > Listener, a request Transform Message that writes information to the BMC Helix ITSM operation, the activity configuration, a response Transform Message that receives the information from the activity and a final logger element to write data to your target application. 

After you create the workflow, run the project (right-click project name and select Run Project As > Mule Application), and then run the flow by using an application like Postman.

The following images show examples of sample workflows created for the BMC Helix ITSM Change Management and Update operations, and the available options for them:

Change Management - Workflow

Update operation - Workflow

Change Management - Available actions

Update operation - Form selection options

BMC Helix ITSM form data operations

The BMC Helix ITSM connector provides operations to create, update, query, merge or delete entries in the selected BMC Helix ITSM form at the BMC Helix ITSM endpoint. These operations are intended to be used as a target in a workflow. 

To configure form operations

1. From the Mule Palette, select BMC Helix ITSM > operationName, where operationsName is Create, Update, Query, Merge, or Delete. 
2. Drag the operationName option to the Message Flow tab. 

3. Select the operationName brick and on the operationName tab, enter the following configuration details:

   Parameter	Value
   Display name	Operation name
   Basic Settings
   Connector configuration	Configuration file created for the connector
   General
   Form	Select the BMC Helix ITSM form name where you want to create, update, query, merge, or delete entries.
   Input payloads	To define specific field mappings for the operation depending on the form selected, click and add your payload data. After you complete mapping the field values, click Done. Important: When using this operation in a flow, to get data from an external source, define the payload metadata in the Transform message.
   Continue on error	Select the action to be taken if an error occurs. You have the following options: True—Continues with the operation even if an error occurs False (Default)— Displays an exception if an error occurs during the operation Expression—Selects a variable that provides details of the message to display when an error occurs

4. To save your updates, click the Save icon on the application toolbar.

Change Management 

Use the Change Management operation to create, query, or update a change request, or create a change request worklog in the BMC Change Management form at a BMC Helix ITSM endpoint. The operation is intended to be used as a target in a workflow. 

To configure the Change Management operation

1. From the Mule Palette, select BMC Helix ITSM > Change Management.
2. Drag the Change Management option to the Message Flow tab. 

3. Select the Change Management brick and on the Change Management tab, enter the following configuration details:

   Parameter	Value
   Display name	Operation name
   Basic Settings
   Connector configuration	Configuration file created for the connector
   General
   Operation	Select an operation to perform on the Change Management form. The following options are available: Create Change Query Change Update Change Create Change Worklog
   Input payload	To define specific field mappings for the operation, click and add your payload data. Sample payload to create multiple records for a Create Change operation: [{ "First Name": "Allen", "Last Name": "Allbrook", "Description": "Change printer cartridge", "Short Description": "Created on Apr12", "Status": "Draft", "Impact": "4-Minor/Localized", "Urgency": "4-Low", "Risk Level": "Risk Level 2", "Company": "Calbro Services", "Location Company": "Calbro Services" }, { "First Name": "Allen", "Last Name": "Allbrook", "Description": "Service printers", "Short Description": "Created on Apr12", "Status": "Draft", "Impact": "4-Minor/Localized", "Urgency": "4-Low", "Risk Level": "Risk Level 2", "Company": "Calbro Services", "Location Company": "Calbro Services" }, ] After you complete mapping the field values, click Done. Important: To add attachments for the Create and Update operations, add the details of the file name and Base64 format of the file content to your payload data, or in the payload metadata in the Transform message. For example: z2AF_Act_Attachment_1: { name: "bmc_readme.txt", href: "4oCiCUFkZGluZyBwcm9qZWN0IHZhcmlhYmxlIGZvciBjdXN0b20gQVBJIHRpbWVvdXRzLg0K4oCiCUZpeCBvZiBoYXJkY29kZWQgdmFsdWUgaW4gdGhlIHNjcmlwdHMNCg==" }, where bmc_readme.txt is the name of the attachment file, and the value defined for href is the Base64 format of the file content. When using this operation in a flow, to get data from an external source, define the payload metadata in the Transform message.
   Continue on error	Select the action to be taken if an error occurs. You have the following options: True—Continues with the operation even if an error occurs False (Default)— Displays an exception if an error occurs during the operation Expression—Selects a variable that provides details of the message to display when an error occurs

4. To save your updates, click the Save icon on the application toolbar.

Incident Management 

Use the Incident Management operation to create, query, or update an incident request, or create an incident request worklog in the BMC Incident Management form at a BMC Helix ITSM endpoint. The operation is intended to be used as a target in a workflow.

To configure the Incident Management operation

1. From the Mule Palette, select BMC Helix ITSM > Incident Management. 
2. Drag the Incident Management option to the Message Flow tab. 

3. Select the Incident Management brick and on the Incident Management tab, enter the following configuration details:

   Parameter	Value
   Display name	Operation name
   Basic Settings
   Connector configuration	Configuration file created for the connector
   General
   Operation	Select an operation to perform on the Incident Management form. The following options are available: Create Incident Query Incident Update Incident Create Incident Worklog
   Input payload	To define specific field mappings for the operation, click and add your payload data. For example, add the following payload for a Create Incident operation: [{ "First_Name": "Allen", "Last_Name": "Allbrook", "Status": "New", "Urgency": "1-Critical", "Impact": "1-Extensive/Widespread", "Service_Type": "User Service Request", "Description": "ITSM Automation summary", "Company": "Calbro Services", "Reported Source": "Fax" }] After you complete mapping the field values, click Done. Important: To add attachments for the Create and Update operations, add the details of the file name and Base64 format of the file content to your payload data, or in the payload metadata in the Transform message. For example, z2AF_Act_Attachment_1: { name: "bmc_readme.txt", href: "4oCiCUFkZGluZyBwcm9qZWN0IHZhcmlhYmxlIGZvciBjdXN0b20gQVBJIHRpbWVvdXRzLg0K4oCiCUZpeCBvZiBoYXJkY29kZWQgdmFsdWUgaW4gdGhlIHNjcmlwdHMNCg==" }, where bmc_readme.txt is the name of the attachment file, and the value defined for href is the Base64 format of the file content. When using this operation in a flow, to get data from an external source, define the payload metadata in the Transform message.
   Continue on error	Select the action to be taken if an error occurs. You have the following options: True—Continues with the operation even if an error occurs False (Default)— Displays an exception if an error occurs during the operation Expression—Selects a variable that provides details of the message to display when an error occurs

4. To save your updates, click the Save icon on the application toolbar.

Known Error 

Use the Known Error operation to create, query, or update a known error request, or create a known error worklog in the BMC Known Error form at a BMC Helix ITSM endpoint. The operation is intended to be used as a target in a workflow.

To configure the Known Error operation

1. From the Mule Palette, select BMC Helix ITSM > Known Error. 
2. Drag the Known Error option to the Message Flow tab. 

3. Select the Known Error brick and on the Known Error tab, enter the following configuration details:

   Parameter	Value
   Display name	Operation name
   Basic Settings
   Connector configuration	Configuration file created for the connector
   General
   Operation	Select an operation to perform on the Known Error form. The following options are available: Create Known Error Query Known Error Update Known Error Create Known Error Worklog
   Input payload	To define specific field mappings for the operation, click and add your payload data. For example: [{ "First Name": "Allen", "Last Name": "Allbrook", "Urgency": "1-Critical", "Impact": "1-Extensive/Widespread", "Priority": "Critical", "Problem Investigation ID": "PBI_10000102", "Description": "Password not automatically updated to all accounts.", "Detailed Decription": "Automation by QA1", "View Access": "Internal", "Contact Company": "Calbro Services", "Company": "Calbro Services", "Support Company Pblm Mgr": "Calbro Services", "Support Organization Pblm Mgr": "IT Support", "Assigned Group Pblm Mgr": "Service Desk", "Problem Manager Login": "Allen", "Target Resolution Date": "2021-05-22T06:27:03.000+0000" }, { "First Name": "Allen", "Last Name": "Allbrook", "Urgency": "1-Critical", "Impact": "1-Extensive/Widespread", "Priority": "Critical", "Problem Investigation ID": "PBI_10000102", "Description": "Multiple save messages displayed", "Detailed Decription": "Automation by QA2", "View Access": "Internal", "Contact Company": "Calbro Services", "Company": "Calbro Services", "Support Company Pblm Mgr": "Calbro Services", "Support Organization Pblm Mgr": "IT Support", "Assigned Group Pblm Mgr": "Service Desk", "Problem Manager Login": "Allen", "Target Resolution Date": "2021-05-22T06:27:03.000+0000" }] After you complete mapping the field values, click Done. Important: To add attachments for the Create and Update operations, add the details of the file name and Base64 format of the file content to your payload data, or in the payload metadata in the Transform message. For example: z2AF_Act_Attachment_1: { name: "bmc_readme.txt", href: "4oCiCUFkZGluZyBwcm9qZWN0IHZhcmlhYmxlIGZvciBjdXN0b20gQVBJIHRpbWVvdXRzLg0K4oCiCUZpeCBvZiBoYXJkY29kZWQgdmFsdWUgaW4gdGhlIHNjcmlwdHMNCg==" }, where bmc_readme.txt is the name of the attachment file, and the value defined for href is the Base64 format of the file content. When using this operation in a flow, to get data from an external source, define the payload metadata in the Transform message.
   Continue on error	Select the action to be taken if an error occurs. You have the following options: True—Continues with the operation even if an error occurs False (Default)— Displays an exception if an error occurs during the operation Expression—Selects a variable that provides details of the message to display when an error occurs

4. To save your updates, click the Save icon on the application toolbar.

Problem 

Use the Problem operation to create, query, or update a problem record, or create a problem worklog in the Problem Management form at a BMC Helix ITSM endpoint. The operation is intended to be used as a target in a workflow. 

To configure the Problem operation

1. From the Mule Palette, select BMC Helix ITSM > Problem. 
2. Drag the Problem option to the Message Flow tab. 

3. Select the Problem brick and on the Problem tab, enter the following configuration details:

   Parameter	Value
   Display name	Operation name
   Basic Settings
   Connector configuration	Configuration file created for the connector
   General
   Operation	Select an operation to perform on the Known Error form. The following options are available: Create Problem Query Problem Update Problem Create Problem Worklog
   Input payload	To define specific field mappings for the operation, click and add your payload data. For example: [{ "First Name": "Allen", "Last Name": "Allbrook", "Status_Reason": "Draft", "Status": "Draft", "Urgency": "1-Critical", "Impact": "1-Extensive/Widespread", "Priority": "Critical", "Investigation Driver": "High Impact Incident", "Description": "Create Problem record", "Assigned Group Pblm Mgr": "Backoffice Support", "Target Resolution Date": "2022-05-22T06:27:03.000+0000" }] After you complete mapping the field values, click Done. Important: To add attachments for the Create and Update operations, add the details of the file name and Base64 format of the file content to your payload data, or in the payload metadata in the Transform message. For example, z2AF_Act_Attachment_1: { name: "bmc_readme.txt", href: "4oCiCUFkZGluZyBwcm9qZWN0IHZhcmlhYmxlIGZvciBjdXN0b20gQVBJIHRpbWVvdXRzLg0K4oCiCUZpeCBvZiBoYXJkY29kZWQgdmFsdWUgaW4gdGhlIHNjcmlwdHMNCg==" }, where bmc_readme.txt is the name of the attachment file, and the value defined for href is the Base64 format of the file content. When using this operation in a flow, to get data from an external source, define the payload metadata in the Transform message.
   Continue on error	Select the action to be taken if an error occurs. You have the following options: True—Continues with the operation even if an error occurs False (Default)— Displays an exception if an error occurs during the operation Expression—Selects a variable that provides details of the message to display when an error occurs.

4. To save your updates, click the Save icon on the application toolbar.

Work Order 

Use the Work Order operation to create, query, or update a work order record, or create a work order worklog in the Work Order form at a BMC Helix ITSM endpoint. The operation is intended to be used as a target in a workflow. 

To configure the Work Order operation

1. From the Mule Palette, select BMC Helix ITSM > Work Order. 
2. Drag the Work Order option to the Message Flow tab. 

3. Select the Work Order brick and on the Problem tab, enter the following configuration details:

   Parameter	Value
   Display name	Operation name
   Basic Settings
   Connector configuration	Configuration file created for the connector
   General
   Operation	Select an operation to perform on the Known Error form. The following options are available: Create Work Order Query Work Order Update Work Order Create Work Order Worklog
   Input payload	To define specific field mappings for the operation, click and add your payload data. For example: [{ "Work Order Type": "General", "Status": "Assigned", "Priority": "Low", "Customer First Name": "Mary", "Customer Last Name": "Mann", "Location Company": "Calbro Services", "Customer Company": "Calbro Services", "Company": "Calbro Services", "Support Group Name": "Backoffice Support", "View Access": "Internal", "Summary": "Create Workorder1", }] After you complete mapping the field values, click Done. Important: When using this operation in a flow, to get data from an external source, define the payload metadata in the Transform message.
   Continue on error	Select the action to be taken if an error occurs. You have the following options: True—Continues with the operation even if an error occurs False (Default)— Displays an exception if an error occurs during the operation Expression—Selects a variable that provides details of the message to display when an error occurs

4. To save your updates, click the Save icon on the application toolbar.