Before RealTheory can create ServiceNow records for Recommendations, ServiceNow must be set up correctly. This article explains exactly what must be configured on the ServiceNow side to support the integration.
Supported Authentication Methods
RealTheory connects to your ServiceNow instance using the ServiceNow REST API and supports one authentication method:
- Basic Authentication
- Username + Secret
- Where Username is the ServiceNow User ID, and Secret is the password associated with the account.
Basic Authentication is pre-selected in the RealTheory Integration Profile when ServiceNow is chosen as the provider. Other authentication methods, such as OAuth 2.0, are not supported at this time.
ServiceNow Integration Account
RealTheory connects to ServiceNow using a single ServiceNow account, referred to in this article as the integration account. This can be either:
- A dedicated service account (highly recommended)
- A person's user account (not recommended)
The integration account must:
- Be active and not locked out
- Sign in with a local ServiceNow password. Accounts that depend on single sign-on (SSO) or multi-factor authentication (MFA) cannot use Basic Authentication.
- Have the roles described in Roles and Permissions
When you enter the Username in RealTheory, use the User ID from the account's user record, not the display name.
If you use a dedicated service account, we recommend enabling Web service access only on its user record. This allows the account to call the REST API but prevents interactive login to the ServiceNow UI.
RealTheory sets the Caller on every record it creates to the integration account, so choose a clear, recognizable name. For example, realtheory.integration.
Roles and Permissions
RealTheory creates ServiceNow records and can delete the records it created. Actions such as assigning a record, adding related tasks, or changing its state must be managed in ServiceNow.
RealTheory works with the Incident and Problem tables through the ServiceNow REST API. The integration account needs the following roles:
- itil - Required. On a standard instance, this role allows RealTheory to validate the connection, create and read Incident and Problem records, and look up the integration account. RealTheory validates the connection by reading the Incident table, so this access is needed even if you only create Problem records.
- snc_platform_rest_api_access - Required only if your instance restricts REST API access to this role. Without it, requests fail even when the credentials are valid.
- A role with delete access - Required to delete records from ServiceNow using the RealTheory Console.
By default, the itil role typically cannot delete Incident or Problem records. Rather than granting the admin role, create a custom role with a delete ACL on the Incident and Problem tables, and assign it to the integration account. Without delete access, RealTheory still creates records successfully, but deleting a record from the RealTheory Console fails with a "Failed to delete" message.
Note: Some newer ServiceNow releases require Problem Management roles, such as problem_coordinator, to create Problem records. If Problem records fail to create but Incident records succeed, add the required Problem Management role.
Issue Types
In ServiceNow, the issue type is the record type RealTheory creates. RealTheory supports two record types, Incident and Problem, each stored in its own ServiceNow table.
RealTheory creates records using the Default Issue Type specified in the Integration Profile. Users can override the Default Issue Type during ticket creation, so ServiceNow must allow the integration account to create whichever record type the user selects.
To ensure this:
-
Mandatory fields must be optional or have defaults
RealTheory sets the Caller field to the integration account, but does not supply values for other mandatory, custom, or special workflow fields. If your record type has mandatory fields such as:- Category or Subcategory
- Assignment group
- Configuration item
- Custom fields
…then each field must either:
- Be configured as optional, or
- Have a default value in the dictionary configuration
If a mandatory field has no value, ServiceNow rejects the create request.
-
Data policies and business rules must not block creation
Data policies and before insert business rules apply to records created through the REST API, so they must not require fields that RealTheory does not provide. Common blocking rules include:- "Field X is mandatory" data policies
- Business rules that abort the insert when a field is empty
- Scripted validation added by custom applications
Remove or relax these rules for the integration account, or add default values in ServiceNow.
Note: UI policies only apply to forms in the ServiceNow UI and do not affect records created by RealTheory.
Multiple Issue Types and Teams
Your organization might want RealTheory to support different workflows, such as:
- Incidents for SREs
- Problems for Operations
- Multiple teams or ServiceNow instances
Create one Integration Profile for each workflow. For example, one profile per ServiceNow instance or per Default Issue Type. Each ServiceNow instance needs its own integration account, configured as described in this article.
URLs and Connection Details RealTheory Needs From ServiceNow
Your ServiceNow administrator must provide the following information to your RealTheory administrator. These values are entered into a RealTheory Integration Profile, and all of them are required.
- Instance URL - For example, https://<instance>.service-now.com
- Console URL - Used to generate direct links to records from RealTheory. For example, https://<instance>.service-now.com
- Username and Secret - The integration account's User ID and password. See Supported Authentication Methods.
See Also
Creating an Integration Profile