> For the complete documentation index, see [llms.txt](https://atlas.anywhere.now/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://atlas.anywhere.now/channels-integrations/crm-service/servicenow.md). # ServiceNow CRM Service Configure CRM Service for ServiceNow. Configure CRM Service for ServiceNow when WebAgent must retrieve ServiceNow information through the ServiceNow REST API. Before requesting the service, confirm the [shared CRM connector licensing prerequisites](/channels-integrations/crm-service.md#licensing-prerequisites). ## Request ServiceNow CRM Service in OnePortal 1. Request the ServiceNow CRM Service for the customer environment through the current OnePortal, delivery, or support process. 2. Confirm which UCC and WebAgent configuration must consume ServiceNow data. 3. Confirm that ServiceNow is the enabled CRM Service provider before changing provider settings. 4. Use [Configure CRM Service settings](/channels-integrations/crm-service/configure-crm-service-settings.md) for shared request, change, `PluginSettings`, `PluginAttributes`, and secret-handling rules. {% hint style="info" %} Exact OnePortal labels can differ by release. Use the current customer-specific request path instead of legacy labels. {% endhint %} ## Prepare ServiceNow Prepare ServiceNow OAuth and integration-user access before CRM Service settings are completed. | Preparation item | What to prepare | Used by CRM Service | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | ServiceNow instance URL | Customer-specific ServiceNow instance URL, such as `https://{instance}.service-now.com`. | `ApplicationHost` | | REST API endpoint | Approved table API or REST API endpoint, such as `https://{instance}.service-now.com/api/now/table`. | `ApiEndpoint` | | OAuth token endpoint | Approved token endpoint, such as `https://{instance}.service-now.com/oauth_token.do`. | `LoginEndPoint` | | OAuth application | Client ID and client secret approved for CRM Service. | `ClientId` and encrypted `ClientSecret` | | Integration user | User approved for API access to the ServiceNow data WebAgent must display. | `Username` and encrypted `Password` | | Roles | Access to the required tables and records. Legacy examples include `itil`, `rest_api_explorer`, and `rest_service`; confirm the current role assignment with the ServiceNow owner. | Provider-side authorization | Use [ServiceNow OAuth setup guidance](https://docs.servicenow.com/csh?topicname=t_SettingUpOAuth) and verify current ServiceNow UI labels before changing OAuth settings. ## Configure ServiceNow CRM Service in Dialogue Cloud Neo / SharePoint Enter or request these values in the active configuration source for `CrmService` `PluginSettings`. | Setting | Requirement | Value | | --------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------ | | `ApplicationHost` | Required | ServiceNow application URL supplied for the environment, for example `https://.service-now.com`. | | `ApiEndpoint` | Required | ServiceNow REST API endpoint supplied for the environment, for example `https://.service-now.com/api/now/table/`. | | `LoginEndPoint` | Required | ServiceNow OAuth token endpoint supplied for the environment, for example `https://.service-now.com/oauth_token.do`. | | `Username` and encrypted `Password` | Required | ServiceNow integration-user credentials. | | `ClientId` and encrypted `ClientSecret` | Required | ServiceNow OAuth application values. | Configure ServiceNow field mappings in `CrmService` `PluginAttributes` when the default mapping is not sufficient for the customer data model. ## Configure optional ServiceNow settings in Dialogue Cloud Neo / SharePoint Add optional settings with scope `CrmService`. | Setting | Where configured | Default or value guidance | | ----------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ShowStatus` | `PluginSettings` | Shows whether the caller is a contact or unknown. Default: `True`. | | `DefaultPhoneNumberRegion` | `PluginSettings` | ISO 3166 alpha-2 region code. Default: `ZZ`. | | `PhoneNumberFormat` | `PluginSettings` | Default: `Wildcard`. Supported modes include `E164`, `International`, `Rfc3966`, and `Wildcard`. Use a more exact supported format when ServiceNow phone fields store numbers consistently. | | `CaseStatus` | `PluginSettings` | Maps ServiceNow status text to WebAgent status. Default mappings: `New=Open`, `Working=Open`, `Escalated=Open`, `Closed=Closed`. Keep this aligned with the case status `SystemName`; the default `PluginAttributes` table maps Status to `status`. | | `ImageUrlFormat` | `PluginSettings` | Format used to retrieve the contact image. Use the current customer instance URL; do not reuse a customer-specific value from another environment. | | `BaseContactQuery` | `PluginSettings` | Contact query template. Default: `q=sys_user?sysparm_fields={0}&sysparm_query={1}&sysparm_limit=100`. `sysparm_limit` is mandatory. | | `BaseCaseQuery` | `PluginSettings` | Case query template. Default: `q=incident?sysparm_display_value=true&sysparm_fields={0}&sysparm_query={1}&sysparm_limit=100`. `sysparm_limit` is mandatory. | | `ContactCaseFilter` | `PluginSettings` | Contact-to-case filter. Default: `caller_id.sys_id={0}`. Attribute and value must be valid `SystemName` values. | | `ContactConversationFilter` | `PluginSettings` | Contact-to-conversation filter. Default: `id=[contactid]`. Value must be a valid `SystemName`. | | ServiceNow `PluginAttributes` | `PluginAttributes` | Map ServiceNow attributes to WebAgent contact, contact-search, case, and case-search output. |
ServiceNow query and mapping guidance For ServiceNow `PluginAttributes`, use ServiceNow attributes as `SystemName` values. If an attribute comes from a linked entity, include the alias before the attribute. Use: * `DisplayName` for the label shown in WebAgent. * `ShowOnExtensionWindow` to control whether WebAgent displays the value. * `Order`; restart numbering for each `Category`. * `FieldType` values such as `Id`, `Name`, `PhoneNumber`, `SipAddress`, `Email`, `Date`, and `Search`. * `Hyperlink` to make a value clickable; include `SystemName` placeholders in square brackets when the link needs field values. * `ShowOnToast` to force the attribute into the query. Keep complete customer-specific query strings in the delivery or configuration record, but preserve `sysparm_limit` when customizing the base queries. ### Default `PluginAttributes` The default mappings below do not include a Case ID row. Before adding one, confirm the Case ID `SystemName` and matching hyperlink with the ServiceNow integration owner. | DisplayName | SystemName | Category | Order | ShowOnExtensionWindow | FieldTypes | Hyperlink | ShowOnToast | | -------------- | ------------------- | -------- | ----: | --------------------- | --------------------- | ----------------------------------------------------------------------- | ----------- | | Company | `companyname` | Account | 0 | No | `Name` | | Yes | | Account ID | `accountid` | Account | 1 | No | `Id` | | No | | Company | `name` | Account | 2 | Yes | `Name, Search` | | No | | Phone Number | `telephone1` | Account | 3 | Yes | `PhoneNumber, Search` | | No | | Owner | `owner.fullname` | Account | 4 | Yes | | | No | | Title | `short_description` | Case | 2 | Yes | `Name, Search` | | No | | Description | `description` | Case | 3 | Yes | | | No | | Date | `sys_updated_on` | Case | 4 | Yes | `Date` | | No | | Status | `status` | Case | 5 | Yes | `FormattedValue` | | No | | Contact ID | `sys_id` | Contact | 1 | No | `Id` | `{uri.Scheme}: //{uri.Host}//nav_to.do?uri=sys_user.do?sys_id=[sys_id]` | No | | Account ID | `company.name` | Contact | 2 | No | `Id` | | No | | Name | `name` | Contact | 3 | No | `Name` | | Yes | | Company | `account.name` | Contact | 4 | Yes | `Name` | | Yes | | Email | `email` | Contact | 10 | Yes | `Search, Email` | | No | | Phone Number | `phone` | Contact | 20 | Yes | `Search, PhoneNumber` | | No | | Phone Number 2 | `home_phone` | Contact | 21 | Yes | `Search, PhoneNumber` | | No | | Mobile Number | `mobile_phone` | Contact | 22 | Yes | `Search, PhoneNumber` | | No | | Photo | `photo` | Contact | 23 | Yes | | | Yes | | Avatar | `avatar` | Contact | 24 | Yes | | | Yes | ContactSearch is a copy of Contact, with `Name` also receiving the `Search` field type.
## Validate ServiceNow CRM Service 1. Confirm that CRM Service can reach the ServiceNow endpoint. 2. Search for a known ServiceNow contact, account, incident, or case from WebAgent. 3. Confirm that expected ServiceNow fields appear in WebAgent. 4. Confirm that phone-number recognition returns the expected ServiceNow record. ## References * [ServiceNow OAuth setup guidance](https://docs.servicenow.com/csh?topicname=t_SettingUpOAuth) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://atlas.anywhere.now/channels-integrations/crm-service/servicenow.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.