How to Use the Assurance API to Integrate with PowerBI

If you use PowerBI for your reporting, you can integrate with Assurance by following the steps below.

In this article, you will learn about:

• Setting Up an Integration API Key
• Setting Up a UUID in a Report to Transfer Data to PowerBI
• Setting Up an API Connection in PowerBI
• What To Do if I Am Getting Timeouts

Setting Up an Integration API Key

To set up an integration for your Assurance site, please submit a request to the CompliSpace Service Desk. Once the CompliSpace Service Desk has switched on the Integration for your Assurance site, please complete the following steps:

Navigate to the Administration Setting in Assurance by selecting on the Gear Wheel:

Select on Integration under the General section:

Select on API Key:

Please Note: If you do not see Integration or API Key, please submit a request to the CompliSpace Service Desk to have these settings turned on for you.

Select on the blue Create API Key button:

Name your API Key and select on the blue Save button:

The API key will appear in the list. Select on the Name:

Copy the Key and then select Activate:

The Key you have copied can now be used for set up in PowerBI. We suggest keeping this Key in a safe place for future reference.

You will now need to set up the API report in Assurance to enable the integration in PowerBI.

Setting Up a UUID in a Report to Transfer Data to PowerBI

Open the report you would like to use and navigate to the Report Settings section.

Select on the tickbox next to Available in API:

Save the report and it will then create a UUID, which will now appear under Available in API.

You now have all the information you need to complete setup in PowerBI.

Please Note: Summary & Trend Chart must remain unticked in your report in Assurance for the data transfer to work.

Once you have set up your API Report, you can select the refresh schedule from a range of available options:

• Every 1 hour (starting from midnight, at the top of the hour)
• Every 3 hours (starting from midnight, at the top of the hour)
• Every 6 hours (starting from midnight, at the top of the hour)
• Every 12 hours (starting from midnight, at the top of the hour)
• Every day (at midnight)
• Every week (at midnight on Monday)
• Every month (at midnight on the first day of the month)

Please Note: This will only work on reports that have been selected as Available in API.

Setting Up an API connection in PowerBI

Select on Get data from another source:

Then select Other > Web and select Connect:

The Web Data Connector form will then appear and should be completed as below:

1. Choose the Advanced option.

2. The URL parts should be in the format:

https://api.csassurance.com/api/v2/reports/{your-report-uuid}/snapshot.

For example, to set up a report with the UUID of 1234. The URL to be set up in PowerBI would be:

https://api.csassurance.com/api/v2/reports/1234/snapshot.

Please Note: If you are connecting to your sandbox site, the URL would be:

https://api.sandbox.csassurance.trycomplispace.com/api/v2/reports/{your-report-uuid}/snapshot.

3. Type to add the following HTTP request header parameters:

Step 3	Step 4
X-Api-Key	API Key from Assurance
X-Tenant	Your Tenant Name

Please Note: Your Tenant Name is in your Assurance URL:

4. Type to add the relevant details for the HTTP request header parameters selected in Step 3.

5. Select OK.

On the next screen, make sure Anonymous is selected on the left-hand side, and that the level applied is the URL you put in on the previous screen. If not select on the drop-down arrow to select the correct one:

Select on Connect.

Once the data connection is created in PowerBI, make sure to select on Close & Apply:

What To Do if I Am Getting Timeouts

If you are getting timeouts, we would suggest:

1. Applying at least some filters to avoid the inclusion of unnecessary data and to speed up the process of generating a report. To learn more about applying field filters, please refer to our Support Hub article on How to Add Custom Fields to an Assurance Report – Support Hub (zendesk.com).
2. Bringing in only those fields that would be useful in PowerBI. As a best practice, we recommend removing unnecessary fields from the report being pulled into PowerBI. This will keep your report free of unwanted fields, which can accumulate quickly and slow down your integration.
3. Checking what your network timeout is set to for PowerBI (or whatever tool they’re using), bearing in mind that some reports can take several minutes to process before they’re available.
4. Adopting the version 2 of the API endpoint (Ensure 'v2' is used instead of 'v1' in the URL).
5. Adopting the snapshot version of the API endpoint, which is much faster and can be automated to refresh based on a schedule. Please refer to our Support Hub article on How to Automate API Reports in Assurance – Support Hub (zendesk.com).

Important Note:

The v1 endpoint for Assurance reports is deprecated as of 1 December 2023. While it will continue to work through the new year, we strongly encourage anyone using the Assurance API reports to adopt the v2 version of the endpoint. (Just substitute 'v2' for 'v1' in the URL - everything else is identical.) The reason for this is that the v1 endpoint can hit certain internal limits when it comes to returning large amounts of data. The v2 version does not have that restriction - although, for really large datasets, we would encourage users to adopt the cache/snapshot strategy detailed in this guide.

You will notice the following changes:

• When using the Swagger-UI frontend, the v1 endpoint is greyed out (although still usable)
• Requests to the v1 version will now return a Deprecated HTTP header in the API response.