Nav

ServiceNow Connector 5.x

Introduction

The ServiceNow Connector facilitates connections between Mule integration and ServiceNow applications. The ServiceNow Connector v5 allows you to perform seven standard operations (insert, update, get, getKeys, getRecords, deleteMultiple, deleteRecord) on standard as well as the custom ServiceNow tables, along with any operations available through the installed plugins.

MuleSoft maintains this connector under the Select support policy.

Prerequisites

This document assumes that you are familiar with Mule, Anypoint Connectors, and the Anypoint Studio interface. To increase your familiarity with Studio, consider completing one or more Anypoint Studio Tutorials. Further, this page assumes that you have a basic understanding of Mule flows and Global Elements in Mule.

This document describes implementation examples within the context of Anypoint Studio, Mule runtime’s graphical user interface, and, also includes configuration details for doing the same in the XML Editor.

Compatibility

The latest version of the ServiceNow connector, presently v5.3.0 released September 2016, is compatible with:

Application/Service Version

Mule Runtime

3.7.0 or later

ServiceNow

Eureka, Fuji, Geneva and Helsinki

The ServiceNow connector has been tested with the Eureka, Fuji, Geneva and Helsinki versions of ServiceNow. It may work with other versions of ServiceNow as well, but the compatibility of the connector with another version has not been tested. The connector is not compatible with Mule runtimes prior to 3.7.

Installing and Configuring

Installing

You can install a connector in Anypoint Studio using the instructions in Installing a Connector from Anypoint Exchange.

However, to use the ServiceNow connector v5 in a production environment, you must have an Enterprise license to use Mule. Contact the MuleSoft Sales Team to obtain either of these. (Read more about Installing an Enterprise License.)

Creating a New Project

To use the ServiceNow connector in a Mule application project:

  1. In Studio, select File > New > Mule Project.

    filenew

  2. Enter a name for your new project and leave the remaining options with their default values.

  3. If you plan to use Git, select Create a .gitignore file for the project with default ignore settings for Studio Projects, and then click Next.

  4. Click Finish to create the project.

Configuring the Global Element

To use the ServiceNow Connector in your Mule application, you must configure a global ServiceNow element that can be used by all the ServiceNow connectors in the application (read more about global elements). The ServiceNow connector supports a simple configuration and an advanced configuration.

Authentication

ServiceNow API relies on HTTP Basic authentication which is the default authentication system to make an HTTP request. The HTTP Request configuration establishes various properties for the HTTP connection: socket properties, proxy settings and even various authentication mechanisms. This simple configuration assumes a default HTTP request configuration. If a different authentication strategy is employed, it can be configured within the advanced configuration of the connector.

Timeout

Using the advance configuration, connection settings like 'Connection Idle Timeout' and 'Response Timeout' can also be configured. You can configure them by modifying 'HTTP Request Configuration' global element that you choose for 'HTTP Request Config'.

Follow these steps to create a ServiceNow global element:

  1. Click the Global Elements tab at the base of the canvas.

  2. On the Global Mule Configuration Elements screen, click Create.

  3. In the Choose Global Type wizard, expand Connector Configuration, and click ServiceNow: Advanced or ServiceNow: Basic, depending on your ServiceNow implementation.

    servicenow-choose-global-type

  4. Click OK

  5. Enter the global element properties:

    1. For ServiceNow Connector: Basic Configuration:

      servicenow-config

      Field Description

      Name

      Enter a name for the configuration so it can be referenced later.

      Username

      Username for connecting to the ServiceNow instance

      Password

      Password to log into the ServiceNow instance

      Service Address

      The URL of the ServiceNow instance. Format: https://<instancename>.service-now.com

      ServiceNow Version

      Select the version of your ServiceNow instance.

      User tables List

      • None - DataSense does not fetch any user (or custom) tables.

      • Create Object manually - A user creates a list and adds the table names to the list - only those user (or custom) tables are acquired by DataSense.

      ServiceNow allows their users to create Custom tables/Views. In order to access these tables use the User Table List Field as described above.
      In the image above, the placeholder values refer to a configuration file placed in the src folder of your project (Learn how to configure properties). You can either enter your credentials into the global configuration properties, or reference a configuration file that contains these values. For simpler maintenance and better re-usability of your project, Mule recommends that you use a configuration file. Keeping these values in a separate file is useful if you need to deploy to different environments, such as production, development, and QA, where your access credentials differ. See Deploying to Multiple Environments for instructions on how to manage this.
  6. For ServiceNow Connector: Advanced Configuration:

    servicenow-advanced-config

    Field Description

    Name

    Enter a name for the configuration.

    HTTP Request Config

    Enter an HTTP Request configuration.

    Service Address

    The URL of the ServiceNow instance. Format: https://<instancename>.service-now.com

    ServiceNow Version

    Select the version of your ServiceNow instance.

    User Table List

    • None - DataSense does not fetch any user tables.

    • Create Object manually - A user creates a list and adds the table names to the list - only those user tables are acquired by DataSense.

    servicenow-advanced-basic-auth

  7. Create the HTTP Request Config object. Provide the ServiceNow username and password in the Authentication tab after selecting "Basic" from the Protocol dropdown.

  8. Keep the default values in the Pooling Profile and the Reconnection tabs.

  9. Click Validate Config to confirm that the parameters of your global ServiceNow connector are accurate, and that Mule is able to successfully connect to your instance of ServiceNow. Read more about Testing Connections.

  10. Click OK to save the global connector configurations.

