User Tools

Site Tools


before_share_script

Before Share Script

v3.1.8

A before share script allows the current record that is being shared to be processed after it is loaded into a GlideRecord, but before it is encrypted and queued up to the Perspectium Cloud Server. This feature is available for both Dynamic Share and Bulk Share.

The script expects server side javascript, and is preconfigured with a globally available variable called current that is the GlideRecord object that is going to be shared.

For example, to ensure that the short_description field value of a record to always be greater than 0 and less than 1000 characters, you may use the following script:

var s = current.short_description.toString();
current.short_description = s.substring(0, 1000);

Because this script is executed every time a record is shared, be aware of the processing delays introduced that will be multiplied when sharing multiple records at the same time.

Note if you have multiple share configurations for the same table (such as different share configurations that each have a different target queue), any changes to the current object may affect any conditions you have to share since this same current object is referenced as we iterate through the table's different share configurations.

For example, if you have multiple share conditions for the ticket table (one will share to the target queue psp.out.servicenow.test and the other shares to the queue psp.out.servicenow.dev) and all have the condition short_description is 'test' in order to share records, if one of your share configurations has the before share script of: current.short_description = 'test123'

Then other share configurations for this will not share the record to their target queues since the short_description of the current object has been changed to 'test123'.

Ignore or Cancel Share

There are 3 ways you can control the Dynamic Share to only fire on certain field updates.

  • Manually in a Before Share Script
  • Only trigger when specified columns have changed
  • Only trigger when columns other than the specified columns have changed

Ignoring or canceling a share in the before share script

v3.6.0

In the Before Share Script of a Dynamic or Bulk share configuration, you can set the global variable ignore to the boolean value true to prevent the current record from being shared.

For example, the following script ignores the Dynamic sharing of an incident record when the priority field value is 1:

if (current.priority == 1) {
    ignore = true;
}

As another example, the following script will ignore sharing the record with a number value TKT0010001 during Bulk sharing of all ticket records:

if (current.number == "TKT0010001") {
    ignore = true;
}

Ignoring a share if only one field has changed

For cases where you have a table's records updated frequently but data doesn't actually change (such as a table that gets updated every single day via another integration or ServiceNow Discovery), you may not want the table's dynamic share (with interactive only not selected) to run and share out any records.

For example, say the field that gets updated every day is u_last_discovered_date. The rest of the fields don't usually change, and you don't want to share these records out again since the subscribing side (such as a database) doesn't really need the latest u_last_discovered_date.

In these cases, you can run the following script to ignore sharing the record:

function listChangedFields(obj){
	var flds = [];
	var aud = new GlideRecord("sys_audit");
	aud.addQuery("documentkey", obj.sys_id);
	aud.addQuery("record_checkpoint", obj.sys_mod_count);
	aud.query();
	while (aud.next()){
		flds.push(aud.getValue("fieldname"));
	}
	return flds;
}

var changedFields = listChangedFields(current);
var ignoreFields = ["priority", "urgency"]; // If any changed field falls outside that list, the update will be sent

ignore = true;

var util = new ArrayUtil();
for (var i=0; i<changedFields.length; i++){
	if (!util.contains(ignoreFields, changedFields[i])) ignore = false;
}

Ignoring a share with multiple field changes

In v3.22.0 users can activate the checkbox “Select column updates to ignore” to ignore sharing records with multiple field changes. To begin, click the checkbox to see the related list which will allow you to select the fields.

Next you can select the fields that you want to be ignored when updated. Using the picture above as an example, the record would be ignored if the number and description fields are the ONLY fields that have been updated; if any other fields have also been updated the record will not be ignored.

Sharing on specific field changes

In Bismuth users can activate the checkbox “Select column updates to share on” to share a record only when one of any number of chosen fields are updated. To begin, click the checkbox to see the related list which will allow you to select the fields.

Note that clicking either “Select column updates to share on” or “Select column updates to ignore” will hide the other checkbox. Only one option can be selected.

Next you can select the fields that you want to trigger a share. Using the picture above as an example, the record would ONLY be shared if the Assigned To or Description fields have been updated; if these fields have not been updated, the record will be ignored.

psp_action

v3.12.0

In the Before Share Script of a Dynamic or Bulk share configuration, you can set the global variable psp_action to specify the “action” value of records being shared.

“action” is the value that appears after the table name in the “name” field of outgoing Replicator messages. For example, action is “insert” in “incident.insert” (for records being inserted), “update” in “incident.update” (records being updated) and so forth. This is useful for integrations with other systems where you want the table to designate a different action from the default one ServiceNow specifies.

For example, say you are integrating with another system and using the correlation_id to designate the incident record's number in the other system. If there was a failure creating the incident in the other system and you do an update to the incident in ServiceNow, instead of sending the record as an “update”, you may want to send it as an “insert” instead so as to create the incident in the other system this time.

The following script will accomplish this by setting action to “insert” when the correlation_id field is not populated:

if (current.correlation_id == null || current.correlation_id == "") {
    psp_action = "insert";
}

share_gr

v3.31.0
To access the Bulk and Dynamic Share records themselves from the Before Share Script, use the global variable share_gr.

For example, the following Before Share script will log the value of the current Bulk/Dynamic share record's system id:

gs.log(share_gr.sys_id);

previous

v3.31.0
To access the previous record in a Dynamic Share (ie, a record before it has been modified), use the global variable previous in the Before Share script. For example, the following script will log the value of the previous record’s short description:

gs.log(previous.short_description);

As another example, you can compare the field values of the previous and current records being shared dynamically.

if(current.short_description != previous.short_description){
	//do something here
}

*Note: you can only access the previous variable when the “Business Rule When” is set to “before” or “after” under Trigger Conditions of the Dynamic Share (it will not work with “async”).

In addition, the information above only applies to Dynamic Shares; the data shared in a Bulk Share is historical and will not have been modified.

psp_key

Carbon
To access the key value of the outbound message, you can change the psp_key global dynamically.

To enabled this functionality, turn off com.perspectium.validate_mismatch_key in your Perspectium properties.

// run on before share
psp_key = "custom_client";
before_share_script.txt · Last modified: 2018/05/15 00:13 by paul