Accessing Submissions
Last updated
Was this helpful?
Last updated
Was this helpful?
There are generally two ways of accessing submissions:
Through the UI.
Through the API.
There are a number of interfaces that can be used to examine and export the submission data of a form. These are as follows.
Form submissions can be seen by clicking on the Data tab on a form within the Developer Portal:
This is best treated as a form administrator or form developer review tool. Submissions containing many fields are not easy to review in the table view, and some field types may not display all the data captured in this view.
The Submissions page provides an administrative overview of submissions to a form.
The Data tab's table only displays the fields that had “Table view” selected on them. To add or remove fields from this display, edit the field on the Form Edit page and uncheck “Table View.”
Developer Portal users with sufficient permissions can view, edit and delete individual submissions to forms. Use the icons on the right to perform these actions.
Use the two Export buttons at the top of the submissions list to export all of the submission data for the given form. These operations are streamlined directly from the database and will work on very large datasets without having to write everything out to the server before starting the download.
JSON (Javascript Object Notation) is a way of representing data in a standardized way for javascript applications. Many other programming languages and tools can read JSON as well. Since data in Form.io is stored in JSON format, this will be the truest form of the data.
CSV (Comma Separated Values) is another way of representing data. Data is squashed down to rows of values with commas between them. This may not work well for complex data structures as it is essentially a flat file. CSV files can be opened by spreadsheet applications like Excel.
Submissions data can be easily accessed via the API. This allows submission data to be used elsewhere within the application, other places in the Form.io platform, or by entirely separate services within the customer environment.
The API provides many powerful and flexible ways to submit, collect, migrate, modify, or otherwise handle submission data.
For more detailed information, refer to the Form.io API reference:
To maintain security, API calls require some kind of authentication. This can take the form of passing JWT tokens in the header, invoking admin keys configured in the deployed environment, or generating temporary tokens.
Temporary tokens are short-lived and usually scoped to a limited purpose. Users will typically generate the token and then use it to make the desired call.
To understand this, consider a user who wants to download a PDF of an individual submission. To do so, they would use the following two calls:
GET a temporary download token:
Headers:
x-allow
GET:/project/{{projectId}}/form/{{formID}}/submission/{{submissionID}}/download
x-expire
3600
x-jwt-token
<Retrieved through the browser's Developer Tools > Storage > Local Store > formioToken>
GET a download of the PDF:
Where {{tempToken}} is the key (not the "token") contained in the body of the reply to the first call.
Consider a Developer Portal at http://localhost:3000.
From the Developer Portal Home, navigating to Doc Team Project > Doc Test Form > Data shows the Submission the user wishes to download as a PDF.
Selecting the Submission and clicking View shows the submission at http://localhost:3000/#/project/2468abc/form/1369def/submission/7777ghi
The Live Stage link shows as http://localhost:3000/qwertasdf
Observe the following:
The projectURL is http://localhost:3000/qwertasdf
The projectID is 2468abc
The formID is 1369def
The submissionID is 7777ghi
Suppose the user found via Tools > Developer Tools > Storaage > Local Storage that
The formioToken is 1z1y2x35w81v32u1 (in practice it will be significantly longer)
The user would use their preferred API tool (such as Postman) to send the following request:
x-allow
GET:/project/2468abc/form/1369def/submission/7777ghi/download
x-expire
3600
x-jwt-token
1z1y2x35w81v32u1
When this is successful, the body of the return will contain both the x-jwt-token submitted by the user as well as a "key" required to issue subsequent calls:
The user would record the key value (GZZFpJsyYQTWoKCdPJOyYfKRZj2GBW) for use in the second request.
Next the user would make the following request:
Note that the endpoint mirrors the scope set in the previous requests x-allow value.
For this call, the key from the previous call is supplied as the parameter by appending
?token=GZZFpJsyYQTWoKCdPJOyYfKRZj2GBW to the request.
This will return the PDF of the submission, accessed with the temporary token.
The same process is used for a variety of calls requiring temporary tokens.
Troubleshooting: The most common errors when attempting to use a temporary token to make an API request are 400 and 440, which may both be reported as "Expired token." To resolve these, first ensure the jwt-token used to generate the temporary token is still valid and entered in its entirety. Next, ensure the that the scope of the temporary token matches that required of the intended request. A malformed x-allow header may still return a temporary token, but if the requested scope is mis-matched to the second request, it will appear expired. Finally, ensure the download request uses the key returned when requesting the temporary token.
