SNOW server-side

A wrapper has been written around the standard database operation .get(), .insert(), update() and remove(). This wrapper called [Prefix]_SNOW() helps to make those request easier, more consistent and often faster to write.

Usage

var snow = new [Prefix]_SNOW();

snow.get(request);
snow.insert(request);
snow.update(request);
snow.remove(request);

snow.getSecure(request);
snow.insertSecure(request);
snow.updateSecure(request);
snow.removeSecure(request);

snow.count(request);
snow.pluck(obj,attr);
snow.ids(obj,attr);
snow.response(obj);

.get() will return an object containing all found records.
.insert() will insert the provided records.
.update() will update records found by the query.
.remove() will remove a single or multiple records based on the query.

.[...]Secure() will use GlideRecordSecure and thus respect acl rules which its counter part using only GlideRecord does not.

.count() will only count the records that match your query using Glide Aggregate. Should also be used if you soley want to verify a record exists.
.pluck() will return an array containing propery values. (Same as .pluck() from the library Underscore)
.ids() same as pluck but aditionally returns the results as a comma seperated string and removes duplicates (mostly used for retrieving unique sys_ids).
.response() should be used to generate the response for the client-side. The method will check the response for possible mistakes and then JSON.stringify() the response for the client to be interpreted.

Examples

`.get()`

Example request to get all incidents updated today.

// Create an instance of the SNOW helper
var snow = new [Prefix]_SNOW();

// Perform the get request
var response = snow.get({

	// Table to request records from
	table: "incident",

	// Attributes to be returned
	items: ["number","opened_at","priority","state","category"],

	// The Service Now encoded query to perform
	query: "sys_updated_onONToday@javascript:gs.beginningOfToday()@javascript:gs.endOfToday()"
});

// Log the result of the get to see the operation status
gs.log(JSON.stringify(response, null, '\t'));

// Example .get() output
{
	// Found records
	"data": {
		"9a5f8038dbcfcb00d3222aea4b961985": {
			"sys_id": "9a5f8038dbcfcb00d3222aea4b961985",
			"number": "INC0010075",
			"opened_at": "2017-12-12 14:24:42",
			"priority": "1",
			"state": "2",
			"category": "inquiry"
		},
		"46e2fee9a9fe19810049b49dee0daf58": {
			"sys_id": "46e2fee9a9fe19810049b49dee0daf58",
			"number": "INC0000015",
			"opened_at": "2017-08-05 23:38:46",
			"priority": "1",
			"state": "3",
			"category": "software"
		},
		"a9e30c7dc61122760116894de7bcc7bd": {
			"sys_id": "a9e30c7dc61122760116894de7bcc7bd",
			"number": "INC0000046",
			"opened_at": "2017-10-29 22:04:15",
			"priority": "1",
			"state": "6",
			"category": "software"
		},
		"d71b3b41c0a8016700a8ef040791e72a": {
			"sys_id": "d71b3b41c0a8016700a8ef040791e72a",
			"number": "INC0000053",
			"opened_at": "2017-10-29 20:48:46",
			"priority": "1",
			"state": "2",
			"category": "inquiry"
		}
	}

	// Possible error message
	"error": null,

	// Count of all found records
	"count": 4
}

`.pluck()`

Here we want to retrieve the state value of the incidents matching the query.

var snow = new [Prefix]_SNOW();

// Note we only request state in items since we dont require the other attributes
var users = snow.get({
	table: "incident",
	items: ["state"],
	query: "sys_updated_onONToday@javascript:gs.beginningOfToday()@javascript:gs.endOfToday()"
});

// Pluck the state of all user records
var states = snow.pluck(users.data, "state");

// Log the state array and stringify to give it an array-like layout
gs.log(JSON.stringify(states, null, '\t'));

// Example .pluck() output
[
	"2",
	"3",
	"6",
	"2"
]

`.insert()`

Insert two records into the incident table.

var snow = new [Prefix]_SNOW();

var result = snow.insert({
	table: "incident",

	// Array of records/objects to be inserted
	records: [{
		category: "inquiry"
		short_description: "insert 1"
	}, {
		short_description: "insert 2"
		description: "Any attribute of the incident table can be set"
	}]
});

