Skip to main content

ServiceNow Integration V2 - Setup Guide

Emily Makroy
Updated

This article provides information for customers to get setup on the Global Risk Exchange V2 Integration with ServiceNow Third-party Risk Management.

Please refer to the User Guide for more information on the end user experience and integration features and functionality. 

For information about supported ServiceNow versions, enhanced Integration functionality, and issues fixed, check out the Release Notes. 

 

Necessary Setup

Integration Prerequisites
Installing the Integration
Integration Admin Role
Configuring the Integration
- Authentication
- Assessment Results
- GRX Assessments
Modifying Business Rules
Required Fields
User Management

Informational Only

GRX Scheduled Jobs
Tiering Assessment
Questionnaire
Issues
Custom Tables

Optional Go Live Step

Bulk Upload

 

Integration Prerequisites

To use this integration, your company must be

  • An active ProcessUnity Global Risk Exchange Customer
    • Contract Add-On required: ServiceNow Integration
    • Talk to your Account Manager about pricing for the ServiceNow Integration Add-On Feature
  • An active ServiceNow TPRM Customer
    • Plugins required: Third-party Risk Management

 

Installing the Integration

The integration is installed using the ServiceNow Update Set functionality.

  • Save the Global Risk Exchange ServiceNow Integration xml file from your GRX representative
    • Ensure you have the file associated with the version installed on your ServiceNow instance
  • Login to your ServiceNow instance as an admin
  • Navigate to All -> System Update Sets -> Retrieved Update Sets
  • Click on "Import Update Set from XML"
  • "Choose File" to select the provided Global Risk Exchange ServiceNow Integration xml file 
  • Select "Upload"
  • Open the record for the update set just uploaded - state will be “Loaded”
  • Click on "Preview Update Set"
    • Wait for the process to finish
  • There will be some expected errors which we will skip importing
  • Select the check box at the top of the "Update Set Preview Problems" tab to select all errors
  • Click on "Actions on selected rows" and choose "Skip remote update"
    • Repeat until no records show in "Update Set Preview Problems" table
  • Lastly, click on the “Commit Update Set” button
    • Wait for the process to finish and click "Close"
  • The "Global Risk Exchange" application is now installed in the instance

 

Integration Admin Role

The following admin role is created as part of the installation: x_cgrx_cybergrx_ri.GRX_admin

This role needs to be assigned to yourself in order to proceed with the integration setup. Specifically, this role grants access to the GRX Configurations, the GRX Assessments, the GRX Scheduled Jobs and the GRX Applications Logs.

  • Navigate to All -> System Security -> User Administration -> Users
  • Search for your own user and open the record
  • Click the "Roles" tab and then "Edit" button
  • Search for x_cgrx_cybergrx_ri.GRX_admin in the available roles list
    • recommendation is to copy/paste when searching for the role
  • Assign this role to proceed with integration setup

 

Configuring the Integration

The following configuration pages are created as part of the installation and need to be updated for the integration setup.

Global Risk Exchange Menu.png

  • Navigate to All -> Third-party Risk Management -> Global Risk Exchange -> GRX Configurations

    • Click on the Authentication tab and complete the required fields first
    • Click on the Assessment Results tab and complete the required fields second
    GRX Configurations Menu.png

 

Authentication

GRX Configurations Authentication.png

API Hostname

  • Select the appropriate API hostname for the integration based on if you are in a production or test environment
    • Production: api.cybergrx.com
    • Test: demo-api.cybergrx.com

Client ID

  • Input the Client ID API credential provided by the GRX representative that matches the environment (demo or production)

Client Secret

  • Input the Client Secret API credential provided by the GRX representative that matches the environment (demo or production)

Token URL

  • Select the appropriate URL for retrieving the authentication token for the integration based on if you are in a production or test environment
    • Production: https://auth.portal.cybergrx.com/oauth/token
    • Test: https://auth.demo.cybergrx.com/oauth/token

API Token

  • Field to hold the session authentication token for the integration - no setup needed

Token Expiration

  • Expiration timestamp for the current authentication token - no setup needed

Validate Configurations

After making any changes, be sure to click "Validate Connections" to verify that the API Token and Hostname values are correct and pass the logic checks. Click "Submit" or "Update" to ensure configuration options are saved.

 

Assessment Results

GRX Configurations Assessment Results.png

