--- title: ServiceNow connector description: This connector lets you manage objects in the ServiceNow platform, integrating with ServiceNow's REST API. component: openicf page_id: openicf:connector-reference:servicenow canonical_url: https://docs.pingidentity.com/openicf/connector-reference/servicenow.html section_ids: servicenow-prerequisites: Before you start install_the_servicenow_connector: Install the ServiceNow connector connector-configuring: Configure the ServiceNow connector test_the_servicenow_connector: Test the ServiceNow connector servicenow_remote_connector: ServiceNow remote connector config-connection-pooling-servicenow: Configure connection pooling servicenow-using: Manage users with the ServiceNow connector servicenow-query-all: Query all ServiceNow users servicenow-query-user: Query a single ServiceNow user servicenow-create: Create a ServiceNow user servicenow-update: Update a ServiceNow user servicenow-delete: Delete a ServiceNow user servicenow-sync: Synchronize ServiceNow users servicenow-implementation-specifics: Implementation specifics implemented-interfaces-org-forgerock-openicf-connectors-servicenow-ServiceNowConnector-1.5.20.33: OpenICF Interfaces Implemented by the ServiceNow Connector config-properties-org-forgerock-openicf-connectors-servicenow-ServiceNowConnector-1.5.20.33: ServiceNow Connector Configuration basic-configuration-properties-org-forgerock-openicf-connectors-servicenow-ServiceNowConnector-1.5.20.33: Basic Configuration Properties --- # 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](https://www.servicenow.com/docs/) 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 don't want to give complete `admin` rights to this user, you can create a new role that provides access to the following tables: * `sys_audit` * `sys_group_has_role` * `sys_user` * `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 | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | To check for an Advanced Identity Cloud application for this connector, refer to:- [Application management](https://docs.pingidentity.com/pingoneaic/latest/app-management/applications.html) - [App catalog](https://docs.pingidentity.com/pingoneaic/latest/app-management/app-catalog.html) | You can download any connector from [Backstage](https://backstage.forgerock.com/downloads/browse/idm/featured/connectors), 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](servicenow.html) | [icon: check, set=fa]Yes | [icon: times, set=fa]No | Download the connector .jar file from [Backstage](https://backstage.forgerock.com/downloads/browse/idm/featured/connectors). * If you're running the connector locally, place it in the `/path/to/openidm/connectors` directory, for example: ``` mv ~/Downloads/servicenow-connector-1.5.20.33.jar /path/to/openidm/connectors/ ``` * If you're 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 list, select ServiceNow Connector - 1.5.20.33. 5. Complete the Base Connector Details and any applicable Additional Options. | | | | - | -------------------------------------------------------------------------------------------------------------------------- | | | For a list of all configuration properties, refer to [ServiceNow Connector Configuration](#servicenow-config-prop-ezLink). | 6. Click Save. When your connector is configured correctly, the connector displays as Active in the admin UI. Refer to [this procedure](configure-connector.html#connector-wiz-REST) to create a connector configuration over REST. The following excerpt of connector configuration shows the required `configurationProperties`: ```json "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/servicenow?_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", "__ACCOUNT__", "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](https://backstage.forgerock.com/downloads/browse/idm/all/productId:idm-connectors). Refer to [Remote connectors](remote-connector.html) for configuring the ServiceNow remote connector. ### Configure connection pooling The ServiceNow connector uses [ICF pooling](pooling.html#icf-pooling) to manage connections. Learn more about the different pooling mechanisms in [Connectors by pooling mechanism](pooling.html#pooling-table). ## 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/__ACCOUNT__?_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/__ACCOUNT__/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/__ACCOUNT__?_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/__ACCOUNT__/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/__ACCOUNT__/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](https://docs.pingidentity.com/pingidm/8/synchronization-guide/mappings.html) 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/__ACCOUNT__?_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, `__ACCOUNT__`) 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](interfaces.html): * 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` | | [icon: check, set=fas]Yes | | URL of the ServiceNow instance, for example: `dev00000.service-now.com`. | | | | | | `username` | `String` | `null` | | [icon: check, set=fas]Yes | | An API user in ServiceNow that can consume the REST API. | | | | | | `password` | `GuardedString` | `null` | [icon: lock, set=fas]Yes | [icon: check, set=fas]Yes | | Password for the user. | | | | | | `clientID` | `String` | `null` | | [icon: check, set=fas]Yes | | Client ID of the OAuth application in ServiceNow. | | | | | | `clientSecret` | `GuardedString` | `null` | [icon: lock, set=fas]Yes | [icon: check, set=fas]Yes | | Client Secret for the preceding Client ID. | | | | | | `pageSize` | `int` | `100` | | [icon: times, set=fas]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.