User Tools

Site Tools


snc_table_maps

Table maps are intended for specific integrations. Please contact support@perspectium.com prior to setting up table maps to determine appropriate usage.

Outbound Table Maps

Outbound Overview

This feature is used to map and/or transform the outbound ServiceNow field data for the record being replicated. If the field names of the record being replicated outbound from ServiceNow need to be modified, or if the value of one or more fields needs to be transformed, you should create and configure an Outbound Table Map. If you are familiar with Transform Maps for Import Sets, its is conceptually the Outbound version of a Transform Map.

Once the Outbound Table Map is configured, it can be assigned to a Dynamic Share or Bulk Share by selecting it in the Table Map field on corresponding forms.

These are often used to grant a greater control of the Outbound Replication. They are utilized and packaged per integration (Jira, Salesforce, etc).

Creating a Table Map

To create an Outbound Table Map:

  1. Create a new Table Map
  2. Set the Direction = Outbound
  3. Choose the Source Table you are mapping from
  4. Enter the Target table name you are mapping to
  5. For topic and type it will depend a little more on what you are doing
    1. ServiceNow to ServiceNow, topic=replicator and type=servicenow
    2. For an Advanced SIAM integration contact Perspectium Support to verify your mapping and use case

Currently you can utilize Table Maps to route through individual field mappings or perform the entire serialization process in the Run Script. We primarily will package our out of box table maps as Field Mappings.

Copy Table Map

You have the ability to copy any Perspectium Table and Transform Maps and all related mappings. If you plan on modifying any of the out-of-box Table Maps and/or Transform Maps we recommend that you modify the new copied map. This will minimize the impact of any Perspectium version upgrades later on.

This is limited to our out-of-box tables / transform maps, whose Source Table Name starts with “u_psp”.

Bismuth


Click the “Copy Table Map” link, located on the table map form under the Related Links section, to copy a table map and all its field maps. This can be useful for when you want to make a copy of a table map to use as a starting point for another integration.

This copied table map will be put into your current Update Set.

Use Script

The pure scripting option is a more advanced configuration. To utilize this you will have to serialize the record yourself. Within this script, you set the variable answer to be the value you want the record to be serialized and returned as.

You have access to the following variables:

Variable Description
current This represents the record that is being shared
gr_tablemap Carbon This represents the outbound table map itself. For example if you want to access the table map's name, you can use gr_tablemap.u_name

Here is an example which will perform those steps:

/*
 * Custom Table Map
 */
 
//Serialize 'current' record into an XMLDocument
var recordSerializer = (typeof GlideRecordXMLSerializer != 'undefined') ? new GlideRecordXMLSerializer() : new Packages.com.glide.script.GlideRecordXMLSerializer(); 
var xmlstr = recordSerializer.serialize(current);
var xmlDoc = new XMLDocument(xmlstr);
 
//Process Display Values As Necessary
var pspUtil = new PerspectiumUtil();
var addDisplayValues = pspUtil.getPspPropertyValue("com.perspectium.replicator.add_display_values", "true");
var currentFieldsOnly = pspUtil.getPspPropertyValue("com.perspectium.replicator.share_current_fields", "false");
if (currentFieldsOnly == "true" || addDisplayValues == "true") {
    addDVFields();
}
 
/*
 * Any extra mapping, to add
 */
 
// Send the XMLDoc string to our answer
answer = xmlDoc.toString();
 
// Helper Functions
 
//Standard DV Field Processing
function addDVFields(){
    var fl = (typeof GlideFieldList != 'undefined') ? new GlideFieldList() : new Packages.com.glide.processors.FieldList();
    var tableName = current.getTableName();
    var fieldNames = fl.get(current.getTableName(),"");
    var arrFields = current.getFields();
 
    for (var i = 0; i < arrFields.size(); i++) {
        var glideElement = arrFields.get(i);
        var ed = glideElement.getED();
        var elName = glideElement.getName();
 
        if (!fieldNames.contains(elName) || (currentFieldsOnly == "true" && tableName != ed.getTableName())) {
            removeElement(elName);
        }
 
        // Create dv fields for reference, choice, or lists
        if (ed.isReference() || ed.isChoiceTable() || ed.getInternalType() == "glide_list") {
            addElement("dv_" + elName, glideElement.getDisplayValue());
        }
 
        if (!glideElement.hasValue()) {
            continue;
        }
    }
}
 
