ServiceNow Integration V1: Implementation Guide

This article provides information for CyberGRX customers to get setup with the CyberGRX Risk Exchange V1 integration with the ServiceNow Third-party Risk Management plugin. Please refer to the related article for more information on the end user experience and integration features and functionality. 

Prerequisites

To use this integration, your company must be:

• An active CyberGRX Customer
• An active ServiceNow VRM Customer
  • Plugins required - GRC: Third-party Risk Management
    • previously named GRC: Vendor Risk Management
  • API V1: Tokyo version - supported and available on the ServiceNow Store
  • API V1: Utah version - supported and available on the ServiceNow Store as of Nov. 2023
  • API V1: Vancouver version - supported and available on the ServiceNow Store as of Dec. 2023

With the release of our CyberGRX API V2 and the planned End of Life for CyberGRX API V1, we are working on transitioning the ServiceNow Integration to the CyberGRX API V2. Previously released versions built on the API V1 will no longer function with the API V1 EOL and will be deprecated. The API V2 Integration with ServiceNow will allow for easier testing and additional functionality.

• API V2: Vancouver version - In Development, Targeted for availability in late Q2 2024
• API V2: Washington version - In Plan, Targeted for availability in early Q3 2024

Not a customer? Contact the appropriate sales team to get started! 

Integration Installation

As a ServiceNow admin, log into the ServiceNow Store and Search for the "CyberGRX Risk Exchange" integration. Select the "Request App" option and follow the instructions to deploy the application to the appropriate ServiceNow instance. 

CyberGRX Configurations

Once the integration is installed in your ServiceNow instance and you are logged into the ServiceNow instance as an admin, add the application-specific role created to your user “x_cgrx_cybergrx_ri.CyberGRX_admin”.  This role is required to have access to the CyberGRX Configuration and CyberGRX Scheduled Jobs views.

You will see a new section called "CyberGRX Configurations". 

API Token

The CyberGRX Admin user will need to create the API token. Please see here for instructions. 

Hostname

Hostname value for production is api.cybergrx.com

Hostname value for our test environment is demo-api.cybergrx.com*

* Please contact your CyberGRX representative for assistance with getting credentials to the test environment. 

Test Connection

Be sure to click "Test Connection" to verify that the API Token and Hostname values are correct and are saved.

Troubleshooting Info: Ensure that there are no spaces before or after the token or the hostname. Make sure the token is valid by going to https://api.cybergrx.com/v1/swagger/ and click the "Authorize" button in the top right and ensure a successful response is received. If not, refer back to the above instructions for creating the API token. 

Log Level

Select the log level of your choice. Log location will default to your existing ServiceNow log settings.

Import PDF

Check this configuration option if you want the CyberGRX PDF Report to be automatically attached to the completed assessments during the "Generating Observations" stage. This is only for Vendors that have been Synced with CyberGRX and have a CyberGRX Assessment requested.

Import Issue Type

Select which level of CyberGRX Findings you want automatically created as Issues for completed assessments during the "Generating Observations" stage. If nothing is selected then assessment issue creation will be skipped. This is only for Vendors that have been Synced with CyberGRX and have a CyberGRX Assessment requested. 

Test Connection

Be sure to click "Test Connection" to verify that all configuration values are saved.

Required Fields

There are a few fields that are required on the Vendor record in order to Sync with CyberGRX. These should be made required by the system admin.

• Name
• Website
• City
• Country

At the time the assessment is Submitted to Vendor, a Third Party contact must be filled in. Depending on your business process, adding the contact prior to submitting the assessment may be a training point.

System Properties

Setup a few system properties for the integration. This is to allow for enough time to pull the assessment results into ServiceNOW - it is a lot of data to load!

• In the navigator, search on "sys_properties.list"
• Select the New button to add 2 additional system properties 

• Set Name to "glide.http.outbound.max_timeout.enabled"
• Set Type to "true | false"
• Set Value to "false"
• Hit Submit

• Set Name to "glide.http.outbound.max_timeout"
• Set Type to "string"
• Set Value to "60"
• Hit Submit

 

Business Rules

Next we need to add some additional bypass logic to the out of the box business rules.

Submit to Vendor

Updating the "Submit to Vendor" business rule is done to ensure that when a CyberGRX assessment is ordered, the vendor is contacted by CyberGRX to complete the assessment and approval instead of getting the notification from ServiceNow to log into the Vendor Portal to complete an assessment.

• Go to filter Navigator -> System Definition -> Business Rules
• Search by name for "Submit to vendor" and click on that record

• Click the edit at the top - stay in the Global application - and click on the Advanced tab
• add the following code at the end of the existing first line after a return/new line
• if (((current.assessment_template).getDisplayValue()).startsWith("CyberGRX"))
  return;
• save the record

CreateAssessmentOnTierUpdate

Updating the "CreateAssessmentOnTierUpdate" business rule is done to ensure that when vendor record is flagged as a CyberGRX record, the system does not auto create an assessment record. 

