Generic connector for Service Now

The connector use Service Now REST API.

For testing the connector you can create free DEMO account, just add your demo system credentials.

The repository contains example of config.json, transformer.js and ui-templates.json for change request and service request use cases.

For more info about: Capriza Connector SDK

Getting Started

These instructions will get you a copy of Capriza connector on your local machine for development and testing purposes.

Prerequisites

Clone the repository

git clone https://github.com/capriza/ServiceNow-Connector.git 

Add your service now credentials (if you don't have one you can create demo system and use it) to systemConfig.json:

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

Installing

Install the connector

npm install

Run Capriza test tool (inspector)

npm run inspector

Open your browser on http://localhost:8080/

How the connector works?

The connector use 3 main requests:

1. GET request = for fetch data - more details here. For example to get approval data for approval id="0349403adba52200a6a2b31be0b8f509": GET https://dev36661.service-now.com/api/now/table/sysapproval_approver, params = {"sysparm_query":"sys_id=0349403adba52200a6a2b31be0b8f509^state=requested"} For example to get all the pending approvals: 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 request = for get attachment data - more details here. For example: get all the attachments (id's) in sysapproval_approver table: GET https://dev36661.service-now.com/api/now/attachment, params = {"sysparm_query":"table_name=sysapproval_approver"}

3. PUT request = to make actions (approve, reject) for changing tables data (in our case the "state" key and the "comments" key for reject reason) - more details here. For example, to make approve action to approval id ="00e9c07adba52200a6a2b31be0b8f5ae": PUT https://dev36661.service-now.com/api/now/table/sysapproval_approver/00e9c07adba52200a6a2b31be0b8f5ae, data = {"state":"approved"}

The utils.js file contain 3 method that wrap the requests to servece-now:

• snGet(instanceName, username, password, api,tableName, params, logger)

• snPut(instanceName, username, password, api, tableName, sysId, data, logger)

• downloadUrlAttachment(username, password, url, mediaType, logger)

config file (resources/config.json):

There are 3 important params:

1. tableName -> The table you want to fetch the approvals e.g: sysapproval_approver, sc_ic_aprvl_type_defn_staging etc...That value not suppose to be changed (all the approvals exist in sysapproval_approver table)

2. useCaseNames -> Array of objects what use cases you want e.g: change_request, std_change_proposal, sc_req_item etc.. every object Consists of 2 properties: name(String) and sourceTable(Boolean), the name property is most, the default value of sourceTable is true. if you set sourceTable to false then it means that you use in usecase that doesn't have 'regular' source table (this use for customize tables in the system).

3. useCaseLabels -> object of key(usecase name) value (array of Strings), the array value include the fields you want the connector will fetch, pay attention, you can ask from x levels of tables. e.g: state, sys_id, document_id.number, document_id.conflict_status etc.

4. Optional param: additionalTables -> If you want to add extra data from different table that not relate to the tableName above, e.g: conflict table. Pay attention, you also need to add your useCaseLabels (just like you add in the main tableName). You can add several tables (it's array, see example below).

5. Optional param: maxApprovals - number for maximum approvals to fetch.

6. Optional param: delegate - if that flag is on, the connector will also check if exist delegate approvals in the system (that relevant to the current date) - if exist the connector will duplicate the approvals to the approver delegate.

7. Optional param: maxConcurrentRequests - In order to avoid overloading the SN server, we limit the maximum number of requests from the connector. It is advisable not to give too high value. A default value is 10. use it of you get 429

8. Optional param: optimizedFetch - This is for optimized the fetch (instead of fetch all the pending approvals, it scan the last modified approvals and fetch only the changes. the default fetched is optimized if you want to avoid optimized logic - set it to false)

for using other use cases(service request, requested item, catalog task, change task etc...), you need to add the usecase name in the config.json, and add the data to: transformer.js and ui-templates.json.

{
  "caprizaConfig": "resources/caprizaConfig.json",
  "systemConfig": "resources/systemConfig.json",
  "controllerConfig": {},
  "blConfig": {
    "tableName": "SOME_TABLE_NAME",
    "useCaseName": "ARRAY_OF_APPROVALS_USE_CASE",
    "useCaseLabels": "ARRAY_OF_LABELS_THAT_WILL_BE_RETURNED",
    "additionalTables": "IF_YOU_WANT_TO_ADD_MORE_TABLES"
	"additionalTables": "IF_YOU_WANT_TO_ADD_MORE_TABLES"
  }
}

Example of config file:

{
  "caprizaConfig": "resources/caprizaConfig.json",
  "systemConfig": "resources/systemConfig.json",
  "controllerConfig": {},
  "blConfig": {
    "tableName": "sysapproval_approver",
    "useCaseNames": [
      {
        "name": "sc_request",
        "sourceTable": true
      },
      {
        "name": "change_request",
        "sourceTable": true
      }
    ],
    "useCaseLabels": {
      "sc_request": [
        "sys_updated_on",
        "document_id.sys_class_name",
        "sys_id",
        "document_id.sys_id",
        "approver.email",
        "approver.name",
        "approver.sys_id",
        "sysapproval.number",
        "document_id.price",
        "document_id.requested_for.name",
        "document_id.priority",
        "comments",
        "document_id.description",
        "document_id.short_description",
        "document_id.opened_by.name",
        "document_id.due_date",
        "document_id.opened_at",
        "document_id.cmdb_ci.name"
      ],
      "change_request": [
        "sys_updated_on",
        "document_id.sys_class_name",
        "sys_id",
        "document_id.sys_id",
        "approver.email",
        "approver.name",
        "approver.sys_id",
        "sysapproval.number",
        "document_id.cmdb_ci.name",
        "document_id.requested_by.name",
        "document_id.priority",
        "document_id.short_description",
        "document_id.state",
        "document_id.risk",
        "document_id.impact",
        "document_id.start_date",
        "document_id.end_date",
        "document_id.description",
        "document_id.category",
        "document_id.assignment_group.name",
        "document_id.assigned_to.name",
        "document_id.justification",
        "document_id.implementation_plan",
        "document_id.risk_impact_analysis",
        "document_id.backout_plan",
        "document_id.test_plan",
        "comments"
      ]
    },
    "additionalTables": {
      "Request": [
        {
          "tableName": "sc_req_item",
          "primaryKey": "request",
          "useCaseLabels": [
            "price",
            "quantity",
            "sys_created_on",
            "impact",
            "active",
            "priority",
            "short_description",
            "comments",
            "due_date",
            "assigned_to",
            "cat_item.name"
          ]
        }
      ],
      "Change Request": [
        {
          "tableName": "conflict",
          "primaryKey": "change",
          "useCaseLabels": [
            "change.number",
            "change.cmdb_ci.name",
            "type",
            "schedule.name",
            "conflicting_change",
            "last_checked"
          ]
        }
      ]
    },
    "maxApprovals": 100,
    "maxConcurrentRequests": 10,
    "delegate": true,
    "optimizedFetch": true
  }
}