Views (API Integration)

Overview

View Reports enable seamless API integration, allowing retrieval of records with a defined subset of fields. They also provide access to Images and Documents through temporary public links to files stored in blob storage.

Unlike Table Reports, View Reports operate exclusively for API Integration, reducing the risk of unintended edits. This ensures a clean, organised, and reliable reporting section in your App Config for API integrations.

• Creating A View Report
• View Property Configuration
• API GET Call for App Data via the View
• Example View API Call with an Image and a Document

Creating A View Report

Access the Application that you would like to add a View Report to in App Studio and then

1. Use the left pane menu to click on the Reports folder in App Studio
2. Then click on the View Report Type from within the Reports folder.
3. To Add a new View, click on the + next to the View sub folder or click on the Add button at the bottom of the screen and select the View Report.
4. To Edit a View Report open the View sub folder and then click on one of the existing View Reports in the List.

In our Contracts App, we click on the Reports Folder, then on the View sub folder and select the View Report to see the current configuration which we can then edit.

View Property Configuration

Once in the Add or Edit View screen there are a number of configuration options to consider. We will now run through each one and explain how they impact on the functionality of the Report. The View Report is exclusively for calling via the API and so there are not the usual visual properties on this Report.

Title, Identifier & Description

The Title is the primary reference to the Report and appears as the friendly reference in App Studio in the list of views. It is most common to label the view by the purpose of the Report such as 'Data For PowerBI' or 'Access to Contract Document via API'

The Identifier is a system ID for referencing a Report. This ID must be unique per Report and must contain only letters and numbers starting with a letter. It must also be a minimum of three characters. This will be used later in the API Call to 

The Description allows you to detail the purpose of the Report for API Integration. This is essential for proper App Governance as it will remind you what the purpose of the View is or maintenance needed as well as allowing you to inform other App Builders. This minimises the risk of another App Builder inadvertently breaking an integration by editing a Report that they were unaware was critical to the process. 

View Fields

Define which fields should be included in your View Report. Only the selected fields and the Record ID will be returned for each Record when an API request is made for the specific View Report.

1. Scroll down to see the View Fields section of the View Report Configuration
2. Click on Add View Fields to start adding Fields
3. You can also optionally include Built-In Fields that are available in all Apps
   • Created Date
   • Updated Date

When clicking on the Add View Fields option, it will allow you to multi-select Fields. Some Fields oof note are Image and Documents which when the View is called will return a link to be able to access the image or document for further use in your integrations.

API GET Call for App Data via the View

Now that we have configured the View, we use the Softools Gateway API to call it and get the record data that is in the configured Fields. Refer to Softools Developer Documentation for detailed API usage and filtering. We will run through a scenario here as well.

API Endpoint Structure

https://api-gateway.softools.net/Api/Apps/{AppIdentifier}/View/{ViewReportIdentifier}

This also needs to be accompanied by 'tenant' and 'apikey' authorisation headers. See the Softools Developer Documentation for more on authorising API Calls.

To limit the records returned via the View Report, use the query header parameter to apply filters in your API requests.

Provide an OData filter string in the format 

[fieldIdentifier] operation filterValue

Here are the common operators that would be used but again consult the Softools Developer Documentation for full functionality

Example View API Call with an Image and a Document

Lets look at an example where we extract data from a Contracts App to display in Power BI with Images and Document Links

Step 1 -- Get the View Report Endpoint

If our App ID is Contracts and our View Report ID is ContractsView, then our endpoint is

https://api-gateway.softools.net/Api/Apps/Contracts/View/ContractsView

Step 2 -- Make the API Call

We use the endpoint with Authentication Headers of tenant and API Key. This returns to us a JSON in the form:

[
 {
   "ContractName": "Service Agreement - ACME Ltd",
   "StartDate": "2025-01-01",
   "EndDate": "2025-12-31",
   "ContractValue": 50000,
   "SignedCopy": "5a837273-8507-44f3-9738-447c036f4299",
   "SignedCopy_FileName": "Service+Agreement+ACME+Ltd+V4.pdf",
   "SignedCopy_Link": "https://softools.....net/.../SignedCopy_12345.pdf?sv=2025-11-07&sig=...",
   "SignedCopy_LinkExpires": "2025-11-08T15:19:18",
   "ClientLogo": "59cac81d-32a0-47f0-b682-662302bd30f4",
   "ClientLogo_Link": "https://softools.....net/.../ClientLogo_12345.png?sv=2025-11-07&sig=...",
   "ClientLogo_LinkExpiry": "2025-11-08T15:19:18"
 },
 {
   "ContractName": "Maintenance Deal - Beta Corp",
   "StartDate": "2025-03-15",
   "EndDate": "2026-03-14",
   "ContractValue": 25000,
   "SignedCopy": "a6d42f86-bf9f-4e17-b2bd-7d8f2936c3f2",
   "SignedCopy_FileName": "Maintenance+Deal+Beta+Corp+V12.pdf",
   "SignedCopy": "https://softools.....net/.../SignedCopy_67890.pdf?sv=2025-11-07&sig=...",
   "SignedCopy_LinkExpires": "2025-11-08T15:19:18",
   "ClientLogo": "b66aaf4a-8327-4c64-b311-6a93a085b262",
   "ClientLogo": "https://softools.....net/.../ClientLogo_67890.png?sv=2025-11-07&sig=..."
   "ClientLogo_LinkExpiry": "2025-11-08T15:19:18"
 }
]

Notice that there are multiple key/value pairs returned for the image and the document Fields. Both will return: 

• The ID of the image/document stored in Softools
• Temporary public URLs to files in blob storage. These URLs expire after a short period for security reasons
• The Expiry for the public URL links

The Document Field will also return the File Name for the Document 

Step 3 -- Load Data into Power BI

Use the Power BI Get Data from Web functionality using the API URL generated in Step 1. Power BI will connect and import the JSON Data.

Use Power BI’s Transform Data view to:

• Expand JSON columns into a tabular format.

• Create visuals such as tables or charts based on ContractValue or StartDate.
• Optionally display ClientLogo as an image and provide a clickable link to the SignedCopy document.

For more on PowerBI integration see our support article on Power BI Connection via the API Web Call.

Step 4 -- (Optional) Apply Filters via Query Parameters

You can limit records returned using an OData-style query filter.
Example: Retrieve contracts with a value greater than £5,000:

https://api-gateway.softools.net/Api/Apps/Contracts/View/ContractsView?$filter=[ContractValue]%20ge%2010000