ServiceNow TPRM

1. About this document

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

2. Introduction

The integration between SAFE and ServiceNow enables SAFE users to discover and import ServiceNow third-party entities along with their associated metadata into SAFE. This bi-directional integration also sends aggregated risk data—such as Likelihood, Loss Magnitude, and Annualized Loss back to ServiceNow.

Once the risk data is calculated in SAFE, it is automatically populated in the corresponding core_company table within ServiceNow, under fields with the same names as those used in the SAFE Aggregate Risk. This ensures that risk insights are consistently reflected in both systems, helping organizations monitor third-party risks more effectively in ServiceNow while leveraging SAFE's advanced risk analysis capabilities.

3. Prerequisites

3.1 Get SAFE Asset Connector application from ServiceNow store

• Log in to ServiceNow:

  • Open your ServiceNow instance and log in with an account that has admin privileges.

• Navigate to the ServiceNow Store:

  • In the application navigator, type "Store" and click on ServiceNow Store to open the store page.

• Search for SAFE Asset Connector:

  • In the search bar of the ServiceNow Store, type "SAFE TPRM Connector" and press Enter.

• Select the SAFE Asset Connector Application:

  • Find the SAFE TPRM Connector in the search results and click on it to view the application details.

• Click "Get" or "Request":

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

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

  

• Review Installation Requirements:

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

• Install the Application:

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

• Verify Installation:

  • After installation, go to the Application section in the ServiceNow instance and search for SAFE TPRM Connector to ensure it's installed.

• Configure the Application:

  • Proceed with the configuration steps detailed in the next section.

3.2 Pre-requisites for configuring the application

• The Third-party Risk Management application should be installed.

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

  • SAFE ONE API Base URL (Mandatory) → SAFE One instance URL (e.g. https://us.safeone.ai/ )

  • SAFE API One Username and SAFE One API Password (Mandatory) →  Refer to generating SAFE API Credentials

  • 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.

  • Custom Field Mapping: Define the mapping between fields in ServiceNow and their corresponding fields in SAFE One.

    Sample JSON to be present as default value

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

  For custom fields to be seen in SAFE, the multi-valued any custom field needs to be created in SAFE. Refer to create custom field in SAFE One.

  • 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.

  • Update SAFE Risk Assessment Values in ServiceNow: Check this option to synchronize the SAFE Risk Assessment values (likelihood, loss magnitude, and annualized loss) into ServiceNow.

4. Configure the SAFE TPRM Connector

To configure 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 One API Base URL, Username and Password.

4. Provide the Encoded query to filter data from ServiceNow to be considered for further processing.

5. Enter the Custom Field mapping.

6. Verify your changes.

7. Click Save.

8. You should see a message saying Properties updated confirming that credentials have been saved .

5. Sync ServiceNow Third-Parties with SAFE

To Sync ServiceNow third-parties into SAFE via SAFE TPRM connector:

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

2. In the SAFE Asset Connector application menu, select Sync Third-parties.

3. Click the Sync Third parties button.

4. A progress bar will be displayed, indicating the progress of sync.

5. Once the progress bar reaches 100%, a pop-up window will display final statistics, including:

   1. The number of successfully onboarded third parties

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

   3. The number of skipped third parties

   4. The number of third-parties successfully updated

   

6. View Sync History

1. Search for SAFE TPRM Connectorin the ServiceNow portal.

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

3. You will see Sync History table that provides a comprehensive overview of sync history, including Last sync at, Last sync result, Details and Last Successful sync at.

   Open image-20240821-131848.p

7. View Results

Once the SAFE TPRM Connector is configured, SAFE pulls all the third-parties from ServiceNow and onboards them as Organizations in SAFE and also update the SAFE Risk Assessment values for the third-parties in ServiceNow.

To view newly onboarded Organizations:

1. Navigate to Third-party.

2. In the Organization List table, apply filter for Onboarding Source with value as ServiceNow TPRM.

3. Filtered list of Organizations onboarded from ServiceNow would show up.

To view SAFE Risk Assessment Value in ServiceNow

1. Search for Companies in ServiceNow portal.

2. The SAFE Risk Assessment values (Likelihood, Loss Magnitude and Annualised Loss) can be seen.

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 Likelihood, Loss Magnitude, and Annualized Loss 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.

   

8. FAQs

1. 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.

   

2. 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).

   

3. 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.

4. How often is the synchronization happens between 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.

5. 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.

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

Organizations may be skipped during the onboarding process if they are missing any of the essential fields required by the SAFE platform for successful integration. The key fields that must be present for onboarding include:

• Name

• Domain

• Industry

• Revenue

• Country

• Employee Count

If any of these fields are missing, the organization will be excluded from the onboarding process. You can review the logs to identify which specific fields are missing, allowing you to update the relevant information before attempting the onboarding process again.

7. 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.

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

If the SAFE Risk Assessment values—such as Likelihood, Loss Magnitude, and Annualized Loss—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.