// Log the result of the insert to see the operation status
gs.log(JSON.stringify(result, null, '\t'));

// Example .insert() output
{
	// Sys_id of inserted records indexed by the records var index
	"data": {
		"0": "863d098ddbd49700881764484b92199a",
		"1": "933d0581db189700881764484b9219fd"
	},

	// Possible error message
	"error": null,

	// Count of inserted records
	"inserted": 2
}

`.update()`

Update all records matching the query with the operation described in update

var snow = new [Prefix]_SNOW();

var result = snow.update({
	table: "incident",
	query: "sys_updated_onONToday@javascript:gs.beginningOfToday()@javascript:gs.endOfToday()"

	// This update operation will change the short_description for all incidents maching the query to "update 1"
	update: {
		short_description: "update 1"
	}
});

// Log the result of the update to see the operation status
gs.log(JSON.stringify(result, null, '\t'));

// Example .update() output
{
	// Sys_id of records attempted to updated + the bool indicating if they where updated or not
	"data": {
		"545c240ddb9497008812644a4b9619df": true,
		"bc7c2c0ddb9497008812644a4b96197c": true,
		"003d0581db1897008812644a4b9619fd": true,
		"843d098ddbd497008812644a4b96199a": true
	},

	// Possible error message
	"error": null,

	// Count of found records
	"count": 4,

	// Count of updated records
	"affected": 4
}

`.remove()`

Remove all records matching the query. The .remove() expects you want to remove only one record by default. So if your query matches multiple records you will get an error message and no records will be removed. If you explicitly want to remove multiple records then set the following boolean to true: multipleExpected: true

var snow = new [Prefix]_SNOW();

var result = snow.remove({
	table: "incident",
	query: "sys_updated_onONToday@javascript:gs.beginningOfToday()@javascript:gs.endOfToday()"
});

// Log the result of the remove to see the operation status
gs.log(JSON.stringify(result, null, '\t'));

// Example .remove() output
{
	// Sys_id of records attempted to remove + the bool indicating if they where removed or not
	"data": {},

	// Possible error message
	"error": "Multiple records (4) where found while only one was expected to be removed. Evaluate your query or set 'multipleExpected:true'",

	// Count of found records
	"count": 4,

	// Count of removed records
	"removed": 0,
}

multipleExpected: true

var snow = new [Prefix]_SNOW();

var result = snow.remove({
	table: "incident",
	query: "sys_updated_onONToday@javascript:gs.beginningOfToday()@javascript:gs.endOfToday()",
	multipleExpected: true
});

// Log the result of the remove to see the operation status
gs.log(JSON.stringify(result, null, '\t'));

// Example .remove() output
{
	// Sys_id of records attempted to remove + the bool indicating if they where removed or not
	"data": {
		"003d0581db1897008812644a4b9619fd": true,
		"545c240ddb9497008812644a4b9619df": true,
		"bc7c2c0ddb9497008812644a4b96197c": true,
		"843d098ddbd497008812644a4b96199a": true
	},

	// Possible error message
	"error": null,

	// Count of found records
	"count": 4,

	// Count of removed records
	"removed": 4
}

Script include example

var [Prefix]_Call = Class.create();

[Prefix]_Call.prototype = Object.extendsObject(AbstractAjaxProcessor, {

	type: "[Prefix]_Call",

	snow: new [Prefix]_SNOW(),

	getGroups: function(id) {
		return this._getGroups(id);
	},
	getGroupsClient: function(id) {
		return this.snow.response({groups: this._getGroups(this.getParameter("sysparm_id")||id)});
	},
	getGroupsOfUserEncodedQuery: function(id) {
		return "sys_idIN"+this._getGroups(id).join(",");
	},
	_getGroups: function(id) {

		// Get all groups of which the provided id is a member
		var groups = this.snow.get({
			table : "sys_user_grmember",
			items : ["group"],
			query : "user.sys_id="+id
		});

		return this.snow.pluck(groups.data, "group");
	}
});

hawkerboy7/SNOW helper server-side.md

SNOW server-side

Usage

Examples

.get()

.pluck()

.insert()

.update()