Introduction

The Neuron ESB ServiceNow Adapter provides access to an instance of ServiceNow.  Using this adapter, organizations can easily integrate their business applications such as SAP, NetSuite or Marketo with ServiceNow.  This adapter operates in both subscribe as well as solicit/response (or query) mode.  When developing applications that utilize this adapter, developers will be able to use the Adapter Metadata Generation Wizard to provide JSON and Swagger samples that describe the request and/or response documents that are exchanged with ServiceNow.

Before reading this document

If you are not familiar with Neuron ESB Adapters, take a moment to consult our online help: https://neuronesb.com/neuron/Help3/Development/Developing_Neuron_Applications/Connecting_to_External_Systems/Adapters/adapters.htm. This document assumes you have the following knowledge:

  1. What adapters are and how they are leveraged in Neuron ESB
  2. Create an Adapter Endpoint in a Neuron ESB Solution
  3. Set Neuron ESB Adapter Endpoint Properties
  4. Invoke a Neuron ESB Adapter Endpoint

Supported Modes

The ServiceNow Adapter supports Subscribe mode, which is used to push data to ServiceNow, and Solicit Response mode which is used to request data from ServiceNow (think query).

ServiceNow Adapter Properties

Every Neuron ESB Adapter has design time properties that can configured within a standard Microsoft property grid (as shown below). These properties are used to determine the behavior of the adapter at runtime.  The group of Connection properties is used to configure the ServiceNow Endpoint URL, along with the security credentials used when sending requests to ServiceNow.

Endpoint URL

The URL for the ServiceNow instance to connect to.  The endpoint URL is made up of two parts – the URL of your ServiceNow instance + “/api/now”.  For example:

https://dev50004.service-now.com/api/now

When making calls to ServiceNow, you will programmatically provide the remainder of the URL, referred to as the local path and query parameters.  In this tutorial you will retrieve a list of departments.  To do that you will set the local path to “table/cmn_department”.

The URLs used by the adapter are the same URLs that would be used for calling the ServiceNow REST API directly.  You can find more information regarding the ServiceNow REST API and the URL formats in the ServiceNow REST API documentation:

https://developer.servicenow.com/app.do#!/rest_api_doc

Security Method

The ServiceNow adapter supports both OAUTH and Basic (Username / Password) authentication with the ServiceNow instance.

When using OAUTH you will need to reference an OAUTH Credential created in the OAUTH section under the security tab of the Neuron ESB Explorer. If you are unfamiliar with how to create and OAUTH provider in the Neuron ESB Explorer please read the following article:

https://www.neuronesb.com/article/introducing-oauth-support/

Selecting the Basic security option allows you to use either a stored Username / Password Credential or enter the Username / Password directly into the Connection properties. If you need more information about creating a stored Username / Password credential please read the following document:

https://www.neuronesb.com/neuron/Help3/Neuron.htm

Note – Choosing to use a stored credential will not populate the username or password fields. However, these do not need to be filled in if a stored credential has been selected.

Proxy Server

Allows you connect to ServiceNow via a proxy server. By default this value is set to System Default. Changing the value to custom will expose additional properties:

  • Address – The URL address to the proxy server
  • Port – The port for the proxy server address
  • Use Custom Credentials – By default this is set to false and will use the credentials that the Neuron ESB instance is running under. Changing this value to True will allow you to select a stored credential from Neuron ESB.

Using the ServiceNow Adapter

When making calls to ServiceNow using the adapter, creating the request messages can be done in many different ways.  You can use a C# or C# Class step in a process or workflow.  You can also use the JSON step to transform XML into JSON that ServiceNow will accept.  This document focuses on creating the requests with a C# step in a process.

Security

As noted previously, the adapter supports using Username / Password credentials when calling the ServiceNow Endpoint URL.  The adapter handles all the security requirements at runtime.  When you’re constructing a request message to send to ServiceNow you do not need to worry about setting credentials.

Walk-through: Creating an Adapter Endpoint

This walkthrough has the following requirements:

  • A ServiceNow account. For a free ServiceNow Developer Account, sign-up here:

https://developer.servicenow.com

  • An instance of ServiceNow. If you are using a ServiceNow Developer Account, you can request a new instance of ServiceNow from the Developer Portal.
  • Neuron ESB 3.6 or later installed
  • A new Neuron Configuration with the following items already created:
    • 1 Topic – Department
    • 1 Subscriber – Department Subscriber
    • 1 Publisher – Department Publisher
  • The Neuron ESB runtime is configured and started with the above solution
  1. Navigate to Connections->Adapter Endpoints and click New. Set the name of the adapter endpoint to ServiceNow Table Endpoint, select ServiceNow from the Adapter drop-down list, select Solicit Response from the Mode drop-down list and select Department Subscriber from the Party ID drop-down list:

  1. Click on the Properties tab. Enter the ServiceNow Endpoint URL for the ServiceNow Instance to connect to. Select Basic as the Security method and enter in the username and password for the ServiceNow instance. Click Apply:

In the next walk-through, you will use this adapter endpoint in the Metadata Generation Wizard to retrieve the Swagger document and sample JSON messages.

Request and Response Message Formats

