1 of 3

Scripting

Snippets

Useful snippets of code given as examples to help with various scripting needs.

Scripted SOAP Service

Use this script to add a SOAP endpoint to a Unifi Process. You will need to update the api_name to be the same as the one you set in the Process record.

Removing Namespaces

Sometimes it's necessary to remove the namespaces sent in by other systems to make it easier to handle the payload in ServiceNow. The easiest place to do this is within the Scripted SOAP Service, but bear in mind that your payloads will no longer be identical to what the other system sent you. This example shows you how:

Scripted REST API

Use this script to add a REST endpoint to a Unifi Process. You will need to update the api_name to be the same as the one you set in the Process record.

By wrapping the code in console, we give context to Activity Log and prevent multiple database updates.

Poll Requests

Bond location and data

This script shows how to find a bond based on an external reference and store some data.

Variables

Here you will find a description of the variables that are available to you when scripting in Unifi.

Integration

Add note script

The Add Note Script is used to notify the end user about integration events. These notes are automatically added during processing and the script allows the target of the note to be customised. E.g., notes are usually added to work notes on Task-based tables, but a custom table might have a different field for this.

// An example add note script
function addNote(target, note, options) {
  var message = '[' + options.integration_name + ' Integration] ' + note;
  if (options.type == 'error' || options.type == 'warn') {
    message = '[code]<span style="color: red">' + message + '</span>[/code]';
  }
  target.work_notes = message;
}

Variable

Type

Description

Identify message script

The Identify Message Script is executed when an inbound request is received. It returns the name of the message that should be used to process the request. Typically, message names are embedded within the request payload, but it's possible to use the other variables available for more complex identification.

// An example identify script
function identify() {
  return (payload.message.name || '') + '';
}

Connection

Endpoint URL

The Endpoint URL will be prepended to Message Path values (providing they do not override). Inline scripts using curly braces {} can be used to construct more advanced endpoints.

See Message Path parameters for available variables.

We recommend dynamic endpoints only be considered for the same environment. New environments should have new connections so they can be managed more easily.

Message

Advanced condition

The Advanced condition is used to script complex trigger logic into the message. Only use this if you cannot use the Outbound condition filters and the single line Outbound condition.

See Outbound condition parameters for available variables.

Extract attachments script

Please refer to Extracting Attachments.

Path

The Path is used to modify the endpoint for the message. It can be used with inline script evaluation to construct more advanced endpoints. Inline scripts should be wrapped with dollar curly braces ${...}.

/table/incident/${bond.getValue("external_reference")}

Outbound condition

The outbound condition is an inline script field useful for simple one-line conditions to be used in conjunction with the filter.

More advanced conditions can be made in the Advanced condition script field.

current.assignment_group && String(current.assignment_group.u_unifi_integrations).indexOf(message.integration) != -1

Reference lookup script

The Reference lookup script is used to extract the internal and external message ID's when an inbound request is received. These ID's are used to locate the bond (and therefore the target) the request applies to.

// An example reference lookup script
var answer = {};

answer.getExternalMessageID = function (payload, request) {
  return '' + (payload.message.source_id || '');
};

answer.getInternalMessageID = function (payload, request) {
  return '' + (payload.message.target_id || '');
};

XML Template

The XML Template is evaluated in a similar way to a UI Macro and is extremely useful in constructing advanced XML based payloads using Jelly. Other types of payload can be constructed here, however it's normally easier to do this with the Fields and Field Maps or directly in the Message Scripts.

The XML Template will only be evaluated if the payload has not already been set within the Stage to Request message script.

Install the Unifi Global Utility for full support of Jelly within XML Templates.

<!-- An example XML template -->
<?xml version="1.0" encoding="utf-8" ?>
<j:jelly trim="false" xmlns:j="jelly:core" xmlns:g="glide" xmlns:j2="null" xmlns:g2="null">
	<g:evaluate jelly="true">
		var transaction = jelly.jvar_transaction;
		var stage = jelly.jvar_stage;
		var message = jelly.jvar_message;
	</g:evaluate>
	<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
		<soapenv:Header />
		<soapenv:Body>
			<MessageName>${HTML:message.message_name}</MessageName>
		</soapenv:Body>
	</soapenv:Envelope>
</j:jelly>

Message Script

Source to Stage (Outbound)

The Source to Stage script is used to capture data from the source record, e.g., an Incident, and save it to the stage record where it is ready to be used to generate a payload.

Source data values should be captured in full (including referenced values) in the Source to Stage script.

// Example source to stage script (using dynamic stage)
$stage.short_description = '' + source.short_description;

Stage to Request (Outbound)

The Stage to Request script is used to generate a payload using the data captured on the stage.

Payload generation and request configuration should be done in the Stage to Request script.

// Example stage to request script (using dynamic stage)
payload.short_description = $stage.short_description;

Payload to Stage (Inbound)

The Payload to Stage script is used to capture data from the inbound request payload and save it to the stage record where it is ready to be used to update the target record.

