BMC Helix Multi-Cloud Broker connector powered by MuleSoft

The BMC Helix Multi-Cloud Broker connector, powered by MuleSoft connects the MuleSoft connector engine and BMC Helix Multi-Cloud Broker and is used to configure activities for the connection. The activities can be used as a source or target within operations defined for the connection. 

Use the BMC Helix Multi-Cloud Broker connector activities to complete the following tasks:

• Create or update BMC Helix ITSM records like Incident, Change, Problem, Work Order, and Known Error records
• Create work log with attachments in BMC Helix Multi-Cloud Broker
• Create or update vendor data in the application
• Create errors in the Flow Transaction record definition for BMC Helix Multi-Cloud Broker error management functionality
• Create or update service unavailability
• Create or update service notification
• Query vendor ticket data from the Vendor Data Record Definition
• Get attachments by attachment group ID

Before you begin

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

• Administrator permissions to BMC Helix Multi-Cloud Broker
• Anypoint Studio version 7.8.0 is installed
• You have the Organization ID and user name and password for your MuleSoft account.
• You have Apache Maven installed and have working knowledge of it.

Supported product versions

Configuring the BMC Helix Multi-Cloud Broker connector 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. Download and add the connector to MuleSoft Anypoint Studio
2. Create a MuleSoft project and add the connector to the project
3. Create the files required for the connector configuration
4. Configure the connector

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

Task 1: To download and add the connector to MuleSoft Anypoint Studio

1. Log in to BMC Support by using your BMC support ID.
2. Download the  Multi Cloud Broker Connector 2021-06-01  file from the BMC Helix iPaaS for MuleSoft 21.3.00 page on the Electronic Distribution Site. 
3. Extract the .jar file to a local directory.

4. From the command prompt, enter the following commands:

   cd <jarFilePath>

   Then, enter:

   mvn install:install-file "-Dfile=bmc-helix-mcb-connector-1.0.1-mule-plugin.jar" "-DgroupId=org.mule.bmc.connector" "-DartifactId=bmc-helix-mcb-connector" "-Dversion=1.0.0" "-DgeneratePom=true" "-Dpackaging=mule-extension"

5. Then, navigate to the C:\Users\<userName>\.m2\repository\org\mule\bmc\connector\mcb\bmc-helix-mcb-connector\1.0.0-SNAPSHOT directory and paste the downloaded .jar file in this directory. 

After you install the connector, it is available in the Mule Palette of MuleSoft Anypoint Studio.

Task 2: 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. 

4. From the Mule Palette, click Add Modules.

5. From the list displayed, drag and drop BMC Helix Multi-Cloud Broker to the palette.
   The BMC Helix Multi-Cloud Broker connector is listed in the Mule Palette for your project.

6. 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-mcb-connector</artifactId>
   	<version>1.0.0</version>
   	<classifier>mule-plugin</classifier>
   </dependency>

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

Task 3: 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: 

      • hostName — Enter the URL of the BMC Helix Multi-Cloud Broker 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 field 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 4: 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 Multi-Cloud Broker, and drag a BMC Helix Multi-Cloud Broker activity to the Message Flow tab. 
   2. On the Message Flow tab, select a BMC Helix Multi-Cloud Broker activity.

   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 Name	Enter the host URL of the BMC Helix Multi-Cloud Broker instance
      User Name	Enter a valid BMC Helix ITSM user name
      Password	Enter the user's 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 defined configuration values, click Test Connection.
   6. Click OK.
   7. To save your updates, click the Save icon on the application toolbar.

The connector configuration is used for all the BMC Helix Multi-Cloud Broker activities in your flow. After you set up the project configuration files and configure the BMC Helix Multi-Cloud Broker connector for MuleSoft, you can create flows between BMC Helix Multi-Cloud Broker and other applications.

Connector flow configuration

A typical flow requires the source configuration, for example HTTP > Listener, a request Transform Message that writes information to the BMC Helix Multi-Cloud Broker 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 flows created for the BMC Helix Multi-Cloud Broker operations:

Create activity flow

Get activity flow

Get Attachments flow

Query activity flow

Update activity flow

Create activity

The Create activity gathers the data to create a new record at the BMC Helix Multi-Cloud Broker endpoint. It is intended to be used as a target in a workflow. 

To configure the Create activity

