Remedy Adapter

The Remedy Adapter microservice creates, synchronizes, and resolves events between Unified Assurance and the BMC Helix ITSM (formerly Remedy) ticketing system.

This microservice is an optional part of the Event microservice pipeline. See Understanding the Event Pipeline in Unified Assurance Concepts for conceptual information.

Remedy Adapter Prerequisites

Before deploying the microservice, complete the following prerequisite tasks:

  1. Confirm that a microservice cluster is set up. See Microservice Cluster Setup.

  2. Create the remedy-adapter mappings folder in the Rules UI:

    1. From the Configuration menu, select Rules.

    2. Expand the following folders:

      Core Rules (core)/Default read-write branch (default)/processing/event

      Note:

      This is the expected default location. If you want to use a different location, you must also update the SVN_BRANCH and SVN_DIR_PATH configuration parameters when you deploy the microservice.

    3. From the Add menu, select Add Folder.

    4. In the Folder Name field, enter remedy-adapter.

    5. Click Submit, enter a commit message, and then click OK.

  3. Create the adapter mappings in JSON files to map Unified Assurance events to BMC Helix ITSM incident templates.

    You can create multiple files to map to multiple templates. The Remedy Adapter loads all mapping files at runtime, applies mappings to events based on whether they match the condition in the template field, and maps matching events to incidents based on the Service_Type key in the mapping file.

    Because the Remedy Adapter does not use the mapping file names to identify matching events and incident templates, you can name them anything. However, for easier identification and debugging, Oracle recommends giving the mapping files the same names as their corresponding incident template in the BMC Helix ITSM system.

    See Event to Incident Mapping File Schema for details about the schema to use and an example.

  4. Create a Kubernetes secret containing the base64 encoded BMC Helix ITSM username and password by running the following command as the assure1 user:

    a1k create secret generic --from-literal=username=<Base64 encoded username> --from-literal=password=<Base64 encoded password> -n <namespace> remedy-adapter-secret

    where <namespace> is the namespace where you will deploy the microservice.

  5. Create an event tool for opening BMC Helix ITSM incidents and add it to event menus:

    1. From the Configuration menu, select Events, and then Tools.

    2. From the Add menu, select SQL Tool.

    3. In the Name field, enter a name for the tool. For example, Open Remedy Incident.

    4. From the Icon menu, choose an icon.

    5. In the SQL field, enter the following:

      UPDATE Events SET TicketFlag=1 WHERE EventID IN ($EVENTLIST)

      Note:

      If you choose a different TicketFlag value here, you must also set that value in the TICKET_FLAG_NEW_ENV configuration parameter when you deploy the microservice.

    6. Optionally, select Journal and specify journal information to add for an event when the tool is used.

    7. Click Submit.

    8. From the Configuration menu, select Events, and then Menus.

    9. Select a menu and add the tool to it. You must add the tool to a menu for it to appear when you right-click in the Event list. Keep user groups, roles, and permissions in mind when choosing a menu to ensure that the right users can access the tool.

      See Event Menus and Event Tools for more information about these UIs.

  6. Create or update event conversions to match the default or overridden TicketFlag values:

    1. From the Configuration menu, select Events, and then select Conversions.

    2. Select the TicketFlag conversion.

      Update the conversion to match the following display values:

      Value Display
      0 No Incident
      1 Pending Incident Creation
      2 Incident Open
      3 Incident Closed

      Note:

      The default display for 3 is Service Request Open. You must update this for this integration.

    3. Click Submit.

Event to Incident Mapping File Schema

The event to incident mapping files must use the following JSON schema:

template : Map<String,Object[]>
incidentMapping : Map<String,Object>
closeCondition : Map<String,Object> 
lookups : Map<Map<String,Object>

The schema uses the following fields:

The following example shows a file that maps a Unified Assurance event to a User Service Restoration incident.

   {
       "template": {
           "$Event.Customer": [
               ""
           ]
       },
       "incidentMapping": {
           "Service_Type": "User Service Restoration",
           "First_Name": "Liam",
           "Last_Name": "Shay",
           "Description": "$Event.Summary",
           "Impact": "$Event.Severity",
           "Status": "$Event.Severity",
           "Urgency": "$Event.Severity",
           "Reported Source": "Direct Input"
       },
       "closeCondition": {
           "Status": "Closed"
       },
       "lookups": {
           "Impact": {
               "5": "1-Extensive\/Widespread",
               "4": "2-Significant\/Large",
               "3": "3-Moderate\/Limited",
               "@default": "4-Minor\/Localized"
           },
           "Urgency": {
               "5": "1-Critical",
               "4": "2-High",
               "3": "3-Medium",
               "@default": "4-Low"
           },
           "Status": {
               "0": "Resolved",
               "@default": "Assigned"
           }
       }
   }

Deploying Remedy Adapter

To deploy the microservice, run the following commands:

su - assure1
export NAMESPACE=<namespace>
export WEBFQDN=<WebFQDN>
a1helm install <release-name> assure1/remedy-adapter -n a1-zone1-pri --set global.imageRegistry=$WEBFQDN --set-string configData.REMEDY_BASE_URL="<Remedy_Server_URL>"