XML Code for Example

To configure the ServiceNow global element:

  1. Ensure you have included the following namespaces in your configuration file:

    
                
             
    1
    2
    
    http://www.mulesoft.org/schema/mule/servicenow
    http://www.mulesoft.org/schema/mule/servicenow/current/mule-servicenow.xsd
  2. Create a global ServiceNow configuration outside and above your flows, using the following global configuration code:

    
                
             
    1
    
    <servicenow:config name="ServiceNow_Connector__configuration" username="${servicenow.username}" password="${servicenow.password}" serviceAddress="${servicenow.serviceEndpoint}" doc:name="ServiceNow Connector: configuration">
    Attribute Description

    name

    Enter a name for the configuration with which to reference it.

    username

    Username for connecting to your ServiceNow instance.

    password

    The corresponding password.

    serviceAddress

    The URL of the ServiceNow instance. Format: https://<instancename>.service-now.com

Using the Connector

ServiceNow connector is an operation-based connector, which means that when you add the connector to your flow, you need to configure a specific operation (Invoke operation) for the connector to perform. The XML element for the Invoke operation is servicenow-wsdl:invoke. After you call the Invoke operation, you can use the "Table" and "Operation" fields to select a method you want to execute on a particular ServiceNow table. The ServiceNow connector v5 allows you to perform seven standard operations (insert, update, get, getKeys, getRecords, deleteMultiple, deleteRecord) on the standard as well as custom ServiceNow tables, along with any operations available through the installed plugins.

Use Cases

Below are a few common use cases for the ServiceNow connector:

  • Get Records from the Incident table.

  • Get Keys from the Incident table.

  • Update Incident table using DataWeave language.

Adding the ServiceNow Connector to a Flow

  1. Create a new Mule project in Anypoint Studio.

  2. Drag the ServiceNow Connector onto the canvas, then select it to open the properties editor.

  3. Configure the connector’s parameters:

    servicenow-getkeys-config

    Field

    Description

    Display Name

    Enter a unique label for the connector in your application.

    Connector Configuration

    Select a global ServiceNow connector element from the dropdown.

    Operation

    Invoke

    Table

    Select a ServiceNow table from the dropdown.

    Operation

    Select the operation to perform on the table your select.

  4. Save your configurations.

Example Use Case - Get ServiceNow Incident Table Keys

See additional examples at this ServiceNow connector resource page.

Create a Mule flow to get keys from the Incident table in your ServiceNow instance.

