Integrating custom connectors into BMC Helix Multi-Cloud Service Management

You can use the out-of-the-box connectors that BMC Helix Multi-Cloud Service Management provides to integrate your service providers with Remedy IT Service Management Suite (Remedy ITSM Suite) or BMC Helix ITSM. If the out-of-the-box connectors do not support your service providers, you can develop custom connectors by using BMC Helix Platform and BMC Helix Integration Service.

You can use BMC Helix Integration Service to integrate an application seamlessly with another application that is either hosted on a cloud environment or is running on an on-premise environment. BMC Helix Integration Service also provides an integration layer and a connector builder that you can use to develop your connectors.

BMC Helix Platform enables you to create connector profiles and processes to send calls to your custom connectors. You can use the process designer in BMC Helix Platform to quickly create your processes by using different, easy to configure elements based on the actions that you want the connector to perform.

Process for developing a custom connector

The following table lists the tasks that you must perform to develop a custom connector:

Before you begin

• Make sure that you have created your custom connector in BMC Helix Integration Studio. 
  For information about connectors, see  Connectors overview .
• After you develop the connector, make sure you configure it in BMC Helix Integration Studio.

Task 1: To convert connector response into a flattened JSON

1. Add code to your connector to convert the connector response object into a flattened JSON. 
   If you are using Node.js, use flatten function to convert an array of array objects into a single array object. 
2. (Optional) You can remove special characters or use the Stringify function on the results. 
   The connector builder does not add this functionality and you need to code it separately depending upon how you handle the connector response object.

Task 2: To create a connector target

1. Log in to BMC Helix Innovation Studio.
2. Select Administration > Configure My Server > Integration Service > Connector Configuration.
3. In the Connector Target section, add the connector targets. 
   The connector target configuration maps with the configuration and account you have created in Integration Studio for your connector and is used in the connector process blocks.
4. To create a connector target, click New.
5. In Name, enter a name for this connector target.
6. From the Connector Type list, select the connector type.
7. Select the Configuration and Profile that you have created in BMC Helix Integration Studio for this connector type.
   

Task 3: To create a connector process and data mapping

In BMC Helix Multi-Cloud Service Management, the process used to create data in a target system is dynamically looked up from the vendor metadata. You must first create the connector process, and then create the data that drives the selection of the process as well as data mappings.

To copy an existing connector process

1. Log in to BMC Helix Innovation Studio.
2. Select Ticket Brokering Library > Processes.
3. From the list of processes, select a connector process that you want to copy; for example, Connector Process Service Cloud, and click Copy.
   This opens the connector process in the edit mode.
4. Name the copied connector process based on the custom connector name, such as Connector Process Lexmark.
   In the copied connector process, there are four process elements:
   • Resolve Case Connector
   • Create Attachment
   • Add Case Comment Connector
   • Create Case Connector
    Each element is called based on the Action Name that is passed from the main process. The action names are the same across all connectors:
   • Create Ticket (used for incidents)
   • Create Worklog
   • Create Attachment
   • Create Ticket From Change
   • Create Ticket From Problem
   • Create Ticket From Work Order
   • Resolve Ticket
5. Remove the elements that are not supported by your custom connector. 
   For example, if you are not supporting attachments, remove the Create Attachment element.

To change the process elements to call your custom connector

Change each element in the process to call your custom connector. In this task, as an example, change the Create Case Connector element to call the Lexmark Create Case action.

1. In the connector process, click the Create Case Connector element. 
   The connector call details are displayed in Properties, as shown in the following image:
   
2. Change the value in the Label field based on your custom connector name.
3. Select the connection for your connector.  
   Note: A message is displayed indicating that if you proceed, some field values are cleared. Click OK.
4. To create a Lexmark case, from Action, select Create Case.
5. Provide appropriate values in Input Field Mappings.
6. See the section about Dynamic fields if you want to make use of metadata to drive data transformations. When you are doing the mappings, select the fields from Incident Record under Available Values. If you are mapping from an incident, if your action was from a change, problem or work order, select the appropriate record to do the mapping from.
   
7. For output mapping, perform the following steps:
   1. Map the Vendor Ticket ID field to the ID field from Lexmark.
   2. Map Vendor Ticket Data to the flattened JSON output object.

To send a comment to the vendor

1. In the connector process, click the Add Case Comment Connector element.
   The connector call details are shown in the Properties section.
2. Change the value in the Label field based on your custom connector name.
3. Select the connection for your connector.  
   Note: A message is displayed indicating that if you proceed, some field values are cleared. Click OK.
4. To create a Lexmark case, from Action, select Create Case.
5. Map the appropriate fields. 
   Ideally, in the INPUT MAP section, select Vendor Ticket ID in Parent and CommentText in Body.  
