BMC Helix

Introduction

BMC Helix supports REST APIs with Custom JWT authentication. Integration between BMC Helix and OpsRamp requires configuring an outbound connection to create or update incidents in BMC Helix.

Unlike out-of-the-box integrations, BMC Helix integration must be configured under Custom Ticketing Integration in OpsRamp.

Install the BMC Helix

1. From All Clients, select a client.
2. Go to Setup > Account.
3. Select the Integrations and Apps tab.
4. The Installed Integrations page, where all the installed applications are displayed. Note: If no integrations are installed, it navigates to the Available Integrations and Apps page.
5. Click + ADD on the Installed Integrations page. The Available Integrations and Apps page appears.It displays all the available applications along with the newly created application with the version.
6. Search for Custom Ticketing integration using the search option.
   Note: Alternatively, you can use the All Categories option to search.
7. Click ADD on the Custom Ticketing integration tile.

Configure the BMC Helix

Follow these steps to configure the outbound integration with BMC Helix:

1. Provide the name of the integration.
2. Select Outbound as the direction.
3. Under the Outbound card, click Add in the Configuration menu.
4. Fill in the configuration page with the following details:

Tokens Path Mapping Configuration

The Tokens Path allows us to map fields from the response payload of the given Token URL to the corresponding tokens.

Sample Tokens Path Mapping

Response Payload of Token URL:

{
  "token": "213990cdnqal21p2ncxmq12oedssw21d"
}

jwtToken = $token

Append the $ symbol to the value of the token field.

Actions on Integration

You can perform actions on an integration.

• See here for more information.

Actions on Event

Follow these steps to perform actions on the events:

1. Click on the integration name.

2. Navigate to Outbound tab > Events section.

3. Hover over the event name.

4. Click the actions (three dots) menu. A popup appears with options.

   • Copy Id: To copy an event Id.
   • Edit: To edit event details.
   • Save as: To save an event name.
   • Validate: Validate if the event is successful.
     • Select Json or Form.
       
       • Json: Enter the payload and click on Validate.
         
       • Form: Enter the property and value in the fields and click on Validate.
         A green tick appears if the event is successful
   • Remove: To remove an event.

   Integration response mapping configuration

Response mapping configuration is mainly based on the response payload that is received in third party payload; below are a few examples for response mapping configuration:

1. sample response payload to mapping the id in response mapping:

   {
   "id":"INC0001",
   "type":"incident",
   "tool":"servicedesk"
   }
   

   external ticket id = $id
   We need to append $ to the value

2. sample response payload to mapping the id in response mapping:

   {
   "result":{
   "id":"INC0001",
   "type":"incident",
   "tool":"servicedesk"
       }
   }
   

   external ticket id = $result.id

3. Sample response payload to mapping the id in response mapping

   {
          "result":[
             {
                "ticketDetails":{
               "id":"INC0001",
               "type":"incident",
               "tool":"servicedesk"
         },
            "Description":{
               "display_value":"testing description",
               "value":"validating"
            }
         }
      ]
   }
   

   external ticket id = $result[0].ticketDetails.id

4. sample response payload to mapping the Incident Number in response mapping

       {
         "result": {
         "Incident Number": "INC0001",
         "type": "Incident"
         }
       }
   

   external ticket id = $result[‘Incident Number’]

Audit Logs

View logs from the Audit Logs tab. You can view if the event was successful or not.

Integration event payloads

The following are the field and example payload to create incidents.

Create incident

Request with OpsRamp tokens

The following is a sample request with OpsRamp tokens.

    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:OpsRamp_CreateIncident">
     <soapenv:Body>
     <urn:Create_OpsRampIncidentNew>
     <!--Optional:-->
     <urn:Incident_Number></urn:Incident_Number>
     <urn:Summary>$incident.subject</urn:Summary>
     <urn:Notes>$incident.impact</urn:Notes>
     <urn:Priority>[@$incident.priority.name@]</urn:Priority>
     <urn:Vendor_Ticket_Number>$incident.uniqueId</urn:Vendor_Ticket_Number>
     <urn:OpsRamp_Status>[@$incident.status.name@]</urn:OpsRamp_Status>
     <urn:Source_Type>Inbound</urn:Source_Type>
     </urn:Create_OpsRampIncidentNew>
     </soapenv:Body>
    </soapenv:Envelope>

Response

The following is a sample response.

    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <soapenv:Body>
     <ns0:Create_OpsRampIncidentNewResponse xmlns:ns0="urn:OpsRamp_CreateIncident">
     <ns0:Incident_Number>INC000003142691</ns0:Incident_Number>
     <ns0:OpsRamp_Status>Open</ns0:OpsRamp_Status>
     </ns0:Create_OpsRampIncidentNewResponse>
     </soapenv:Body>
    </soapenv:Envelope>

Use tag: $Body.createResponse.createResult.EntityResults.Entity.TicketNumber to read the BMC Helix ticket ID and save it to the external entity ID of the OpsRamp incident.

Authentication error message

The following is a possible error message for an authentication error:

    <?xml version="1.0" encoding="UTF-8"?>
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <soapenv:Body>
     <soapenv:Fault>
     <faultcode>soapenv:Server.userException</faultcode>
     <faultstring>ARERR [623] Authentication failed</faultstring>
     <detail>
     <ns1:hostname xmlns:ns1="http://xml.apache.org/axis/">dv-mt-01</ns1:hostname>
     </detail>
     </soapenv:Fault>
     </soapenv:Body>
    </soapenv:Envelope>

Required field error message

The following is a possible error message for a required field error:

    <?xml version="1.0" encoding="UTF-8"?>
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <soapenv:Body>
     <soapenv:Fault>
     <faultcode>soapenv:Server.userException</faultcode>
     <faultstring>ERROR (326): Required field cannot be blank.; 536870914</faultstring>
     <detail>
     <ns1:hostname xmlns:ns1="http://xml.apache.org/axis/">dv-mt-01</ns1:hostname>
     </detail>
     </soapenv:Fault>
     </soapenv:Body>
    </soapenv:Envelope>

Failures

In the case of failure in integration, an Email is sent to the user about the failure in integration.
To configure failure notification:
1. Click add from the Failures section. 1. Select notification type as Email. 1. Enter the email address(es) in the To and CC fields 1. Click Add Failure Notifications. The details are added. 1. Click Finish. The integration is installed.