The ServiceNow adapter only supports JSON content for request and response messages.  The request and response message formats depends on the service operation being called.  You can retrieve request and response JSON samples, using the Metadata Generation Wizard described below.

Dynamic Message Properties

The ServiceNow adapter supports the same message properties as a REST-based Service Connector.

These properties are used to dynamically set values for request messages sent to ServiceNow:

  • LocalPath – Used to provide the path to the resource (appended to the URL set in the adapter endpoint property grid)
  • Method – The Http Method to call, i.e. GET, POST, etc
  • Query – Used when adding a query string to the URL being called
  • Headers – Sets the request headers sent to ServiceNow with the request, such as ContentType.

These properties are applied to responses from ServiceNow when using the adapter in Solicit Response mode:

  • Headers – Contains the Http headers returned with the response message
  • StatusCode – Response status code
  • StatusDescription – Response status description

Walk-through: Using the Metadata Generation Wizard

The Metadata Generation Wizard is a tool that is used to generate sample messages and schema definitions for certain adapters and their operations.  The Metadata Generation Wizard can be used to generate sample JSON request and response messages for the ServiceNow Adapter, as well as create the Swagger document associated with the REST operation.  The following guide assumes you have already completed the first walk-though – Creating an Adapter Endpoint.

  1. First, in Neuron ESB Explorer navigate to Repository->JSON Documents:

2. Next, click the Generate button:

The Generate button can be accessed from any of the following menus:

In the “Repository” tab in:

XML Schemas

XML Documents

Json Documents

In the Connections tab in:

Adapter Registration

Adapter Endpoints

3. On the Welcome Page, click Next:

4. On the Connect to Data Source page choose an adapter and adapter endpoint. In this case, choose ServiceNow and the adapter endpoint created in the first walk-through.  Click Next:

5. For the ServiceNow adapter, the Category represents all the APIs that are available at the Endpoint URL that was set in the adapter endpoint. Expand an API (i.e. Table API), select a table (i.e. Departments) and then select the Operation (i.e Retrieve a Record) you want to perform and add them to the list of Chosen Operations by clicking the Add  More than one operation can be added by choosing each operation and adding it to the list.  Click Next:

6. Choose whether or not to overwrite the JSON documents, if they have already been added, by clicking on the appropriate boxes. Click Next:

7. Finally, click Finish to generate the documents:

To see the sample request and response messages, navigate to the JSON Documents Repository and select a document.  This is an example of a JSON document:

{
  "result": [
  {
    "company": {
      "link": "asdf",
      "value": "asdf"
    },
    "cost_center": {
      "link": "asdf",
      "value": "asdf"
    },
    "dept_head": {
      "link": "asdf",
      "value": "asdf"
    },
    "description": "asdf",
    "head_count": "0",
    "id": "asdf",
    "name": "asdf",
    "parent": {
      "link": "asdf",
      "value": "asdf"
    },
    "primary_contact": {
      "link": "asdf",
      "value": "asdf"
    },
    "sys_created_by": "asdf",
    "sys_created_on": "2018-06-04 11:07:19",
    "sys_id": "dad3340564154b239b5e1315427abf19",
    "sys_mod_count": "0",
    "sys_updated_by": "asdf",
    "sys_updated_on": "2018-06-04 11:07:19"
  }
  ]
}

Walk-through: Testing the ServiceNow Adapter

This walk-through will show you how to test the ServiceNow Adapter at runtime.  This assumes you completed the previous walk-throughs and the Neuron ESB Service is configured to host the Neuron configuration you’ve been working on.

  1. Navigate to Processes in the Neuron ESB Explorer

  1. Click the New drop down and select Create Process

 

  1. Click on the UI element named New Process 1 and in the Property Grid on the right hand side of the Neuron ESB Explorer enter “Get Departments” in the Name text field.

  1. In the Search Steps text field of the Process Step Library enter “Http”

  1. Drag an Http Client Utility process step on to the design canvas and drop it in the middle of the UI element labeled “Get Departments”.
  2. Right-click on the UI element named “Http Client Utility” and select “Configure”. The Http Client Utility editor will open:
  3. Set the Method drop-down list to GET and the path to table/cmn_department. Click on the Body tab and check the box for “Clear ESB Message Body”:

8. Click the Save button to close the editor.

9. Click the Apply button to save the “Get Departments” business process.

10. Navigate to Messaging

11. Click on Publishers

  1. Click on the Department Publisher
  2. In the Publisher Property Grid that opens at the bottom of the Neuron ESB Explorer, click on the Processes

  1. Click Edit Processes to launch the Processes dialog window.

  1. Select the “Get Departments” process and move it to the Selected Processes using the right arrows.

  1. Click OK
  2. Apply your changes to the DepartmentPublisher
  3. Save the Neuron ESB Configuration.
  4. Open a Neuron Test Client by clicking on the Test Client icon in the Neuron ESB Toolbar and select 1 Test Client:

  1. When the Neuron Test Client open, select Department Publisher from the Party Id drop-down list and click the Connect button:

  1. In the Neuron Test Client, click on the send tab. Set the Semantic to Request

 

  1. Click the Send button. If everything works correctly, you should see the Recv: counter at the bottom of the Test Client increase by one.  Navigate to he Receive tab to see the response message: