@capriza/service-now-connector

Connector for ServiceNow

This connector uses the ServiceNow REST API.

Getting Started

Follow these instructions to download and configure your ApproveSimple Service-Now connector for development and testing.

1. Run the following command on your terminal:

npx @capriza/service-now-connector 

The service-now-connector folder is created in the folder from which you ran the command and the service-now-connector is installed in it.

The folder contains config.json, transformer.js and ui-templates.json for the change request,service request and item request use cases.

2. If you don't have a service-now account, you can create demo here.

3. Edit systemConfig.json file, a copy of which is displayed below, replacing the placeholder texts with your instance name and your service-now credentials.

Example of system.json before editing:

 {"instanceName": "YOUR_INSTANCE", "integrationUser": { "username": "admin", "password": "ADMIN_PASSWORD" }}  

4. Run the command below to start the Capriza ApproveSimple test tool, the ApproveSimple Inspector:

npm run inspector  

NOTE: If the inspector does not open after running the "npm run inspector" command, open http://localhost:8080/ in your browser.

How the connector works

The connector uses 2 types of requests - GET and PUT:

GET requests can be used to fetch a single specific approval request or all open approval requests. Get requests are also used for fetching attachments.

PUT requests are used to take an action such as approve or reject.

Examples of Using GET and PUT Requests

Paragraphs 1, 2 and 3 below illustrate how the service-now connector uses these GET and PUT requests.

1. The connector uses a request of type GET to retrieve approval request data for a single approval request.
   For details click here.

The example below shows how approval request data for a single approval request with with id "0349403adba52200a6a2b31be0b8f509" is fetched:
GET: https://dev36661.service-now.com/api/now/table/sysapproval_approver, params = {"sysparm_query":"sys_id=0349403adba52200a6a2b31be0b8f509^state=requested"}

The next example fetches approval request data for all pending approval requests:
GET https://dev36661.service-now.com/api/now/table/sysapproval_approver, params = {"sysparm_query":"state=requested^source_table=change_request","sysparm_fields":"approver.sys_id,approver.name,approver.user_name","sysparm_limit":1000}

2. GET requests are also used to fetch attachment data. For more details, click here.
   The following example of uses a GET request to fetch all the attachments from the sysapproval_approver table (that holds all pending approvals):
   GET https://dev36661.service-now.com/api/now/attachment, params = {"sysparm_query":"table_name=sysapproval_approver"}

3. PUT requests are used to modify the table data following approve and reject actions. The service-now connector uses PUT requests to modify the "state" key when any action is taken, and the "comments" key when a reject reason or comment was provided by the user. For more details click here.

Here is an example of how the Capriza ApproveSimple Service-Now connector updates the table data when the user has taken an approve action on an approval request whose id is "00e9c07adba52200a6a2b31be0b8f5ae":
PUT: https://dev36661.service-now.com/api/now/table/sysapproval_approver/00e9c07adba52200a6a2b31be0b8f5ae, data = {"state":"approved"}

Config.json (resources/config.json) Parameters

The BlConfig object of Config.json (resources/config.json) defines three mandatory parameters and several optional parameters:

Required	Param Name and Type	Description
Yes	TableName String	The name of the table from which approvals are fetched e.g: sysapproval_approver, sc_ic_aprvl_type_defn_staging etc. The correct value should be in the file that you download as part of the configuration, and therefore should not be changed. It should be the name of the table in which all the approvals exist.
Yes	useCaseNames Array of Objects	This array of objects contains the use cases your connector will treat, for example: change_request, std_change_proposal, sc_req_item etc. NOTE: .. Each object has two properties: name(String) and sourceTable(Boolean). The name property is required. The default value of sourceTable is true. If sourceTable is true, the use case uses the approvalsTable value. If sourceTable is false, the use case uses the table whose name is the same as the usecase.name property. So in the example below -.[Example of Using Table other than Approvals Table for a use case ()] - the sc_request use case uses the sc_request table, while the change_request use case uses the sysapproval_approver table which is the approvalsTable value.
No	additionalTables Array of Objects	This property lets you add extra data from tables that are not related to the main source table (tableName), for example - a conflict table. Note: useCaseLabels are inserted under the each additionalTables key (useCase) in the same manner that useCaseLabels are inserted under the main tableName. You can add several tables under each useCase. for request item variables: if you wants to get the item variables (list of variables), add: tableName: sc_item_option_mtom table, primaryKey: request_item. if the variable type is 'Reference' and you want to fetch the reference table for each item, mark getReferenceTable: true. for specify the reference table field, use referenceTableMap. the default value for case you didn't define the reference table is "name". for full example view the config.json
No	additionSysparmQuery String	addition system parm query, for example: additionSysparmQuery: "^approver.email=[e-mail]"
No	userAuthentication Boolean	For making approval actions (approve/reject) via the current AS user credentials. if userAuthentication set to false, then the approval actions is done by the integration user.
No	maxApprovals Integer	Maximum number of approval requests per fetch.
No	delegate Boolean	If true, the connector will check if there are relevant (to current date) delegated approvals in the system. If there are, the connector will duplicate the approvals to the delegated approver.
No	maxCurrentRequests Integer	The maximum number of http: requests that the connector can send at one time. The number should prevent overloading the ServiceNow server. The default value (and recommended value) is 10. If you receive error code 429 from Service-Now, decrease maxCurrentRequests.
No	optimizedFetch Boolean	When true only fetches the changes in the last modified approvals and only the changes in them. By default, the Fetch is optimized. To avoid optimized Fetch, set this parameter to false.
No	fetchApprovalsByManager Boolean	When true, the fetch function fetches only the specific pending approval requests directed to the users registered in Capriza. When false, the fetch will return all pending approvals, regardless of whether they are directed at ApproveSimple users or not.
No	Pagination Boolean	When true, pending approvals are separated into multi-requests any of which does not exceed the bulksize parameter. When false, all pending approvals are pulled in one http request.
No	authenticationMethod Object	Object that has two properties: type (String) and data (object). type can be: custom/credentials/onbehalf, credentials is the defualt.

Connector actions:

The connector has three methods in order to make actions (approve and reject):

1. Action on behalf - using the integration user to perform actions. making approval actions (approve/reject) via the integration user. Note that this requires admin permissions.

Example:

 "authenticationMethod": {"type": "onbehalf"}

2. Action using the approver credentials. making approval actions (approve/reject) via the AS user.

Example:

 "authenticationMethod": {"type": "credentials"}

3. Execute script that does the actions for us - this means that the script is already set up in the system. the connector invoke the script.
   This data defines how an action script can be executed by remote. Note: To use this parameter, you must create the script and store it in your ServiceNow system.

Example:

 "authenticationMethod": {
      "type": "custom",
      "data": {
        "apiAbsoluteUrlPath": "YOUR_FULL_PATH_SCRIPT_URL",
        "httpMethod": "POST",
        "body": {
          "approvalRecId": null,
          "userId": null,
          "comments": null,
          "action": null
        }
      }
    }

Further Reading

For more info about creating Capriza Connectors and the files mentioned above, see: Capriza Connector SDK

For more info about how Capriza Connectors are created and configured, see also Capriza Connector SDK - Connector Creation Steps

For more info about how Capriza Connectors are created and configured, see: Capriza Connector SDK (github) and [Capriza Connector SDK - Connector Creation Steps] (https://docs.approvesimple.com/v1.2/docs/connector-creation-steps-general)