ICF 1.5.20.26

ServiceNow connector

This connector lets you manage objects in the ServiceNow platform, integrating with ServiceNow’s REST API.

Before you start

The connector requires a ServiceNow instance with OAuth enabled. You might need to activate the OAuth plugin and set the OAuth activation property if OAuth is not yet enabled on your ServiceNow instance. For more information, refer to the ServiceNow documentation that corresponds to your ServiceNow version.

When Oauth is enabled, register an OAuth client application for the connection to IDM. Take note of the client_id and client_secret of the application, as you need these values when you configure the connector.

The connector configuration must include a ServiceNow user who has the following roles:

  • admin

  • rest_api_explorer

If you do not want to give complete admin rights to this user, you can create a new role that provides access to the following tables:

  • sys_user_has_role

  • sys_user_grmember

  • sys_user_delegate

  • sys_user_role

  • sys_user_group

  • core_company

  • cmn_department

  • cmn_cost_center

  • cmn_location

Install the ServiceNow connector

If you are looking for the Advanced Identity Cloud application for this connector, refer to:

You can download any connector from Backstage, but some are included in the default deployment for Advanced Identity Cloud, IDM, or RCS. When using an included connector, you can skip installing it and move directly to configuration.

Connector included in default deployment
Connector IDM RCS

ServiceNow

Yes

No

Download the connector .jar file from Backstage.

  • If you are running the connector locally, place it in the /path/to/openidm/connectors directory, for example:

    mv ~/Downloads/servicenow-connector-1.5.20.26.jar /path/to/openidm/connectors/

  • If you are using a remote connector server (RCS), place it in the /path/to/openicf/connectors directory on the RCS.

Configure the ServiceNow connector

Create a connector configuration using the IDM admin UI:

  1. From the navigation bar, click Configure > Connectors.

  2. On the Connectors page, click New Connector.

  3. On the New Connector page, type a Connector Name.

  4. From the Connector Type drop-down list, select ServiceNow Connector - 1.5.20.26.

  5. Complete the Base Connector Details.

    For a list of all configuration properties, refer to ServiceNow Connector Configuration

  6. Click Save.

When your connector is configured correctly, the connector displays as Active in the admin UI.

Refer to this procedure to create a connector configuration over REST.

The following excerpt of connector configuration shows the required configurationProperties:

"configurationProperties" : {
    "instance" : "example.service-now.com/",
    "username" : "admin",
    "password" : {encrypted-password},
    "clientID" : "4xxxxxxxxxxxxxxxxxxxxxxxxxxxxxee",
    "clientSecret" : {encrypted-client-secret},
    "readSchema" : false
}
instance (string)

The ServiceNow instance URL; for example, example.service-now.com/.

username (string)

The name of a ServiceNow user with the admin and rest_api_explorer roles.

password (string)

The password of the ServiceNow user.

clientID (string)

The ID of your OAuth application.

clientSecret (string)

The client secret of your OAuth application.

IDM encrypts the value of the password and clientSecret on startup.

Test the ServiceNow connector

When your connector is configured correctly, test its status by running the following command:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/system?_action=test"
[
  {
    "name": "serviceNow",
    "enabled": true,
    "config": "config/provisioner.openicf/serviceNow",
    "connectorRef": {
      "bundleVersion": "[1.5.0.0,1.6.0.0)",
      "bundleName": "org.forgerock.openicf.connectors.servicenow-connector",
      "connectorName": "org.forgerock.openicf.connectors.servicenow.ServiceNowConnector"
    },
    "displayName": "ServiceNow Connector",
    "objectTypes": [
      "delegate",
      "role",
      "__ALL__",
      "costCenter",
      "location",
      "company",
      "userHasGroup",
      "department",
      "user",
      "userHasRole",
      "group"
    ],
    "ok": true
  }
]

A status of "ok": true indicates that the ServiceNow connector can reach the configured resource provider.

ServiceNow remote connector

If you want to run this connector outside of PingOne Advanced Identity Cloud or IDM, you can configure the ServiceNow connector as a remote connector. Java Connectors installed remotely on a Java Connector Server function identically to those bundled locally within PingOne Advanced Identity Cloud or installed locally on IDM.

You can download the ServiceNow connector from here.

