At the name suggests, Context fields provide access to dynamic information about the form that is currently in progress (i.e. the form context). This information can be used to dynamically drive logic in the form (e.g. only display a certain set of options for a particular data collector) or to store additional information that can be analysed later. Some Context fields are also available when a submission is being edited.
You can reference context fields in your form by typing the dollar symbol ("$") and then selecting the relevant context field from the available options. The table below lists the available context fields:
| Context Field | Description | Applicability |
|---|---|---|
| $context.deviceId | System-assigned identifier that uniquely identifies the handset being used to capture the form. | Only available when capturing a form via the mobile app |
| $context.editorId | System-assigned identifier that uniquely identifies the user currently editing the submission. | Only available when editing a submission |
| $context.editorName | Full name of user that is currently editing the submission. | Only available when editing a submission |
| $context.fieldworkerId | System-assigned identifier that uniquely identifies the Data Collector currently capturing the form. | Available when capturing a form via the mobile app or web (if form has been restricted to Data Collectors only) |
| $context.fieldworkerName | Full name of the Data Collector currently capturing the form. | Available when capturing a form via the mobile app or web (if form has been restricted to Data Collectors only) |
| $context.formVersion | The version of the form currently being captured/edited. | Available during form capture (web & mobile) and submission editing |
| $context.language | The version of the form currently being captured/edited. | Available during form capture (web & mobile) and submission editing |
Context fields can be displayed in the form by referencing the context field in the display text of any field as seen below.
Context fields can also be used to populate Calculated Value fields (see advanced field types). This will ensure the data is stored as part of the submission and will be available for analysis later. Note that certain information is automatically included in every submission (e.g. device identifier, Data Collector name, form version) so you don't need to manually save this information using a Context field.
Like other fields, Context fields can also be used to drive logic in your form as explained in the example below.
Example: display participants that are assigned to the current fieldworker
By combining Context fields with option list filtering, you can create dynamic option lists that - for example - only display the list of options that are relevant to the Data Collector who is completing the form. This could be used to manage individual caseloads (e.g. assign a list of participants or tasks to specific Data Collectors).
Here's a step by step explanation of how to support a Participant caseload scenario where each Participant is assigned to a specific Data Collector:
Firstly, you need to create a CSV file that contains a column for the option labels (e.g. participant's name - "Fullname"). Then add a column that stores the option value (e.g. participant identifier - "PID"). Finally, add a column that stores the name of the Data Collector who the participant is assigned to (e.g. "FieldworkerName").
Once you've uploaded the file to your workspace resource library, you are ready to set up the form:
- Create a select field and choose to use an external source file (i.e. the CSV file you uploaded that contains all the participants as well as the Data Collector that each participant is assigned to). Visit our article on Populating an option list from an external source for detailed steps on using and setting up a select field with an external source file.
- Configure the option labels and values by choosing the appropriate columns from the CSV file.
- Use the 'Advanced Filter options' feature to apply a filter (this topic is covered in more detail here).
- To filter for the participants that are assigned to the Data Collector capturing the form use the following filters:
- Select the column that lists the fieldworkers (that are assigned to the participants). E.g. FieldworkerName
- Choose the data type, in this case the Data Collector's name is Text
- Select the operator, in this case 'equal to'
- Use the context field to access the Data Collector currently completing the form - $context.fieldworkerName
Note: The Data Collectors' names in the CSV file must correspond exactly with the names of the fieldworkers on the console. If they are spelled differently for example, they will not be filtered correctly.
When the form is rendered, only participants assigned to the Data Collector currently completing the form will be displayed in the options list.
Tip: Select the Preview button from the toolbar to test your form and see how it will be displayed when using the mobile app.
