Resolution Routing

Resolution Routing Overview

Resolution Routing (RR) provides a centralized, rule-based mechanism to match an incident with Resolve Actions Pro guided procedures and/or automation. RR can be set up to:

• Trigger an automation from a gateway filter.
• Show user a wiki page for troubleshooting which includes executing automation embedded in the wiki page.

Figure 1 – High Level Architecture Diagram
Resolution Routing (RR) utilizes a collection of schemas and mappings to locate the right solution for the incident behind the scenes.

note

• A schema is a list of filed names and sources (for example, gateway) that participates in the matching.
• A mapping is based on a schema and define the matching value for each filed.

This list is a high level description of how RR works.

1. An alert is received by a gateway, or a user navigates to a URL that is configured to use RR. The fields of this alert or URL will be parsed out. As an example, there are two fields; Field A and B.
2. Resolution Routing currently has one schemas and two mappings defined. Each mapping uses a schema and supply the matching criteria.
   1. Schema: Field_A + Field_B
   2. Mapping 1: Field_A = 10 and Field_B = 20, execute Runbook 1
   3. Mapping 2: Field_A = 15 and Field_B = 30, execute Runbook 2
3. Actions Pro searches through the list of mappings to locate a match. If a match is found, RR executes the Runbook listed in the mapping. For example, if Mapping 1 is found to match, Runbook 1 will be executed. RR will keep searching until all mapping rules are exhausted. It stops at the first match.

Resolution Routing Cycle

A general example of the resolution routing cycle is as follows:

1. An alert is received by the gateway.
2. The gateway is currently configured with 2 schemas.
3. Schema_1: Field_A + Field_B + Field_C.
4. Schema_2: Field_A + Field_D.
5. Schema_3: Field_B + Field_C.
6. The gateway script loops through the schemas to try to find an RR mapping entry.
7. Constructs key using Schema_1.
8. If a matching entry exists, execute the Runbook listed in the RR mapping (the "GW Automation") or navigate to the wiki page (the "UI Display").
9. If an entry is not found, try the next schema on order, Schema_2.
10. If an entry matches Schema_2, then Actions Pro stops and does not continue to check and execute Schema_3.

For UI navigation, a URL with name/value parameters is used to navigate to Actions Pro (instead of a gateway alert). The parameter "rid=true" within the URL indicates that resolution routing lookup is required.

Resolution ID Schema

A RID schema is a defined combination of field names and sources. You can define multiple schemas and assign order to them. For example, schema with order of "1" will be checked before schema with order of "2".

• A schema provides structure to a mapping rule. Multiple mapping rules can share the same schema and yet be distinctively different by setting different values for the same set of fields.
• A schema will only be activated if the incoming alert or URL has all the fields that are used by the schema.
• If a Gateway is also specified as part of the schema, only alerts from that Gateway will be considered.

Resolution ID Mapping

A RID mapping embodies a RID schema by setting actual lookup values.

• Multiple RID mappings can use the same RR schema with different lookup values.
• The Resolution ID (RID) is the unique identifier for a mapping. It is automatically generated from that unique combination of preset field and the values.
• The RID will be used to find match efficiently.

Installation and Configuration

Resolution Routing is a feature of Actions Pro, and it does not need to be installed separately. The only configuration necessary outside of the platform is to turn on any gateways to be used in the blueprint file. Inactive gateways are not accessible in RR schemas. 

To use the Resolution Routing functionality:

1. In the blueprint file, turn on any gateways that will be used by resolution routing. RIDmappings used only as wiki lookup mapping (and not gateway filters) do not require gateways to be activated.
2. Restart Actions Pro components to enact any blueprint changes.
3. Create gateway connection pools (if necessary) and gateway filters.
4. Deploy filters.
5. In the Resolution ID Schema menu option, create a schema with the desired fields. The field names should match the fields expected from incoming data (for example, for a database gateway, the fields should match the database column names).
6. In the Resolution ID Mapping menu option, create a mapping to link an existing schema with an existing wiki page and/or Runbooks.
7. In the Mappings list, click Sync to deploy the RID mapping and sync the RID schema with the gateways. Any changes to schemas and mappings are not conveyed to gateways until they are synced.

Accessing Resolution Routing

To access this functionality, go to the Actions Pro Main Menu > Remote Administration > select Resolution ID Schema or Resolution ID Mapping.

Resolution ID Schema option enables you to define a Resolution Routing schema.