Refer to Remote connectors for configuring the ServiceNow remote connector.

Manage users with the ServiceNow connector

These examples show the basic CRUD operations using the ServiceNow connector.

Query all ServiceNow users

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/system/serviceNow/user?_queryId=query-all-ids"
{
  "result": [
    {
      "_id": "02826bf03710200044e0bfc8bcbe5d3f",
      "__NAME__": "lucius.bagnoli@example.com"
    },
    {
      "_id": "02826bf03710200044e0bfc8bcbe5d55",
      "__NAME__": "jimmie.barninger@example.com"
    },
    {
      "_id": "02826bf03710200044e0bfc8bcbe5d5e",
      "__NAME__": "melinda.carleton@example.com"
    },
...
  ],
  "resultCount": 578,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

Query a single ServiceNow user

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/system/serviceNow/user/02826bf03710200044e0bfc8bcbe5d3f"
{
  "_id": "02826bf03710200044e0bfc8bcbe5d3f",
  "internal_integration_user": false,
  "department": "5d7f17f03710200044e0bfc8bcbe5d43",
  "sys_mod_count": "5",
  "location": "0002c0a93790200044e0bfc8bcbe5df5",
  "web_service_access_only": false,
  "sys_updated_on": "2018-02-25 16:42:47",
  "sys_domain": "global",
  "notification": "2",
  "sys_created_by": "admin",
  "locked_out": "false",
  "__NAME__": "lucius.bagnoli@example.com",
  "company": "81fd65ecac1d55eb42a426568fc87a63",
  "sys_domain_path": "/",
  "password_needs_reset": "false",
  "active": "true",
  "gender": "Male",
  "sys_created_on": "2012-02-18 03:04:49",
  "sys_class_name": "sys_user",
  "calendar_integration": "1",
  "email": "lucius.bagnoli@example.com",
  "sys_id": "02826bf03710200044e0bfc8bcbe5d3f",
  "user_password": "md5230ls7L",
  "user_name": "lucius.bagnoli",
  "sys_updated_by": "developer.program@snc",
  "vip": "false",
  "last_name": "Bagnoli",
  "first_name": "Lucius"
}

Create a ServiceNow user

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "__NAME__": "bjensen@example.com",
  "first_name": "Barbara",
  "last_name": "Jensen",
  "email": "bjensen@example.com",
  "phone": "555-123-1234"
}' \
"http://localhost:8080/openidm/system/serviceNow/user?_action=create"
{
  "_id": "4116e0690fa01300f6af65ba32050e7a",
  "sys_mod_count": "0",
  "password_needs_reset": "false",
  "notification": "2",
  "locked_out": "false",
  "phone": "555-123-1234",
  "sys_created_on": "2018-02-27 13:33:38",
  "first_name": "Barbara",
  "email": "bjensen@example.com",
  "active": "true",
  "sys_domain": "global",
  "calendar_integration": "1",
  "web_service_access_only": false,
  "vip": "false",
  "sys_id": "4116e0690fa01300f6af65ba32050e7a",
  "sys_updated_on": "2018-02-27 13:33:38",
  "sys_domain_path": "/",
  "sys_created_by": "admin",
  "sys_class_name": "sys_user",
  "last_name": "Jensen",
  "__NAME__": "bjensen@example.com",
  "sys_updated_by": "admin",
  "internal_integration_user": false
}

Update a ServiceNow user

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--header "If-Match:*" \
--request PUT \
--data '{
  "__NAME__": "bjensen@example.com",
  "first_name": "Barbara",
  "last_name": "Jensen",
  "email": "bjensen@example.com",
  "phone": "555-000-0000"
}' \
"http://localhost:8080/openidm/system/serviceNow/user/4116e0690fa01300f6af65ba32050e7a"
{
  "_id": "4116e0690fa01300f6af65ba32050e7a",
  "sys_mod_count": "1",
  "password_needs_reset": "false",
  "notification": "2",
  "locked_out": "false",
  "phone": "555-000-0000",
  "sys_created_on": "2018-02-27 13:33:38",
  "first_name": "Barbara",
  "email": "bjensen@example.com",
  "active": "true",
  "sys_domain": "global",
  "calendar_integration": "1",
  "web_service_access_only": false,
  "vip": "false",
  "sys_id": "4116e0690fa01300f6af65ba32050e7a",
  "sys_updated_on": "2018-02-27 13:35:32",
  "sys_domain_path": "/",
  "sys_created_by": "admin",
  "sys_class_name": "sys_user",
  "last_name": "Jensen",
  "__NAME__": "bjensen@example.com",
  "sys_updated_by": "admin",
  "internal_integration_user": false
}