servicenow-getkeys-flow

  1. Create a Mule project in your Anypoint Studio.

  2. Drag an HTTP connector into the canvas, then select it to open the properties editor console.

  3. Add a new HTTP Listener Configuration global element:

    1. In Connector Configuration, click the green plus button (+):

      servicenow-http-conn-cfg

    2. Configure the following HTTP parameters:

      servicenow-http-listener-cfg

      Field Value

      Port

      8081

      Host

      localhost

      Display Name

      HTTP_Listener_Configuration

    3. Reference the HTTP Listener Configuration global element:

      servicenow_get

  4. Add a Set Payload transformer after the HTTP connector, and configure it as follows:

    Field Value

    Display Name

    Enter a name of your choice.

    Value

    #[['description': 'Get Keys Demo']]

  5. Drag a ServiceNow connector into the flow to create a ServiceNow user with the message payload.

  6. If you haven’t already created a ServiceNow global element, add one by clicking the plus sign next to the Connector Configuration field. Select ServiceNow: Basic Configuration and click OK.

  7. Configure the global element:

    servicenow-config

    Field Description

    Name

    Enter a unique label for this global element to be referenced by connectors in the flow.

    Username

    Enter a Username for connecting to the ServiceNow instance.

    Password

    Enter the user password.

    ServiceNow Address

    Enter the URL of your ServiceNow server.
    The format of the ServiceNow URL is: https://<instancename>.service-now.com

  8. Click Validate Config to confirm that Mule can connect with your ServiceNow instance. If the connection is successful, click OK to save the configurations of the global element. If unsuccessful, revise or correct any incorrect parameters, then test again.

  9. Back in the properties editor of the ServiceNow connector, configure the remaining parameters:

    servicenow-getkeys-config

    Field Value

    Display Name

    ServiceNow - GetKeys (or any other name you prefer)

    Config Reference

    Enter name of the global element you have created

    Operation

    Invoke

    Table

    Incident

    Operation

    getKeys

  10. Drag a DataWeave transformer between the Set Payload transformer and the ServiceNow connector, then configure it as follows:

    servicenow-dw-keys

  11. The Output properties are automatically configured to correspond to the ServiceNow connector’s input properties.

  12. Add an XML to JSON transformer.

  13. Save and run the project as a Mule Application.

  14. From a browser, navigate to http://localhost:8081/incident/get

  15. Mule performs the query to get keys from the Incident table and displays them in the browser.

For this code to work in Anypoint Studio, you must provide the credentials for the ServiceNow instance. You can either replace the variables with their values in the code, or you can add a file named mule.properties to the src/main/properties folder to provide the values for each variable.

         
      
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:http="http://www.mulesoft.org/schema/mule/http" xmlns:data-mapper="http://www.mulesoft.org/schema/mule/ee/data-mapper" xmlns:servicenow="http://www.mulesoft.org/schema/mule/servicenow" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation" xmlns:spring="http://www.springframework.org/schema/beans" xmlns:core="http://www.mulesoft.org/schema/mule/core"  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/ee/data-mapper http://www.mulesoft.org/schema/mule/ee/data-mapper/current/mule-data-mapper.xsd
http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/servicenow http://www.mulesoft.org/schema/mule/servicenow/current/mule-servicenow.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd">
 <http:listener-config name="HTTP_Listener_Configuration" host="0.0.0.0" port="8081" basePath="/incident" doc:name="HTTP Listener Configuration"/>
 <servicenow:config name="ServiceNow_Connector_configuration" username="${servicenow.username}" password="${servicenow.password}" serviceAddress="${servicenow.serviceEndpoint}" doc:name="ServiceNow Connector: configuration">
 <servicenow:list-of-user-table>
 </servicenow:list-of-user-table>
 </servicenow:config>

<data-mapper:config name="Map_To_Xml_insert_" transformationGraphPath="map_to_xml_insert_.grf" doc:name="Map_To_Xml_insert_"/>

 <data-mapper:config name="Xml_getKeysResponse_To_JSON" transformationGraphPath="xml_getkeysresponse_to_json.grf" doc:name="Xml_getKeysResponse_To_JSON"/>

<flow name="demo-getkeys-incident">
 <http:listener config-ref="HTTP_Listener_Configuration" path="/getkeys" doc:name="/getkeys"/>
 <set-payload value="#[['description':'TESTWSDLQA']]" doc:name="Set Payload"/>
 <data-mapper:transform config-ref="Map_To_Xml_getKeys_" doc:name="Map To Xml&lt;getKeys&gt;"/>
 <logger message="#[payload]" level="INFO" doc:name="Logger"/>
 <servicenow:invoke config-ref="ServiceNow_Connector_configuration" type="incident||getKeys" doc:name="ServiceNow - GetKeys"/>
 <logger message="#[payload]" level="INFO" doc:name="Logger"/>
 <data-mapper:transform config-ref="Xml_getKeysResponse_To_JSON" doc:name="Xml&lt;getKeysResponse&gt; To JSON"/>
 </flow>

</mule>

Example Use Case - Get Records from ServiceNow Incident Table

Create a Mule flow to get records from the Incident table.