• Go to filter Navigator -> System Definition -> Business Rules
• Search by name for "CreateAssessmentOnTierUpdate" and click on that record
• Click the edit at the top - stay in the Global application - and click on the When to Run tab
• Add the condition AND/OR "CyberGRX ID" "is empty"
• Update the record to save

 

Send single questionnaire: Questionnaire Table

Updating the "Send single questionnaire" business rule is done to allow the integration to create questionnaires under the CyberGRX assessment in order to populate the CyberGRX Coverage Scores and CyberGRX Risk Ratings for each group in our assessment.

• Go to filter Navigator -> System Definition -> Business Rules
• Search by name for "Send single questionnaire", associated with the Questionnaire table, and click on that record
• Click the edit at the top - stay in the Global application - and click on the When to Run tab
• Use Ctrl + Click on "Generating Observations" to unselect the state
• Update the record to save

User Management

Three application-specific roles will be created in your instance once the app is installed

“x_cgrx_cybergrx_ri.CyberGRX_admin”: For the CyberGRX Configuration and CyberGRX Scheduled Jobs pages

• As noted above, this role grants the user access to the integration administration pages
• This is the base integration role needed by a user

“x_cgrx_cybergrx_ri.CyberGRX_Manager_Sync”: For the Sync with CyberGRX and Unsync with CyberGRX buttons on the vendor record

• This is the primary user role for the integration functionality
• Allows the user to initiate the syncing of an existing vendor from ServiceNow to CyberGRX
• Users also need the “x_cgrx_cybergrx_ri.CyberGRX_admin” base role for this role to function

“x_cgrx_cybergrx_ri.CyberGRX_Manager_Create”: For the Create from CyberGRX button on the vendor table page

• • Only use this role if you intend to Create new vendor records in ServiceNow with CyberGRX information
  • If you have another process or integration to create new vendors in ServiceNow, you do not need to assign this role
  • Users also need the “x_cgrx_cybergrx_ri.CyberGRX_admin” base role for this role to function

You have the flexibility to assign these roles to the required users in order to provision application administration and use functionality. 

Bulk Upload - Optional

For existing customers who have vendors in both CyberGRX and ServiceNow, there are some additional steps to get the records synced between the systems.

In ServiceNow

• Navigate to the All Vendors table
• Add the new custom fields "CyberGRX Sync" and "CyberGRX ID" to your column view
• Either Select All Vendors or Filter Down to your Cyber relevant vendors
• Right click on any column name header
• Export -> Download those vendors and save that file (Vendor List 1)

In CyberGRX

• Navigate to the Portfolio Management -> Third Party Portfolio table
• Select the Download Portfolio xlsx option and save that file (Vendor List 2)
• Find the "Company ID" column

In ServiceNow

• Comparing the 2 files, edit the Vendor List 1 to add in the CyberGRX ID data from the "Company ID" column for the corresponding vendor record
• For all records with the CyberGRX ID, also set CyberGRX Sync = true
• Save the updated ServiceNow Vendor file with the additional values (Vendor List 2 updated)
• Navigate back to the All Vendors table
• Select Import and Update records

 

CyberGRX Scheduled Jobs

For ongoing syncing of data between the systems, there is another new section "CyberGRX Scheduled Jobs." All scheduled jobs only action on vendors where "CyberGRX Sync" = true

CyberGRX Sync Vendors

This daily job is to keep key vendor data points in sync from CyberGRX to ServiceNow

• CyberGRX Name
• Likelihood Score
• Likelihood Band
• Impact Score
• Impact Band
• Tier Ordered

CyberGRX Pending Sync

This daily job is to check if a newly requested "Pending" vendor on the exchange has been reviewed and added. Once the job sees that the vendor is created and in the portfolio, it updates CyberGRX Sync to True from Pending. 

CyberGRX Map CustomIDs

This daily job populates the "Vendor sys_id" from ServiceNow to the third-party "Custom ID" in CyberGRX. This is intended as a cross reference primarily for reporting or troubleshooting.

Note: Please ask your CyberGRX account manager to enable the Custom ID visibility in the CyberGRX UI. The integration functionality will work but the field display in the UI is not on by default. The "Custom ID" field will show under the Company Information tab on the Vendor Profile Page. 

CyberGRX Update Tags

This daily job populates "tags" that have been added to the Vendor record in ServiceNow to CyberGRX. Tags are a great addition for reporting and filtering in CyberGRX. 

If you do not wish to sync the vendor tags, deactivate the job.

CyberGRX Assessment Status

This daily job checks to see if assessments with a CyberGRX assessment template are ready to move from "Submitted to Vendor" to "Responses Received". This occurs when the vendor has both completed and authorized the CyberGRX assessment.

CyberGRX Assessment Results

This daily job runs after the assessment status is updated to "Responses Received" and will update the assessment status to "Generating Observations". Depending on the configurations selected, it will import the CyberGRX PDF Report and the CyberGRX Findings to the Issues table. The job also pulls into the Assessment -> CyberGRX area the Assessment Coverage Scores and Maturity Scores for review.