// Example payload to stage script (using dynamic stage)
$stage.short_description = payload.short_description;

Data should be extracted from the inbound payload and headers in the Payload to Stage script.

Stage to Target (Inbound)

The Stage to Target script is used to update the target record, e.g., an Incident, with the data and references given in the stage.

Reference lookups, data validation, and business logic should be done in the Stage to Target script.

// Example stage to target script (using dynamic stage)
target.short_description = $stage.short_description;

Field

Default inbound

The default inbound script can be used so set the default value to be used by the Field Map when no value is found on the stage.

See Stage to Target (Inbound) for available variables.

Default outbound

The default outbound script can be used so set the default value to be used by the Field Map when no value is found on the source.

See Source to Stage (Outbound) for available variables.

Field Map

Fields maps are compiled during Build operations with the field as an input and the resulting code is added to the respective Message Scripts.

Only code contained within dollar-square brackets $[...] will be compiled. During inbound/outbound processing, standard Message Script variables will apply.

var is_mandatory = $[field.mandatory];

if (is_mandatory && $payload.$[field.property] == undefined) {
  throw 'Mandatory field $[field.property] was not provided';
} else {
  $stage.$[field.element] = $payload.$[field.property];
}

var is_mandatory = false;
  
if (is_mandatory && $payload.short_description == undefined) {
  throw 'Mandatory field short_description was not provided';
} else {
  $stage.short_description = $payload.short_description;
}

Response Action

The Response Action script is executed when Run Script is checked. It can be used to do anything based on a response to an outbound request.

Event Action

Poll Processors

Variables

Poll Processor scripts have the following variables available.

Data Store Values

Some useful data values can be fetched from the Poller data store. e.g. poller.getData("$last_execution_time")

Snippets

Useful snippets of code given as examples to help with various scripting needs.

Scripted SOAP Service

Use this script to add a SOAP endpoint to a Unifi Process. You will need to update the api_name to be the same as the one you set in the Process record.

Removing Namespaces

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Header/>
    <soapenv:Body>
        <ns0:CreateServiceNowCase xmlns:ns0="urn:Unifi_RemedyCase_Service">
            <ns0:Message>
                <ns0:SourceMessageID>TXN0001001</ns0:SourceMessageID>
                <ns0:Timestamp>2022-10-27T15:01:41Z</ns0:Timestamp>
                <ns0:SourceReference>00001337</ns0:SourceReference>
            </ns0:Message>
            <ns0:Detail>
                <ns0:RequestedBy>Lance Armstrong</ns0:RequestedBy>
                <ns0:Description>This is a test</ns0:Description>
                <ns0:Impact>5</ns0:Impact>
                <ns0:ShortDescription>Testing with Unifi</ns0:ShortDescription>
            </ns0:Detail>
        </ns0:CreateServiceNowCase>
    </soapenv:Body>
</soapenv:Envelope>

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Header/>
    <soapenv:Body>
        <CreateServiceNowCase xmlns="urn:Unifi_RemedyCase_Service">
            <Message>
                <SourceMessageID>TXN0001001</SourceMessageID>
                <Timestamp>2022-10-27T15:01:41Z</Timestamp>
                <SourceReference>00001337</SourceReference>
            </Message>
            <Detail>
                <RequestedBy>Lance Armstrong</RequestedBy>
                <Description>This is a test</Description>
                <Impact>5</Impact>
                <ShortDescription>Testing with Unifi</ShortDescription>
            </Detail>
        </CreateServiceNowCase>
    </soapenv:Body>
</soapenv:Envelope>

Scripted REST API

Use this script to add a REST endpoint to a Unifi Process. You will need to update the api_name to be the same as the one you set in the Process record.

(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {

    x_snd_eb.ws_console.execute('Request received', function() {
        var helper = new x_snd_eb.RestHelper('incident_guide'); // the API name of the Unifi Process
        processAttachment(helper.getRequest().getRecord());
        helper.processRequest(request, response, 'POST'); // the HTTP method of the resource
    });

})(request, response);

By wrapping the code in console, we give context to Activity Log and prevent multiple database updates.

Poll Requests

Bond location and data

This script shows how to find a bond based on an external reference and store some data.

var integration = poll_request.$model.getIntegration();
var bond = new Bond(integration.getConfig());
var external_ref = 'BP-41951';

try {
  if (bond.locateReference(integration, '', external_ref, 'external')) {
    // found bond ... do your processing here

    bond.setData('key', 'abc');
    bond.setDataObject('key', {foo: 'bar'});

  } else {
    throw 'Unable to locate bond for reference "' + external_ref + '"';
  }
} catch (e) {
  log.error(e);
}

Variables

Here you will find a description of the variables that are available to you when scripting in Unifi.

Integration

Add note script

// An example add note script
function addNote(target, note, options) {
  var message = '[' + options.integration_name + ' Integration] ' + note;
  if (options.type == 'error' || options.type == 'warn') {
    message = '[code]<span style="color: red">' + message + '</span>[/code]';
  }
  target.work_notes = message;
}