Resolution ID Mapping option enables you to configure an RR mapping using that schema. Use the schemas to choose which Runbooks or wiki pages to run.

Resolution ID Schema

A Resolution Routing schema is the combination of fields used by an RR mapping to match against incoming data outside Actions Pro. The RR schema also includes which gateways to check and see if the fields match and trigger the mapping. To create, delete, and edit RR schemas, select the Resolution ID Schema option from the Remote Administration panel.

The Schemas list displays each of them along with their configured fields and gateways, and the (optional) description for each schema. Each schema is also listed by its order number (starting at zero), which determines the order in which the schemas are checked. Event data from all gateways are screened together, and the schemas are matched against the gateway data in the listed order. The first schema that successfully matches the proper gateway data is executed (which Runbook is decided by the RR mapping using that schema).

Actions Pro executes only the first schema that matches: once the first match in the list is found, then further matching stops.

To re-order the schemas to prioritize more important mappings earlier, simply drag-and-drop the individual schema rows in the list. If the incoming gateway is not included in the schema definition, then that schema is ignored and skipped.

Creating, Editing, or Deleting a Schema

Creating a new Schema

1. To create a new schema, simply click the New button, located below the title.
   The Schema screen displays. 
2. Fill in the necessary information.
   • An Resolution ID Schema definition includes its name and an optional description. The schema Fields are matched against incoming event or ticket data fields, which can vary from system to system. Different schemas are be distinguished by their different compositions of fields. The field names should match the expected gateway data (for example, for a database gateway, the field names should match the SQL field names of the database table).
   • Alternatively, a schema field name can be more descriptive for the convenience of general users of the RR schema, in which case use the optional Source name or Regex (regular expressions) to match the event data. The regex is used for RR schema with partial field values. Ideally, the entire field name is used for matching, however if only part of a field is required, the regex rule can be defined to extract specific parts of the field to be used to construct the lookup key.
   • Schemas are also associated with specific Actions Pro gateways. Only those Gateways specified in the schema definition receive the RR mapping information upon deployment, thus only events or tickets from those gateways are matched against schema information.
     note

     Only gateways activated in the blueprint file can be added to an RR schema.

3. When you are finished filling in the necessary information, click Save and then Back.
   The newly created schema appears on the dashboard immediately.

Editing a Schema

To edit an existing Schema:

1. Click the View Details icon  in front of the Schema's Name.
2. Make the necessary changes, save them and click Back.
   The changes are applied immediately.

Deleting a Schema

To delete a Schema:

1. Highlight the Schema you wish to delete and click the Delete button.
   The following message appears: "Are you sure you want to delete the selected schema?"
2. Click Delete to perform the action or click Cancel to abolish it.

Resolution ID Mapping

In Actions Pro, Resolution ID Mapping is the association between an external alert or incident and an automation or UI wiki page to be executed or displayed. Mapping is used to check incoming event data for specific values (for a specific combination of fields, defined in the RR schema), then executes a Runbook or displays a wiki page, if matched.

Accessing Resolution ID Mapping

To access this fictionality, go to the Actions Pro Main Menu > Remote Administration >Resolution ID Mapping.

The Mappings list displays each Resolution Mapping by RID (Resolution ID) along with the associated RR schema, UI Display (wiki page to display), and GW Automation (Runbook to execute for gateway). The RID mapping is the actual lookup entries that contain information on how to handle the alert, specifically which automation to run and/or what wiki page to navigate and display for the user. The RID is the unique identifier for a mapping, and is automatically created from the values sought by the RR mapping in the RR schema fields.

A column labeled RegEx is located in the RID Mapping table helping identify which of the RR schemas are set to use RegEx. A check mark in the RegEx column indicates when RegEx flag is enabled for a value. Use the "+" button to expand the Details of the RID mapping. Only the RegEx values are indicated in brackets "(regex)", while the non-RegEx value types are not indicated.

• If there are more than 1 values per schema and there is at least one of them using RegEx, the check mark is presented for the RID mapping.
• If there are more than 1 values per schema and none of them uses RegEx, the check mark is not presented for the RID mapping.
• If there are more than 1 schema values per schema and all of them uses RegEx, the check mark is presented for the RID mapping.

Resolution ID Mapping: Add, Delete, Sync and Bulk

The toolbar at the top of the Mappings list contains four options: Add, Delete, Sync and Bulk.

