ServiceNow

Minimal User Permissions & Hub User

We recommend that you create a new user within your external tool, to be used only for your Hub integration. This is the user information you will enter when setting up your repository connection within Planview Hub. By creating a new user, you will ensure that the correct permissions are granted, and allow for traceability of the modifications that are made by the synchronization. 

In general, your user account should have sufficient permissions to create, read, and update artifacts in your repository. However, depending on the use case, your user may need different permissions. For example, if you are only interested in flowing data out of your repository, your user may not need to have full CRUD access, as the 'create' and 'update' permissions may not be needed.

Your user should have a secure password or token. Please be aware that Hub will not allow you to save a repository connection utilizing a weak password/token, such as 'tasktop.'

See ServiceNow instructions on how to create a new Hub user in ServiceNow.

Hub requires access to a specific set of tables within the ServiceNow repository. Follow the instructions below to grant the Hub user access to the required tables:

1. Create a new role in ServiceNow for Hub (e.g., tasktop_user).
2. Save the changes:
   Ensure that the following permissions are granted to the newly created role:

• • For each table that is to be used in an integration, READ access is required on the table itself as well as any table directly related to it (e.g. reference fields, parent fields, etc). 
  • CREATE and WRITE access is required for any table that you'd like integrations to write to.
  • Caution: ServiceNow will silently ignore attempted updates to unauthorized fields while successfully updating authorized fields. This means that Hub cannot provide warning when field-specific updates are not happening.
  • Assign the global_tags_creator role to the user to create tags that are visible to everyone.

Finally, assign this role to the user which Hub will be configured to use.

In addition to the user having permission to access the tables, the tables must be configured to allow access via web services. To allow access via web services, open the relevant table definition and switch to the Application Access tab. Make sure the Allow access to this table via web services option is checked. This access will be needed for all of the tables listed in the ACL section above, as well as any tables for artifacts to be synchronized.

Note: The default admin role has access to all the necessary tables within the ServiceNow (Service Desk) repository.

Connecting to the ServiceNow Repository

Standard Authentication

Required fields:

• Location/Connection URL
  • Example Format: https://server.service-now.com
• Username
• Password

Optional fields:

• Fast Reference Field Support: See details below
• Full Reference Field Support: See details below
• Enabled Non-Task Extended Tables: Allows you to synchronize non-task extended tables as artifacts. See details below
• Maximum Attachment Size: See details below
• Comment Enablement: See details below
• Comment Field (Outbound): Determines which field is used when flowing comments out of ServiceNow. See details below
• Public Comment Field (Inbound): Determines which field is used when flowing public comments into ServiceNow. See details below
• Private Comment Field (Inbound): Determines which field is used when flowing private comments into ServiceNow. See details below
• Filter Out Duplicate Inactive Users: If checked, inactive users will be filtered from search results when exactly one active user matching the search criteria is found.
• Throttling Settings: This field indicates the number of API calls that can be made per minute. See details here.
  • Note: This field should only be set under the guidance of customer care as the ideal value is highly dependent on each customer's unique environment. 
• Connection Security: If checked, insecure connections to this repository will be allowed. See details here.

Standard Authentication (Via AWS Secrets Manager) 

Overview

This authentication method uses Standard Authentication to authenticate with ServiceNow, with the actual credentials being retrieved from the customer’s AWS Secrets Manager. The application connects to AWS Secrets Manager to retrieve the username and password, and then uses those to authenticate with the ServiceNow repository via Standard Authentication. 

Prerequisites

• The on-premise agent should be deployed in the customer’s AWS account in the same region as the customer’s AWS Secrets Manager service that holds the Service Now credentials

• The machine hosting the agent must possess IAM Role permissions to access the necessary AWS Secrets Manager secret 

• Customer managed keys created in AWS Key Management Service (KMS), used for encrypting secrets, should be created in the same AWS account and region

Field Explanation

1. Location/Connection URL
   • Example format: https://server.atlassian.net
