--- title: ServiceNow connector description: Connectors continue to be released outside the IDM release. For the latest documentation, refer to the OpenICF documentation. component: pingidm version: 7.2 page_id: pingidm:connector-reference:servicenow canonical_url: https://docs.pingidentity.com/pingidm/7.2/connector-reference/servicenow.html section_ids: servicenow-prerequisites: Before you start connector-configuring: Configure the ServiceNow connector 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.15: OpenICF Interfaces Implemented by the ServiceNow Connector config-properties-org-forgerock-openicf-connectors-servicenow-ServiceNowConnector-1.5.20.15: ServiceNow Connector Configuration basic-configuration-properties-org-forgerock-openicf-connectors-servicenow-ServiceNowConnector-1.5.20.15: Basic configuration properties --- # ServiceNow connector | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Connectors continue to be released outside the IDM release. For the latest documentation, refer to the [OpenICF documentation](https://docs.pingidentity.com/openicf/index.html). | 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, see the [ServiceNow documentation](https://docs.servicenow.com) 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` ## Configure the ServiceNow connector Create a connector configuration using the 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.15. 5. Complete the Base Connector Details. * `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. 6. Click Save. 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 } ``` IDM encrypts the value of the `password` and `clientSecret` on startup. 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. ## 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](../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/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 [OpenICF 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.