In this article
This is an introduction to using the Forsta Visualizations Data Export API. Using the API allows for download of metadata and case data from your Forsta Visualizations projects
Using the API will require programming knowledge to create an API client.
Getting started with the Data Export API
Basics
Access - Who Can use the API?
All Forsta Visualizations admin accounts have access to the API to download data from the projects for which they have access.
Where do I find the API endpoint (the URL used for the API)
It is on all live installs, always named host name + “-dataapi” –
A couple of examples:
If you use dc.dapresy.com then the endpoint is dc-dataapi.dapresy.com,
for live.dapresy.com the end point is live-dataapi.dapresy.com
If you use a vanity URL, e.g. yourcompany.dapresy.com you will need to use the main URL for the install to find the end point, if in doubt please contact support to get the correct address.
Where is the Swagger documentation?
All of the installs have the Swagger, our demo installs are here:
https://dashboards-dataapi.dapresy.com/ - Europe
https://dashboards-na-dataapi.dapresy.com/ -- US
To use the Swagger to test functions you must use the relevant one for the server where you have your admin account.
To use the API you will need to create an API client (i.e. a custom sol, for further information and resources please refer to the articles here in the manual.
If you know the ID of the project you want to download then you can use that directly. If you need to browse available projects to get an ID, you will need to use a different API to get the details of available projects or simply login to the application to find the ID. Please refer to the guide for working with users and projects for details of retrieving available projects.
Endpoints
Export Metadata
Call this to download the project metadata, the only required parameter is the numeric project id.
Export
Call this to download the project data.
File Formats
This initial version of the export API supports JSON files. Further formats will be added over time.
The schema of the JSON matches the import format, so it is possible to use the import API to upload a data file downloaded from the export API. Some of the options below will cause issues with this, it would not be appropriate to upload grouped answers for instance.
Options
DataExportFormat
Should be set to "JSON", support for other formats is planned to be implemented soon. (Q2 and Q3 2021)
ExportStackedData
Include stacked data as separate files. Defaults to true.
IncludeGroupedAnswers
Whether to have grouped answers in exported data. Defaults to false.
IncludeComputeVariables
Download user defined variables. Defaults to false.
IncludeInputVariables
Include the input variables used, of rinstance, in forms for closed loop management, Defaults to false.
IncludeMergedVariables
Allow for the download of merged variables, which are multiple choice variables created by admins grouping existing variables. Defaults to false.
CheckDataExportStatus
Used to get the status of the export. Pass the RequestID from the Export request and the same project ID. When complete this will return a link to the file(s) for the data.
When ready the Status will be StatusCode "SUCCESS" and the Data element will have links will be in th Files array - first file is main data, subsequent files are the stacked data if present.