You can include media (audio, file, and image) 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, media questions allow one attachment. To allow multiple attachments, set their appearance.
By default, Survey123 automatically generates a file name for media submitted in a question. The file name includes the question name as a prefix, followed by a unique number. You can customize 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.
Audio
The audio question type allows users to record audio in Survey123. A progress bar indicates remaining time for the recording. Users can pause or stop the recording at any time. Once the recording is complete, they can edit the file name.
Note:
In the Survey123 field app, pausing audio while it's being recorded is not supported on Android.
By default, audio recordings are limited to a maximum file size of 10 MB in Survey123 Mobile and the Survey123 field app and 10 minutes in the Survey123 web app.
You can set a different 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:
In the Survey123 field app, the maximum file size for an individual submitted attachment is 10 MB. Ensure that the max-duration or max-size value you set does not cause the audio file to exceed this maximum file size.
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:
In Survey123 Mobile, audio files are encoded using the Advanced Audio Coding (AAC) codec by default if the device supports it. The following are the codecs supported for each operating system:
- Android—AAC, MP3
- iOS—AAC, ALAC, FLAC, MP3, PCM, Vorbis
- Windows—AAC, ALAC, MP3, PCM, Vorbis, WMAudioLossless, WMAudioV8, WMAudioV9
Note:
In the Survey123 field app, recording captures an audio file using the default audio capture format for your device. The codecs supported by the device are listed on the About page in the 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.
Audio questions only allow uploading an existing audio file in the web app. 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.
Files
Note:
This section describes functionality that is only available in Survey123 Connect and the Survey123 field app. This functionality is not available in Survey123 Studio or Survey123 Mobile.
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.
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.
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 using Options in Survey123 Studio or 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 Survey123 Mobile or the Survey123 field app.
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.
Customize image size and capture method
Note:
This section describes functionality that is only available in the Survey123 field app. This functionality is not available in Survey123 Mobile.
You can control the size of the image preview provided in the Survey123 field app 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 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.
Appearance
You can change the behavior of questions and how they are presented by setting the appearance. To confirm which submission apps support a particular appearance, refer to the Appearances table.
By setting the appearance column to multiline, a file or image question accepts multiple attachments in a single question.
This appearance can be combined with other appearances by setting both appearances separated by a space, such as multiline annotate for an image question.
You can control the number of files or images that can be submitted using the count-selected function in the constraint column. Examples are as follows:
- count-selected(${file_question}) <= 5 limits the number of files that can be submitted to a maximum of five.
- count-selected(${image_question}) <= 3 limits the number of images that can be submitted to a maximum of three.
By setting the appearance to signature, an image question can be used to pen a signature.
Note:
In Survey123 Connect, you can also set the following appearances for image questions in surveys used with the Survey123 field app:
- By setting the appearance to new-front or new-rear, you can limit image questions to only using the device's camera with the front-facing or rear-facing camera, respectively, as a default. These appearances can be combined with annotate by setting both appearances separated by a space, such as new-front annotate.
- By setting the appearance to draw or annotate, you can allow users to draw on or annotate photos.
- By setting the appearance to spike, an image question displays a button to open the Spike mobile app to integrate Survey123 with Spike. For more information, see Spike images appearance.
Signature appearance
By setting the appearance to signature, an image question presents a pop-up to capture a signature.
A signature is saved as a .jpg image attachment with the same dimensions as the pop-up. By default, the width of the pop-up stretches to the width of the device's screen, with a fixed height of 200 pixels. To set the maximum width for this pop-up using the max-pixels parameter, see Customize image size and capture method.
You can also provide an image in the default column to set a custom background for the signature. The dimensions of the default image determine the aspect ratio of the pop-up.
The width of the pop-up will be the smallest of the following:
- The max-pixels value
- The width of the default image
- The width of the device's screen
The height will be 200 pixels unless a default image is provided.
When designing a survey using the signature appearance, be sure to take the screen size of all target devices into consideration.
Footer text can be provided for a signature question pop-up using the footerText parameter in the body::esri:style column. By using just the footerText parameter with no value, the question's guidance hint will appear below the signature. This can be changed to the question's hint using footerText=@[hint]. The hint or guidance hint used for the footer text will not appear in the default location below the question name. For more information about hints, see Hints.
Note:
The Survey123 web app does not support multiline, the max-pixels parameter, or defaults when applied to the signature appearance.
Draw and annotate appearance
Note:
This section describes functionality that is only available in Survey123 Connect and the Survey123 field app. This functionality is not available in Survey123 Studio or Survey123 Mobile.
By setting the appearance to draw, an image question displays a button to load a canvas on which you can sketch. In the drawing tools palette, you can switch between drawing tools as well as control the settings for each tool, such as text size, line width, color, and so on. For information about the canvas interface, see Draw and annotate. You can create custom palettes that allow you to configure drawing and annotation tools to suit your needs. For more information, see Draw and annotate palettes.
By setting the appearance to annotate, an image question displays a button to open the device's camera to take a photo that you can annotate with graphics and text. In the drawing tools palette, you can switch between drawing tools as well as control the settings for each tool, such as text size, line width, color, and so on. For information about the canvas interface, see Draw and annotate. You can create custom palettes that allow you to configure drawing and annotation tools to suit your needs. For more information, see Draw and annotate palettes.
Tip:
At Survey123 3.13 and later, EXIF data is copied from the source image to the annotated image.
Alternatively, you can allow the user to annotate an existing image from the device's storage or a snapshot of a map. To do this, set body::esri:style for that question to method=browse, method=camera, or method=map. The default behavior for the annotate appearance is identical to providing method=camera. You can set the question to provide a number of options for the source image by providing multiple options separated by commas, for example, method=camera,browse.
Caution:
Regardless of the method set, the Survey123 web app only displays a browse for file option.
Defaults and calculations behave differently with image questions using draw and annotate. If the file name of an image in the survey's media folder is used as a default value or the result of a calculation, the image is used as an initial background for the canvas. With annotate, this image is replaced by a provided image, and it only displays if the user specifically declines to provide an image or resets the image once already provided.
Note:
You can set the resolution for an image by defining a max-pixels value in the parameters column. For a draw question, setting max-pixels=1000 will set the canvas to a square image of 1000 x 1000 pixels. For an annotate question, setting max-pixels=1000 will set the longest side of the image to 1000 pixels while preserving the aspect ratio of the provided image. If max-pixels is not set, the image size will instead be defined by the image size setting in the Options settings for your survey in Survey123 Connect.
Both of these ways of setting image resolution are overwritten by providing a default image for the question, in which case the default image's resolution will be applied. This can be used to ensure a standard resolution for all submitted images. Providing a snapshot of a map for annotation will also overwrite any other image resolution settings, with the image being set to the size of the viewable canvas area.
Spike images appearance
Note:
This section describes functionality that is only available in Survey123 Connect and the Survey123 field app. This functionality is not available in Survey123 Studio or Survey123 Mobile.
Note:
Spike integration is not supported in the Survey123 web app.
Image questions also support appearances to integrate Survey123 with Spike, a laser measurement solution developed by ikeGPS that allows you to capture the measurements and location of an object from a photo. By setting the appearance to spike, spike-full-measure, or spike-point-to-point, an image question displays a button to open the Spike mobile app on iOS and Android devices.
A photo taken with the Spike app and laser device allows you to record the coordinates of and distance to the object, and measure the dimensions of objects in the photo through drawing areas and lines. The photo with measurement markup is then attached to your survey, and the metadata from the photo, such as coordinates and measurements, is made available to be recorded. Associated Spike and measurement metadata is recorded in the image file using standard exchangeable image file (EXIF) tags. The EXIF information can then be extracted and used to populate other fields.
The difference between the Spike appearances is the extent of values stored in the image. The spike appearance only measures distance and location, while the spike-full-measure appearance measures distance, location, area, and length. The spike-point-to-point appearance captures a series of values exclusive to it, denoted by the property names beginning with P2P.
For more information about these EXIF tags, see Spike integration. For more information about Spike, see the Spike website.
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")
Common locational EXIF tags you can 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.
| EXIF tag | ||
|---|---|---|
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
Note:
This section describes functionality that is only available in Survey123 Connect. This functionality is not available in Survey123 Studio.
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 Spike images 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 about 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.
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 repopulate 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 repopulate 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
Note:
This section describes functionality that is only available in Survey123 Connect and the Survey123 field app. This functionality is not available in Survey123 Studio or Survey123 Mobile.
By default, Survey123 automatically generates a file name for media submitted in a question. 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:
In the web app, customized file names are supported for image, audio, and file questions. In the field app, customized file names are only supported for image questions.
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 that 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 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.
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.
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.