/service-now

Service Now JSONv2 API wrapper. Includes easy to use functions to perform common tasks. Formerly published as 'snow-query'.

Primary LanguageJavaScript

Disclaimer

This is based on https://github.com/steppjos/service-now, with improvements to error handling, and changes to move from callbacks to Promises. This project is provided AS IS, and not supported in any way, though PRs are welcome.

ServiceNow v2.0

Service Now JSONv2 API wrapper. Includes easy to use functions to perform common tasks. Formerly published as 'snow-query'.

Highlight Features:

  • Querying tables (GET),
  • Updating Records (POST),
  • Specialized Classes and Methods for common tasks (i.e. Closing RITMs.).

SNOW JSONv2 API Reference:

1. Getting Started

Get ServiceNow now!
npm install service-now --save
Require, and Initiate
'use strict'
const ServiceNow = require('service-now');
const Snow  = new ServiceNow({
    url: 'https://<your-instance-name>.service-now.com/',
    username: yourUsername,
    password: yourPassword
});

2. GET and POST - How to Query and Update Records (Class: Snow)

getRecords

A streamlined method to set your table and query then retrieving records.

Note: by default query Object contains "displayVariables: true". Each record's primary key will be converted to their proper value.

const record = await Snow.getRecords(queryObject)

Code Example:

const record = await Snow.getRecords({
    table: 'sc_req_item',
    query: {
        number:'RITM0123456'
        }
    }
});
setTable

Sets the table variable for your Snow instance.

Snow.setTable(Table)    // Table as String

Code Example:

Snow.setTable('sc_req_item');
setQuery

Sets the query variable for your Snow instance.

Snow.setQuery(Arguments[Object], DisplayVariables, DisplayValues)

Code Example:

Snow.setQuery({
    active: true,
    number: 'RITM0123456',
    }, 'true', 'false');
get

Gets records from using the variables set from the setTable and setQuery methods.

Snow.get()

Code Example:

const data = await Snow.get();
post

Updates records using the variables set from the setTable and setQuery methods. This will update all records matching the query.

Snow.post(JSONbody[object])

Code Example:

const result = await Snow.post({
    close_notes: 'Batch closing tickets from ServiceNow.',
    active: false
});

3. RITM Methods (Class: Snow.Ritm)

getRitms

Gets RITMs matching the queryObject passed to the function.

Snow.Ritm.getRitms(queryObject)

Code Example:

const records = await Snow.Ritm.getRitms({
    active: true,
    assignment_group: ''
});
getActive

Gets all active RITMs.

Snow.Ritm.getActive()

Code Example:

const data = await Snow.Ritm.getActive();
getByNumber

Gets a single RITM by number.

Snow.Ritm.getByNumber(Number)

Code Example:

const data = await Snow.Ritm.getByNumber('RITM0123456');
closeByNumber

Closes a single RITM by number.

Snow.Ritm.closeByNumber(Number, CloseNotes)

Code Example:

await Snow.Ritm.closeByNumber('RITM0123456', 'Closing the ticket, issue was resolved.');

4. User Methods (Class: Snow.User)

getUsers

Gets all users in your SNOW instance.

Snow.User.getUsers()

Code Example:

await Snow.User.getUsers();
getUserGroups

Gets all user groups in your SNOW instance.

Snow.User.getUserGroups()

Code Example:

const groups = await Snow.User.getUserGroups();
getUserByUserName

Gets a single user by their username in your SNOW instance.

Snow.User.getUserByUserName(username)

Code Example:

const user = await Snow.User.getUserByUserName('JSmith');
getUserById

Gets a single user by their sys_id in your SNOW instance.

Snow.User.getUserById(userId)

Code Example:

const user = await Snow.User.getUserByUserName('007c75ce6f2c9100222a57ee2c3ee43d');

5. Category Methods (Class: Snow.Category)

getCategories

Gets all categories in your SNOW instance.

Snow.Category.getCategories()

Code Example:

const categories = await Snow.Category.getCategories();
getCategoryItems

Gets all category items in your SNOW instance.

Snow.Category.getCategoryItems()

Code Example:

const items = await Snow.Category.getCategoryItems();

6. Utility Methods (Class: Snow.Utilities)

groupBy

Groups an array of JSON documents by a specific oject property.

Snow.Utilities.groupBy(data, property)

Code Example:

const activeRequests = awaitSnow.Ritm.getActive();
const groupData = Snow.Utilities.groupBy(activeRequests, 'cat_item');
flattenVariables

Note: Only for use with RITM documents when querying the same cat_item. Refactors the embedded variables document, to be included in the parent document.

Snow.Utilities.flattenVariables(data)

Code Example:

const activeRequests = awaitSnow.Ritm.getActive();
const flatData= Snow.Utilities.flattenVariables(activeRequests);

Script Examples

Query Records Script Example 1

This is the preferred method of querying records.

'use strict'
const ServiceNow = require('service-now');
var Snow  = new ServiceNow('https://<your-instance-name>.service-now.com/', yourUsername, yourPassword);

const records = await Snow.getRecords({
    table: 'sc_req_item',
    query: {
        number:'RITM0123456'
    }
});
Query Records Script Example 2

This is an alternative method of querying records.

'use strict'
const ServiceNow = require('service-now');
const Snow  = new ServiceNow({
    url: 'https://<your-instance-name>.service-now.com/',
    username: yourUsername,
    password: yourPassword
});

// Input whatever table you like.
Snow.setTable('sc_req_item');

// Declare your query object, and the 'displayvariables' & 'displayvalues' boolean as a string. By default it is true.
// Snow.setQuery(QueryObject, DisplayVariables, DisplayValues);
Snow.setQuery({
    active: true,
    number: 'RITM0123456',
}, 'true', 'false');

// Get your data and do stuff.
const data = await Snow.get();
Update Records Script Example 2

This is an example method of updating records.

'use strict'
const ServiceNow = require('service-now');
const Snow  = new ServiceNow({
    url: 'https://<your-instance-name>.service-now.com/',
    username: yourUsername,
    password: yourPassword
});

// Set your table.
Snow.setTable('sc_req_item');

// Set your query.
Snow.setQuery({
    active:true,
    priority: 3
}, 'true', 'true');

// In this example we close all the tickets matching our query.
const result = await Snow.post({
    close_notes: 'Batch closing tickets from ServiceNow.',
    active: false
});
License

The MIT License (MIT)

Copyright (c) 2016 Elias Hussary

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.