6. For output mapping, set the Vendor Ticket ID to the ID of the activity note created on the vendor side.
   

To update the status of vendor ticket when ITSM ticket is resolved

To close the vendor ticket whenever the ITSM ticket is resolved, update the Resolve Case Connector element.

1. In the connector process, click the Resolve Case Connector element.
   The connector call details are displayed in the Properties section.
2. Change the value of the Label field based on your custom connector name.
3. Select the connection for your connector.
   Note: A message is displayed indicating that if you proceed, some field values are cleared. Click OK.
4. To create a Lexmark case, from Action, select Create Case.
5. Map the appropriate fields. 
   Ideally, in the INPUT MAP section, in Case Number, select Vendor Ticket IDand in Status, select Closed.
   
   
   To support creating tickets from multiple ITSM ticket types, add additional connector elements by using Create Case Connector as the template and then add a line to it from the Exclusive Gateway where the qualification matches one of the options above for where the ticket is created from. Then use that record in your mappings. Refer the Connector Process Jira  in Ticket Brokering Library > Processes as an example for handling multiple ITSM ticket types.

Task 4: To add technology provider data

To add a new connector, you also need to create metadata in BMC Helix Multi-Cloud Service Management. This technology provider data is contained in the Technology Provider record definition. You need to populate few key fields. In this task, let us use the Salesforce Service Cloud technology provider data as an example.

To add the technology provider data for Salesforce Service Cloud

1. Log in to BMC Helix Innovation Studio.
2. Select Ticket Brokering Library.
3. In Records, select Technology Provider, and click Edit Data.
4. Select the record with description as Salesforce Service Cloud and click Edit.
   The technology provider data for Salesforce Service Cloud is displayed.
5. Add data in the fields as shown in the following image:
   

• • Display Field Mapping
    Add data that is needed to map data that is returned from the vendor JSON object to Smart IT fields. Add the data mapping in the common and vendor specific section of the JSON file. In the JSON file, fields to the left are Smart IT fields, and the fields to the right are the vendor JSON object fields. In the vendor specific section, map fields that are specific to the technology provider.

    {   "common": {     "Subject": "title",     "CaseNumber": "id",     "Id": "objectId",     "Status": "status",     "LastModifiedDate": "updated",     "Description": "description"   },   "vendorSpecific": [     {       "name": "Reason",       "type": "text",       "labelGUID": "service-cloud.field.label.case_reason"     }   ] }

  • Vendor Field Mapping
    

    Add vendor field mapping JSON if you are making use of the Dynamic Data Handling to let the system know how to transform data. 

    • fieldName is the name of the field of the vendor, and type can be static (has a default value), or dynamic (you are doing mappings). 

    • fieldId refers to the field in the BMC Helix Multi-Cloud Service Management record definition that holds the data (for example, Incident, Problem Investigation, Work Order or Change) . 

    • mappings is the mapping of the value from the field in BMC Helix Multi-Cloud Service Management to the value to send to the vendor.

    Use this mapping in the connector code to send the appropriate data to the vendor. However, you need to code your connector to handle Dynamic data.

    {   "keyField": "CaseNumber",   "statusField": "Status",   "fieldMappings": [     {       "fieldName": "Reason",       "type": "static",       "value": "Other"     },     {       "fieldName": "Type",       "type": "static",       "value": "Other"     },     {       "fieldName": "Priority",       "type": "dynamic",       "value": {         "fieldId": "1000000164",         "mappings": {           "1000": "High",           "2000": "High",           "3000": "Medium",           "4000": "Low",           "default": "Low"         }       }     }   ] }

  • Ticket URL Format

    Enter the format of the ticket URL such as https://[vendor server name]:[port]/browse/{key}. The format is used by Smart IT to create a link on the ID of the ticket and to navigate to the ticket. This needs to be in a format that matches the vendor. Smart IT uses the id keyword to pass the appropriate ID to the URL. Take a look at the various out-of-the box vendors such as AWS or Atlassian Jira Software as examples.

Task 5: To add vendor metadata

After you have added the technology provider data, create the metadata in BMC Helix Multi-Cloud Service Management to drive the specific integration. This task is similar to adding a vendor metadata record for any of the other supported vendors.

To create a new vendor metadata record

1. Log in to BMC Helix Multi-Cloud Service Management.
2. Select Settings > Configure Vendors > Map Vendors.
3. To create the new vendor metadata record, click +Map Vendor.
   The custom connector that you have built is displayed in the Ticketing Technology Provider list, and the default vendor and display field mappings, and default URL are populated in the screen.
4. Save the record.
   Your custom connector is configured and ready to use.