2. AWS Region
   • The region can be determined from the AWS Secrets Manager console where the secret is created.
   • Examples of input: us-east-1, us-west-2, etc 
     
     

3. AWS Secret Name

   • The AWS Secret Name is the title by which the secret is created on the AWS Secrets Manager console

   • The username and password must be created in that secret with keys “username” and “password” respectively

   • Below is a screenshot of an example from the AWS Console: 

     

OpenID Connect Private Key Signed JWT Authentication

Required Fields

• URL for OpenID Connect credentials

  • The token endpoint. You can get this from the authentication servers well known configuration endpoint.

  • Example: https://authserver.com/adfs/oauth2/token

• OpenID Connect client ID

  • The client ID registered with the authentication server.

  • The client must have the client credentials grant type enabled.

  • The client must have registered the public certificate given in the “RSA certificate and private key (.p12)” field

• OpenID Connect scope

• Public Certificate

  • A PEM encoded public certificate of the private key being used to sign JWTs included in the requests client_assertion parameter

• RSA Private Key

  • A PEM encoded PKCS8 private key used to sign JWTs included in the requests client_assertion parameter.

Optional Fields

• Key ID

  • The “kid” header of the JWT sent in the access token request

• Resource Parameter

  • The Open ID Connect resource parameter sent in the access token request.

  • Required for versions of Microsoft AD FS prior to 2019.

Learn more about how to set up your repository in Planview Hub here. 

Attachments 

You can set maximum attachment size on the Repository Connection screen. This will allow you to override the default maximum size of 25MB, and to flow larger attachments.

In Planview Hub 19.4.0.20190916 and later, users can exclude encrypted attachments from attachment flow. Learn more here.

In order to be able to use this feature, the Hub user needs to have the ‘itil’ role assigned to them in ServiceNow, and access to the encryption_context used to encrypt attachments.

For information on setting up encryption contexts, click here.
The details of ‘itil’ role can be found here.

Learn more about how to configure attachment flow in Planview Hub here.

Comments 

In Planview Hub 19.4.13+, users can configure comment support through the Comment Enablement field. Comment Enablement specifies if comment support is enabled, disabled, or auto-detected based on user permissions.

To learn more about recommended permission configurations, see Comment and Attachment Permissions.

In Planview Hub 20.1+, support was added for custom comment fields in ServiceNow. To configure custom comment fields in your integration, you will need to specify the names of the fields you would like to use upon configuring your ServiceNow repository connection. 

If you choose not to configure custom comment fields on the repository connection screen, default comment configuration will be used as shown below.

Catalog Variables on Requested Items

Depending on the associated Catalog Item, each Requested Item artifact can have a different set of variables associated to it in addition to the common artifact schema that all Requested Items share.

Hub supports Catalog Item variables with a single Catalog Variables string field. The content of this field is a mapping from the variable name (not label) to string value in JSON format, however, you can enable an enhancement for Planview Hub versions: 24.2 and later where Hub populates the readable label for reference type variables along with sys_id for Catalog Variables and Variable Sets of type "Reference" by setting includeLabel property true.

Note: Hub does not support Catalog Variable Sets in Planview Hub versions earlier than 21.4. 

You can map the variables individually from the single String field to multiple other fields using a Custom Data Transformation Extension.

This works for synchronizing variables both to and from Requested Item, though some restrictions apply:

• Hub only supports writing to variables of the following types: Single Line Text, Multi Line Text, Wide Single Line Text, Date, Date/Time, Select Box, Numeric Scale, and CheckBox.
• ServiceNow does not validate incoming variable values and stores them as strings regardless of variable type. If using this feature, you should be aware of the following:
  • Writing a value to a Select Box whose configured choices do not include that value results in ServiceNow displaying the value as the selected choice, but it will not be an option when selecting a new value.
  • Writing a value instead of true/false to a variable with type Checkbox results in ServiceNow displaying the value as an unchecked checkbox, but the value will still be retained as the variable value.
