• About
• Initiate a CSV Export Job
• Available Metadata Fields
• 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:

1. Initiate an Export Job.  This will queue the export request in the ProntoForms system.
2. 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)
3. 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.
4. Download the CSV Export.  As mentioned, the CSV Export will be available for retrieval for 24 hours.

[ top ]

 

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/[version]/data/export.xml
api.prontoforms.com/api/[version]/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

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

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/data/export.xml
curl -v -k -u user:password -X POST --upload-file FILENAME.json https://api.prontoforms.com/api/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.

[ top ]

 

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/[version]/data/export/[id]/status.xml
api.prontoforms.com/api/[version]/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/data/export/[id]/status.xml
curl -v -k -u user:password -X GET https://api.prontoforms.com/api/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.

 [ top ]

 

Download the Generated CSV File

Use this method to retrieve a completed CSV export.

URL Structure

api.prontoforms.com/api/[version]/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/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.

[ top ]