Import Report Spreadsheet

  • Select if you want the Assessment Report Spreadsheet imported and automatically attached to the Third-party risk assessment record as part of the completed assessment results. This occurs during the "Generating Observations" stage.
    • See Third Party Portfolio -> Risk Profile -> Risk Navigator -> Download (XLSX) for reference when deciding
    • If "Import Report Spreadsheet" is selected, it will reference the "Framework ID: Report" from the GRX Assessment table for your preferred spreadsheet report format (reviewed below)

Import Report PDF

  • Select if you want the Assessment Report PDF imported and automatically attached to the Third-party risk assessment record as part of the completed assessment results. This occurs during the "Generating Observations" stage.
    • See Third Party Portfolio -> Risk Profile -> Risk Navigator -> Download (PDF) for reference when deciding
    • If "Import Report PDF" is selected, it will reference the "Framework ID: Report" from the GRX Assessment table for your preferred spreadsheet report format (reviewed below)

Import Issue Type

  • Select which questions from the completed GRX assessment you want automatically imported as Issues in ServiceNow, associated with the Third-party risk assessment record. This occurs during the "Generating Observations" stage. If nothing is selected then assessment issue creation will be skipped. 
    • See Third Party Portfolio -> Risk Profile -> Risk Navigator -> Finding Severity for reference when deciding
    • If any options in "Import Issue Type" are selected, it will reference the "Framework ID: Controls" from the GRX Assessment table for your preferred spreadsheet report format (reviewed below)
    • If High is selected -> High priority issues will be created for Cyber Controls where the Finding Severity is "HIGH"
    • If Moderate is selected -> Moderate priority issues will be created for the Cyber Controls where the Finding Severity is "MEDIUM"
    • If Low is selected -> Low priority issues will be created for the Cyber Controls where the Finding Severity is "LOW"
    • If Minor: Yes is selected -> Minor priority issues will be created for the Cyber Controls where the Finding Severity is null and the Third Party answered "Yes"
    • If Minor: NA is selected -> Minor priority issues will be created for the Cyber Controls where the Finding Severity is null and the Third Party answered "NA"
    • If Not Validated is selected -> High priority issues will be created for the Cyber Controls where "Validation Status" is "NOT VALIDATED" even though the Third Party answered "Yes"
      • This option would only apply for validated assessments

Validate Configurations

After making any changes, be sure to click "Validate Connections" to verify that the API Token and Hostname values are correct and pass the logic checks. Click "Submit" or "Update" to ensure configuration options are saved.

 

GRX Assessments

The following configuration pages are created as part of the installation and need to be updated for the integration setup.

The GRX Assessment table is a driver for Request options and Assessment Result options. 

Navigate to All -> Third-party Risk Management -> Global Risk Exchange -> GRX Assessments

GRX Assessments Menu.png
  • Hover over the dots on the field "Questionnaire" and right click
  • Import XML
  • Select the provided file: GRX_Assessments V2.4.xml

The provided xml file has our recommendations and defaults. If you have a custom framework or industry framework you would prefer, Frameworks can be updated. 

 

GRX Assessments Import Process.png

 

