- About
- Initiate a CSV Export Job
- Check the Status of a CSV Export Job
- Download the Generated CSV File
About
Exporting multiple data records to a CSV is handled asynchronously by the ProntoForms system. Exports are retained in the ProntoForms system for 24 hours, after which they are purged. To successfully perform a CSV Export, you must:
- Initiate an Export Job. This will queue the export request in the ProntoForms system.
- Loop to check the status of the Export Job. Continue checking until the status indicates the export is complete. (Note: Each status check request counts toward your team's daily maximum)
- Check the success indicator of the Export Job. If the job completed successfully, you can proceed with the download step. If it failed, an error message will indicate what went wrong.
- Download the CSV Export. As mentioned, the CSV Export will be available for retrieval for 24 hours.
This API call does not handle Repeatable Section data. For this, you require the Single Form CSV Export.
Initiate a CSV Data Export Job
Use this method to initiate an export job. The request is put in queue, and a job identifier is returned. Retain this job identifier to query the status of the job, and fetch the final results when complete.
URL Structure
api.prontoforms.com/api/1.1/data/export.xml
api.prontoforms.com/api/1.1/data/export.json
Method
POST
Request Parameters
None.
Request Body Samples
The XML and JSON examples below show how to filter the data on several optional criteria. To remove the user-based filter criteria, simply exclude the [userIds] and [usernames] xml nodes from the request body. This will eliminate the need to specify individual user IDs or usernames in your filter. This is also the case for the form and form space filters -- simply remove these from the request body if they are not required.
The exportAddresses node is strictly optional and can be used to specify email addresses that should be notified when the export has completed. This is typically used as an alternative to the status check loop + retrieve combination.
XML
<exportData>
<tz>America/Vancouver</tz>
<filter>
<formIds><identifier>123</identifier></formIds>
<formSpaceIds><identifier>234</identifier></formSpaceIds>
<userIds><identifier>345</identifier></userIds>
<usernames><username>uname</username></usernames>
<startTime>2012-12-12T12:12:12Z</startTime>
<endTime>2012-12-12T12:12:13Z</endTime>
<timeFilterField>ServerReceiveDate</timeFilterField>
<state>Complete</state>
<executionState>HasFailed</executionState>
</filter>
<format>
<singleHeaderBlock>false</singleHeaderBlock>
<masterFormId></masterFormId>
<addQuestionTextHeader>true</addQuestionTextHeader>
<addQuestionLabelHeader>false</addQuestionLabelHeader>
<delimiter>,</delimiter>
<metadataFields>
<field>LocalSubmitterEntryTime</field>
<field>DeviceEntryTime</field>
<field>ServerReceiveTime</field>
</metadataFields>
<locale>en</locale>
</format>
<exportAddresses>
<email>test123@prontoforms.com</email>
<email>test456@prontoforms.com</email>
</exportAddresses>
</exportData>
JSON
{
"tz":"America/Vancouver",
"filter": {
"formIds": ["123"],
"formSpaceIds": ["234"],
"userIds": ["345"],
"usernames": ["uname"],
"startTime": "2012-12-12T12:12:12Z",
"endTime": "2012-12-12T12:12:13Z",
"timeFilterField": "ServerReceiveDate",
"state": "Complete",
"executionState": "HasFailed"
},
"format": {
"singleHeaderBlock": false,
"masterFormId": null,
"addQuestionTextHeader": true,
"addQuestionLabelHeader": false,
"delimiter": ",",
"metadataFields": [
"LocalSubmitterEntryTime",
"DeviceEntryTime",
"ServerReceiveTime"
],
"locale": "en"
},
"exportAddresses": [
"test123@prontoforms.com",
"test456@prontoforms.com"
]
}
Available Metadata Fields
The following values are valid for the metadataFields property:
- LocalSubmitterEntryTime
- DeviceEntryTime
- ServerReceiveTime
- Location
- FormSpaceName
- FormName
- FormVersion
- UserName
- DataRecordName
- ReferenceNumber
- LocationAddress
- DeviceOs
- DeviceOsVersion
- ProntoFormsClientSoftwareVersion
Note:The UserName column returns the user who last submitted the form, except for forms in an In Progress (Dispatched) status. In that case, the username corresponds to the user who currently has the form in their Inbox. This is important for forms with Editing enabled, or for forms with ProntoForms Teamwork (Enterprise Tier Only) enabled.
Time Filter Field Values
The following values are valid for the time filter:
- DeviceEntryDate
- ServerReceiveDate
- DataRecordProcessedDate
- DataRecordCompletedDate
- DataRecordLastUpdatedDate
Data State Values
- Uploading
- Uploaded
- UploadFailed
- Processing
- Processed
- ProcessingFailed
- Dispatching
- Dispatched
State Values
The following values are valid for the state filter:
- InProgress
- Declined
- Complete
- Incomplete
Execution State Values
The following values are valid for the execution state filter:
- HasFailed
- AllSuccessful
Response Body Samples
XML
<exportDataResult>
<identifier>export_id</identifier>
</exportDataResult>
JSON
{
"identifier": "export_id"
}
Sample cURL Commands
curl -v -k -u user:password -X POST --upload-file FILENAME.xml https://api.prontoforms.com/api/1.1/data/export.xml
curl -v -k -u user:password -X POST --upload-file FILENAME.json https://api.prontoforms.com/api/1.1/data/export.json
Important Note: Replace user with your API Key ID and password with your API Key secret. Also, replace FILENAME with the name of your actual file which should be formatted as per the XML or JSON request body samples above.
Error Codes
There are no method-specific errors for this method.
Consult the API Error Handling reference for general information on error handling.
Check the Status of a CSV Export Job
Use this method to check on the status of an executing export job.
URL Structure
api.prontoforms.com/api/1.1/data/export/[id]/status.xml
api.prontoforms.com/api/1.1/data/export/[id]/status.json
Method
GET
Request Parameters
None.
Request Body
None.
Response Body Samples
XML
<exportDataStatus>
<complete>true</complete>
<success>false</success>
<errorMessage>Invalid request data</errorMessage>
</exportDataStatus>
JSON
{
"complete": true,
"success": false,
"errorMessage": "Invalid request data"
}
Sample cURL Commands
curl -v -k -u user:password -X GET https://api.prontoforms.com/api/1.1/data/export/[id]/status.xml
curl -v -k -u user:password -X GET https://api.prontoforms.com/api/1.1/data/export/[id]/status.json
Important Note: Replace user with your API Key ID and password with your API Key secret. Also, replace [id] with your export ID.
Error Codes
There are no method-specific errors for this method.
Consult the API Error Handling reference for general information on error handling.
Download the Generated CSV File
Use this method to retrieve a completed CSV export.
URL Structure
api.prontoforms.com/api/1.1/data/export/[id].csv
Method
GET
Request Parameters
Parameter | Required | Default value | Description |
enc | no | UTF-8 | encoding type of the CSV file (ie. CP1252 for Windows encoding) |
Request Body
None.
Response Body
The contents of the CSV Export file.
Sample cURL Commands
curl -v -k -u user:password -X GET https://api.prontoforms.com/api/1.1/data/export/[id].csv
Important Note: Replace user with your API Key ID and password with your API Key secret. Also, replace [id] with your export ID.
Error Codes
Error Code Response Header |
HTTP Response Code |
Description |
---|---|---|
DataExportNotAvailable | 404 | The export is not available, either because it is not complete, failed, purged, or an export with the specified key was never created. |
Comments
1 comment
I have a problem checking the download status. I'm waiting to 20 minutes and the download never gets ready.
See my function for vba.
Please sign in to leave a comment.