//Remove an element from xmlDoc
function removeElement(elName){
    var nn = xmlDoc.getElementByTagName(elName);
    if(nn && nn.parentNode) {
        nn.parentNode.removeChild(nn);
    }
}
//Add an element from xmlDoc
function addElement(elName, elValue){
    xmlDoc.createElement(elName, elValue);
}

This will essentially mimic the Replication process without a Table Map. Walking through it you should see the essentially 5 sections:

  1. Creating and serializing the base record
  2. Adding Display Values as necessary
  3. A section for your custom changes
  4. Converting the XMLDocument to a string and sending it to “answer”
  5. Helper functions which you can call

You can then utilize the function removeElement(elName) and addElement(elName, elValue) to modify the outgoing columns and data as you see fit.

Field Mappings

Field mappings allow you to map fields in the outbound record based on values from the ServiceNow record to be shared.

To map a record field to a different field name (ex: name→title) :

  1. Click “New” in the PSP Table Field Maps list to open up Field Map configuration form.
  2. Enter the name of the Source field you are mapping (ex: name). For Reference field use dot notation to specify the Source field (ex: user.name).
  3. Enter the name for the Target field (ex: title)
  4. Save

Bismuth
The “Add all source table fields” option is available to allow you to quickly add all fields of the specified source table as field maps. This can be useful for cases where you want all fields to be in the outbound table map and only want to modify a few fields to have different values.

These field maps will be created with default values as follows:

  • Target field will have the same name as the source field
  • Use Script - false
  • Field type - String
  • Field length - 40

Field Mapping Script

You can utilize a Script per field as well. This can be used to enrich, sanitize, or create whole new columns of data. Check the “Use Script” box within the Field Mapping record to bring up the Scripting section.

Here is an example where we are utilizing the caller_id column to create a caller_id_full_name column in the Outgoing record.

Get Display Value

Dubnium

In the Field Map form, checking the Get Display Value checkbox will set your Table Map values to the following:
Source Field: assignment_group
Target Field: assignment_group_name
Source Script: answer = current.assignment_group.getDisplayValue();

The Get Display Value checkbox will only appear after you enter a value into Source Field.

Checking the Get Display Value checkbox will disable the use of the Source Script field to add any other scripting.

Preview Output

Starting in Carbon users will be able to preview Outbound Table Maps. Instead of repeatedly modifying a record, finding the outbound message, and decrypting the value whenever you make a change to your Outbound Table Map, users can just use the preview option to speed up this process.

To do so select a record for the “Preview With” column which will key off the “Source Table” specified and hit the “Preview Output” button. This will take into account XML and JSON output, embedded records, and running the Table Map through the “Run Script”. If you do not specify a “Preview With” record it will just grab the latest updated record.

Extra Mappings

Adding to the Attributes

You can map a field to the “attributes” field of the Replicator outbound message. To do so you will use the @ (for attributes). Specify “@name” in the Target field, which will create “name=value” in the attributes field.