servicenow 84375

  1. Create a Mule project in your Anypoint Studio.

  2. Drag an HTTP connector into the canvas, then select it to open the properties editor console.

  3. Create a new HTTP Listener Configuration global element by clicking the green plus sign +:

  4. Configure the following HTTP path as getrecords:

  5. Add a Set Payload transformer after the HTTP connector, and configure it as follows:

    Field Value

    Display Name

    Enter a name of your choice.

    Value

    #[['description': 'Get Records Demo']]

  6. Drag a ServiceNow connector into the flow to create a ServiceNow user with the message payload.

  7. If you haven’t already created a ServiceNow global element, add one by clicking the plus sign next to the Connector Configuration field of the ServiceNow element and select ServiceNow: Basic Configuration. Click OK.

  8. Configure the global element with the Username, Password and Service Address, selecting the appropriate version of ServiceNow as well.

    Field Description

    Name

    Enter a unique label for this global element to be referenced by connectors in the flow.

    Username

    Enter a Username for connecting to the ServiceNow instance.

    Password

    Enter the user password.

    ServiceNow Address

    Enter the URL of your ServiceNow server.
    The format of the ServiceNow URL is: https://<instancename>.service-now.com

  9. Click Validate Config to confirm that Mule can connect with your ServiceNow instance. If the connection is successful, click OK to save the configurations of the global element. If unsuccessful, revise or correct any incorrect parameters, then test again.

  10. Back in the properties editor of the ServiceNow connector, configure the remaining parameters:

    servicenow-get-records-configuration

    Field Value

    Display Name

    getRecords (or any other name you prefer).

    Config Reference

    Enter the name of the global element you have created.

    Operation

    Invoke

    Table

    Incident

    Operation

    getRecords

  11. Drag a DataWeave element between the Set Payload transformer and the ServiceNow connector, then configure it as follows:

    servicenow-dw-records

  12. The Output properties are automatically configured to correspond to the ServiceNow connector’s input properties.

  13. Add a Logger component and an XML to JSON transformer after the ServiceNow connector.

  14. Save and Run as Mule Application.

  15. From a browser, navigate to http://localhost:8081/incident/getrecords

  16. Mule performs the query to retrieve records from the Incident table and displays the response in the browser.

XML Code for Example


          
       
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns:json="http://www.mulesoft.org/schema/mule/json" xmlns:dw="http://www.mulesoft.org/schema/mule/ee/dw" xmlns:data-mapper="http://www.mulesoft.org/schema/mule/ee/data-mapper"
        xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:http="http://www.mulesoft.org/schema/mule/http" xmlns:datamapper="http://www.mulesoft.org/schema/mule/ee/data-mapper" xmlns:servicenow="http://www.mulesoft.org/schema/mule/servicenow" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation" xmlns:spring="http://www.springframework.org/schema/beans" xmlns:core="http://www.mulesoft.org/schema/mule/core"  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/servicenow http://www.mulesoft.org/schema/mule/servicenow/current/mule-servicenow.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/ee/dw http://www.mulesoft.org/schema/mule/ee/dw/current/dw.xsd
http://www.mulesoft.org/schema/mule/json http://www.mulesoft.org/schema/mule/json/current/mule-json.xsd">
 <http:listener-config name="HTTP_Listener_Configuration" host="0.0.0.0" port="8081" basePath="/incident" doc:name="HTTP Listener Configuration"/>
 <servicenow:config name="ServiceNow_Connector_configuration" username="${servicenow.username}" password="${servicenow.password}" serviceAddress="${servicenow.serviceEndpoint}" doc:name="ServiceNow Connector: configuration">
 </servicenow:config>
<flow name="demo-getrecords-incident">
 <http:listener config-ref="HTTP_Listener_Configuration" path="/getrecords" doc:name="/getrecords"/>
        <set-payload value="#[['description':'TESTWSDLQA']]" doc:name="Set Payload"/>
        <dw:transform-message doc:name="Transform Message">
            <dw:set-payload><![CDATA[%dw 1.0
%output application/xml
%namespace ns0 http://www.service-now.com/incident
---
{
        ns0#getRecords: payload.description
}]]></dw:set-payload>
        </dw:transform-message>
 <servicenow:invoke config-ref="ServiceNow_Connector_configuration" type="incident||getRecords" doc:name="ServiceNow - GetRecords"/>
 <logger message="#[payload]" level="INFO" doc:name="Logger"/>
        <json:xml-to-json-transformer doc:name="XML to JSON"/>
 </flow>
 </mule>

See Also