Skip to main content

Connecting Hyperproof to ServiceNow

Roles and permissions

  • Only administrators can configure the ServiceNow integration for their organization.

Hyperproof can connect to ServiceNow using either Basic authentication (a ServiceNow username and password) or OAuth client credentials (the client ID and client secret of an OAuth client in ServiceNow). Both methods require the same two types of ServiceNow accounts: an administrator account that Hyperproof uses to configure the integration and read data across your instance, and user or service accounts that create and update ServiceNow tasks on behalf of Hyperproof users.

Each Hyperproof user can connect to only one ServiceNow account. Because the ServiceNow administrator account is read-only, the Hyperproof user who connects it can't use the integration to create or update ServiceNow tasks. To avoid this, create a separate service account in Hyperproof under Settings > People, and use it to configure the administrator connection. Individual users can then use their own ServiceNow connections to link Hyperproof tasks to ServiceNow tasks, with the same permissions in both systems.

Once the integration is configured, each Hyperproof user who creates or links Hyperproof tasks to ServiceNow tasks must have a Hyperproof account and a corresponding ServiceNow user or service account. Those users perform the day-to-day task creation and task update functions.

Administrator permissions for configuring the ServiceNow integration

In ServiceNow, you must create at least one administrator account to configure the Hyperproof integration. It should have the following roles:

  • admin

  • snc_read_only

Hyperproof never writes data with this account. It uses the account to read the following tables across your instance:

  • Form layouts, so fields are rendered when creating a new task in Hyperproof: sys_ui_element, sys_ui_form_section, sys_dictionary, and sys_dictionary_override

  • Ticket states: sys_choice

  • Groups and users: sys_user_group and sys_user

  • Change history, so Hyperproof can detect updates to linked tasks: sys_audit and the incident, incident_task, sc_task, and problem_task tables

A base ServiceNow instance allows only the admin role to read sys_audit and the dictionary tables; no other preset roles or ACLs grant the same access. The snc_read_only role restricts the account to read-only access to everything it can see.

The administrator account must have the Identity type set to MACHINE, with the Web service access only setting enabled.

User permissions for integrating Hyperproof and ServiceNow tasks

In ServiceNow, create a user or service account for each Hyperproof user who will create and/or link Hyperproof tasks to ServiceNow tasks. Users in Hyperproof are matched with users in ServiceNow by email address. These users must have the following roles assigned:

  • itil - This role grants read and write permission on Incidents, Incident Tasks, Problem Tasks, and Catalog Tasks

  • catalog_admin - This role grants permissions for Catalog tasks when combined with the itil role.

OR

  • sn_incident_write - This role grants permissions for Incidents and Incident tasks.

  • sn_problem_write - This role grants permissions for Problem tasks.

  • sn_request_write and catalog_admin - The combination of these two roles grants permissions for Catalog tasks.

These roles are used to create and update tickets, work notes, and attachments in the incident, incident_task, sc_task, and problem_task tables, and keep each linked ServiceNow object in sync with the coordinating Hyperproof task.

Note: See the official ServiceNow documentation for more information on base system roles.

Add these users to assignment groups in ServiceNow. Membership in assignment groups determines which ServiceNow tasks and task types the user can create.

Setting up OAuth clients in ServiceNow

If you use Basic authentication, skip to Connecting the administrator account.

With OAuth client credentials, you create one OAuth client in ServiceNow for the administrator account and one for each user account. Each OAuth client acts as the ServiceNow user set as its OAuth Application User, so every client must be backed by one of the accounts described above and have the roles listed above.

Enable the client credentials grant

  1. In ServiceNow, enter sys_properties.list in the navigation search bar and press Enter.

  2. Search for the glide.oauth.inbound.client.credential.grant_type.enabled property.

  3. Set its value to true. If the property doesn't exist, create it with the Type set to true | false, and then set the value to true.

Note: If this property isn't enabled, ServiceNow rejects token requests from every OAuth client, and Hyperproof can't connect.

Create the administrator OAuth client

  1. In ServiceNow, go to System OAuth > Application Registry.

  2. Click New > New Inbound Integration Experience > New Integration > OAuth - Client credentials grant.

  3. Enter a name, such as Hyperproof - read-only admin. Leave Client ID and Client Secret blank so ServiceNow generates them.

  4. Set OAuth Application User to the administrator account.

  5. Save the entry, and then reopen it.

  6. Copy the Client ID. Unlock the Client Secret and copy it.