1. From the Mule Palette, select BMC Helix Multi-Cloud Broker > Create. 
2. Drag the Create option to the Message Flow tab. 

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

   Parameter	Value
   Display name	Activity name
   Basic Settings
   Connector configuration	Configuration file created for the connector
   General
   Record definition	Select the type of record you want to create. The following options are available: Active Vendor Tickets Brokered Incidents Change Flow Transaction Incident Known Error Problem Retry Error Schedule Job Service Service Notification Service Unavailability Vendor MetaData Technology Provider Technology Provider Instance Technology Provider Parameters Vendor Data Vendor Metadata Vendor Notification Vendor Service Worklog Work Order
   Input Payloads	To define specific field mappings for the activity, click and add your payload data. For example: {        Status: "New",        Webhook_Condition_Parameter: "Remedy",        Description: "Test Description",        vendor: "Service Cloud",        vendorTicketProperties: write({              "Id": "123457",              "CaseNumber": "98349590234",              "Subject": "Test Summary MCB Create",              "Status": "New",              "Description": "Test Description",              "Reason": null,              "Type": null,              "Priority": "High"        }, "application/json"),        Company: "Calbro Services",        Incident_Type: "User Service Restoration",        vendorTicketId: "123457",        Reported_Source: "Other",        Impact: "4-Minor/Localized",        Priority: "High",        First_Name: "Allen",        Last_Name: "Allbrook",        Summary: "Test Summary MCB Create",        Urgency: "2-High" } After you complete mapping the field values, click Done. Important: When using this activity in a flow, to get data from an external source, define the payload metadata in the Transform Message element.

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

Get activity

The Get activity retrieves data for a particular record from the BMC Helix Multi-Cloud Broker endpoint. It is intended to be used as a source in a workflow. 

To configure the Get activity

1. From the Mule Palette, select BMC Helix Multi-Cloud Broker > Get. 
2. Drag the Get option to the Message Flow tab. 

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

   Parameter	Value
   Display name	Activity name
   Basic Settings
   Connector configuration	Configuration file created for the connector
   General
   	Select the type of record you want to retrieve. The following options are available: Active Vendor Tickets Brokered Incidents Change Flow Transaction Incident Known Error Problem Retry Error Schedule Job Service Service Notification Service Unavailability Vendor MetaData Technology Provider Technology Provider Instance Technology Provider Parameters Vendor Data Vendor Metadata Vendor Notification Vendor Service Worklog Work Order
   Ticket GUID	The GUID value of the ticket you want to retrieve.

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

Get Attachments activity

The Get Attachments activity retrieves data for a particular record from the BMC Helix Multi-Cloud Broker endpoint. It is intended to be used as a source in a workflow. 

To configure the Get Attachments activity

1. From the Mule Palette, select BMC Helix Multi-Cloud Broker > Get Attachments. 
2. Drag the Get Attachments option to the Message Flow tab. 

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

   Parameter	Value
   Display name	Activity name
   Basic Settings
   Connector configuration	Configuration file created for the connector
   General
   Attachment Group ID	Enter the group ID of the attachment you want to retrieve.

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

Query activity 

The Query activity searches record data at the BMC Helix Multi-Cloud Broker endpoint. It is intended to be used as a source in a workflow. 

To configure the Query activity

1. From the Mule Palette, select BMC Helix Multi-Cloud Broker > Query. 
2. Drag the Query option to the Message Flow tab. 

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

   Parameter	Value
   Display name	Activity name
   Basic Settings
   Connector configuration	Configuration file created for the connector
   General
   Record definition	Select the record type to query. The following options are available: Active Vendor Tickets Brokered Incidents Change Flow Transaction Incident Known Error Problem Retry Error Schedule Job Service Service Notification Service Unavailability Vendor MetaData Technology Provider Technology Provider Instance Technology Provider Parameters Vendor Data Vendor Metadata Vendor Notification Vendor Service Worklog Work Order
   Input payload	To define specific field mappings for the activity, click and add your payload data. For example: { "query" : "Created_Date > \"2021-04-03T07:23:41.000Z\"", "pageSize": 25, "startIndex" : 0 } After you complete mapping the field values, click Done. Important: When using this activity in a flow, to get data from an external source, define the payload metadata in the Transform message.

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

Update activity

The  Update activity searches case data at the BMC Helix Multi-Cloud Broker endpoint. It is intended to be used as a target in a workflow. 

To configure the Update activity

1. From the Mule Palette, select BMC Helix Multi-Cloud Broker > Update. 
2. Drag the Update option to the Message Flow tab. 

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

   Parameter	Value
   Display name	Activity name
   Basic Settings
   Connector configuration	Configuration file created for the connector
   General
   Record Definition	Select the record type to update. The following options are available: Active Vendor Tickets Brokered Incidents Change Flow Transaction Incident Known Error Problem Retry Error Schedule Job Service Service Notification Service Unavailability Vendor MetaData Technology Provider Technology Provider Instance Technology Provider Parameters Vendor Data Vendor Metadata Vendor Notification Vendor Service Worklog Work Order
   Input payloads	To define specific field mappings for the activity, click and add your payload data. For example: { "Created_By": "Allen", "Summary": "This is a test summary-Update.", "Company": "Calbro Services", "Sync_Vendor_Ticket": true } After you complete mapping the field values, click Done. Important: When using this activity in a flow, to get data from an external source, define the payload metadata in the Transform message.
   Ticket ID	The ID for the ticket you want to update.

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