In Web Apps, users can upload and attach files like images, documents, audio recordings, and videos to their form submissions as well as capture signatures in-form.

Web Apps Users

When users encounter a form in CommCare Web Apps that includes questions for uploading multimedia or documents, they will see a Browse option for each question. 

1. Locate the Browse Button: Any questions that allow for file attachments will have a "Browse" button next to it, as well as the option to Clear the selected file.

2. Select Your File: Click the "Browse" button. This will open your computer's file selection window. Select the file you want to upload and click "Open" or the equivalent button in your file selection window.

   • File Size Limit: If the file you select is larger than 4MB, an error message will be displayed, and you will need to choose a smaller file.

   • Supported File Types: The system only allows specific file types to be uploaded. When you are browsing for a file, unsupported file types will not appear or will be greyed out and cannot be selected. The supported file types are:

     1. Image: .jpg, .jpeg, .png

     2. Audio: .mp3, .wav, .amr, .ogg, .qcp

     3. Video: .3gpp, .3gp, .3ga, .3g2, .mp4, .3gp2, .mpg4, .mpeg4, .m4v, .mpg, .mpeg

     4. Document: Word, Excel, PDF, TXT, RTF, HTML, MSG

         

3. File Name Displayed: Once you've selected a file, its name will appear next to the "Browse" button, confirming your selection. To replace the file you can browse and select a different file, or click “Clear” to clear the file selected.

Open

4. Signature Capture: For questions specifically designed for signatures, you will see a signature widget. You can use your mouse cursor or other input device to draw your signature within this widget. Click “Clear” to delete the signature 

Open

App Building Configurations

Configuring Multimedia and Document Uploads

To learn how to add Image, Audio, Video, Signature Capture or Document Upload questions to your forms, please refer to the help page https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143958321/Media+Capture+Questions#Adding-Media-Capture-Questions-To-Your-Application. These question types, when included in a form accessed via Web Apps, will automatically utilize the multimedia upload functionality.

Displaying and Linking to Uploaded Files in Other Forms

 When a file is uploaded through a multimedia question, CommCare stores it and assigns it a unique identifier (UUID). You can then use this UUID to display or link to the uploaded file in other forms for the same case. 

Creating the URL for the File in a Hidden Expression

To generate a direct link to the uploaded file, you can create a hidden expression within your form to construct the file URL and save it as a case property. The URL follows this pattern:

• your_domain: Replace this with your CommCare project space name

• form_instance_id: This is the unique ID of the form submission where the file was uploaded. You can typically access this using /data/meta/instanceID

• uuid_filename: This is the UUID of the uploaded file, which is the value of your multimedia case property (e.g., #form/image).

Open

Displaying or Linking in a Second Form

In a subsequent form for the same case, you can use the case property containing the file URL to display the media or create a clickable link:

1. To display an image use the image markdown syntax: 

   • 

2. To create a clickable link to the file use the link markdown syntax:

   • [Link to image](#case/image_url)

Open

Using the Uploaded File Name Within the Form

If you would like to save or refer to the original file name (e.g., to display it in a link), you can utilize the Filename Broadcast feature:

• Apply Appearance Attributes: In Formbuilder, for your multimedia question (e.g., "Image"), under the Advanced formatting section add the appearance attribute broadcast-image. For a subsequent text question where you want to store the filename (e.g., "Image File Name"), add the appearance attribute receive-image-indexed.

Open

Open

• Filename Population: When the form with the broadcast-image question is submitted, the "Image File Name" question will be automatically populated with the name of the uploaded file.

• Using the Filename: You can then save the value of the "Image File Name" text question to a case property. In a later form, you can reference this case property to display the filename in a link

Displaying images or image links in case lists and case details

Images or Image Links can also be displayed in Case Lists and Case Details using the Format ‘Markdown’. 

• To display the image use the syntax: concat('')

• To display the image link use the syntax: concat('[Image](', ./image_url ,')')

Open

Permissions to View Uploaded Documents

To view files that have been uploaded, users need the “View Submit History Report” permission. More information about permissions can be found here: https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143957921/Roles+and+Permissions+Overview#Role-Descriptions-&-Permissions

Limitations

• Attachment Limits

  • File Size Limit: Maximum file size for uploads is 4MB.

  • Number of Attachments: A maximum of 50 files can be attached per form submission.

• No Multiple File Upload: Only one file can be uploaded at a time per upload question.

• No In-Form Preview: You cannot preview the uploaded media directly within the form before submitting.

• Case API Incompatibility: Users are not able to submit multimedia file attachments through the CommCare Case API.

• The Signature Capture widget frontend display is reset if the Web Apps browser window is re-sized. The answer signature data is still saved on the backend, thus no data is lost even if the frontend display is affected. This can be avoided by users not re-sizing their browser window after entering a signature. 

• Performance expectations: We recommend users attach no more than eight files to upload in each form submission to prevent form submission performance degradation.