This documentation supports the 20.02 version of BMC Helix Multi-Cloud Service Management.

Integrating custom connectors into BMC Helix Multi-Cloud Service Management

If BMC Helix Multi-Cloud Service Management does not provide connectors that support your service provider, you can develop your own connectors to integrate your service provider with Remedy IT Service Management (ITSM) or BMC Helix IT Service Management (ITSM) using BMC Helix Platform and BMC Helix Integration Service. The BMC Helix Integration Service enables different applications to integrate seamlessly with applications that are either hosted on cloud or running on on-premise. The BMC Helix Integration Service provides an integration layer and connector builder that you can use to build connectors.

Process for integrating a custom connector with BMC Helix Multi-Cloud Service Management

The following table describes the roles involved, and the steps required, in enabling a custom connector.

Role

Action

Developer

Flattens the connector response JSON

Administrator

Creates connector profiles

Business Analyst

Creates connector process to make calls to your custom connector

Business Analyst

Adds technology provider data

Business Analyst

Adds vendor metadata

Developer

(Optional) Adds code to your connector to support dynamic field mapping


Before you begin

To learn about how you develop your own connectors, see the Connectors overview.

Task 1: Ensure that your connector response is flattened JSON

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. You might have to remove special characters or stringify 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: Create a connector profile

Pre-requisite: Create Configuration and Profile for connector targets in BMC Helix Integration Studio.

  1. Log in to BMC Helix Innovation Studio.
  2. Select Administration > Configure My Server > Integration Service > Connector Configuration.
  3. Add connector targets in the Connector Target section. 
    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 new connector target, click New.
  5. In Name, enter a name for this connector target.
  6. Select the connector type from the Connector Type list.
  7. Select the Configuration and Profile that you have created in BMC Helix Integration Studio for this connector type.
    connector_target.png

Task 3: Create a connector process and data mappings

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. To integrate a custom connector, 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

The easiest way to create a connector process is to copy an existing process and then update that process for your custom connector. In this task, we will copy the Connector Process Service Cloud connector process as an example.

  1. Log in to Innovation Studio.
  2. Select Ticket Brokering Library > Processes.
  3. Select Connector Process Service Cloud from the list of processes and click Copy.
    This opens the connector process in the edit mode.

  4. Name the connector process based on the custom connector name, such as Connector Process Lexmark.
    In the copied connector process, there are four blocks:

    • Resolve Case Connector
    • Create Attachment
    • Add Case Comment Connector
    • Create Case Connector

     Each of the blocks will be 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 blocks that are not supported by your custom connector. For example, if you are not supporting attachments, remove the block Create Attachment.

To change process blocks to call your custom connector

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

  1. Click the Create Case Connector block. 
    The connector call details are shown in the Properties.
    change_conn_process.png
  2. Change the Label name based on your custom connector name.
  3. Select the connection for your connector.  
    A message is displayed stating some field values will be cleared if you proceed.
  4. In the message stating the field values will be cleared, click OK.
  5. Select the action Create Case from Action to create a Lexmark Ticket.
  6. Provide the appropriate Input Field Mappings to create the Lexmark Case.
  7. 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 the Incident Record tree under Available Values. If you are mapping from an incident, if your action was from a change, problem or work order, pick the appropriate record to do the mapping from.
    edit_expres.png
  8. For output mapping
    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. Click the Add Case Comment Connector block.
    The connector call details are shown in the Properties.
  2. Change the Label name based on your custom connector name.
  3. Select the connection for your connector.  
    A message is displayed stating some field values will be cleared if you proceed.
  4. In the message stating the field values will be cleared, click OK.
  5. Select the action Create Case Comment from Action to send a comment to Lexmark Ticket.
  6. Do the appropriate field mappings. Ideally, in the INPUT MAP section, select Vendor Ticket ID in Parent and CommentText in Body.  
  7. For output mapping, set the Vendor Ticket ID to the ID of the activity note created on the vendor side.

add_Case_Comm.png

To update the status of vendor ticket upon resolution of ITSM ticket

Update the Resolve Case Connector block to update the status of your vendor ticket to closed whenever the ITSM ticket is resolved.

  1. Click the Resolve Case Connector block.
    The connector call details are shown in the Properties.
  2. Change the Label name based on your custom connector name.
  3. Select the connection for your connector.
    A message is displayed stating some field values will be cleared if you proceed.
  4. In the message stating the field values will be cleared, click OK.
  5. Select the action Update Case from Action to update the status of the Lexmark Ticket.
  6. Do the appropriate field mappings. Ideally, in the INPUT MAP section, select Vendor Ticket ID in Case Number and Closed in Status.

resolve_Case_conn.png

To support creating tickets from multiple ITSM ticket types, add additional connector boxes using the 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: 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, we will 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 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.
    Technology provider data for Salesforce Service Cloud is displayed.
  5. Add data in the following fields:
    technology_provider.png

    • Display Field Mapping
      Add data that is needed to map data that is returned from the vendor JSON object to Remedy with 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. The fieldName is the name of the field of the vendor, and type is static meaning it has a default value, or dynamic which means you are doing mappings.  The fieldId refers to the field in the BMC Helix Multi-Cloud Service Management record definition which holds the data (for example, Incident, Problem Investigation, Work Order or Change) and finally 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 will 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 do a cross launch. This needs to be in a format that matches the vendor. The keywords used are id, which let Smart IT 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: 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 vendors we support.

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. Click +Map Vendor to create the new vendor metadata record.
    The custom connector that you have built is displayed in the Ticketing Technology Provider drop-down 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.




 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*