How to configure ServiceNow with REST for integration with ONEiO

Endpoint Setup

Here's how to set up a ServiceNow endpoint in ONEiO in a short video.

Endpoint Setup Details

You can sign up for a free trial of ONEiO from the following link: ONEiO Free Trial

Outbound from ONEiO to ServiceNow

ONEiO accesses ServiceNow with ServiceNow's Table API and Attachment API

Access from ServiceNow to ONEiO

ServiceNow accesses ONEiO with the same kind of web service call as ONEiO accesses ServiceNow. With ServiceNow concepts, this is called an outbound REST message. The following chapter explains how to configure the needed REST message definitions and business rules to trigger calling the web services when inserting and/or updating incidents in ServiceNow.

Create Integration user to ServiceNow

Add integration user to ServiceNow. This user is used to send updates and creates to ServiceNow through the Table API interface. The credentials have to match those configured to the ServiceNow adapter configuration in ONEiO, so share the credentials with ONEiO support.

  • Add user
    • username "oneio(you can choose a different name also, but remember to change it to used business rule conditions)
    • Check "web service access only"
    • Add roles: web_service_admin & itil
      • The user must also have access to the tables integrated, in this example incident and sys_attachment

Attachment handling

Sending attachments to ServiceNow

SF sends attachments to ServiceNow through the ServiceNow's Attachment API. For this operation, outbound message to ServiceNow needs to include attribute sys_id, with the target entity's sys_id as the value.

 


Inbound from ServiceNow to ONEiO

This paragraph describes the needed functions for setting up communication for Incident table. If other tables are needed to be integrated, make changes accordingly.

Download the update set

The update set contains:

  • 1 REST message
  • 5 Business Rules for following tables: incident, sc_request, change_reguest and problem.
  • 2 Business Rules for sending out attachments.

Tasks to perform after the update set is committed

  • Add outbound credentials to the REST message. These credentials can be retrieved from ONEiO UI.
  • Activate the Business Rules you want to use. Please note that you might want to add additional Filter Conditions to limit when the messages are triggered out.

 

Setup without Update Set

Update set contents

Warning

In case you choose to use the update set, you do not need to implement these functions. This section simply describes the contents of the functions inside the update set.

Create new REST Message definition

You can either create a separate REST Message for every table used in the integration, or use populate ServiceNow-table element in the REST message dynamically indifferent Business Rules. 

Navigate to "System Web Services" -> "Outbound" -> REST Message -> Create new REST Message

  • Name: "ONEiO REST Message"
  • Add an auth profile with the credentials you get from ONEiO UI
  • Open HTTP Request
    • Add HTTP Header Content-Type with value application/json
  • Add a new HTTP Method
    • Name: send
    • HTTP Method: POST
    • Endpoint:
      • test: https://rest-receiver-test.service-flow.com/api
      • production: https://rest-receiver.service-flow.com/api
    • HTTP Query Parameters

      Example Query Parameters

      {
      "ServiceNow-table": "${ServiceNow-table}",
      ${payload}
      "attachments": [${attachments}]
      }

Attachment handling

Sending attachments to ONEiO

Attachments are sent from ServiceNow to ONEiO the following way. The update REST messages from ServiceNow to ONEiO can contain attachments element that contains metadata about attachments that the incident has. The following excerpt shows example of the JSON structure:

Example of attachment XML structure
 
"attachments": [
    {
      "content_type": "image/png",
      "file_name": "Snip20180609_3.png",
      "size_bytes": "297940",
      "sys_id": "4ea99992db6a1f00811ddd3b5e961903"
    },
    {
      "content_type": "image/png",
      "file_name": "Snip20180609_4.png",
      "size_bytes": "297123",
      "sys_id": "4ea99992db6a1f00811ddd3b5e962121"
    }
  ]
 
Using this information, ONEiO then takes the sys_id of the attachment and retrieves it from ServiceNow using the ServiceNow Attachment API.

 


Triggering messages out

To send messages out from ServiceNow you need to create business rules that match the pre-defined workflows. These are usually defined in process workshops where all parties are present.

Create business rule for incident

Navigate to System Definition -> Business Rules

  • Click "New"
  • Name: "ONEiO: REST from Incident"
  • Table: "Incident [incident]"
  • When: "after"
  • Check: "update" and "insert"
  • (Condition example: current.assignment_group.name == '3rd Party Vendor' || current.correlation_id != '')
    • Copy the following example code to the Script field
Business rule for incident update
 
var exclude_from_outbound = ["comments_and_work_notes","undefined"];
var debug = false;
 
var arrayUtil = new ArrayUtil();
var requestBody;
var responseBody;
var status;
var sm;
 
gs.info("Initiating Business Rule: ONEiO - Send Incident");
 