In the commands:

You can also use the Unified Assurance UI to deploy microservices. See Deploying a Microservice by Using the UI for more information.

Changing Configuration Parameters

When running the install command, you can optionally change default configuration parameter values by including them in the command with additional --set arguments. You can add as many additional --set arguments as you need.

Set a parameter described in Default Remedy Adapter Configuration by adding --set configData.<parameter_name>=<parameter_value>. For example, --set configData.LOG_LEVEL=DEBUG.

Default Remedy Adapter Configuration

Name Default Value Possible Values Notes
LOG_LEVEL INFO FATAL, ERROR, WARN, INFO, DEBUG The logging level used by the microservice.
SVN_BRANCH "/core/default" String The SVN branch to use. Note the slash (/) at the beginning of string and lack of it at the end.
SVN_DIR_PATH "processing/event/remedy-adapter/" Text The SVN path to the event to the directory containing the incident to mapping files. Note the slash (/) at the end of string and lack of it at the beginning.
POLL_TIME_S 60 Integer The interval at which the Remedy Adapter synchronizes incidents and events, in seconds.
SYNC_INCIDENT_RESOLUTION_TO_UA true true, false When set to true, when the Remedy Adapter detects a BMC Helix ITSM incident that matches the close conditions in the mapping file, the Remedy Adapter resolves the corresponding Unified Assurance event by setting EventCategory to Resolution (1) and Severity to Normal (0).
SYNC_INCIDENT_RESOLUTION_TO_REMEDY true true, false When set to true, when the Remedy Adapter detects an event where EventCategory is set to Resolution (1) or Discrete (3), and Severity is set to Normal (0), the Remedy Adapter closes the corresponding BMC Helix ITSM incident with the close condition set in the mapping file.
TICKET_FLAG_NEW_ENV 1 Integer The event TicketFlag value indicating events to create BMC Helix ITSM incidents for.
TICKET_FLAG_EXISTING_ENV 2 Integer The event TicketFlag value indicating events that have a corresponding BMC Helix ITSM incident.
TICKET_FLAG_CLOSED_ENV 3 Integer The event TicketFlag value indicating events that have a corresponding closed BMC Helix ITSM incident.
PROXY_PORT 80 Integer The proxy port (if used).
PROXY_URL String The proxy URL to use, without protocol, when your network does not have direct internet access.
INSECURE_SKIP_VERIFY false false, true (Experimental) Only set this to true if your BMC Helix ITSM instance is running on your local network without a properly signed certificate.
REMEDY_BASE_URL String The URL of the BMC Helix ITSM API.

Remedy Adapter Work Flow

The Remedy Adapter runs the following workflow at the interval set in POLL_TIME_S, counting from top of the hour:

  1. Retrieve all Unified Assurance events to create a new ticket BMC Helix ITSM for.

    These are events that have TicketFlag set to the value in TICKET_FLAG_NEW_ENV.

  2. For each retrieved event that matches a template condition:

    1. Call the BMC Helix ITSM API to create a new incident based on the mapping file.

    2. Retrieve the corresponding Verification TicketID.

    3. Call the BMC Helix ITSM API to retrieve the Incident Number that corresponds to the Verification TicketID.

    4. Call the BMC Helix ITSM API to retrieve the Incident RequestID that corresponds to the Incident Number.

      BMC Helix ITSM also pulls the new incident information for further API processing.

    5. If all of the BMC Helix ITSM API calls succeed, update the Unified Assurance event. Set TicketFlag to TICKET_FLAG_EXISTING_ENV and update TicketID with the value of Incident Number and Incident RequestID.

  3. Retrieve all Unified Assurance events that have existing BMC Helix ITSM tickets.

    These are events that have TicketFlag set to the value in TICKET_FLAG_EXISTING_ENV.

  4. For each retrieved event with an existing ticket, do the following:

    1. Read the corresponding Incident Number and Incident RequestID for further processing.

    2. Call the BMC Helix ITSM API to retrieve the work log for the incident.

    3. Add any new entries from the BMC Helix ITSM work log to the Unified Assurance event journal.

    4. Retrieve the Unified Assurance event journal.

    5. Call the BMC Helix ITSM API to add any new Unified Assurance event journal entries to the work log.

    6. For Unified Assurance events where EventCategory is set to Resolution or EventCategory is set to Discrete and Severity is set to Normal:

      1. Set the Unified Assurance event TicketFlag to the value of TICKET_FLAG_CLOSED_ENV.

      2. If SYNC_INCIDENT_RESOLUTION_TO_REMEDY is set to true, call the BMC Helix ITSM API to update the incident with the close condition from the mapping file and skip the next check in the workflow.

    7. Call the BMC Helix ITSM API to retrieve the incident. If the closeCondition from the mapping file is met:

      1. Set the Unified Assurance event TicketFlag to the value of TICKET_FLAG_CLOSED_ENV.

      2. If SYNC_INCIDENT_RESOLUTION_TO_UA is set to true, update Unified Assurance event. Set EventCategory to Resolution and Severity to Normal.