You can include image, audio, and file questions in surveys to allow users to submit attachments with their survey responses.
Tip:
Images and audio can also be added to other questions in a survey for reference and styling purposes. For more information, see Add media to a survey.
By default, image, audio, and file questions allow one attachment. By setting their appearance to multiline in the appearance column, multiple attachments can be included.
Images
The image question type allows users to submit images saved on their device or photos taken with their device's camera.
A photo taken in Survey123 is saved as a .jpg file, with a quality level dependent on the device's camera. The image size, measured by pixels on the longest edge, can be set on the Options tab in Survey123 Connect. This size is applied to all image questions in the survey. The following options are available:
- 320 pixels
- 640 pixels
- 1280 pixels
- 1920 pixels
- Unrestricted (Any photo size can be attached to the survey.)
The default image size is 1280 pixels. Submitted images that were saved on the device keep their original file type, resolution, and quality.
These image sizes don't affect the image preview provided in the Survey123 field app. You can control this with the previewHeight parameter. This parameter supports all unit types supported by the height parameter, but the preview image height is ultimately limited by the device's screen width and the image's aspect ratio. Use previewHeight=0 to set the image preview to be the maximum size without unnecessary blank space.
You can set the maximum allowable size of an image for each individual image question in a survey. Specify max-pixels in the parameters column of the XLSForm for the question you want to limit. For example, max-pixels=100 scales the image down proportionally to 100 pixels on the longest edge. If the max-pixels parameter is not specified, the image size set in Survey123 Connect is used.
You can limit an image question to a particular capture method by specifying method=camera or method=browse in the body::esri:style column of the XLSForm. You can also set the appearance to new-front or new-rear to limit an image question to only use images from the device's camera, using the front-facing or rear-facing camera, respectively, as a default. When the annotate appearance is used, you can also specify method=map.
The default maximum file size for an individual image is 10 MB. For image questions in the Survey123 web app, you can specify the maximum file size in megabytes using max-size in the bind::esri:parameters column. For example, max-size=5 allows users to attach an image up to 5 MB.
Note:
The maximum file size for an individual attachment submitted from the Survey123 field app is 10 MB.
When applied to image questions, the max-size parameter is only supported in the Survey123 web app. The maximum size cannot exceed 100 MB for ArcGIS Online, and 20 MB for ArcGIS Enterprise.
Image questions support other appearances that allow you to annotate photos, draw on a canvas, or pen a signature. For more information, see Appearance.
By default, Survey123 automatically generates a file name for images submitted in a question. The file name includes the question name as a prefix, followed by a unique number. For some questions, you may want to customize the file names to make them more meaningful. For more information, see Customize file names. If survey data is exported and published as a feature layer for reuse in Survey123, it is recommended that you do not customize file names. For more information, see Keywords.
Extract image metadata
You can use the pulldata("@exif") function to extract standard Exchangeable Image File (EXIF) metadata tags from the response to an image question. Entering the following example into a decimal question extracts the device latitude value from an image:
pulldata("@exif", ${image}, "GpsLatitude")
Commonly used locational EXIF tags to use with the pulldata("@exif") function are listed in the following table:
| EXIF tag | Description |
|---|---|
| GpsLatitude | The latitude of the device location as a string |
| GpsLongitude | The longitude of the device location as a string |
| GpsAltitude | The altitude of the device location as a string |
| GpsLatitudeRef | The latitude reference (that is, N,E,S,W) of the device location as a string |
| GpsLongitudeRef | The longitude reference (that is, N,E,S,W) of the device location as a string |
| GpsDestDistance | The distance between the device and destination locations, in kilometers, as an integer |
| GpsImgDirection | The direction to the destination location from the device location as a string |
| GpsDestLatitude | The latitude of the destination location as a string |
| GpsDestLongitude | The longitude of the destination location as a string |
| GpsDestLatitudeRef | The latitude reference (that is, N,E,S,W) of the destination location as a string |
| GpsDestLongitudeRef | The longitude reference (that is, N,E,S,W) of the destination location as a string |
You can use the following example to display both the latitude and longitude value in a single field, which you can then use to populate a geopoint question:
string(pulldata("@exif", ${image}, "GpsLatitude")) + " " + string(pulldata("@exif", ${image}, "GpsLongitude"))
Other image EXIF tags that can be extracted by Survey123 are listed below. Depending on the hardware being used, not all of these tags will be available.
GpsAltitudeRef | GpsTimeStamp | GpsSatellites |
GpsStatus | GpsMeasureMode | GpsDop |
GpsSpeedRef | GpsSpeed | GpsTrackRef |
GpsTrack | GpsImgDirectionRef | GpsMapDatum |
GpsDestBearingRef | GpsDestBearing | GpsDestDistanceRef |
GpsProcessingMethod | GpsAreaInformation | GpsDateStamp |
GpsVersionId | GpsDifferential | GpsHPositioningError |
ImageWidth | ImageLength | ImageBitsPerSample |
ImageCompression | ImagePhotometricInterpretation | ImageDescription |
ImageMake | ImageModel | ImageStripOffsets |
ImageOrientation | ImageSamplesPerPixel | ImageRowsPerStrip |
ImageStripByteCounts | ImageXResolution | ImageYResolution |
ImagePlanarConfiguration | ImageResolutionUnit | ImageTransferFunction |
ImageSoftware | ImageDateTime | ImageArtist |
ImageWhitePoint | ImagePrimaryChromaticities | ImageYCbCrCoefficients |
ImageYCbCrSubSampling | ImageYCbCrPosition | ImageReferenceBlackWhite |
ImageRating | ImageRatingPercent | ImageCopyright |
ImageXPTitle | ImageXPComment | ImageXPAuthor |
ImageXPKeywords | ImageXPSubject | ImageLensSpecification |
ImageLensModel | ImageLensMake | ImageLensSerialNumber |
ExtendedSubjectDistanceRange | ExtendedExposureTime | ExtendedFNumber |
ExtendedExposureProgram | ExtendedSpectralSensitivity | ExtendedISOSpeedRatings |
ExtendedOecf | ExtendedExifVersion | ExtendedDateTimeOriginal |
ExtendedDateTimeDigitized | ExtendedComponentsConfiguration | ExtendedCompressedBitsPerPixel |
ExtendedShutterSpeedValue | ExtendedApertureValue | ExtendedBrightnessValue |
ExtendedExposureBiasValue | ExtendedMaxApertureValue | ExtendedSubjectDistance |
ExtendedMeteringMode | ExtendedLightSource | ExtendedFlash |
ExtendedFocalLength | ExtendedSubjectArea | ExtendedMakerNote |
ExtendedUserComment | ExtendedSubSecTime | ExtendedSubSecTimeOriginal |
ExtendedSubSecTimeDigitized | ExtendedFlashPixVersion | ExtendedColorSpace |
ExtendedPixelXDimension | ExtendedPixelYDimension | ExtendedRelatedSoundFile |
ExtendedFlashEnergy | ExtendedSpatialFrequencyResponse | ExtendedFocalPlaneXResolution |
ExtendedFocalPlaneYResolution | ExtendedFocalPlaneResolutionUnit | ExtendedSubjectLocation |
ExtendedExposureIndex | ExtendedSensingMethod | ExtendedFileSource |
ExtendedSceneType | ExtendedCfaPattern | ExtendedCustomRendered |
ExtendedExposureMode | ExtendedWhiteBalance | ExtendedDigitalZoomRatio |
ExtendedFocalLengthIn35mmFilm | ExtendedSceneCaptureType | ExtendedGainControl |
ExtendedContrast | ExtendedSaturation | ExtendedSharpness |
ExtendedDeviceSettingDescription | ExtendedImageUniqueId |
To see these tags in detail, see the EXIF sample in Survey123 Connect.
Caution:
If an image question contains multiple images, you cannot extract EXIF data from the images using the pulldata("@exif") function. To extract EXIF data from multiple images submitted to the same question, consider using a repeat.
Spike integration
Image questions also support integration with the Spike laser measurement solution developed by ikeGPS, which allows you to capture the measurements and location of an object from a photo. For information about how to use Spike with Survey123, see Appearance.
Spike records a number of additional custom tags by writing a JSON object to the ImageDescription EXIF tag containing nonstandard properties relating to the Spike device and the measurements it has taken. The tags are described in the following table:
| Spike tag | Description |
|---|---|
| device_id | The ID of the Spike device as a string |
| local_accuracy | The accuracy of the Spike device as a decimal |
| destination_altitude | The altitude of the destination location as a rational |
| declination | The declination of the Spike device as a rational |
| pitch | The pitch of the Spike device as a rational |
| rotation | The rotation of the Spike device as a string |
| objects | A JSON array of the measured objects (area and lengths) as a string |
| P2P.capture_id | The ID of the two images of the point-to-point process as a string |
| P2P.horizontal_distance | The horizontal distance between the two points in meters |
| P2P.distance | The distance between the two points in meters |
| P2P.gradient | The gradient between the two points in degrees |
| P2P.vertical_distance | The vertical distance between the two points in meters |
| P2P.azimuth | The azimuth of the two points in degrees |
To access these Spike tags, first extract the JSON object stored in the EXIF using pulldata("@exif") on the objects property as follows:
pulldata("@exif", ${image}, "objects")
Once this JSON object is in another field, you can use the Spike. object name path in a pulldata("@json") function to extract a specific value from the JSON array. For more information on the pulldata("@json") function, see Retrieve a value from JSON. The following example extracts the pitch of the Spike device from the question with the array inside it:
pulldata("@json", ${spikedata}, "Spike.pitch")
The objects array also contains the areas and lengths captured by the Spike device. This array contains the measured objects in the image, including shapes and lines, as well as an alignment shape used for image transformation. The objects in the array can be extracted by referring to their position in the array, an order that corresponds to the order in which they were captured. The following example returns the first area or line in the array:
pulldata("@json", ${spikedata}, "Spike.objects[1].type")
Note:
Position 0 in the array always contains the alignment shape.
To return the amount of objects present in the array, use the length property as follows:
pulldata("@json", ${spikedata}, "Spike.objects.length")
To see examples of these tags in use, see the Spike sample survey in Survey123 Connect. For more information about Spike, visit the ikeGPS products page.
Audio
The audio question type allows users to record and upload audio in Survey123. Recording captures an audio file using the default audio capture format for your device. A progress bar indicates how much time is left for the recording. Users can pause or stop the recording at any time. Once the recording is complete, you can edit the file name by selecting it.
Note:
Pausing audio while it's being recorded in the field app is not supported on Android.
The ability to upload an existing audio file is not supported in the field app.
By default, audio recordings are limited to a maximum file size of 10 MB in the field app and 10 minutes in the web app.
You can set a lower size limit in megabytes using the max-size parameter in the bind::esri:parameters column. The recording stops automatically when the maximum file size is reached. For example, max-size=5 allows users to record up to 5 MB of audio.
Alternatively, you can specify a time limit in seconds using the max-duration parameter in the bind::esri:parameters column. The recording stops automatically when the maximum duration is reached. For example, max-duration=30 allows users to record up to 30 seconds of audio.
Caution:
The maximum file size for an individual attachment submitted from the Survey123 field app is 10 MB. Ensure that the max-duration or max-size value you set does not cause the audio file to exceed the maximum file size.By default, audio files are encoded on iOS and Android devices using the Advanced Audio Coding (AAC) codec, if the device supports it. You can specify preferred audio codecs using the codec parameter in the bind::esri:parameters column. Multiple codecs can be provided separated by commas, for example, codec=amr-nb,aac. The first codec compatible with the device is used.
Note:
The codecs supported by the device are listed on the About page in the Survey123 field app. Press and hold the About ArcGIS Survey123 title at the top of the About page to reveal additional information about the device, including the audio codecs it supports. On Windows devices, audio files are always recorded in uncompressed WAV format.
You may not be able to play some audio files in a web browser because not all codecs are supported by browsers. For more information about audio codecs on the web, see the Mozilla Developer Network documentation.
You can also submit an audio file stored on your device using a file question. For a list of supported audio file types, see Files.
By default, Survey123 automatically generates a file name for audio submitted in a question. The file name includes the question name as a prefix, followed by a unique number. For some questions, you may want to customize the file names to make them more meaningful. For more information, see Customize file names. If survey data is exported and published as a feature layer for reuse in Survey123, it is recommended that you do not customize file names. For more information, see Keywords.
Files
The file question type allows users to submit a range of file types.
The default maximum file size for an individual file is 10 MB. For file questions in the Survey123 web app, you can specify the maximum file size in megabytes using max-size in the bind::esri:parameters column. For example, max-size=5 allows users to attach a file up to 5 MB.
Note:
The maximum file size for an individual attachment submitted from the Survey123 field app is 10 MB.
When applied to file questions, the max-size parameter is only supported in the Survey123 web app. The maximum size cannot exceed 500 MB for ArcGIS Online and 20 MB for ArcGIS Enterprise.
By default, a file question allows one file. Use multiline for the appearance column to allow attachment of multiple files to a file question.
The file question type accepts all file attachment types supported by ArcGIS Online and ArcGIS Enterprise. Supported file types are as follows:
| Category | File type |
|---|---|
Archive | 7Z, GTAR, GZ, TAR, TGZ, ZIP |
Audio | AIF, M4A, MID, MP2, MP3, MPA, RA, RAM, RMI, WAV, WMA |
Data | CSV, GEODATABASE, GEOJSON, GML, GPKG*, JSON, MDB, PBF*, SD*, VRML, XML |
Document | DOC, DOCX, DOT, PDF, PPT, PPTX, TXT, WPS, XLS, XLSX, XLT |
Image | BMP, ECW, EMF, EPS, GIF, IMG, J2K, JP2, JPC, JPE, JPEG, JPF, JPG, PNG, PS, PSD, RAW, SID, TIF, TIFF, WMF |
Video | AVI, MOV, MP4, MPE, MPEG, MPG, MPV2, QT, WMV |
*This attachment type is not supported in ArcGIS Enterprise.
You can limit the file types that can be submitted to a file question using the body::accept column. This column allows both file extensions (for example, .wav) and MIME types (for example, audio/*). Multiple file extensions or MIME types can be set by separating them with commas.
For information about accepted formats for MIME types, see the Mozilla list of common MIME types.
By default, Survey123 automatically generates a file name for files submitted in a question. The file name includes the question name as a prefix, followed by a unique number. You can customize the file names to make them more meaningful. For more information, see Customize file names. If survey data is exported and published as a feature layer for reuse in Survey123, it is recommended that you do not customize file names. For more information, see Keywords.
Keywords
Survey123 uses attachment keywords to associate attachments with specific questions in a survey. When you create an image, audio, or file question in a survey and publish it, the question name is used as the keyword in the attachments table. For example, if a survey contains image questions called image_closeup and image_wideview, the value stored in the KEYWORDS column of the attachments table will be either image_closeup or image_wideview for each photo. Survey123 automatically matches the attachment keyword with the question name to associate attachments to questions.
The purpose of the keyword association is most evident when printing reports, Survey123 will ensure the correct photo is printed as a response to the correct question in the survey. Keyword association is also used to allow editing Images in the inbox.
If you change the name of an image question and republish the survey, you must also change the keyword for any existing attachment records.
Caution:
When Survey123 data is exported, the KEYWORDS column of the attachments table will not be retained.
If this data is then republished as a hosted feature service, you have one image question, and default filenames have been used for attachments, you can use the Update attachment keywords Python notebook to re-populate the KEYWORDS column. If you have more than one image question in your survey, you cannot use the notebook and must manually determine which file is associated with which question and enter the question name into the KEYWORDS column for each attachment record. For more information, see this Technical Support article.
If the data is republished as an ArcGIS Server feature service, you must first add the KEYWORDS column to the attachment table. You can use the Upgrade Attachments tool to add this column. If you have one image question, and default filenames have been used for attachments, you can use the Update attachment keywords Python notebook to re-populate the KEYWORDS column. If you have more than one image question in your survey, you cannot use the notebook and must manually determine which file is associated with which question and enter the question name into the KEYWORDS column for each attachment record. For more information, see this Technical Support article.
In either environment, when you next view these records in Survey123, the keyword value in the attachment table will match the question name, and the association will automatically be made.
Customize file names
By default, Survey123 automatically generates a file name for images, audio, and files submitted in a question. The file name includes the question name as a prefix, followed by a unique number. You can customize the file names to make them more meaningful. For example, you can include the first and last names of the signer in a signature file name. For a photo, you can include the date or a descriptor of the object you are photographing.
Caution:
Customized file names are supported for image, audio, and file questions in the web app. Customized file names are supported for image questions only in the field app.
Customized file names are set as the file is added to a media question and do not automatically update to reflect subsequent changes in the survey. For example, if a file name references a text question and that question's value changes after the file was added, the file name will not be updated to reflect the change.
You can use the fileName parameter in the bind::esri:parameters column to dynamically set the file name for a file that is to be created. In the following example, an image file name similar to ASSET406-20221018145109.jpg is created from the asset_id question and the current date and time:
For more syntax examples, see the Images and Annotation sample in Survey123 Connect.
File names must adhere to the following:
- File names must be unique for all questions in all surveys on the device. The My Survey Attachments folder stores all images for all surveys on the device and cannot contain duplicate file names. To ensure file names are unique, consider using a function such as now() in the fileName expression.
- File names cannot be longer than 140 characters.
- File names cannot contain spaces or the following special characters: \ / : * ? < > ; | . , ". Spaces and special characters will be replaced with an underscore.
Caution:
In the field app, if the expression for the fileName parameter results in a file name that is a duplicate or that exceeds the maximum length, the automatically generated file name for the image will be used. Similarly, if users manually edit the file name in the survey, the file name will not be accepted if it is a duplicate or exceeds the maximum length.
In the web app, if the expression for the fileName parameter, or a manual edit of the file name results in a duplicate, an incremented number will be appended to the new file name.
The following parameters can be applied in the body::esri:style column for a question to further control file names:
- fileNameVisible—Specifies whether the name of the file will be visible in the survey. The default is true. To hide the file name, type fileNameVisible=false.
- allowRename—Specifies whether users are allowed to edit the name of the file manually. The default is true. Users cannot edit the file name when fileNameVisible=false, even if allowRename=true.