For example, if you want the name field to map to a title attribute you can specify name as the source field and @title as the target field. The resulting attribute will have “title=value” (where value is the name's value) will be stored into the attributes field of the outgoing message.

Resolving a Field Using Another Table Map - Sending Attachments

You can have a field be mapped such that it resolves to and represents the output of another table map. For example, you can create an incident table map that will query to get a record's attachments and add it to its outbound record by creating the following field map:

Where the source field has a value of “${TM:psp_attachment;table_sys_id=$[GR:sys_id]}” and the target field has a value of “attachments”.

The source field breaks down as follows:

  • TM - The field is mapped to another table map
  • psp_attachment - The name of the other table map to use
  • table_sys_id=$[GR:sys_id] - An optional query to limit the records returned where the query is based on fields of the other table map. In this case, we are using the the sys_id of the current GlideRecord (incident) being table mapped so that we only get its attachments in the psp_attachment table map. Since the sys_attachment table is being used in the psp_attachment table map as the source table, we do so by looking for records in sys_attachment with a table_sys_id of the incident record's sys_id.
  • limit n (optional) - Limits to sending only n attachments per message (such as limit 1). Refer to “Setting Individual Attachments Replication” below.

The psp_attachment table map then looks as follows:

The psp_attachment table contains the source table we want to query for table mapped data (sys_attachment) and like any other table map, the target field represents the parent element of a record after its been mapped and the fields are the fields we want in the output data. A psp_attachment table mapped record would look as follows:

<attachment>
   <file_name>test.png</file_name>
   <size_bytes>23453</size_bytes>
</attachment>

So by by creating a field map in our incident table map to maps to the psp_attachment table map, the psp_attachment table map's data will then be stored as a child of the field map's target field “attachments” as follows:

<common_incident>
    <attachments>
        <attachment>
           <file_name>test.png</file_name>
           <size_bytes>23453</size_bytes>
        </attachment>
    </attachments>
</common_incident>

In v3.19.0, the above field map representing another table map feature will log an error and not add the other table map if it resolves to a value greater than the outbound bytes properties for sending outbound messages or greater than 16MB. This is to account for ServiceNow 16MB limit for querying for a field's value (anything over this will cause an error of “java.lang.RuntimeException: String object would exceed maximum permitted size”).

So in the above example, if the psp_attachment table map was greater than the outbound bytes properties or 16MB, no value would be added for <attachments> into the <common_incident> table map.

Setting Individual Attachments Replication

In cases where only one attachment is to be sent per outbound message, the “limit n” parameter in the embedded table map helps us achieve this. The following steps describe what needs to be set up:

  1. Add the “limit 1” parameter to the psp_attachment embedded table map as follows: ${TM:psp_attachment;table_sys_id=$[GR:sys_id];siam_sent;limit 1}
  2. Verify that the siam_sent tag exists in your system. Tags is what prevents attachments from being sent every time. Go to the Tags table (label.list) and create a tag with name siam_sent if it does not exist.
  3. In your Before Share Script of your dynamic share, we will make a function call to send them individually:
  <code javascript>
  ...
  // sending attachments added before submitting ticket for the first time
  if(!ignore && current.operation() == "insert") {
      var tableMap = share_gr.u_table_map;
      new PerspectiumAttachment().sendIndividualAttachments(current, "deferred", "siam_sent", share_gr, '', tableMap);
  }
  </code>

Further Examples

Embedded table maps can be used to uphold related records in ServiceNow. This will allow users to embed child records into the parent payload to be restored on the receiving instance.

<common_incident>
       <problems>
             <problem>
                 <short_description>Problem Example</short_description>
                 <assignment_group_name/>
                 <id>7299dbc5db22230071f25421cf9619c1</id>
                 <assigned_to_name/>
                 <state>1</state>
                 <number>PRB0040104</number>
             </problem>
      </problems>
</common_incident>

Conversion to a New Format

To script the transformation of an entire record to a new format (ex: convert to a custom JSON format), select the Use Script checkbox on the Table Map configuration form. This will display a Script input that will execute a script instead of using individual field mappings. Use the current variable to reference values in the source record and set the answer variable to be the new value returned. The following example builds a JSON string from the value of correlation_id and short_description in the current record:

var attributes = {"type":"Case"};
var o = {};
o.attributes = attributes;
o.Id=current.correlation_id;
o.Subject = current.short_description.toString();

var j = new JSON();
j = j.encode(o);

answer = j.toString();

Inbound Table Maps

Inbound Overview

While Outbound Table Maps are more built to be an Outbound Transform Map the Inbound Table Maps more function as a Subscribe definition. They will direct the traffic to a Import Set Table where then a ServiceNow Transform Map will do the processing. We will traditionally package the Table Maps and Transform Maps for the advanced integrations.

These configurations are used to map inbound replication messages to a ServiceNow table based on the Topic and Type specified in the message. For example: a record coming in with the “topic=siam” and the “type=common_incident” will be mapped to the “u_psp_common_incident” Import Set Table. The corresponding Transform Map will then process that appropriately.

Creating an Inbound Table Map

To create an Inbound Table Map:

  1. Set the Direction = Inbound
  2. Enter the Topic of the inbound message
  3. Enter the Type of the inbound message
  4. Enter in the Target Table, this is traditionally an Import Set Table

That is all that is necessary for the base Inbound Table Map. You will then of course want to make sure your Import Set table and Transform Map are set up correctly as well.

snc_table_maps.txt · Last modified: 2019/02/05 13:31 by javier.valerio