In addition to being able to format the text that you wish to display for a particular field, you are also able to include multimedia content (images, video and audio) and documents (PDFs) - referred to as resources. This is useful in many situations, such as:


  • Playing an audio clip that verbally communicates a question/instruction in low literacy settings or where the data collector might not know the local language.
  • Displaying animations or videos to help explain a complex concept.
  • Allowing a data collector/respondent to choose from a list of images rather than text options.
  • Including reference or training material which needs to be reviewed as part of the data collection process.


To utilise a resource in a form, you need to upload it to the "Resource Library" for the workspace that houses the form. The same resources can be used by any form within the workspace and resources download automatically to all data collectors in the workspace ensuring they can be accessed offline in the field.


Resources can be referenced in both field display text and in option labels (in the case of choice field types).


This article covers:


Adding and managing workspace resources

Any resource that you want to include in a form needs to be uploaded to your workspace Resource Library - which can be accessed when designing/editing any form. Click on the settings cog in the toolbar and select 'Workspace Resources'.



This will open the Resource Library for the current workspace and display any existing resources (3) which are listed in alphabetical order. If you need to, you can download existing resources (4) to your computer (e.g. to edit them).


You can easily add a new resource to the workspace by dragging and dropping a file from your computer into the window or clicking on "Browse your PC" (5). You can upload multiple files at the same time. Resource filenames can only contain letters, underscores and numbers and any illegal characters will be removed automatically when you upload the file.



You'll see a progress bar as each file uploads and a confirmation message once it has completed uploading or failed for any reason, such as the file being too large (resources must be less than 30MB each). If a file upload fails due to a temporary issue (such as connectivity), simply try uploading it again. The following file types can be uploaded:



Note: Not all file types are supported by all web browsers and handset versions.

CSV files are cannot be uploaded on community plans. Only on paid plans. File types allowed on community plans are: "gif", "jpg", "jpeg", "png", "mp3", "wav", "m4a", "mp4", "webm",  "pdf". All other files will show as 'Invalid file' when uploading to a free community plan.




If you upload a resource with a filename that already exists, you'll be prompted to choose to either overwrite the resource or keep both files (which will rename the file you are uploading to make it unique).


Note: you cannot rename a resource once it has been uploaded so we recommend giving the resource a descriptive filename before you upload it. If your form is available in multiple languages, you might need your resources to be available in different languages too - in this case, it helps to include the language in the resource filename so you know which one to reference in each language variation.


Resources are managed at a workspace level. This means you can reference the same resource (file) from any of the forms in the same workspace, i.e. "Form 1" and "Form 2" (in the same Workspace) can both reference the resources added to the Workspace Resource Library. However, you cannot reference files across workspaces, i.e. a form in your current workspace cannot reference a resource that was added to a different workspace. In order to reference a resource in both workspaces, it has to be uploaded to each workspace's Resource Library.


To delete a resource from the Resource Library, simply click on the trashcan/bin icon. You will be prevented from deleting a resource that is still being referenced by a form. You need to remove any references to a resource (and re-publish the form after removing the reference) before you can completely delete a resource from the workspace.


Referencing a resource in a form

To display a resource in a form, simply enter the "@" symbol when entering display text (1). This will bring up a list of all available resources from the Workspace Resource Library for you to choose from. The list will update as you type to display matching resources and their type (e.g. image, video). To select a resource, click on it - the reference to the filename will be inserted in the display text (2).



When you finish editing, the resource reference will be highlighted (3) to differentiate it from the rest of the display text.



You can insert resources anywhere in a field's display text, or in option labels, and you can include multiple resources. By default, images and videos will be displayed left-aligned and on new lines. You can alter the appearance, layout and behaviour of a resource by typing the "~" symbol at the end of the resource filename. This will bring up a list of available modifiers allowing you to centre-, left-, or right-align images, video and audio controls. For images and videos, you can also stretch the media to maximise the available space. You can also configure video and audio clips to play automatically when the page loads. PDFs can be set to display inline (only applicable when the form is accessed via a desktop web browser).




Tip: Use the Preview feature to test your media has been referenced and appears correctly.





Resources and languages

If your form is available in more than one language, you might want to reference a different resource, depending on the language selected. If you add a media file to the default language of a form and then add another language variation, the same media file will automatically be used. 



If you wish to reference a different resource, simply select a difference resource file when editing the display text in that language.



Importing or moving forms

When you import a form, it might contain references to resources that are not in your Workspace Resource Library. You will have to upload these files separately and update the resource references in the form after import to reference the correct filenames.


The same applies when moving a form from one workspace to another. Since resources are workspace-specific, the files might not be available in the new workspace, and will have to be uploaded separately. Again, ensure that all your references to all resources are correct using the Preview feature before publishing.


Troubleshooting missing resources on a handset


Resources download automatically and are stored locally on a data collector 's handset. This allows the resources to display instantly and for data collectors to work offline and avoids incurring data costs once the files have downloaded initially.


If any resources are missing (e.g. they have not been able to download due to poor connectivity), an error will be displayed where the resource was supposed to appear in the form. Ensure data collectors have upgraded to the latest version of the Mobenzi Gateway Android app. It may take a few minutes for all resources to download, depending on connectivity. 


If resources are still missing, the data collector can manually retry any failed resource downloads from the Help module (1) by expanding "Resources" (2). This will list any resource downloads that have failed. The data collector can tap "retry" and monitor the download progress until all resources have successfully downloaded.




CSV file validation


Additional validation rules are applied to both the header and data rows of a CSV file resource to ensure errors do not occur during data collection. 

  • Header values can only contain letters, numbers or underscores and must begin with a letter. No spaces or other special characters are allowed. The length of a header value cannot exceed 100 characters.
  • Data can contain any characters except for double quotes " or backticks `.
  • Dates should always be in the format yyyy-mm-dd
  • It is best practice to remove spaces from the columns used to reference values (for example when populating an option list from a CSV file). Replacing spaces with underscores is a good alternative.
  • CSV files cannot be uploaded to community plans. They will only be uploaded on paid plans. 


Note: The size of the CSV file referenced in a form will impact the performance and usability of the form. Particularly launching or resuming a form, adding repeats and completing choice fields (selects and cascades) with external sources. This is compounded by the number of fields in the form that use CSV files. 


For devices with specs on the lower end, we would recommend a maximum of 1 000 rows. For devices with specs on the higher end, we would recommend a limit of 10 000 rows in the CSV file.