Delete a ServiceNow user

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "If-Match:*" \
--request DELETE \
"http://localhost:8080/openidm/system/serviceNow/user/4116e0690fa01300f6af65ba32050e7a"
{
  "_id": "4116e0690fa01300f6af65ba32050e7a",
  "sys_mod_count": "1",
  "password_needs_reset": "false",
  "notification": "2",
  "locked_out": "false",
  "phone": "555-000-0000",
  "sys_created_on": "2018-02-27 13:33:38",
  "first_name": "Barbara",
  "email": "bjensen@example.com",
  "active": "true",
  "sys_domain": "global",
  "calendar_integration": "1",
  "web_service_access_only": false,
  "vip": "false",
  "sys_id": "4116e0690fa01300f6af65ba32050e7a",
  "sys_updated_on": "2018-02-27 13:35:32",
  "sys_domain_path": "/",
  "sys_created_by": "admin",
  "sys_class_name": "sys_user",
  "last_name": "Jensen",
  "__NAME__": "bjensen@example.com",
  "sys_updated_by": "admin",
  "internal_integration_user": false
}

Synchronize ServiceNow users

The ServiceNow connector supports bidirectional reconciliation and liveSync. To set up user synchronization, create a mapping between managed users and ServiceNow users.

This example assumes that you have configured a mapping. The example runs a reconciliation operation from ServiceNow to the managed user repository:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/recon?_action=recon&mapping=systemServicenowUser_managedUser"
{
  "_id": "19755e51-5c3b-4362-b316-601856cb282c-13624",
  "state": "ACTIVE"
}

The following example runs a liveSync operation from ServiceNow to the managed user repository:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/system/serviceNow/user?_action=liveSync"
{
  "connectorData": {
    "nativeType": "string",
    "syncToken": "2018-02-275 11:29:15"
  },
  "_rev": "0000000031285d9b",
  "_id": "SYSTEMSERVICENOWUSER"
}

The ServiceNow connector does not support the __ALL__ object type, so you must specify the object type (for example, User) in your liveSync operation.

Implementation specifics

For PATCH requests, a connector can potentially add, remove, or replace an attribute value. The ServiceNow connector does not implement the add or remove operations, so a PATCH request always replaces the entire attribute value with the new value.

OpenICF Interfaces Implemented by the ServiceNow Connector

The ServiceNow Connector implements the following OpenICF interfaces. For additional details, see ICF interfaces:

Create

Creates an object and its uid.

Delete

Deletes an object, referenced by its uid.

Schema

Describes the object types, operations, and options that the connector supports.

Script on Connector

Enables an application to run a script in the context of the connector.

Any script that runs on the connector has the following characteristics:

  • The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.

  • The script has access to a connector variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration.

  • The script has access to any script arguments passed in by the application.

Search

Searches the target resource for all objects that match the specified object class and filter.

Sync

Polls the target resource for synchronization events, that is, native changes to objects on the target resource.

Test

Tests the connector configuration.

Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.

This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).

You can invoke the test operation before a connector configuration has been validated.

Update

Updates (modifies or replaces) objects on a target resource.

ServiceNow Connector Configuration

The ServiceNow Connector has the following configurable properties:

Basic Configuration Properties

Property Type Default Encrypted(1) Required(2)

instance

String

null

Yes

URL of the ServiceNow instance, for example: dev00000.service-now.com.

username

String

null

Yes

An API user in ServiceNow that can consume the REST API.

password

GuardedString

null

Yes

Yes

Password for the user.

clientID

String

null

Yes

Client ID of the OAuth application in ServiceNow.

clientSecret

GuardedString

null

Yes

Yes

Client Secret for the preceding Client ID.

pageSize

int

100

No

Default page size.

(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.

(2) A list of operations in this column indicates that the property is required for those operations.