The GRX Assessment table has the following fields:

  • Assessment template
    • A lookup field to the ServiceNow "Assessment template" table, filtered to template names starting with "GRX"
    • The following Assessment templates have been created to support the integration and can be viewed by navigationg to All -> Third-Party Risk Management -> Assessment Setup -> Assessment Template. If you do not intend to use one of them for requesting assessments on third parties, the template can be deactivated. Other assessment template attributes may also be updated to fit your business process. However, do not edit the Name of the template.
      • GRX: Tier 1 Validated
        • Extensive and validated examination of a cyber risk program at the control level via strength, coverage and timeliness data via all the Cyber Controls and associated Metric effectiveness questions, as well as Validation of the 60 Critical Controls
        • Triggers request for the ProcessUnity Cyber Risk Questionnaire Controls and Metrics, Validated
        • Comparable with legacy Tier 1 Validated
      • GRX: Tier 2 Validated
        • Robust and validated examination of how a cyber risk program is implemented and managed via all the Cyber Controls and Validation of the 60 Critical Controls
        • Triggers request for the ProcessUnity Core Controls, Validated
        • Comparable with legacy Tier 2 Validated
      • GRX: Tier 2
        • Robust examination of how a cyber risk program is implemented and managed via all the Cyber Controls
        • Triggers request for the ProcessUnity Core Controls
        • Comparable with legacy Tier 2
      • GRX: Critical Controls Validated
        • Efficient and validated examination of how a cyber risk program is implemented and managed via the 60 Critical Controls and Validation of the 60 Critical Controls
        • Triggers request for the ProcessUnity Essential Controls, Validated
      • GRX: Critical Controls
        • Efficient examination of how a cyber risk program is implemented and managed via the 60 Critical Controls
        • Triggers request for the ProcessUnity Essential Controls
  • Questionnaire
    • A text field, not currently a driver for anything in the UI, it is only included to lay the groundwork for future enhancements
  • Metrics
    • True/False drives if Metric level questions and responses are included in the assessment request to the Third Party
  • Validation
    • True/False drives if the Validation process and results are included in the assessment request to the Third Party
  • Score Type
    • Attested vs Predictive
    • Note: Predictive is not yet supported, it is only included to lay the groundwork for future enhancements 
  • Framework: Controls
    • If any options in "Import Issue Type" are selected, this Framework drives controls evaluated for Import on completion of the assessment 
  • Framework: Report
    • If the "Import Report Spreadsheet" and/or "Import PDF Spreadsheet" options are selected, provide your preferred Framework ID to drive the format of the report imported on completion of the assessment 

 

Modifying Business Rules

After installation is complete, several business rules need to be modified in order to support the integration functionality.  

Submit to third-party

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

  • Navigate to All -> System Definition -> Business Rules
  • Search by name for "Submit to third-party" and click on that record

submit to tp list1.pngsubmit to tp details1.png

  • Click the edit at the top - stay in the Global application
  • Click on the "Advanced" tab
  • Put your curser at the end of the existing first line and hit return to go to a new line
  • On the new line, copy/paste to add the following code:
if (((current.assessment_template).getDisplayValue()).startsWith("GRX"))
return;
  • Click on the "Update" button to save the changes to that record

 

Assessment Creation Manual - CreateAssessmentOnTierUpdate

Updating the "CreateAssessmentOnTierUpdate" business rule is done to ensure that when a third-party record is flagged as a GRX record, the system does not auto create an assessment record. The assumption is that the user will manually create the assessment record and select one of the GRX assessment templates.

  • Navigate to All -> System Definition -> Business Rules
  • Search by name for "CreateAssessmentOnTierUpdate" and click on that record

create on tier update list1.png

  • Click the edit at the top - stay in the Global application
  • Click on the "When to Run" tab
  • Click on "Add Filter Condition"
  • Add the condition AND/OR field "GRX Sync" + "is not" + value "true"
  • Click on the "Update" button to save the changes to that record

createassessmentontierupdate details.png

 

Assessment Creation Automatic - Tier-Based Submission

Alternatively, instead of updating "CreateAssessmentOnTierUpdate" business rule, you can configure the Tier-Based Submission rules to tie to the GRX assessment templates when a third party tier is set or updated.

tier rules1.png

 

Send single questionnaire: Questionnaire Table

Updating the "Send single questionnaire" business rule is done to allow the integration to create questionnaires under the GRX Third-party risk assessment record. There will be a questionnaire for each Risk Domain of the assessment and it will hold the GRX Coverage Scores and GRX Risk Ratings, showing how well the third party did on the assessment.

  • Navigate to All -> System Definition -> Business Rules
  • Search by name for "Send single questionnaire", associated with the Questionnaire table, and click on that record

send single questionnaire list1.png

  • Click the edit at the top - stay in the Global application
  • Click on the "When to Run" tab
  • Use Ctrl + Click on "Generating Observations" to unselect that option for Assessment.State
  • Click on the "Update" button to save the changes to that record

send single questionnaire details 1.png

 

Required Fields

There are a few fields that are required on the Vendor record in order to "Sync with GRX". These should be made required by the system admin when creating or updated a Vendor record in ServiceNow.

  • Name
  • Website
  • Country

At the time the assessment is Saved as Draft or Submitted to Vendor, a Third Party contact must be associated with the Third Party record. Depending on your business process, adding the contact prior to submitting the assessment may be a training point.

 

User Management

These roles need to be assigned to the appropriate individuals in order to experience the full integration functionality.

  • Navigate to All -> System Security -> Users
  • Search for Users 
  • Assign the appropriate role based on the User's needs

