API
      Back to home
      1. Unified Compliance Knowledge Base
      2. Common Controls Hub FAQs
      3. API

      How do I allow ServiceNow to access my account via the API?

      This FAQ provides step-by-step guidance for clients integrating ServiceNow with the Unified Compliance Framework – Common Controls Hub (UCF-CCH), using the current API key–based method.

      This guide is intended for our clients who rely on ServiceNow for compliance and control management.

       

      Applies to supported ServiceNow versions:

      • Vancouver

      • Washington DC

      • Yokohama

      • Xanadu

      Note: Older versions (e.g., Kingston, Jakarta) are deprecated and not covered here. We strongly encourage all clients to work with their ServiceNow team to upgrade to a supported version.

       

      CCH Customer Prerequisites:

      Applications that are configured to access your account via the API can read your CCH account, users, Authority Document lists, groups, initiatives, and other account data.

       

      ServiceNow Prerequisites:

      • Role required: admin
      • GRC: Compliance UCF (com.sn_comp_ucf) plugin

       

      1. Activate the GRC: Compliance UCF Plugin

      Plugin ID: com.sn_comp_ucf
      Subscription Required: Yes
      Role Required: admin

      Before you begin:

      • The plugin includes demo data and may activate related plugins.

      • The admin user must be in the global domain if domain separation or delegated admin is enabled.

      Installation steps:

      1. Navigate to All > System Applications > All Available Applications > All.

      2. Search for GRC: Compliance UCF or com.sn_comp_ucf.

      3. If the plugin is not listed, contact your ServiceNow support team to request access.

      4. Click Install. A message will confirm when the installation is complete.

      If you encounter an error stating another operation is in progress, make sure no other installations are running and that you’re operating in the global domain.

      2. Configure the Unified Compliance Integration

      1. Navigate to All > Policy and Compliance > Administration > Unified Compliance Integration.

      2. Open the UCF Configuration record.

      3. Fill in the following fields:

      Field Description
      Shared List Select the shared list from your UCF account
      Authentication Type Select API Key
      API Key Enter the API key provided by your UCF (Common Controls Hub) account
       

      1. Click Save Configuration.

      2. Then click Import Shared List.

      A progress bar will display the download and import status. When complete, a confirmation message will appear.

      :

       

      Known Issues When Importing Shared Lists into ServiceNow

      The following errors have been reported by users when importing UCF Shared Lists into ServiceNow. These are known issues within the ServiceNow platform, not the UCF API, but we’re listing them here to assist with troubleshooting and to guide you to relevant fixes.

       

      Error: "Error encountered while downloading UCF content. Try again or contact your system administrator for further assistance."

      This general error message may appear under several conditions:

       

      1. Internet Connectivity Loss

      This error will appear if your internet connection drops while downloading a Shared List.

      Solution: Reconnect to the internet and click Import Shared List to retry the download.

       

      2. Invalid or Deprecated Authority Documents

      This message can also indicate that some Authority Documents, citations, or mappings in the Shared List are either invalid or deprecated.


      Beginning in Policy and Compliance Management v12.0.4, ServiceNow sends an email to the UCF Administrator listing all invalid records.

      Solution:

      1. Review the email and click each link to examine the listed invalid records.

      2. Fix the identified issues (e.g., invalid documents, missing citations).

      3. Click Import Shared List again to retry.

      Note: ServiceNow controls this behavior via a system property:
      sn_comp_ucf.deactivate_deprecated_docs

      • When set to true (default), deprecated records are removed and a notification is sent.

      • When set to false, deprecated documents are retained, and the email is still sent.



      3. Resolution Shared by ServiceNow Support

      The last solution posted by ServiceNow’s support team has helped resolve this error in the past. You can also find this guidance on their community site, but here is a summary:

       

      Steps to try:

      1. Delete any records from the following tables:

        • [sn_comp_ucf_download_status_list](https://<instance name>.service-now.com/sn_comp_ucf_download_status_list.do)

        • [sn_comp_ucf_import_status_list](https://<instance name>.service-now.com/sn_comp_ucf_import_status_list.do)

      2. Ensure there is only one UCF configuration record in your system.

      3. If you're using the OAuth method, clear the access token.

      4. Clear the server cache by typing cache.do in the left-hand navigation.

      5. Return to the UCF integration page and try importing the Shared List again.

      If the error still persists after following these steps, contact ServiceNow support and include the steps you’ve already taken. This will help them resolve the issue more quickly by reviewing backend logs.

       

       

      Error: "The selected Shared List does not match the existing Authority Document list."

      This error is generated by ServiceNow and has to do with a limitation in how many Shared Lists clients are allowed to import.

      Historically, ServiceNow only supported importing one Shared List per instance. If a second Shared List was imported — and it didn’t match the previously imported list — users would receive this error.

       

      Solution:

      1. Reinstall the GRC: Compliance UCF plugin

        • Go to the Plugins module in ServiceNow.

        • Reinstall the plugin titled: GRC: Compliance UCF (com.sn_comp_ucf).

      2. Retry the import.

      If the issue continues:

      • Contact the ServiceNow support team.

      • Let them know that:

        • You are receiving the “Shared List mismatch” error.

        • You have already reinstalled the plugin.

        • You believe you are using the most recent version of the GRC: Compliance UCF plugin.

      • Ask them to verify whether the “multiple Shared Lists” feature is enabled for your instance.

      Only ServiceNow can enable this functionality if it’s currently restricted on your platform.

       

      Note: These known issues originate within the ServiceNow platform. Unified Compliance does not control the way Shared Lists are processed once our API delivers them. For further troubleshooting, please reach out to the ServiceNow support team or consult their documentation.

       

      Helpful Links