Introduction

A common use case for the Report API is to invoke the endpoint from an external system or process.

It would be possible to setup a nightly process (such as a cron job) to retrieve a report via the API, and push it to some external system via SFTP or some other endpoint per customer requirements. The ClinSpark API enables this, however all of the integrations including invoking the API must be designed and implemented by the customer outside of ClinSpark.

Customers that have questions about the usage of the Report API are encouraged to reach out via service desk ticket.

Permissions

Warning

In versions of ClinSpark prior to 23.3, the API does not recognize study restrictions (Restricted Studies) placed on the user (or ‘Service Account’). Any user, including programmatic / scripted users, accessing reports via the Report API will be able to access all studies.

On ClinSpark 23.3 and greater, the endpoint ‘invokeReport’ will prevent a given study report from generating if the user account does not have access to the study.

In order to successfully invoke a report, the user account needs to have the API role action, in addition to any role action or roles specified against the report to execute. These report permissions are established on an individual basis within the Administration > System Settings component.

An example of Role Action and Role restrictions in place for a given report. The API user must also have these to successfully invoke the report.

Performance

The response times will vary depending on what report is requested, parameters passed, and the underlying dataset the report is reliant on. This same principle applies to reports requested directly through the user interface - a request that may take several seconds or minutes to generate results will require users to wait until the report has finished and becomes available. Using the API to invoke reports is no ‘quicker’ than the same requests done directly from within the application.

Programmatic invocation of study reports however may cause a large number of requests to queue up over time. As all report requests are processed sequentially, it’s possible that use of the API to retrieve reports would queue ahead of reports requested through the user interface. Depending on time of day and frequency of requests, these may have impacts to study operational teams who are reliant on reports retrieved through the user interface.

Swagger Interactive Documentation