JSDoc: common

module with common methods used by other modules.

Members

# inner delete

The xmapi common delete api request wrapper. Used for deleting an object in the xmapi.

Methods

# inner AssignParentObject(childsParent, destinationParents, matchId, fields) → {string}

Assists with ExportToImport functions. Accepts a data object's parent, all destination Parents and the field they are matching on for the parent and update the parent with the id of the parent in the destination if it exists or

Parameters:

Name	Type	Description
`childsParent`	Object	The Object that represents the current child's parent.
`destinationParents`	Array.<Object>	An array of the parent objects to find a match.
`matchId`	String	The key name from the child that represents the parent.
`fields`	Array.<String>	additional fields to match on.

View Source common.js, line 609

Returns:

child's parent id or matchId id if not available.

Type: string

# async inner create(env, api, json, label, dropId) → {Object}

The xmapi common create api request wrapper. Used for creating an object in the xmapi.

Parameters:

Name	Type	Description
`env`	module:environments.xMattersEnvironment	The xmtoolbox representation of an xMatters instance
`api`	string	The api endpoint past the base URL. Example: '/api/xm/1/groups'
`json`	Object	The object to include in the request body as json
`label`	string	The Label to define what type of object or objects are being acted on with this request. Primarily used for logging.
`dropId`	boolean	Whether or not to drop the id key in the request. If true the id key is deleted before the request is made.

View Source common.js, line 209

Returns:

Body from from create request response

Type: Object

# async inner get(env, api, id, query, label) → {Object}

The xmapi common get api request wrapper. Used for getting an object in the xmapi.

Parameters:

Name	Type	Description
`env`	module:environments.xMattersEnvironment	The xmtoolbox representation of an xMatters instance
`api`	string	The api endpoint past the base URL. Example: '/api/xm/1/groups'
`id`	string	The identifier for the object. This is used in the URL for the request. The endpoints vary with exactly what this can be but is usually the object's id however some requests allow for the targetName or name.
`query`	Object	A json object representing the query string parameters for this request.
`label`	string	The Label to define what type of object or objects are being acted on with this request. Primarily used for logging.

View Source common.js, line 138

Returns:

Body from from get request response

Type: Object

# async inner getMany(env, api, query, label) → {Array.<Object>}

The xmapi common get api request wrapper for paginated requests. Used for getting all objects in the xmapi that match the query.

Note: This simplifies and speeds the access to paginated data. This returns all objects in an array. Not the first request from the matching endpoint.

Parameters:

Name	Type	Description
`env`	module:environments.xMattersEnvironment	The xmtoolbox representation of an xMatters instance
`api`	string	The api endpoint past the base URL. Example: '/api/xm/1/groups'
`query`	Object	A json object representing the query string parameters for this request.
`label`	string	The Label to define what type of object or objects are being acted on with this request. Primarily used for logging.

View Source common.js, line 164

Returns:

Objects from all body.data arrays concatenated to a single array.

Type: Array.<Object>

# inner getNullDefaults(fields) → {Object}

Takes an array of strings to return an object with keys for each string included in the array with it's value set to null.

Parameters:

Name	Type	Description
`fields`	Array.<string>

View Source common.js, line 631

Returns:

Returns an array of null value keys where the keys match the fields.

Type: Object

# inner omit(obj, props)

Removes properties from an object.

Parameters:

Name	Type	Description
`obj`	Object	object to delete property from.
`props`	Array.<string>	array of string property names to delete from object.

View Source common.js, line 82

# inner queryString(query) → {string}

Builds a query string from object using key/value pairs.

Parameters:

Name	Type	Description
`query`	Object	object

View Source common.js, line 93

Returns:

A uri query string without leading ?

Type: string

# async inner request(env, api, query, options, label) → {Object}

wrapper for request-promise

Parameters:

Name	Type	Description
`env`	module:environments.xMattersEnvironment	The xmtoolbox representation of an xMatters instance
`api`	string	The api endpoint past the base URL. Example: '/api/xm/1/groups'
`query`	Object	An object representing the query string parameters for this request.
`options`	Object	The node request options for this request.
`label`	string	The Label to define what type of object or objects are being acted on with this request. Primarily used for logging.

View Source common.js, line 323

Returns:

Body from from create request response

Type: Object

# inner requestList(total, auth, uri, method, json, pageSize) → {Array.<Object>}

Builds a list of request options for paginated results like getPeople, getGroups, or other paginated endpoints.

Parameters:

Name	Type	Default	Description
`total`	number		The number of objects.
`auth`	Object		node request auth object.
`uri`	string		The URI to request without the offset query parameter.
`method`	string	GET	The HTTP
`json`	Object	null	The object to include in the node request.json
`pageSize`	number	100	Default: 100 The number of objects included in a request.

View Source common.js, line 116

Returns:

An array of request option objects

Type: Array.<Object>

# async inner rp(options, log) → {Promise.<Object>}

request promise wrapper with retry logic.

Parameters:

Name	Type	Description
`options`	Object	request promise options.
`log`	Object	Log object with log, error, warn, and info functions.

View Source common.js, line 18

Returns:

Promise of the request or nothing if error.

Type: Promise.<Object>

# inner sleep(ms)

A simple sleep function to add delay where needed.

Parameters:

Name	Type	Description
`ms`	number	The number of milliseconds to sleep.

View Source common.js, line 371

# async inner syncObject(name, sourceObjects, destinationObjects, destination, syncField, objectFields, createFunction, updateFunction, deleteFunction, options, parentKey) → {Promise.<module:common.SyncResults>}

Synchronizes an array of objects into xMatters using the available functions. It looks for a match based on the syncField. It then performs object comparison based on the fields list. If source matches it is skipped. If it does not match it updates using the update function or or not available performs a delete and create. If options.mirror is true the object is deleted if a match is not found in the source. If delayedRemoval is true these object are note removed and returned instead for later removal.

Parameters:

Name	Type	Description
`name`	string	The
`sourceObjects`	Array.<Object>	An array of xMatters Objects to synchronize. These are considered to be all the the objects from the source.
`destinationObjects`	Array.<Object>	An array of xMatters Objects to synchronize. These are considered to be the objects from the destination.
`destination`	module:environments.xMattersEnvironment	The xmtoolbox representation of an xMatters instance
`syncField`	Array.<string> \| string	A string or an array of strings for the keys to identify the source object in the destination objects. Ex: targetName or name.
`objectFields`	Array.<string>	The default array (defined in each object module) of strings for the keys to compare to determine if an update is needed in the destination.
`createFunction`	function	The function to create an object in xMatters. Needs to match the common create function structure.
`updateFunction`	function	The function to update an object in xMatters. Needs to match the common update function structure. If unavailable, set to undefined.
`deleteFunction`	function	The function to delete an object in xMatters. Needs to match the common delete function structure.
`options`	module:common.SyncOptions	Options object to control the outcome of the sync.
`parentKey`	string	Optional: string identifier for the key that represents the parent in the source object. Example: A shift would use the parentKey of 'group'

View Source common.js, line 442

Returns:

Type: Promise.<module:common.SyncResults>

# async inner update(env, api, json, id, label) → {Object}

The xmapi common update api request wrapper. Used for updating an object in the xmapi.

Parameters:

Name	Type	Description
`env`	module:environments.xMattersEnvironment	The xmtoolbox representation of an xMatters instance
`api`	string	The api endpoint past the base URL. Example: '/api/xm/1/groups'
`json`	Object	The object to include in the request body as json
`id`	string	The identifier for the object. This is used in the URL for the request. The endpoints vary with exactly what this can be but is usually the object's id however some requests allow for the targetName or name.
`label`	string	The Label to define what type of object or objects are being acted on with this request. Primarily used for logging.

View Source common.js, line 267

Returns:

Body from from update request response

Type: Object

# async inner upload(env, api, formData, label) → {Object}

The xmapi common upload api request wrapper. Used for uploading multipart/form data to the xmapi.

Parameters:

Name	Type	Description
`env`	module:environments.xMattersEnvironment	The xmtoolbox representation of an xMatters instance
`api`	string	The api endpoint past the base URL. Example: '/api/xm/1/groups'
`formData`	Object	node request formData object to upload
`label`	string	The Label to define what type of object or objects are being acted on with this request. Primarily used for logging.

View Source common.js, line 297

Returns:

Body from from upload request response

Type: Object

Type Definitions

Type: Object

# SyncOptions

Options to set when synchronizing data into xMatters.

Properties:

Name	Type	Description
`mirror`	boolean	Whether or not to remove non-matching objects from the destination xMatters instance when there is no match found in the sourceObjects. Default: false
`delayRemoval`	boolean	Used only with mirror is true. Whether or not to delete the objects immediately or return an array of objects to be removed later. Default: true
`fields`	Array.<string>	An array of strings for the keys to compare to determine if an update is needed in the destination. default: undefined. If undefined uses all default syncable fields for synchronization.

View Source common.js, line 375

Type: Object

# SyncResults

An common object to return the results of synchronizing many objects of a single object type.

Properties:

Name	Type	Description
`synced`	Array.<Object>	An array of objects that were created in the destination.
`synced`	Array.<Object>	An array of objects that need to be removed due to mirror and delayRemoval being true.

View Source common.js, line 387

Type: Object

# xMattersData

Object representation of the data from an xMatters instance or data intended for an xMatters Instance.

Properties:

Name	Type	Description
`annotations`	Array.<Annotation>
`audits`	Array.<Audit>
`deviceNames`	Array.<DeviceName>
`devices`	Array.<Device>
`deviceType`	Array.<DeviceType>
`dynamicTeam`	Array.<DynamicTeam>
`events`	Array.<Event>
`eventSuppressions`	Array.<EventSuppression>
`forms`	Array.<Form>
`groupMembers`	Array.<GroupMember>
`groups`	Array.<Group>
`importJobs`	Array.<ImportJob>
`integrations`	Array.<Integration>
`onCalls`	Array.<OnCall>
`people`	Array.<Person>
`planConstants`	Array.<PlanConstant>
`planEndpoints`	Array.<PlanEndpoint>
`planProperties`	Array.<PlanProperty>
`plans`	Array.<Plan>
`roles`	Array.<Role>
`scenarios`	Array.<Scenario>
`sharedlibrary`	Array.<SharedLibrary>
`shifts`	Array.<Shift>
`sites`	Array.<Site>
`subscriptionForms`	Array.<SubscriptionForm>
`subscriptions`	Array.<Subscription>
`temporaryAbsences`	Array.<TemporaryAbsence>

View Source common.js, line 394