BMC Remedy ARS Adapter

Requirements

BMC Remedy server version 7.0 or higher

Adapter Configuration

• Adapter Class - this is the value that must be added to the adapters.json configuration file:
  com.kineticdata.calendar.adapters.ars.ArsAdapter

Connection Configuration

• Adapter Class: com.kineticdata.calendar.adapters.ars.ArsAdapter
• Properties:
• Server - the name or IP Address of the Remedy server
• Username - the Remedy Login ID used to connect to the Remedy server
• Password - the password associated to the username
• Port - the TCP port the Remedy server listens on (use 0 if port mapper is enabled)
• Authentication - the authentication string the Remedy server expects, or leave as a blank string if not used

Event Type Source Configuration

The event type source configuration for a BMC Remedy ARS Adapter defines what form the event data resides in, and the qualification that determines what criteria will be displayed.

On the event type configuration page, we saw that the source configuration property was dependent on the adapter used by the connection. The BMC Remedy ARS Adapter requires two properties to properly determine what event data should be rendered in the calendar:

• Form - the name of the Remedy form the data records reside in, such as "CHG:Infrastructure Change"
• Qualification - the criteria used to query the data records on the specified form

An example of a Remedy adapter source configuration property might look like the following:

"source": {
    "configuration": {
        "Form": "CHG:Infrastructure Change",
        "Qualification": "'1' != $\\NULL$"
    },
    ...
}

Source Configuration Qualification

The qualification consists of criteria that contains values in specific form fields to a desired value or keyword. Here are some common guidelines to follow for a valid qualification:

• Qualifications must begin and end with quotation marks (").
• Any quotation marks needed in the qualification must be escaped by prefixing the quotation mark with a backslash ().
• Remedy form fields must be referenced by wrapping the field database name or field id in apostrophes (').
• Remedy keywords must be escaped by placing a double backslash after the first $ symbol, such as $\NULL$.
• All Remedy operators are supported, such as =, !=, AND, OR, NOT, >, and <.
• Date ranges are not necessary - the date portion of qualifications is built up automatically depending on the date range the user is currently viewing - and therefore should not be used in the qualification.
• Dynamic values may be supplied as URL parameters, and the values substituted in the event type qualification. See Dynamic Qualifications below for details on how to accomplish this.

Dynamic Qualifications

The BMC Remedy ARS Adapter supports dynamic qualifications, which allow users the ability to change the qualification by supplying URL parameters with desired values.

A couple of things are needed for this to work:

• The event type source configuration qualification must be setup to substitue parameter values. This is accomplished by wrapping parameter names with moustaches (double braces - {{ and }} ).
• The qualification parameter(s) must be supplied in the URL. Qualification parameters must be wrapped in a parameter object of the form parameter[NAME]=VALUE, so they are distinguished from other URL parameters that may have different meanings.

Example

Qualification:

"'101'="{{user}}""

URL Parameter:
parameter[user]=Don Demo

Next example, the following process is taking place:

The Remedy Adapter attempts to build up the qualification, but sees it requires a value from a URL parameter, as one of the values is enveloped in moustache syntax -

• {{user}}

The Remedy Adapter sees that a qualification parameter exists, as denoted by the parameter[] syntax. It retrieves the parameter name within the apostrophes, and the parameter value.

• parameter name: user
• parameter value: Don Demo

The Remedy Adapter then substitutes the parameter value for the parameter name specified in the qualification, and the resulting qualification becomes:

• "'101'="Don Demo""

The resulting qualification is then used when retrieving events from the form on the Remedy server.

📘

Note

The end user can easily change the qualification by updating the URL parameter value and reloading the page.

If the user does not supply the URL parameter, or the if the URL parameter value is blank, then the qualification will most likely fail as the qualification, at least in this example, will result in zero records matching the qualification, as it is comparing the value in field 101 to a blank string.

"'101'="""

Event Type Source Mappings

Event type mappings create a relationship between a field on the Remdy form, and one of the event properties. Fields on the Remedy form are referenced by the field ID, since this is a value that cannot be changed once the field is created, and it is consistent across all Remedy views of this form.

The syntax used to parse data fields from the Remedy form must be consistent with the rules for mappings, which means that all Remedy field values must be enclosed in moustaches (double braces). Currently event type mappings only support a direct mapping to one field on the Remedy form. These rules apply to all event type mappings - core mappings, details mappings, and filter mappings.

An example of a Remedy field mapping:

"detailMappings": {
"Category": "{{700000051}}"
}

In this example, a mapping has been created to add a "Category" property to the event details. The value for this property will come from field 700000051 on the Remedy form.

Event Type Core Source Mapping Restrictions

There are some restrictions on what types of Remedy fields can be used for the Start and End core source mappings:

• Only Remedy Date/Time or Remedy Date fields can be used when mapping the Start and End core mappings.
• The type of Remedy field used in the Start core mapping, must match the type of Remedy field used in the End core mapping.
• For example - if a Remedy Date/Time field is used for the Start core mapping, a Remedy Date/Time field must be used for the End core mapping. The End core mapping cannot be a Remedy Date field.

Changelog

v1.0.2 (2013-10-07)

Modified ARS qualification to optimize performance in some remedy environments.

v1.0.0 (2012-10-12)

Initial release.