roles1.png

 

GRX Admin Role: x_cgrx_cybergrx_ri.GRX_admin

  • This application-specific role grants the user access to the following functionality in the "Global Risk Exchange" module
    • GRX Configurations
    • GRX Assessments
    • GRX Scheduled Jobs
    • GRX Applications Logs
  • Assign this role to TPRM users authorized to make Risk Management process decisions and run ad hoc jobs and assist with troubleshooting
  • The assumption is that this an add on role to a user with an OOB TPRM role, such as a Third-party risk admin [sn_vdr_risk_asmt.vendor_risk_admin]

GRX Sync Role: x_cgrx_cybergrx_ri.GRX_sync

  • This application-specific role grants the user access to the following functionality
    • Sync with GRX
    • Unsync with GRX
    • Add Vendor to GRX
    • Global Risk Exchange View
  • Assign this role to TPRM users authorized to add companies to your GRX Third Party Portfolio
  • The assumption is that this an add on role to a user with an OOB TPRM role, such as a Third-party risk manager [sn_vdr_risk_asmt.vendor_risk_manager] or Third-party risk assessor [sn_vdr_risk_asmt.vendor_assessor]

GRX View Role: x_cgrx_cybergrx_ri.GRX_view

  • This application-specific role grants the user access to the following functionality
    • Global Risk Exchange View
  • Assign this role to TPRM users authorized to see GRX information on companies in your Third Party Portfolio
  • The assumption is that this an add on role to a user with an OOB TPRM role, such as a Third-party assessment reviewer [sn_vdr_risk_asmt.vendor_assessment_reviewer]

view_changer

  • This out of the box ServiceNow role allows a user to change a "view"
    • For ease of use, a "Global Risk Exchange" view has been created as part of the integration
  • Assign this role to TPRM users with the GRX Sync or GRX View role if you want them to be able to switch between the "Global Risk Exchange" view and "Vendor Risk" view

snc_internal

  • This out of the box ServiceNow role allows a user to be assigned as a tiering assesser on a third party tiering assessment
  • Assign this role to TPRM users who understand the vendor business relationship and can answer questions about how the third party does business with your company

 

GRX Scheduled Jobs

No setup required, this section is informational only.

The following scheduled jobs are created as part of the installation. These jobs power the integration and the flow of data between ServiceNow and the Exchange. All scheduled jobs only action on vendors where "GRX Sync" = true

GRX Scheduled Jobs Menu.png
  • Navigate to All -> Third-Party Risk Management -> Global Risk Exchange -> GRX Scheduled Jobs
  • Click to view the installed scheduled jobs to support the integration functionality
  • Once a day is typically frequent enough. However, the frequency of the job can be updated if needed by your business process to a max of 4 times a day
GRX Schedule Jobs.png

GRX Sync Vendors

This daily job is to keep third party data points in sync from GRX to ServiceNow. These custom fields are located on the Third Party record, on a new tab called GRX Profile.

GRX Update Custom ID & Tags

This daily job populates the "Vendor sys_id" from ServiceNow to the third-party "Custom ID" associated with the Third Party record in your portfolio. The "Custom ID" field will show in the Exchange portal under the Relationship tab on the Third Party Profile Page. This is intended as a cross reference primarily for reporting or troubleshooting.

This daily job also populates "tags" that have been added to the Vendor record in ServiceNow over to the Third Party record in your GRX portfolio. Tags are a great addition for reporting and filtering on your Third Party portfolio.

GRX Assessment Status

This daily job checks to see if Third-party risk assessments with a GRX assessment template are ready to move from "Submitted to Vendor" to "Responses Received". This occurs when the vendor has both completed and authorized the GRX questionnaire. In the case where you have requested a Validated assessment, both the questionnaire and the validation must be completed and authorized for the assessment to update to "Responses Recieved".

Custom fields reporting on the progress of the assessment are located on the Third-party risk assessment record, on a new tab called GRX Assessment:

GRX Assessment Results

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

GRX Delete Import Issues

This daily job runs on the custom GRX Import Issues working custom table to delete and cleanup the working records. The final information is saved to the Issues table based on the selected configurations. 

 

 

Tiering Assessment

No setup required, this section is informational only.