Note: In ServiceNow releases before Zurich, click New > Create an OAuth API endpoint for external clients in step 2. The OAuth Application User and Default Grant type fields aren't on this form by default. Add them with Configure > Form Layout, and set Default Grant type to Client Credentials.

Create a user OAuth client

Create one OAuth client for each Hyperproof user who will create or link ServiceNow tasks.

  1. In ServiceNow, go to System OAuth > Application Registry.

  2. Click New > New Inbound Integration Experience > New Integration > OAuth - Client credentials grant.

  3. Enter a name, such as Hyperproof - [user name]. Leave Client ID and Client Secret blank so ServiceNow generates them.

  4. Set OAuth Application User to the ServiceNow account for that user.

  5. Save the entry, and then reopen it.

  6. Copy the Client ID. Unlock the Client Secret, copy it, and then share both securely with the user.

Note: Hyperproof credits every ServiceNow change to the client's OAuth Application User. If multiple Hyperproof users connect with the same client, all of their changes appear in ServiceNow as the same user.

Connecting the administrator account

Note: This section applies to administrator accounts for both OAuth and Basic Authentication.

The administrator credentials are saved in Hyperproof and used to set up the integration, populate certain fields in the task window, and map task statuses between the two systems. The Hyperproof user who initially configures the administrator connection is the sole owner of the credential settings. Other Hyperproof users can update the administrator credentials.

Caution: Deleting existing integration credentials causes the associated task integrations to stop working.

  1. Sign in to Hyperproof with the service account you created for the administrator connection.

  2. From the left menu, select Settings.

  3. From the Settings menu, select Integrations.

  4. On the Integrations page, select ServiceNow. The ServiceNow window displays.

  5. Toggle the button next to ServiceNow is disabled to enable it. If ServiceNow is already enabled, you can skip this step.

  6. At the bottom of the window, click the Settings link to continue the setup process.

    The setup page displays.

  7. Click the New connection button.

  8. In the Select Authentication Method window, select Basic authentication or OAuth client credentials.
    ​

    The Create connection window displays.

  9. In the Instance field, enter the name of your ServiceNow instance. It is derived from the URL that displays when you are logged in to ServiceNow. For example, if your ServiceNow URL is https://megatech555.service-now.com, your instance name is megatech555.

  10. Enter the credentials for the administrator account:

    • Basic authentication: In the Username and Password fields, enter the administrator account's username and password.

    • OAuth client credentials: In the Client ID and Client Secret fields, enter the values you copied from the administrator OAuth client.

  11. Click Submit to save the connection.

  12. The connection displays on the setup page.

See Mapping Hyperproof and ServiceNow task statuses to continue configuring your ServiceNow integration.

Connecting user accounts

Note: This section applies to user accounts for both OAuth and Basic Authentication.

Each Hyperproof user who wants to use the task integration must set up their own connection from the task window. Users should enter their own ServiceNow credentials or OAuth client, not the administrator's. Their credentials are stored in Hyperproof along with their Hyperproof user information.

  1. Open a task in Hyperproof.

  2. Click the task integration tile for your ServiceNow instance. The first time you link a task to ServiceNow, Hyperproof prompts you to connect to ServiceNow.

  3. In the Select Authentication Method window, select Basic authentication or OAuth client credentials.

  4. In the Instance field, enter the name of your ServiceNow instance. It is derived from the URL that displays when you are logged in to ServiceNow. For example, if your ServiceNow URL is https://megatech555.service-now.com, your instance name is megatech555.

  5. Enter your credentials:

    • Basic authentication: In the Username and Password fields, enter your ServiceNow username and password.

    • OAuth client credentials: In the Client ID and Client Secret fields, enter the client ID and client secret your ServiceNow administrator shared with you for your OAuth client.

To update your ServiceNow credentials, go to Settings > Connected accounts, locate the ServiceNow task integration credentials card, and disconnect. Then return to the task window and start a ServiceNow interaction. Hyperproof prompts you for your credentials again.

Did this answer your question?