Configure Strato Reporting via API

This article explains how to configure Strato Reporting via an API request.

Requirements

Make sure that Strato Reporting is installed in the Upgrade Center.

A foundational knowledge and experience with APIs and API client applications like Postman are required.

If creating a report on Workflows, ensure that the target Workflow is configured and working properly.

⚠️

Postman will be used as samples for this guide. There may be some differences in the instructions when using other applications.

Instructions

Create or Update a Report Configuration

To create a new Strato Reporting configuration or update an existing one, follow the steps below:

Type the URL in the format <System URL>/report/workflow/settings and set the method to POST.
💡

You can get the System URL from the General Settings in your Strato Admin Tool.
Go to the Authorization tab and set the Auth Type to Bearer Token. Fill in the Token field with your Bearer Token.
💡

Learn how to retrieve OAuth Token via API.
Go to the Body tab. Set the request body to raw and update the corresponding values:

{
    "id": "<optional, string>",
    "reportKey": "<string, unique>",
    "odataUrl": "<string>",
    "columnDefinitions": "<stringified JSON, string>",
    "tableDefinitions": "<stringified JSON, string>"
}

The table below provides an explanation for each of the keys and expected values:

Key	Required / Optional	Value
`id`	Optional	The unique ID for the report configuration. If you are updating an existing Strato Reporting configuration, add its ID here. If no value is added, a new configuration will be created.
`reportKey`	Required	Must be a unique value. If you are creating a new configuration or updating an existing one and you use an existing `reportKey`, the API will return an error.
`odataUrl`	Required	The URL to the OData entity you will use in the report. 💡 Learn more about the OData entities for Workflows and for Documents.
`columnDefinitions`	Required	The columns of your report. This must be in stringified JSON format. 💡 You can use a JSON formatter to convert your JSON to a string.
`tableDefinitions`	Required	The columns of your report. This must be in stringified JSON format. 💡 You can use a JSON formatter to convert your JSON to a string.

For the columnDefinitions, the table below provides an explanation for each of the keys and expected values:

Key	Required / Optional	Value
`accessorKey`	Required	The column field. This is based on the OData entities that are currently supported. 💡 Learn more about the OData entities for Workflows and for Documents.
`headerText`	Required	The text you want to appear as the column header. For spaces between text, use - (hyphen).
`type`	Required	The type of value in the column. This is used when doing basic search to determine what operand to use. If the type is “Date”, the text will be formatted in the default format, unless `dateFormat` is set in the column.
`enableSorting`	Optional	Allows the column to be sorted. Array columns are currently not supported.
`size`	Optional	The width of the column. The default is set to 200.
`isSearchable`	Optional	Specifies if the column will be searchable through basic search.
`isArray`	Optional	If the value you are trying to access is in an array or object, this will allow the report to find the data you are looking for based on the provided `accessorKey`.
`dateFormat`	Optional	If the value for the column is a date, the format can be set here. 💡 A list of supported patterns for the date format can be found here.
`isClickableLink`	Optional	Specifies if the object in the column is a clickable link. If the value in the column is a valid URL and this property is enabled, the value will display as a clickable link. Otherwise, the value should show as plain text.
`filter: {` `"key": "",` `"value": ""}`	Optional	Creates a custom column based on the filter values. The `key` would be the OData Entity to be filtered, and the `value` would be the value to be obtained. For example, a user wants to get the Status for the User Decision using a filter. In this case, the values would be: `key`: UserDecisions `value`: Status Additionally, the `accessorKey` should follow the format `Filter.Object.Value`: Filter: The word "Filter". Object: The same value as `key`. Value: The same value as `value`. Following the example above, the `accessorKey` would be `Filter.UserDecisions.Status`. ❌ Filter columns cannot be sorted and searched, and are not compatible with `isArray`.

A sample columnDefinitions in stringified JSON would look like this:

"[{
\"accessorKey\": \"<string>\",
\"headerText\": \"<string>\",
\"type\": \"<string | number | Date>\",
\"enableSorting\": \"<optional, boolean, false>\",
\"size\": \"<optional, number, 200>\",
\"isSearchable\": \"<optional, boolean, false>\",
\"isArray\": \"<optional, boolean, false>\",
\"dateFormat\": \"<optional, string, 'Pp'>\"
}]"

For the tableDefinitions, the table below provides an explanation for each of the keys and expected values:
Key
Explanation
dateRangeKey
Specifies the date range of the report.
isDateRangeDisabled
Specifies if changing the date range is disabled.
A sample tableDefinitions in stringified JSON would look like this:

Key	Explanation
`dateRangeKey`	Specifies the date range of the report.
`isDateRangeDisabled`	Specifies if changing the date range is disabled.

"{
\"dateRangeKey\": \"<string>\",
\"isDateRangeDisabled\": \"<string>\"
}"

Click Send. If done correctly, the API should return a success message and the report configuration should now show in Strato Reporting.

View Report Configurations

To view all existing Strato Reporting configurations, or a specific one, follow the steps below:

Type the URL in the format <System URL>/report/workflow/settings and set the method to GET.
💡

You can get the System URL from the General Settings in your Strato Admin Tool.
Go to the Authorization tab and set the Auth Type to Bearer Token. Fill in the Token field with your Bearer Token.
💡

Learn how to retrieve OAuth Token via API.
Go to the Parameters tab. If you want to view a single existing configuration, add a reportKey parameter with its corresponding value. Otherwise, if no value is provided, all existing configurations are returned.
Click Send. If done correctly, the API should return a success message and show the settings of all existing configurations (or a specific one if a reportKey has been specified).

Delete a Report Configuration

To delete a Strato Reporting configuration, follow the steps below: