User Tools

Site Tools


snc_siam_mapping

SIAM Mapping

v3.29.0

This feature allows clients to map unique data fields after messages leave their instance and before arriving at their instance. The SIAM Mappings are applied to messages during the processing steps of the Message Broker Service. This is useful to maintain the structure and coherence of the data as different providers have varying formats of messages they produce and consume.

SIAM Mappings are tokenized templates representing the format of the target message. The tokens embedded in the template represent the path or location of the data value in the source message that will be substituted for the token. The Message Broker Service looks up the SIAM Mapping to apply to a message based on the type of the message, the provider, and the action (ex: create, update, close, etc…). The Message Broker Service then parses the tokens in the SIAM Mapping template and uses them to look up the data value in the source message to substitute for the token. Once all tokens have been substituted, a complete target message is sent to the provider or instance.

The syntax for a token is determined by the format of the source message. If a source message is XML formatted then XPATH notation is used in the token to locate values. If a source message is JSON formatted then JSONPath notation is used in the token to locate values. Both XPATH and JSONPath are widely used and well-documented. A token begins with the characters ${ and end with the character }.

Below is a sample SIAM Mapping template for a target Remedy CreateIncident JSON formatted message from a source common_incident XML formatted message:

{
  "values" : {
    "First_Name" : "${XPATH:/common_incident/caller_first_name}" ,
    "Last_Name" : "${XPATH:/common_incident/caller_last_name}" ,
    "Description" : "${XPATH:/common_incident/short_description}" ,
    "Impact" : "${XPATH:/common_incident/impact}" ,
    "Urgency" : "${XPATH:/common_incident/urgency}" ,
    "Status" : "${XPATH:/common_incident/status}" ,
    "Reported Source" : "Direct Input" ,
    "Service_Type" : "User Service Restoration" ,
    "Vendor Ticket Number" : "${XPATH:/common_incident/number}",
    "z1D_Action" : "CREATE"
  }
}

Below is a sample SIAM Mapping template for a target commmon_incident XML formatted message from a source Remedy JSON formatted message (NOTE: Empty fields in common_incident are not shown to save space)

<?xml version="1.0" encoding="UTF-8"?>
<common_incident>
    <action>incident_created</action>
    <correlation_display>${JSONPATH:$.Request_ID}</correlation_display>
    <correlation_id>${JSONPATH:$.Incident_Number}</correlation_id>
    <group_list></group_list>
    <impact>${JSONPATH:$.Impact}</impact>
    <number>${JSONPATH:$.Vendor_Ticket_Number}</number>
    <short_description><![CDATA[${JSONPATH:$.Description}]]></short_description>
    <urgency>${JSONPATH:$.Urgency}</urgency>
</common_incident>

In order to access the SIAM Mapping interface, first install the Perspectium SIAM Mapping update set and then navigate to the “SIAM Mappings” module located under Perspectium > Control and Configuration:

Viewing Mappings

After clicking on the module, the SIAM Mapping interface will be displayed like so:

In order to view the list of available mappings from the current instance to a SIAM provider, select the URL (from the “Choose MBS” dropdown menu) you'd like to connect to, the provider, and the client.

NOTE: As of the Fluorine release, clients within the same PSP Family can be selected from the client dropdown.

Once those three options have been selected a list of mapping records will be displayed along with each record's respective values for the “Source”, “Target”, and “Action” fields:

Here is a sample XML of a mapping record:

To update the mapping, you can click either the save button icon, or the “Update” button located below the text editor.

Updating and Versioned Mapping

To update the mapping, you can click either the save button icon, or the “Update” button located below the text editor. Once you update the mapping, the new mapping will be saved, and the older versions of the mapping record will be displayed on the bottom of the page the next time the mapping gets selected.

Importing and Exporting Mappings

Dubnium

This feature allows you to import a mapping from an XML or JSON file, as well as export a mapping as an XML or JSON file. This allows you to move mappings across different environments and instances without having to cut and paste each map.

To import a mapping, you click on the upload button icon (the one on the left circled above). You will be able to upload a file with the extension .xml or .json, but other types of files are not supported. The uploaded file will be displayed to the editor, and automatically syntax checked (see section below). If the file is valid syntax, it will be automatically saved to the mapping. If not, you will be prompted to fix the syntax errors before being able to save.

To export a mapping, you click on the download button icon (the one on the right circled above). A file will be automatically downloaded to your computer as a .xml or .json file, depending on the mapping type. You will only be able to export a syntactically valid mapping.

Syntax Checker for Mappings

This feature checks for syntax or format errors in the mapping, in either XML or JSON depending on the mapping type. To validate a mapping, you click on the checker button icon (circled below). The validation will also automatically run when the Export button, Import button or Save/Update buttons are pressed. If the mapping has syntax or format errors, they will be displayed and the mapping will not be exported or saved until the errors are fixed.

When a syntactically correct mapping is saved, it will allow you to save:

When an incorrect mapping is saved, it will display the error and not allow you to save:

snc_siam_mapping.txt · Last modified: 2019/02/14 13:31 by timothy.pike