The following tiering questionnaire template is created as part of the installation. 

  • Navigate to All -> Third-Party Risk Management -> Tiering Setup -> Tiering Questionnaire Template
  • Click to view the installed tiering assessment template to support the integration functionality
  • If you do not intend to use it as part of your business process, the template can be deactivated

IQ template1.png

GRX: Impact Questionnaire

  •  
    • Global Risk Exchange provided tiering questionnaire to determine the Third Party impact on the business, in the event they experience a cyber incident. Triggers recalcuation of Inherent Risk and drives impact associated with assessment findings. 

To leverage the GRX: Impact Questionnaire, the third party record must have GRX Sync = true. Once the user "Assigned to" completes the 8 impact questions, the Tiering assessment will move to the "Tiering Assessment" state. 

Note: To answer the questions, tiering assessors should have the "snc internal" role. They must login with their ServiceNow credentials and search for "My assessments and surveys".

 

Questionnaire

No setup required, this section is informational only.

The GRX Assessment Results job will pull in Assessment information into the following standard Questionnaire fields, as well as 2 additional custom fields:

 

Questionnaire Field Value
Assessment Questionnaire is linked to the associated Assessment record
Third-party risk area Set to "Cybersecurity Risk"
Percent complete Set to 100%
Name Set to the GRX Risk Domain
GRX Coverage Score (custom field) Set to the GRX Risk Domain coverage score - how well the third party scored across that collection of questions
GRX Risk Rating (custom field) Set to the GRX Risk Domain risk rating - rating associated with how well the third party scored across that collection of questions

 

If users want to see the GRX Risk Rating and GRX Coverage Score custom fields in the Questionnaire list table, they will need to use the gear icon to update the columns in the Questionnaire table. 

When viewing a Questionnaire record, the user should be in the "Global Risk Exchange" view.

 

Issues

No setup required, this section is informational only.

If the Configuration field "Import Issue Type" is set, the GRX Assessment Results job will pull in Assessment information into the following standard as well as custom Issue fields.

 

Issue Field Value
State Set to New
Third Party Issue is linked to the associated Third party record
Assessment Issue is linked to the associated Assessment record
Classification Set to Vendor Risk
Priority Based on the GRX Cyber Control Finding Severity or if the Control fails validation in the "Not Validated" case
Impact Based on the GRX Cyber Control Impact, driven by the answers to the tiering assessment "GRX: Impact Questionnaire"
Correlation ID Set to the GRX Cyber Control ID
Name Set to the GRX Cyber Control Name. Note this field is displayed to the Third Party if "Visible in third-party portal" is checked
GRX Question Prompt (custom) Set to the GRX Question Prompt. 
GRX Answer (custom) Set to the GRX Answer.
GRX Score (custom) Set to the GRX Score.
GRX Score Basis (custom) Set to the GRX Score Basis.
GRX Validation Status (custom) Set to the GRX Validation Status.
GRX Evidence Type (custom) Set to the GRX Evidence Type.
Description Set to the GRX Control Prompt, Answer, Score, Comment, Mitigation, and Validation. Note this field is displayed to the Third Party if "Visible in third-party portal" is checked

 

Custom Tables

No setup needed, this section is informational only.

The following custom tables are created as part of the installation. 

  • Navigate to the All -> System Definition -> Tables
  • Add the Application column to your view (if not displayed) via the gear icon
  • Search on Application = Global Risk Exchange
GRX Custom Tables.png

GRX Configurations

  • Holds the integration configurations for Authentication and Assessment Results customized above

GRX Assessment

  • Holds the integration configurations for GRX Assessments customized above

GRX Import Issues

  • Staging table for the import of Issues during the GRX Assessment Results scheduled job

GRX Vendor Staging

  • Staging table for the import of third party records during the GRX Sync Vendors scheduled job

 

Bulk Upload - Optional

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

In ServiceNow

  • Navigate to the All -> Third-Party Risk Management -> Third Parties table
  • Ensure the third party Name, Website, and preferrably address/country are in the view
  • Add the new custom fields "GRX Sync" and "GRX 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
  • Provide the file to your GRX Representatives to help with record matching
    • this process may take several business days
  • Populate the GRX ID data from the "Company ID" column provided by GRX
  • For all records with a GRX ID, also set GRX Sync = true
  • Navigate back to the All Vendors table
  • Select Import and Update records

Was this article helpful?

0 out of 0 found this helpful
Return to top

Related articles