You can Add a new mapping or Delete an existing mapping from the list. The Sync button automatically deploys RID mappings to the gateways, using mapping information to search and, if found and matched, to execute the corresponding automation. Similarly, the RSView uses the mapping information to redirect the browser to the associated wiki page for display.

Multiple mappings can be imported or exported in Bulk using CSV files. The Bulk drop-down menu also includes the Activate and Deactivate options. If you do not want a RID mapping to be triggered, but do not want to delete the mapping definition either, simply deactivate the mapping. The Bulk drop-down options will activate or deactivate all selected mappings in the "Mappings List". Individual mappings can be activated or deactivated in their edit screens.

Editing RID Mapping

To edit an existing RID mapping, click the Edit button    next to the selected mapping.

The Mapping edit screen appears.

A Module for a RID mapping is similar to a file folder, and is simply used to help organize related mappings together.

• Modules are displayed in the folder tree in the left-hand panel of the RID Mapping list.
• Link an RID mapping with an RID schema using the Schema drop-down menu, which lists all the schemas defined in the Schemas list.
• When a schema is selected, the schema fields will auto-populate the fields table at the bottom of the mapping edit screen.
• The field values, which trigger the mapping if they match URL or event data, must be input manually.

Although a RID mapping can be used to trigger both a wiki page to display and a gateway automation to execute, it is not necessary for both to occur. Thus, not all the RID mapping fields need to be filled in.

Gateway Automation

The GW Automation and Event ID fields in an RID mapping is analogous to the gateway filter functions. However, the GW Automation Runbook is executed in connection to the Runbook listed in the corresponding gateway filter (if an event could trigger both). A RID mapping takes precedence over existing wiki lookup mappings or gateway filters concerned with same problem type (matched in the RR schema, wiki lookup regex, or filter rule). If a RID mapping is not triggered, or there is no Runbook specified in the GW Automation field, then Actions Pro reverts to previous existing event resolutions, such as Runbooks triggered by the gateway filter or wiki lookup mapping.

note

The optional (and potentially complicated) code written in the "Script" field in a Gateway filter definition actually does override the RR mapping "GW Automation". The priority order is:

• Gateway filter script.
• RR mapping automation.
• Gateway filter Runbook (only one of these can run).
• To make a Runbook execution conditional instead of always running when the mapping is triggered, place the Runbook in the UI Automation field instead.

UI Navigation

The UI Display field is analogous to the Wiki lookup functions. If a RID mapping is triggered, then the wiki page selected in UI Display is displayed, along with automation results from the Runbook selected in UI Automation. If the UI fields are asked for, but do not match, then the Actions Pro homepage is displayed instead.

Unlike the GW Automation Runbook, which is almost always executed if the RR mapping is triggered, the UI Automation Runbook is executed only if you interact with the event or ticket on the wiki page. An interaction example is using an Execute button shown on the wiki page or the Guided Resolution button in the Actions Pro for ServiceNow app.

To trigger an RID mapping as a wiki lookup mapping, the proper URL must be inserted into the browser. The URL must include the "rid=true" parameter, followed by all the field name=value parameters listed in the mapping. The field name=value parameters can be written in any order in the URL, but all the fields of the RR schema must be included to properly match and trigger the lookup. Optionally, the Worksheet parameters "REFERENCE=&autoCreate=true&" can be inserted before the "rid=true" parameter to make Actions Pro create a new Worksheet for the "UI Automation" Runbook.

When a RID mapping is synced, it takes precedence over any other wiki lookup mapping and gateway filter that use the same matching schema/criteria. The Runbook listed in the RID mapping GW Automation field will execute instead of the Runbook listed in the gateway filter Runbook field.

It should be noted that a RID mapping takes precedence over a wiki lookup mapping or gateway filter, but does not overwrite the lookup or filter. Any existing wiki lookup or filter remain viable. An event that does not trigger an RR mapping can still trigger a wiki lookup mapping or gateway filter.

However, Actions Pro will execute:

