ServiceNow TPRM

About this document

This document provides step-by-step instructions to configure the SAFE TPRM Connector in the ServiceNow portal.

Introduction

The integration between SAFE and ServiceNow enables synchronization of third-party records and risk insights across both platforms. SAFE automatically discovers and imports third parties from ServiceNow with their associated metadata, ensuring a unified and accurate vendor inventory.

This bi-directional integration also pushes aggregated risk metrics, SAFE Score, Likelihood, and Loss Magnitude, from SAFE back into ServiceNow.

Prerequisites

Get the SAFE TPRM Connector from the ServiceNow Store

1. Log in to your ServiceNow instance with admin privileges.

2. Navigate to the SAFE TPRM Connector page on the ServiceNow Store.
   
   

3. Click "Get" or "Request":

   1. If you have access to install the app directly, click the "Get" button.

   2. If you need approval from your ServiceNow admin, click "Request" to submit a request.

4. Check for prerequisites listed on the application page, including required roles or dependencies.

5. Follow the prompts to install the application into your instance.

6. After installation, navigate to the Application section in the ServiceNow instance and search for "SAFE TPRM Connector" to verify that it has been installed.

Pre-requisites for configuring the application

To configure the SAFE TPRM Connector, you need the following details:

1. SAFE API Base URL: SAFE One instance URL (e.g., https://us.safeone.ai/ )

2. SAFE API  Username and Password:  Refer to SAFE API Credentials.

3. Encoded Query for Data Filtering in ServiceNow: If you need to filter data from ServiceNow, provide the encoded query.
   The default query filters for vendors and third parties where both criteria are true.
   

4. Custom Field Mapping: Define the mapping between fields in ServiceNow and their corresponding fields in SAFE.
   Sample JSON to be present as a default value

   [
     {
       "serviceNowField": "city",
       "safeField": "City"
     }
   ]

5. Create the corresponding multi-valued custom field in SAFE to make ServiceNow custom fields visible. Refer to Custom Fields.

6. Update Metadata for Existing Organizations in SAFE: Check this option if you want to update metadata (such as revenue, country, and industry) for existing organizations in SAFE using data from ServiceNow.

7. Update SAFE Risk Assessment Values in ServiceNow: Check this option to synchronize the SAFE Risk Assessment values (SAFE Score, Likelihood, and Loss) into ServiceNow.

Configure the SAFE TPRM Connector

To configure the SAFE TPRM application in ServiceNow:

1. Search for SAFE TPRM Connector in the ServiceNow portal.

2. In the application menu, select Configure.

3. Enter the SAFE API Base URL, Username, and Password.

4. Enter the Encoded Query to filter data from the ServiceNow table for further processing. If no custom query is provided, the default query will filter for records where the organization is both a vendor and a third party. Ensure the query aligns with the specific filtering requirements.

5. Enter the Custom Field mapping.

6. Click Save.

7. You should see a message stating 'Properties updated,' confirming that the credentials have been saved.

Sync ServiceNow Third-Parties with SAFE

To sync ServiceNow third parties into SAFE via the SAFE TPRM connector:

1. Search for SAFE TPRM Connector in the ServiceNow portal.

2. In the SAFE TPRM Connector application menu, select Sync Third Parties.

3. Click the Test Connector button to validate the connection.
   

4. Once validated, click the Sync Third Parties to SAFE button.
   

5. A progress bar will be displayed, indicating the progress of sync. Once the progress bar reaches 100%, a pop-up window will display the final statistics, including:

   1. The number of successfully onboarded third parties

   2. The number of third parties that failed to get onboarded/updated

   3. The number of skipped third parties

   4. The number of third parties successfully updated

View Sync History

1. Search for SAFE TPRM Connector in the ServiceNow portal.

2. In the SAFE Asset Connector application menu, click on Sync History Table.

3. You will see the Sync History table, which provides a comprehensive overview of the sync history.
   

View Results

Once the SAFE TPRM Connector is configured and synced, SAFE automatically imports all third parties from ServiceNow and lists them under “Newly Discovered” in SAFE. Refer to Auto-Discovery via Integrations.

To view the SAFE Risk Assessment Value in ServiceNow

1. Search for Companies in the ServiceNow portal.

2. The SAFE Risk Assessment values (Score, Likelihood, and Loss Magnitude) are visible.

To view the SAFE Risk Assessment Values in ServiceNow for the Companies in the Form View

1. Follow the ServiceNow documentation to update the Form View using the Form Builder.

2. Add SAFE Risk Assessment Fields:

   • Search for the fields SAFE Score, Likelihood, and Loss Magnitude in the left column.

   • Drag these fields into the form layout under the appropriate section (SAFE Risk Assessment).

   

3. After adding the fields, click Save.

4. Once saved, the SAFE Risk Assessment values will be visible on the Form View whenever a company record is opened in the core_company table.

   

FAQs

How do I map the country defined in ServiceNow to the accepted SAFE country name?

The SAFE TPRM Connector allows you to map country names in the core_company table of ServiceNow to the corresponding country names accepted by SAFE. For example, you can map "USA" (in ServiceNow) to "United States of America" (the SAFE standard country value). To update these mappings, navigate to <ServiceNow Portal Base URL>/x_safse_safe_tprm_safe_country_mapping_list.do and update the "User Defined Country" field to match the appropriate SAFE standard country name.

How do I map the industry defined in ServiceNow to the accepted SAFE industry name?

The SAFE TPRM Connector allows you to map industry names in the core_company table of ServiceNow to the corresponding industry names accepted by SAFE. You can also provide multiple comma-separated industry values for mapping. For example, you can map "Entertainment, Media, Recreation" (in ServiceNow) to "Entertainment & Arts" (the SAFE standard industry name). To update these mappings, navigate to <ServiceNow Portal Base URL>/x_safse_safe_tprm_safe_industry_mapping_list.do and update the "User Defined Industry" field with the appropriate SAFE standard industry name(s).

How do I troubleshoot sync errors in the SAFE TPRM Connector?

Check the ServiceNow logs for any error messages related to the SAFE TPRM Connector. Verify that all required fields are properly mapped, the API credentials are correct, and that the integration is configured according to SAFE's prerequisites.

How often does the synchronization happen between the SAFE TPRM connector and SAFE One?

The synchronization of onboarding third-party organizations and updating SAFE Risk Assessment values is triggered by predefined scheduled jobs in ServiceNow. This ensures periodic synchronization between the two systems. Users can adjust the synchronization schedule by following these steps:

1. Navigate to the Scheduled Script Executions List at <ServiceNow Portal Base URL>/sysauto_script_list.do.

2. Search for and select SAFE TPRM Connector Full Sync - Cron.

3. Modify the scheduled time and frequency as needed to fit your requirements.

What user permissions are required to configure and run the SAFE TPRM Connector?

You will need admin-level privileges in both ServiceNow and SAFE One to install, configure, and run the connector. Ensure that the ServiceNow user account has access to the core_company table and any related tables that contain third-party information. SAFE API credentials with appropriate access rights are also required.

Why are organizations skipped during onboarding in the SAFE TPRM Connector?

Organizations may be skipped during onboarding if they are missing essential fields required by SAFE for successful integration. The key field that must be present for discovery is the organization’s Name.

If this field is missing, the organization will be excluded from the discovery process. You can review the logs to identify which specific information is missing and update it before attempting onboarding again.

Why are custom field values still visible in SAFE after removing the custom field mapping from the configuration?

This is the expected behavior. When custom field mappings are removed from the configuration, the values that were previously synced for those fields remain in SAFE. The removal of the mapping prevents future updates or syncing of the custom fields, but does not automatically delete or remove the existing values in SAFE. You will need to manually clear or update those custom field values in SAFE if you no longer want them to be displayed.

Why are the SAFE Risk Assessment values (SAFE Score, Likelihood, and Loss Magnitude) not visible in the core_company table?

If the SAFE Risk Assessment values are not visible in the core_company table, it could be because these columns are not displayed by default.

You can easily add these columns to the view by using the Personalize List option in ServiceNow:

1. Navigate to the core_company table in ServiceNow.

2. Click the Personalize List icon (gear icon) located in the upper-left corner of the table.

3. From the list of available columns, select Likelihood, Loss Magnitude, and Annualized Loss.

4. Add these columns to your current view and click Save.