if (current.sys_updated_by != 'oneio') {
    try{
        sm = new sn_ws.RESTMessageV2("ONEiO REST Message", "send");
        sm.setStringParameter("ServiceNow-table", current.getTableName());
        var payload ='';
        var target = new GlideRecord(current.getTableName());
        target.addQuery('number', current.number);
        target.query();
        var gru = new GlideRecordUtil();
 
        while (target.next()) {
            var fieldNames = gru.getFields(target);
            for (var i = 0; i <= fieldNames.length; i++) {
                var a = fieldNames[i].toString();
                var v = target.getValue(fieldNames[i]);
                var v_obj = target.getElement(fieldNames[i]);
                 
                if (!(arrayUtil.contains(exclude_from_outbound,a))) {
                    if (v == null) {
                        v='';
                    }else if (v_obj.name) {
                        payload += addToPayload(a+"_name", v_obj.name);
                        if (v_obj.email) {
                            payload += addToPayload(a+"_email",v_obj.email);
                        }
                    }
                    payload += addToPayload(a,v);
                }
            }
        }
         
        if (current.work_notes.changes()) {
            payload += addToPayload("work_notes", current.work_notes.getJournalEntry(1));
        }
         
        if (current.comments.changes()) {
            payload += addToPayload("comments", current.comments.getJournalEntry(1));
        }      
         
        //To add additional elements to outbound message, use the following syntax
        //payload += addToPayload("attribute_name", "attribute_value");
         
        sm.setStringParameterNoEscape("payload", payload);
 
        response = sm.execute();
        status = response.getStatusCode();
 
        if (debug){
            gs.info("Payload sent to ONEiO: " + sm.getRequestBody());
            gs.info("Response to ONEiO call: " + response.getBody());
            gs.info("Status of the ONEiO call: " + status);
        }
    } catch(ex) {
        responseBody = ex.getMessage();
        status = '500';
    } finally {
        requestBody = sm ? sm.getRequestBody():null;
    }
}
 
function addToPayload(element,value) {
    var jsonline = '';
    jsonline += '"'+ element +'":' + global.JSON.stringify(value+"") + ',\n';
    return jsonline;
}

Create business rule for triggering out attachments

Here's an example how to create a business rule that send out an attachment when it is uploaded to an incident that has an external vendor's id.

Navigate to System Definition -> Business Rules

  • Click "New"
    • Name: "ONEiO: attachment insert Incident"
    • Table: "Attachment[sys_attachment]"
    • When: "after"
    • Check: "Insert"
    • Condition: current.sys_updated_by != 'oneio'
  • Copy the following example code to the Script field

Business rule for triggering out attachments
var included_tables = ["incident","change_request","problem","sc_request"];
var debug = true;
 
var arrayUtil = new ArrayUtil();
var requestBody;
var responseBody;
var status;
var sm;
 
gs.info("Initiating Business Rule: ONEiO - Send Attachment");
 
if (current.sys_updated_by != 'oneio') {
    if (typeof GlideStringUtil != 'undefined')
        var StringUtil = GlideStringUtil;
    else
        var StringUtil = Packages.com.glide.util.StringUtil;
 
    var gr = new GlideRecord(current.table_name);
    gr.addQuery('sys_id', current.table_sys_id);
    gr.query();
 
    if (gr.next()) {
        if (arrayUtil.contains(included_tables,current.table_name) && (gr.correlation_id != '')) {
            var payload ='';
            try{
                sm = new sn_ws.RESTMessageV2("ONEiO REST Message", "send");
                payload += addToPayload("ServiceNow-table", current.table_name);
                payload += addToPayload("number", gr.number);
                payload += addToPayload("sys_id", gr.sys_id);
                payload += addToPayload("correlation_id", gr.correlation_id);
                payload += addToPayload("comments", "Attachment uploaded via ONEiO");
                payload += addToPayload("priority", gr.priority);
                 
                sm.setStringParameterNoEscape("payload", payload);
                 
                var attachmentsJson = '';
                attachmentsJson += ' { "content_type":"' + current.content_type + '",';
                attachmentsJson += '"file_name":"' + JSUtil.escapeText(current.file_name) + '",';
                attachmentsJson += '"size_bytes":"' + current.size_bytes + '",';
                attachmentsJson += '"sys_id":"' + current.sys_id + '"';
                attachmentsJson += '}';
 
                sm.setStringParameterNoEscape('attachments', attachmentsJson);
 
                response = sm.execute();
                status = response.getStatusCode();
 
            if (debug){
                    gs.info("Payload sent to ONEiO: " + sm.getRequestBody());
                    gs.info("Response to ONEiO call: " + response.getBody());
                    gs.info("Status of the ONEiO call: " + status);
            }
            } catch(ex) {
                responseBody = ex.getMessage();
                status = '500';
            } finally {
                requestBody = sm ? sm.getRequestBody():null;
            }
        }
    }
}
function addToPayload(element,value) {
    var jsonline = '';
    jsonline += '"'+ element +'":' + global.JSON.stringify(value+"") + ',\n';
    return jsonline;
}
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.