Report
Survey123 reports allow you to turn your survey responses into richly formatted printable documents. For more information on creating reports directly in the Survey123 website and see Report templates. Behind the website, there is an API that manages this capability, and you can use this API directly in your own scripts and apps.
The same limitations that apply to report creation in the website, apply to report creation with the API.
URL: | https://survey123.arcgis.com/api/featureReport |
Operation: | quickReference, createSampleTemplate, checkTemplateSyntax, createReport, createSampleReport, jobs/<jobId>, queryJobs, estimateCredits |
The most common workflow is to submit a report generation job and then retrieve the results. The steps to complete this workflow are as follows.
- Submit the report request using the
createReport/submitJob
endpoint. The response will include ajobId
with which you can track this request. - Make a request at
jobs/
to check the status of the job. Once finished, the job will have ajobStatus
ofesriJobSucceeded
,esriJobPartialSucceeded
oresriJobFailed
. - Repeat the previous step at intervals of approximately 5 to 10 seconds, until one of the identified
jobStatus
values appears. - If the
jobStatus
is eitheresriJobSucceeded
oresriJobPartialSucceeded
, you can then download the output files. Either a URL to the file will be present in theresultInfo
property for each file, or an identifier which corresponds to the itemID of the file in ArcGIS Online.
Quick Reference
URL: | https://survey123.arcgis.com/api/featureReport/quickReference |
Method: | GET |
Operation: | None |
An operation to create samples of report template syntax depending on the input feature layer and survey item info. This assists the template author to create a report template.
Request parameters
Parameter | Required | Details |
---|---|---|
featureLayerUrl | true | The feature layer or table URL which contains the underlying data. |
surveyItemId | false | Survey itemID, if present, will take survey question types into consideration when generating the result. |
token | true | The token to access all resources if needed. |
portalUrl | false | Default is www.arcgis.com. The portal which includes the survey item. |
locale | false | The ISO 639-1 code to localize the date and time in the regional format. See Set language and region for supported languages and formats. |
f | false | Supported value is html . |
Response
A hosted HTML page containing samples of report template syntax.
Create Sample Template
URL: | https://survey123.arcgis.com/api/featureReport/createSampleTemplate |
Method: | POST only |
Operation: | None |
An operation to create the default Word document template with placeholder, for authors to get started.
Request parameters
Parameter | Required | Details |
---|---|---|
featureLayerUrl | true | Feature layer or table URL, will return a Word document that includes placeholders for all fields in both main layer or table and all related layers or tables. |
surveyItemId | false | Survey itemId, if presents, return a Word document generated by the Survey123 website. |
token | true | The token to access all resources if needed. |
portalUrl | false | Default is www.arcgis.com. The portal which includes the survey item. |
outputFormat | false | Supported value is docx . |
contentType | false | Specify which sections to include in the template. Accepted types are individual , summary , and summaryIndividual . Default is individual . |
Response
The binary file of the generated sample template.
Check Template Syntax
URL: | https://survey123.arcgis.com/api/featureReport/checkTemplateSyntax |
Method: | POST only |
Operation: | None |
A sync operation to check syntax which may lead to failure to generate a report, in a given report template file.
Request parameters
Parameter | Required | Details |
---|---|---|
templateFile | true | The report template file which syntax to be checked. |
featureLayerUrl | true | Feature layer or table URL which contains the underlying data schema. |
surveyItemId | false | Survey itemId, if presents, will check the syntax from a survey perspective, such as Image question can be found by attachment's keywords property. |
token | true | The token to access all resources if needed. |
portalUrl | false | Default is www.arcgis.com. The portal which includes the survey item. |
Response example
A JSON object which contains an array of syntax errors.
Create Report
URL: | https://survey123.arcgis.com/api/featureReport/createReport |
Method: | POST only |
Operation: | submitJob |
A task resource that represents a report printing tool based on a Word document template that can be leveraged by any feature layer in a feature service.
Request parameters
Parameter | Required | Details |
---|---|---|
featureLayerUrl | true | Feature layer or table URL. |
queryParameters | true | A JSON object whose value will be passed to the query operation which filters features/records to be printed. If the filtered result has more than one record, the request will be considered as a batch printing. One individual report will be generated for each record. Supported list: where , objectIds , orderByFields , resultRecordCount . Syntax: {"<supportedParam>": "<value>"} . For example: {"where": "STATUS = 'broken'","orderByFields":"inspectionDate DESC","resultRecordCount":10} |
templateItemId | true | The print template itemId, item type Microsoft Word is required. |
token | true | The token to access all resources in the account. |
portalUrl | false | Default is www.arcgis.com. The portal which includes the print template item, survey item, webmap item etc. |
f | false | Supported value is json . |
mergeFiles | false | Specify if print multiple records into a single report file (merged mode) or multiple files (split mode), and if in merge mode, start the next record on a new page or continue with the current page. Note: A merged file larger than 500MB will be split into mulitple files.
|
outputFormat | false | Supported values are docx and pdf . |
outputReportName | false | Specify the file name (without extension) of the result report file. For example, if outputFormat is pdf , input: "abc" -> output: "abc.pdf"; input: "abc.docx" -> output: "abc.docx.pdf". If packageFiles is true, outputReportName will be used for report files inside the packaged file. If mergeFiles is either nextPage or continuous , outputReportName will be used as the merged file name. |
outputPackageName | false | Specify the file name (without extension)of the packaged file when packageFiles is true , for example, <outputPackageName>.zip . |
packageFiles | false | Default is auto , which leaves the serverside to automatically decide whether to package generated report(s) as a .zip file depending on the output files count. A package larger than 500MB will be splitted into mulitple packages. The value is always true for arcgis storage service due to it does not have capability to package multiple files dynamically before downloading. |
uploadInfo | false | A JSON object specifies additional storage service where the printed file(s) should be uploaded to for future access. If it's not specified, the printed file(s) will only be available to download for 24 hours. Syntax: {"type": "<storage service>", "parameters": <JSON object>} .
For example: {"type": "arcgis", "parameters": {"title": "item title here", "folderId": "folder id here"}} |
surveyItemId | false | Provides additional information on survey structure. For example, Multiple Choice questions require this parameter in order to access information on list labels. |
webmapItemId | false | Specify the base map for printing task when printing a point/polyline/polygon. This takes precedence over the map set for each question inside a survey. |
mapScale | false | Specify the map scale when printing, the map will center on the feature geometry. |
utcOffset | false | Specify the time zone info when printing date/datetime in server-side. Acceptable formats are "±hh:mm", "±hhmm" and "±hh". UTC time will be used if not specified. |
locale | false | The ISO 639-1 code to localize the date and time in the regional format. See Set language and region for supported languages and formats. |
Response example
When the operation is submitJob
and f
is json
, the result is a job resource.
Create Sample Report
URL: | https://survey123.arcgis.com/api/featureReport/createSampleReport |
Method: | POST only |
Operation: | submitJob |
A similar task resource to createReport
for creating test sample report and refining a report template before generating any formal report.
Request parameters
Parameter | Required | Details |
---|---|---|
featureLayerUrl | true | Feature layer or table URL. |
queryParameters | true | A JSON object whose value will be passed to the query operation which filters features/records to be printed. If the filtered result has more than one record, the request will be considered as a batch printing. One individual report will be generated for each record. Supported list: where , objectIds . Syntax: {"<supportedParam>": "<value>"} . For example: {"where": "CITY_NAME = 'Barrington'"} or {"objectIds": "37, 462"} |
templateItemId | true | The print template itemId, item type Microsoft Word is required. |
token | true | The token to access all resources in the account. |
portalUrl | false | Default is www.arcgis.com. The portal which includes the print template item, survey item, webmap item etc. |
f | false | Supported value is json . |
mergeFiles | false | Specify if print multiple records into a single report file (merged mode) or multiple files (split mode), and if in merge mode, start the next record on a new page or continue with the current page. Note: A merged file larger than 500MB will be split into mulitple files.
|
outputReportName | false | Specify the file name (without extension) of the result report file. For example, if outputFormat is pdf , input: "abc" -> output: "abc.pdf"; input: "abc.docx" -> output: "abc.docx.pdf". If packageFiles is true, outputReportName will be used for report files inside the packaged file. If mergeFiles is either nextPage or continuous , outputReportName will be used as the merged file name. |
surveyItemId | false | Provides additional information on survey structure. For example, Multiple Choice questions require this parameter in order to access information on list labels. |
webmapItemId | false | Specify the base map for printing task when printing a point/polyline/polygon. This takes precedence over the map set for each question inside a survey. |
mapScale | false | Specify the map scale when printing, the map will center on the feature geometry. |
utcOffset | false | Specify the time zone info when printing date/datetime in server-side. Acceptable formats are "±hh:mm", "±hhmm" and "±hh". UTC time will be used if not specified. |
locale | false | The ISO 639-1 code to localize the date and time in the regional format. See Set language and region for supported languages and formats. |
Response example
When the operation is submitJob
and f
is json
, the result is a job resource.
Jobs
URL: | https://survey123.arcgis.com/api/featureReport/jobs/<jobId> |
Method: | GET |
Operation: | None |
The job resource provides basic information about the job such as the job ID, status, and messages. Additionally, if the job has successfully completed, it provides information about the results as well as the input parameters.
Request parameters
Parameter | Required | Details |
---|---|---|
token | true | The token of the named account. |
portalUrl | false | Default is www.arcgis.com. |
f | false | Supported value is json . |
Response parameters
Parameter | Details |
---|---|
jobId | The requested job ID |
jobStatus | The main job status. The following values are supported: esriJobSubmitted , esriJobExecuting ,esriJobSucceeded ,esriJobPartialSucceeded and esriJobFailed |
jobStatusInfo | Only available when jobStatus is esriJobExecuting and esriJobFailed , reflects the underlying status of a batch printing job. Syntax: {"jobStatusInfo": {"detailedStatus": "<detailedStatus>", "startTime": <startTime>, "progress": <progress>}} .detailedStatus : the following values are supported preparing , prepared , printing , printed , printFailed , merge , merging , mergeFailed , pdfConverting , pdfConverted , pdfConvertFailed , packaging , packaged , packageFailed , uploading and uploadFailed .startTime : available for esriJobExecuting , the unix time when this specific phase started.progress : available for esriJobExecuting , a double value smaller than 1 indicates the completed progress of this phase. |
submitted | The unix time when the job is accepted by the server |
completed | The unix time when the job finishes processing on server-side. Only available for esriJobSucceeded , esriJobPartialSucceeded or esriJobFailed |
resultInfo | A JSON object contains all the information related to the job result. It varies according to the jobType of the inputInfo . See the table below for details. |
inputInfo | Syntax: {"jobType": "<operation>", "parameters": <JSON object>} .jobType : the requested operation, for example: createReport or createSampleReport .parameters : a JSON object contains all request parameters to the submitJob method. |
messages | A JSON array of string. Detailed messages which describes the jobStatus . |
The following table shows details of the resultInfo
object when jobType
of inputInfo
is createReport
.
Property | Details |
---|---|
title | The instance name of the job in case it will show up in the client-side UI. Usually, it's the item/file title in uploadInfo , or outputReportName if uploadInfo is not specified. |
totalCount | Available when jobStatus is esriJobExecuting , esriJobSucceeded , esriJobPartialSucceeded or esriJobFailed . The count of records in the survey or the feature layer which are needed to generate report for. |
succeededObjectIds | Available when jobStatus is esriJobSucceeded , esriJobPartialSucceeded or esriJobFailed . The array of object id for the record which report has been generated successfully. |
failedObjectIds | Available when jobStatus is esriJobSucceeded , esriJobPartialSucceeded or esriJobFailed . The array of object id for the record which report has not been generated successfully. |
resultFiles | Only available when jobStatus is esriJobSucceeded or esriJobPartialSucceeded , an array of resultFile object, which syntax is: {"resultFiles": [{"id": "<resultFileId>", "url": "resultFileUrl", "objectIds": [<arrayOfObjectIdContainedInTheFile>]},...]} .
Notes:
|
details | Available when jobStatus is esriJobSucceeded , esriJobPartialSucceeded or esriJobFailed . An array of JSON object, which syntax is {"objectId": <object id>, "status": "<current processing status>", "success": <is report generated successfully>, "messages": <message array>} , represents the details of the report generating result for each record. Note: only records contained in failedObjectIds will appear.
|
Response example
Query Jobs
URL: | https://survey123.arcgis.com/api/featureReport/queryJobs |
Method: | GET |
Operation: | None |
An operation to retrieve submitted jobs to the createReport
task. Only the latest 10 jobs of the user will be returned.
Request parameters
Parameter | Required | Details |
---|---|---|
username | true | The user which to query against. |
token | true | The token of the named account. |
portalUrl | false | Default is www.arcgis.com. |
surveyItemId | false | If specified, only jobs submitted to this survey will be returned. |
featureLayerUrl | false | If specified, only jobs submitted to this feature layer will be returned. |
f | false | Supported value is json . |
Response example
An array of simplified job resource which resultInfo
only contains title
and totalCount
.
Estimate Credits
URL: | https://survey123.arcgis.com/api/featureReport/estimateCredits |
Method: | GET |
Operation: | None |
An operation to estimate how many credits are required for a task with the given parameters.
Request parameters
Parameter | Required | Details |
---|---|---|
featureLayerUrl | true | Feature layer or table URL which contains the underlying data schema. |
queryParameters | true | A JSON object whose value will be passed to the query operation which filters records to be printed. If the filtered result has more than one record, the request will be considered as a batch printing. One individual report will be generated for each record. Supported list: where , objectIds . Syntax: {"<supportedParam>": "<value>"} . For example, {"where": "CITY_NAME = 'Barrington'"} or {"objectIds": "37, 462"} |
templateItemId | true | The print template itemId, item type Microsoft Word is required. |
token | true | The token to access all resources in the account. |
surveyItemId | false | Provides additional information on survey structure. For example, Multiple Choice questions require this parameter in order to access information on list labels. |
portalUrl | false | Default is www.arcgis.com. The portal which includes the input resources. |
f | false | Supported value is json . |
Response example
A JSON object which contains the estimation result or error message.