• The value of Select Box variables that the connector uses is the Value, not the Label of each choice. This means that Select Box variables configured to reference a Choice Table instead of its own list of Question Choices will only provide sys_id values to Custom Data Transformation extensions.

Requested Item artifacts additionally have a Catalog Item single-select field that can be used to restrict integration scenarios to include only the Requested Items belonging to a specific Catalog Item. This may be necessary to reduce the complexity of Catalog Variable mappings.

This system property allows users to get a readable label of the corresponding value for reference fields along with the sys_id for Catalog Variables and Catalog Variable Sets on Request Items. After adding this property, a user should expect reference-type variables to be represented as a string JSON with "label" and "id" properties.

For example:

For Cloud Installations

Please contact customer care to apply this system property.

For On-Premise Installations

To enable ServiceNow, include label property:

1. Find the property tomcat.custom.system.properties
2. If it is commented out, uncomment it
3. Add -Dcom.tasktop.connector.servicenow.servicedesk.catalogItem.referenceVariable.includeLabel=true to the end of this property

For example:

Or,  if there are other existing values in that property, add it after a comma at the end:

Note: this property can be applicable in case of catalog variable sets as well.

Reference Field Support as Single Select 

There are only a few out-of-the-box reference fields that the ServiceNow connector supports by default: user, configuration item, and assignment group. The connector will not expose or retrieve any other reference fields unless you specify them on the Repository/Tool Connection screen.

Note: User, configuration item, and assignment group are supported as Fast Reference Fields by default (see details below), and must be added as Full Reference Fields in order to support retrieving and mapping field values in Hub or writing to those fields in ServiceNow.

When setting up your repository/tool connection, you will have two options for how extensively to support reference fields: 

• Fast Reference Field Support: This option will work if you want to add fast, lightweight support for one or more reference fields. To enable this, add reference table column names, not labels (separated by commas). Using this configuration, the connector will only retrieve the available values on an as-needed basis and thus, the options will not be listed for simple value mapping. You will have to either pass in a correct value or use more advanced mapping configuration. A column name in this list overrides the same value in "Full Reference Field Support" list. Example value: "company, u_custom_reference"
• Full Reference Field Support: Listing column names here will add full support, meaning that the connector will retrieve all available options for a reference field (even if there are thousands). Note that listing all options can take a lot of time and memory depending on the number of values (records) in the reference tables. This option is recommended if you want to list field values or map them one by one. 

To find a sample table name, right click on the field (reference field) that you are interested in:

And then find the 'Element' line. 

Reference Field Support as Internal ARM Relationship Links

If you create a custom reference field that references another supported artifact type (table type), you will be able to integrate this field as an internal ARM (artifact relationship management) field and apply available relationship mappings (in Planview Hub).

Learn how to configure relationships in Planview Hub here.

Enabled Non-Task Extended Tables

If you'd like to use non-task extended tables, you will need to ensure that you have sufficient read/write permissions for the tables you'd like to use.

It is important to note that if the same table is listed in both the Enabled Non-Task Extended Tables field and the Full/Fast Reference Support field, the table will be supported as an artifact type, and any columns referencing the table will be treated as artifact links, not single selects.

Note: Formatted ID should be unique for Hub.

Execution Time Limit

Setting the execution time limit too low in ServiceNow may cause errors in logs and operations. See ServiceNow documentation for more information. 

Person Reconciliation

For person reconciliation, the following fields are available:

Learn more about how to configure person reconciliation in Planview Hub here.

Full Scan

Due to third party API limitations, changes to the following fields may not trigger change detection or cause a synchronization immediately.  To ensure these updates synchronize, a high fidelity full scan must occur or another qualifying change must be made to the artifact:

• 'Catalog Variables' field

Learn more about how to configure change detection and full scan intervals in Planview Hub here. 

Special Features Supported

Supported Work Items

Learn about the difference between containers and work items in Planview Hub here. 

Supported Containers

Learn more about containment in Planview Hub here.