Table maps are intended for specific integrations. Please contact support@perspectium.com prior to setting up table maps to determine appropriate usage.
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).
To create an Outbound Table Map:
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.
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”.
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.
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:
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 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) :
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:
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.
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.
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.
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.
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:
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.
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:
<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>
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>
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();
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.
To create an Inbound Table Map:
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.