• only the automation or display the wiki page defined by the RID mapping
• and not the Runbook defined in other filters, but a RID mapping triggered by links the same problem types (the same matching schema as the lookup or filter criteria takes precedence.

However, if no RID mapping for a particular schema exists, but the incoming event/ticket information does match a wiki lookup or filter, then Actions Pro displays the page mapped by an existing wiki lookup or executes automation already set within the gateway filter. 

Use of Resolution Routing with Gateways

A Gateway can be configured to use Resolution Routing to trigger automaton. A prerequisite is to have an appropriate Gateway enabled first.

The RID schema fields are the core of the schema. Different schemas are distinguished by their different combinations of fields (schemas cannot have the same fields). Click the Add button in the Fields panel to set the schema fields.

There are two general ways to define a field: using a name, or provide the formatting (regex) of its expected value.

• To define a field by name, type in the "Name" column the exact field name from the gateway data. For example, the field names of a schema meant for a database gateway should match the SQL column names of the database table. Optionally, if the actual field name is rather complicated and non-descriptive, you can insert an alias in the "Name" column. This will make the schema more understandable, but then you must enter the exact field name into the "Source" column instead.
• By default, the entire value of the field will be used for matching. If additional processing is needed, user can define an optional regular expression under the "Extract Regex" column to extract the desired value from the full value.
  note

  This will add to process time, so use it only if necessary.

• For a schema to be used by a specific gateway, you need to explicitly associate that gateway. Click Add in the Gateways panel to specify the gateways permitted to match this schema. Data from an unlisted gateway will be ignored.
• After an RID schema is completed, create the corresponding RID mapping to utilize that schema.

RID Mapping for Gateway Integration

An RID mapping uses a RID schema to:

• Extract information from gateway data.
• Compare the gateway data values against the preset mapping values.
• And if the values match, then Actions Pro executes the Runbook preset in the RID mapping.

RID Mapping UI Buttons

• Add - creates new RR mapping.
• Delete - removes an existing mapping from the list.
• Sync - automatically deploys RR mappings to the gateways, and is comparable to a "Save" button in that any changes made to an RR schema or RR mapping must be synced with the proper gateways before the resolution routing can be executed (similarly, changes must be synced for RSView to use the wiki lookup mapping information to redirect the browser to the associated wiki page for display).
• Bulk - Multiple mappings can be imported or exported in Bulk using CSV files.
  • Activate - activate all selected mappings in the "Mappings List".
  • Deactivate options, deactivate all selected mappings in the "Mappings List". Deactivate the mapping, if you want an:
  • RID mapping NOT to be triggered
  • but do not want to delete the mapping definition either.

The following table shows the RID Mapping settings.

Icon	Description
Module	Similar to a file folder and is used to help organize related RR mappings together. Existing modules can be selected from the drop-down menu. Modules are shown in the folder tree in the left-hand panel of the "Mappings List".
Active	If you want to keep the definition or disable it, check the box.
Integration Behavior: UI Display	The UI Display boxes are used for wiki lookup mapping in resolution routing. Page: used for wiki lookup mapping in resolution routing. Automation: used for wiki lookup mapping in resolution routing.
Integration Behavior: Gateway	The section are used for gateway filtering in resolution routing. Automation: used for gateway filtering in resolution routing. Event ID: used for gateway filtering in resolution routing.
Schema	Used to link an RR mapping with a RR schema using the drop-down menu, which lists all the schemas defined in the "Schemas List".
Save	Saves the setting entered.
Close	Ends the operation and closes the popup window.

To create an RID mapping in the Mapping edit screen:

1. There are three features to use:
   1. Module - is akin to a file folder, and is simply used to help organize related RR mappings together. Existing modules can be selected from the drop-down menu. Modules are shown in the folder tree in the left-hand panel of the "Mappings List".
   2. Schema - used to link an RR mapping with a RR schema using the drop-down menu, which lists all the schemas defined in the "Schemas List".
   3. Edit Selected Schema - If the schema fields are incorrect or need to be changed, then click the More Information icon  to the right of the Schema box to edit the chosen schema.
2. The UI Display and UI Automation boxes are used for wiki lookup mapping in resolution routing. An RR mapping can be used for both UI navigation and gateway automation, using the same schema to match data from an incoming URL or gateway. The wiki lookup mapping functions (UI Display, UI Automation) are independent from the gateway filter functions (Gateway, Event ID). Although an RR mapping can be used to trigger both a wiki page to display and a gateway automation to execute, it is not necessary for both to occur. Thus, not all the RR mapping fields need to be filled.
3. The Gateway and Event ID boxes are used for gateway filtering in resolution routing.
   1. When the RR mapping is triggered via gateway, then the Runbook in Gateways is executed.
   2. If an Event ID number is entered, then the RR mapping can be used to resume a paused but actively running automation waiting at that specified event. Gateway is not run if the RR mapping is used to continue an active Runbook.
   3. Both Gateway and Event ID boxes can be filled, but only one is used by the RR mapping at any one time.
4. When an RR schema is chosen, the schema fields will auto-populate the fields panel at the bottom of the mapping edit screen (in the example above, the schema uses "RRTest1Field1", "RRTest1Field2", and "RRTest1Field3").
   1. The actual values must be input manually.
   2. These values comprise the RID for the mapping, and are the field values compared against incoming gateway data to check whether the RR mapping is triggered.
   3. if the schema fields are incorrect or need to be changed, then click the More Information icon  to the right of the Schema box to edit the chosen schema.

note

After an RR mapping is created and saved, it must still be synced from the "Mappings List" to deploy the mapping.

Interaction with Other Actions Pro Features

An RR mapping takes precedence over any existing wiki lookup mapping or gateway filter, but does not overwrite that lookup or filter. In other words;

• Any non-RR gateway filter using the same gateway listed in an RR schema is not deleted and remains viable.
• Therefore, a gateway event that does not trigger an RR mapping might still trigger a non-RR gateway filter.
• Because resolution routing takes precedence, however, Actions Pro will only execute the Runbook listed in the Gateway field, rather any Runbook listed in the gateway filter "Runbook" field (of course, it is possible that an RR mapping is created that links to the same Runbook and Event ID).

Remember that RR mappings must be synced with gateways with the Sync button in the "Mappings List" to deploy properly. An RR mapping that is saved but not synced will never trigger.
When no RR mapping is triggered for a particular gateway, only then does Actions Pro run automation from the gateway filter. However, the optional script (in the "Script" box) of a gateway filter always executes. The priority order is:

1. Gateway filter script.
2. RR mapping automation.
3. The gateway filter Runbook (only one Runbook from either RR mapping or gateway filter will execute).

Use Resolution Routing in UI

The same Resolution Routing Schema and Mapping can be invoked through the browser URL.

1. The information is passed in through browser's URL.
2. The URL must include the "rid=true" in its parameters, followed by all the required field in the format of name=value pairs.
3. The information will parsed and used to find a matching RR mapping.

In addition, the parameters "REFERENCE=WORKSHEET_NUMBER" and "autoCreate=true" can be inserted into URL to make Actions Pro create a new Worksheet for the "UI Automation" Runbook.

CSV File Format for Resolution Routing

If you are importing RR mappings from a CSV file, then the CSV file must follow a specific format. The CSV file should consist of only the following:

• LINE 1: The headers. The headers must have the following required columns:
  • module
  • schema
  • wiki
  • runbook
  • automation
  • eventid
  • active
  • new Worksheet Only
  • and followed by field names from all RR schemas used by all RR mappings in the CSV file
• LINES 2 and after: Each line corresponds to a distinct RR mapping. Because the headers include all fields used by all schemas in this file, if a schema does not use a particular field, just use empty value.

The following table shows the RR Mapping settings.

RR Mapping Setting Name	Description
module	Module name
schema	Schema name
wiki	UI Display wiki page
runbook	UI Automation Runbook
automation	GW Automation
eventid	Event ID
active	true/false whether the mapping is active
new Worksheet Only	true/false whether the mapping uses new Worksheet each execution

The following text from a sample CSV file lists three RR mappings with:

• The first header line listing the mapping settings and schema fields
• The next three lines listing the separate RR mappings

note

Every RR mapping uses a different RR schema, with each schema using only 2 of the 3 schema fields ("field A", "fieldB", "fieldC") listed in the header line:

1. module,schema,wiki,runbook,automation,eventid,active,newWorksheetOnly,fieldA,fieldB,fieldC
2. HisModule,schemaAB,UI.Page1,UI.Runbook,,true,true,yes,low,
3. HerModule,schemaAC,UI.Page2,,true,true,no,,good
4. OurModule,schemaBC,,Gateway.Runbook,,false,false,,high,bad

Additionally:

1. The first RR mapping in His Module has "UI.Page1" for the wiki setting (the UI Display page), and the Runbook "UI.Runbook" underrun book runbook (the UI Automation). It has the field values "yes" (field A) and "low" (fieldB), but its RR schema does not include field C.
2. The second mapping in HerModule also has a wiki setting ("UI.Page2"), but nothing listed for runbook. It has the values "no" (field A) and "good" (fieldC), but skips field B.
3. The third mapping in Our Module is a gateway automation instead of a wiki lookup, and lists "Gateway. Runbook" for automation setting. It has the values "high" (fieldB) and "bad" (fieldC), but skips field A.