Data provisioning
In the Provisioning section of the system configuration, in the Enable provisioning dialog, select the ServiceNow ITSM Relay Connector as the provisioning connector.
General settings
| Parameter | Description |
|---|---|
| Enable password reset | Enable the system for self-service password reset |
| Password policy | Indicate a password policy for the ServiceNow |
| Provisioning claims validity | Enter the number of days a provisioning claim is valid. If this field is set to 0 or empty, the provisioning claim is not valid and the provisioning call is sent once more. |
| Failed provisioning claims validity | Enter the number of days a failed provisioning claim is valid |
| Account deletion unsupported | Check this option if account deletion should not be supported |
Provisioning configuration
| Parameter | Description |
|---|---|
| Base address | Specify the server address. |
| API root | Specify the relative address for the ServiceNow Table API. The default value is: api/now/table |
| Authentication type | The type of authentication to use for the REST system. Depending on the type of authentication that you choose to use, you may see more or fewer settings. The available options are: Basic (username and password are required), None (there are no authentication headers)., OAuth2 (all OAuth mandatory fields must be completed with proper values). These values can be configured during ServiceNow OAuth Setup. |
| Security protocol | Security protocol of your REST system. |
| Timeout in seconds | Specify the timeout value in seconds. |
Basic authentication
| Parameter | Description |
|---|---|
| Username | The username for the user to authenticate with the service. |
| Password | The password for the user to authenticate with the service. |
OAuth2 authentication
| Parameter | Description |
|---|---|
| URL for Authorization token | The URL address for the Authorization token. Configured during ServiceNow OAuth Setup. |
| OAuth Grant Type | The type of OAuth2 Grant used for authorization. Password credentials is the recommended authorization type. Possible grants: Password credentials, JWT bearer |
| OAuth Client ID | The Client ID, configured during ServiceNow OAuth Setup. |
| OAuth Client Secret | OAuth Client Secret, configured during ServiceNow OAuth Setup. |
| OAuth Resource | OAuth Resource Owner. Not required, can be left blank. |
| OAuth Token Revoke URL | URL address for the Token Revoke. Not required, can be left blank. |
| Token cache policy | The token cache policy, with the following options available: Never cache – we should not cache the token, Always cache – get the token once and store always, Expiration interval – expire the token after some time interval (in seconds). |
Password credentials Grant
| Parameter | Description |
|---|---|
| Username | The username for the ServiceNow user to authenticate with. |
| Password | The password for the ServiceNow user. |
ServiceNow settings
These settings allow you to configure the requests sent to the ServiceNow.
| Parameter | Description |
|---|---|
| Create request object per job | Specify if the request object is created for a job. If this is unchecked, only request items are created. |
| Request object type | Specify the used request updates. The default object is ‘sc_request’. |
| Request fields* | Choose the fields that are added on the request. The default fields are ‘priority’, ‘description’, and ‘special_instructions’. |
| Properties to copy to request | Specify the properties that will be copied to the request and request item objects. The default property is ‘requested_for’. |
| Properties to move to request | Specify the properties that will be moved to the request object only. |
| Request status field | Specify the field in the request that will be used to determine the request’s state. The default property is ‘requested_state’. |
| Request message field | Allows you to retrieve a message added to the request. |
| Request pending values | Specify the values of the request that set it as pending. The default values are ‘requested’ and ‘in_process’. |
| Request failed values | Specify the values of the request that set it as failed. The default values are ‘closed_cancelled’, ‘closed_rejected’, and ‘closed_skipped’. |
| Request partially completed values | Specify the values of the request that set it as partially completed. The default values are ‘closed_incomplete’. |
| Request completed values | Specify the values of the request that set it as completed. The default values are ‘closed_complete’. |
| Request item status field | Specify the field in the request item that will be used to determine the request’s state. The default property is ‘state’. |
| Request item message field | Allows you to retrieve a message added to the request item. |
| Request item pending values | Specify the values of the request item that set it as pending. The default values are ‘-5’, ‘1’, and ‘2’. |
| Request item failed values | Specify the values of the request item that set it as failed. The default values are ‘4’ and ‘7’. |
| Request item completed values | Specify the values of the request item that set it as completed. The default values are ‘3’. |
| Correlation display value | This value is used by the connector to identify the failed requests or tasks in order not to create multiple requests or request items for the same job. |
| Trigger workflow on create | Set this to true to trigger a ServiceNow workflow. The Connector will update the request item that will trigger a workflow. |
| Properties to move from task | Specify the properties which will be moved from the task and used in the PATCH operation (should be separated by a comma). |
| Properties to copy from task | Specify the properties which will be copied from the task and used in the PATCH operation (should be separated by a comma). |
| Field to update | This field is available if the Trigger workflow on create checkbox is set to true. Specify the field on the request item object that the connector updates. This field is mandatory. |
| Value | This field is available if the Trigger workflow on create checkbox is set to true. Specify the value set by the connector. If the field is left blank, the value will be set to current date (as text). |
note
In the case of Request fields, you can remove any of the described ones but not add new ones. To map additional fields to the request object you must add them to the Properties to copy or Properties to move. The fields are taken from the first task in the job.
The status values described above are only the default values. You can define your custom status values to suit your ServiceNow configuration.
Advanced settings
The Advanced settings dialog for the ServiceNow Relay Connector features a special Relaying tab in.
| Parameter | Description |
|---|---|
| Poll frequency (hours) | Specify how often the OPS polls (asks) for the job status. |
| Poll timeout (days) | Specify the number of days after which the OPS will stop the above polling and set the job to failed. |
Data model
The ServiceNow Relay Connector creates Request objects linked to OPS jobs and the request fields are mapped to the job fields in the following way.
| Request field | Job field | Description |
|---|---|---|
| description | OriginJobId | This is a name value pair list |
| special_instructions | Job.Tasks[].Description | Contains the description of each of the tasks in the request |
| priority | Job.Priority | If the job priority is higher than 5 then the value of this field is automatically set to 5 |
note
The contents of the above fields cannot be controlled. However, using the connector configuration, you can control if a given field from the list is at all set or not.
In addition, below you can see the examples of the POST calls for the Request object and Request item object.
Task Mappings
System configuration Task Mappings
For the ServiceNow Relayed provisioning to work correctly, you need to manually select the following task mappings in the Task mappings dialog of the Provisioning section for your system.
| Parameter | Description |
|---|---|
| RoPE Assignment to ServiceNow Request Item | Contains RoPE mappings between an account and a resource in the ServiceNow |
| RoPE Account to ServiceNow Request Item | Contains RoPE mappings for an account name in the ServiceNow |
API Task Mappings
The ServiceNow Relay Connector uses the following four default task mappings for the ServiceNow Table API calls:
POST request
Creates a request:
| Omada Identity Attribute | ServiceNow Attribute | Required | Description |
|---|---|---|---|
| Requested by or identityref | Opened_by | yes | Not set. Filled with the sys_id of the ServiceNow user who has connected to the Table API. |
| Beneficiary (identityref) | Requested_for | yes | Sys_id for the user in ServiceNow. By default, resolved by matching account name on the CRA with the username. |
| Job ID | Correlation_id | yes | Unique identifier for the job in Omada Identity. Cannot be changed. |
| Correlation_display | Value Omada Value to display which external system has provided the Id. |
GET request
Queries for the status of the request:
| Omada Identity Attribute | ServiceNow Attribute | Required | Description |
|---|---|---|---|
| AssignmentAnchor | sys_id | Yes | Sys_id for request in ServiceNow |
| State | State | Yes | Integer representing state. The value can be set in the ServiceNow settings section. |
| Message | comments | No | Comments for the request. Comments can be set in the ServiceNow settings section. |
POST request item
Creates a request item:
| Omada Identity Attribute | ServiceNow Attribute | Required | Description |
|---|---|---|---|
| Requested by | Opened_by (Sys_user) | Yes | Not set. Filled with the sys_id of the ServiceNow user who has connected to the Table API. |
| Beneficiary (identityref) | Requested_for | Yes | Sys_id for the user in ServiceNow. By default, resolved by matching account name on the CRA with the username. |
| Task ID | Correlation_id | Yes | Unique identifier for the task in Omada Identity. Cannot be changed. |
| Short_description | Description of the Request. The description has the following format: In system {0}, {1} account with name {2}", ROPE\_System, Operation, ROPE\_AccountName | ||
| Correlation_display | A value to display which external system has provided the Id. The value can be set in the ServiceNow settings section. Default is ”Omada” |
GET Request item
Queries for the status of the request item:
| Omada Identity Attribute | ServiceNow Attribute | Required | Description |
|---|---|---|---|
| AssignmentAnchor | sys_id | Yes | Sys_id for request item in ServiceNow |
| State | State | Yes | Integer representing state. The value can be set in the ServiceNow settings section. |
| Message | comments | No | Comments for the request. Comments can be set in the ServiceNow settings section. |