Variable

Type

Description

Identify message script

// An example identify script
function identify() {
  return (payload.message.name || '') + '';
}

Variable

Type

Description

Connection

Endpoint URL

The Endpoint URL will be prepended to Message Path values (providing they do not override). Inline scripts using curly braces {} can be used to construct more advanced endpoints.

See Message Path parameters for available variables.

We recommend dynamic endpoints only be considered for the same environment. New environments should have new connections so they can be managed more easily.

Message

Advanced condition

The Advanced condition is used to script complex trigger logic into the message. Only use this if you cannot use the Outbound condition filters and the single line Outbound condition.

See Outbound condition parameters for available variables.

Extract attachments script

Please refer to Extracting Attachments.

Path

/table/incident/${bond.getValue("external_reference")}

Variable

Type

Description

Outbound condition

The outbound condition is an inline script field useful for simple one-line conditions to be used in conjunction with the filter.

More advanced conditions can be made in the Advanced condition script field.

current.assignment_group && String(current.assignment_group.u_unifi_integrations).indexOf(message.integration) != -1

Variable

Type

Description

Reference lookup script

// An example reference lookup script
var answer = {};

answer.getExternalMessageID = function (payload, request) {
  return '' + (payload.message.source_id || '');
};

answer.getInternalMessageID = function (payload, request) {
  return '' + (payload.message.target_id || '');
};

Variable

Type

Description

XML Template

The XML Template will only be evaluated if the payload has not already been set within the Stage to Request message script.

Install the Unifi Global Utility for full support of Jelly within XML Templates.

<!-- An example XML template -->
<?xml version="1.0" encoding="utf-8" ?>
<j:jelly trim="false" xmlns:j="jelly:core" xmlns:g="glide" xmlns:j2="null" xmlns:g2="null">
	<g:evaluate jelly="true">
		var transaction = jelly.jvar_transaction;
		var stage = jelly.jvar_stage;
		var message = jelly.jvar_message;
	</g:evaluate>
	<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
		<soapenv:Header />
		<soapenv:Body>
			<MessageName>${HTML:message.message_name}</MessageName>
		</soapenv:Body>
	</soapenv:Envelope>
</j:jelly>

Variable

Type

Description

Message Script

Source to Stage (Outbound)

The Source to Stage script is used to capture data from the source record, e.g., an Incident, and save it to the stage record where it is ready to be used to generate a payload.

Source data values should be captured in full (including referenced values) in the Source to Stage script.

// Example source to stage script (using dynamic stage)
$stage.short_description = '' + source.short_description;

Variable

Type

Description

Stage to Request (Outbound)

The Stage to Request script is used to generate a payload using the data captured on the stage.

Payload generation and request configuration should be done in the Stage to Request script.

// Example stage to request script (using dynamic stage)
payload.short_description = $stage.short_description;

Variable

Type

Description

Payload to Stage (Inbound)

The Payload to Stage script is used to capture data from the inbound request payload and save it to the stage record where it is ready to be used to update the target record.

// Example payload to stage script (using dynamic stage)
$stage.short_description = payload.short_description;

Data should be extracted from the inbound payload and headers in the Payload to Stage script.

Variable

Type

Description

Stage to Target (Inbound)

The Stage to Target script is used to update the target record, e.g., an Incident, with the data and references given in the stage.

Reference lookups, data validation, and business logic should be done in the Stage to Target script.

// Example stage to target script (using dynamic stage)
target.short_description = $stage.short_description;

Variable

Type

Description

Field

Default inbound

The default inbound script can be used so set the default value to be used by the Field Map when no value is found on the stage.

See Stage to Target (Inbound) for available variables.

Default outbound

The default outbound script can be used so set the default value to be used by the Field Map when no value is found on the source.

See Source to Stage (Outbound) for available variables.

Field Map

Fields maps are compiled during Build operations with the field as an input and the resulting code is added to the respective Message Scripts.

Only code contained within dollar-square brackets $[...] will be compiled. During inbound/outbound processing, standard Message Script variables will apply.

var is_mandatory = $[field.mandatory];

if (is_mandatory && $payload.$[field.property] == undefined) {
  throw 'Mandatory field $[field.property] was not provided';
} else {
  $stage.$[field.element] = $payload.$[field.property];
}

var is_mandatory = false;
  
if (is_mandatory && $payload.short_description == undefined) {
  throw 'Mandatory field short_description was not provided';
} else {
  $stage.short_description = $payload.short_description;
}

Variable

Type

Description

Response Action

The Response Action script is executed when Run Script is checked. It can be used to do anything based on a response to an outbound request.

Variable

Type

Description

Event Action

Variable

Type

Description

Poll Processors

Variables

Poll Processor scripts have the following variables available.

Variable

Type

Description

Data Store Values

Some useful data values can be fetched from the Poller data store. e.g. poller.getData("$last_execution_time")

Name

Type

Description