Example 1: Retrieving all incident records from an external source
Summarize
Summary of Example 1: Retrieving all incident records from an external source
This example demonstrates how to retrieve all incident records from an external source into a ServiceNow instance using a scripted Remote Table API. The script uses ServiceNow's RESTMessageV2 API to call an external REST service namedRemote Instance Incidentswith the functionAll Incidents. The retrieved data is then processed and cached in a remote table accessible within the current instance.
Show less
Key Features
- RESTMessageV2 Integration: The script initiates a REST call to an external system, fetching incident data.
- Error Handling: If the REST call fails, the script sets a last error message for visibility and debugging.
- Transformer API Usage: The response body is parsed using ServiceNow’s Transformer API, which extracts rows and maps external data fields to local table fields.
- Field Mapping: The
getTransformerDefinition()function defines the mapping between external JSON fields and ServiceNow table fields, including mandatory mapping ofsysidfor proper form operation. - Data Transformation: Additional transformations (e.g., converting durations or date/time values) can be applied to extracted rows before adding them to the remote table.
Practical Application for ServiceNow Customers
This script enables customers to seamlessly integrate and synchronize incident data from external systems into their ServiceNow environment. By using a RESTMessageV2 integration combined with the Transformer API, customers can define precise field mappings and handle large data sets efficiently. Proper sysid mapping ensures that incident records behave correctly within ServiceNow forms and processes.
Important Considerations
- Ensure the external REST message Remote Instance Incidents and function All Incidents are correctly configured in your instance.
- Map all necessary fields explicitly in the Transformer definition; unmapped fields are not retrieved.
- sysid must be mapped and is limited to 32 characters to maintain record integrity.
- Use debugging functions like
gs.debug()to troubleshoot any data retrieval or transformation issues.
Related APIs and References
- RESTMessageV2 API for external REST integrations.
- TransformerDefinition, TransformerRuleList, and TransformerScripted APIs for defining and applying data transformations.
- Remote Table API for caching and querying external data within ServiceNow.
These are examples of script definitions you might create for retrieval and caching of data from sources external to your current instance. In this first example, we create a script to load all incident records from an external source.
/**
* Using `v_query`, add the rows to `v_table`
*/
(function executeQuery(v_table, v_query) {
fetchAllIncidents(v_table, v_query);
/**
* fetch all incidents records from the remote instance
*/
function fetchAllIncidents(v_table, v_query) {
// Uses RestMessage with name 'Remote Instance Incidents' and function 'All Incidents'
// Create a RestMessage first which calls an external REST service
try {
var restMessage = new sn_ws.RESTMessageV2('Remote Instance Incidents', 'All Incidents');
var response = restMessage.execute();
var responseBody = response.getBody();
// if REST call ends up in an error, set the last error message which shows up
// at the bottom of the list view
if (response.haveError()) {
v_query.setLastErrorMessage(response.getErrorMessage());
// can use gs.error() or gs.addErrorMessage() while debugging
// gs.debug() messages visible in session debugger
// gs.debug(response.getErrorMessage());
return;
}
} catch (ex) {
v_query.setLastErrorMessage(ex.message);
// gs.debug(ex.message);
return;
}
var transformerDefinition = getTransformerDefinition();
var transformer = new sn_tfrm.Transformer(transformerDefinition, responseBody);
// transformer parses the responseBody and extracts rows
while (transformer.transform()) {
// row is field-value map e.g. { active:"true", number: "INC0000001"}
var row = transformer.getRow();
// you may do any additional transformations to the row like GlideDuration, GlideDataTime etc. For example,
// row.duration = new GlideDuration(row.duration);
// finally add the row to the remote table
v_table.addRow(row);
}
}
/**
* returns a sn_tfrm.TransformerDefinition, which defines the mapping of the table fields and elements in the response body
*/
function getTransformerDefinition() {
// create a rule list to map a field to its element path
var ruleList = new sn_tfrm.TransformerRuleList()
.fromJSON() // the response body is a JSON
// 'active' field maps to path '$.active'
.addRule("active", "$.active")
.addRule("caller_id", "$.caller_id.value")
.addRule("number", "$.number")
.addRule("short_description", "$.short_description")
.addRule("sys_id", "$.sys_id")
.addRule("updates", "$.sys_mod_count");
var recordPath = "$.result";
return new sn_tfrm.TransformerDefinition(ruleList, recordPath);
}
})(v_table, v_query);
These code snippets are of note in this script:
function fetchAllIncidents(v_table, v_query) {
// Uses RestMessage with name 'Remote Instance Incidents' and function 'All Incidents'
// Create a RestMessage first which calls an external REST service
try {
var restMessage = new sn_ws.RESTMessageV2('Remote Instance Incidents', 'All Incidents');
var response = restMessage.execute();
var responseBody = response.getBody();
// if REST call ends up in an error, set the last error message which shows up
// at the bottom of the list view
if (response.haveError()) {
v_query.setLastErrorMessage(response.getErrorMessage());
// can use gs.error() or gs.addErrorMessage() while debugging
// gs.debug() messages visible in session debugger
// gs.debug(response.getErrorMessage());
return;
}
} catch (ex) {
v_query.setLastErrorMessage(ex.message);
// gs.debug(ex.message);
return;
}
You can create a RestMessage and directly use it in the script. In this example, it
uses a RESTMessageV2 API with the name of Remote Instance
Incidents, and the function All Incidents, which gets all
incident data. Once a response is returned from the server, an error message appears
if problems are encountered in the data retrieval.
If no problems are encountered in the data retrieval, it gets the data body for the records.
var transformerDefinition = getTransformerDefinition();
var transformer = new sn_tfrm.Transformer(transformerDefinition, responseBody);
// transformer parses the responseBody and extracts rows
while (transformer.transform()) {
// row is field-value map e.g. { active:"true", number: "INC0000001"}
var row = transformer.getRow();
// you may do any additional transformations to the row like GlideDuration, GlideDataTime etc. For example,
// row.duration = new GlideDuration(row.duration);
// finally add the row to the remote table
v_table.addRow(row);
It then uses the Transformer API to perform any required data transformations, extracts rows, and then adds a row for each record to the remote table.
/**
* returns a sn_tfrm.TransformerDefinition, which defines the mapping of the table fields and elements in the response body
*/
function getTransformerDefinition() {
// create a rule list to map a field to its element path
var ruleList = new sn_tfrm.TransformerRuleList()
.fromJSON() // the response body is a JSON
// 'active' field maps to path '$.active'
.addRule("active", "$.active")
.addRule("caller_id", "$.caller_id.value")
.addRule("number", "$.number")
.addRule("short_description", "$.short_description")
.addRule("sys_id", "$.sys_id")
.addRule("updates", "$.sys_mod_count");
var recordPath = "$.result";
return new sn_tfrm.TransformerDefinition(ruleList, recordPath);
}
})(v_table, v_query);
getTransformerDefinition defines the schema of the record in the
external API response body. It maps each of the fields in the table script to an
element in the external record. Any external data elements outside of this mapping
are not supported or retrieved.