The Form Override event hook can be used to modify certain aspects of a form's design before it is sent to a fieldworker's handset. When a fieldworker checks for updates on their handset, a call will be made to the Override URL specified (along with a number of GET parameters) that must then respond with XML according to a predefined format.


By specifying the XML output, it is possible to modify or override any of the following form design parameters:

  • Generate one or more "instances" of the form - each of which can have a unique title when displayed on the handset
  • Specify the folder in which the form (or instance) should be placed in on the handset
  • Specify the display text for any field (you only need to override the fields you wish to change)
  • Modify the options available for a specified field (select one or select many field types)
  • Set or override default values for fields and variables
  • Modify a field's constraints


A simple example of a useful override would be where a contextual option list should be displayed, depending on which fieldworker was conducting the form (e.g. the list of areas assigned to each fieldworker). Overrides also allow the possibility of sending down multiple instances of a form template to a handset, pre-populated with instance specific default values and/or custom field text.


The GET parameters that will be sent to your override URL endpoint are:


Name
Type
Description
 survey_id
integer
 Identifies the form about to be sent to the fieldworker
 device_id
uniqueidentifier
 Identifies from which handset the update request has been made (and to which the form will be sent)
 fieldworker_id
uniqueidentifier
 Identifies from which fieldworker the update request has been made
 survey_external_id
string
 User-defined reference for developer's internal use
languages
string
Comma separated list of languages the fieldworker is associated with
 survey_xml
string
XML representing the unmodified form (can also be downloaded manually)


The override feature enables third-party systems to provide context to forms that are sent to handsets. The features that the form override mechanism supplies:


Feature
Description
 Instance count
Default instance count is 1. If the instance count is reduced to 0, the form will not be sent to the fieldworker even they are assigned to it. If the instance count is increased, different override parameters can be provided for each instance.
Form title
 The title of the form (as it appears on the handset) may be overridden.
Field text
The display text of any field (including instruction fields) may be overridden.
 Option label
 The list of options (labels and values) for select fields may be overridden.  
Default value
 The default values of any field may be overridden. This is also the mechanism used to set the value of variable field types.
Required field flag
 Override whether the field should be required or optional.
Survey removal
 Specify whether the instance should be removed upon completion.


Override configuration


  • From the Design tab, select 'Integration Settings'. 
  • Enter a URL that will process the override in the "Form Override" box. This must point to an endpoint on your server or you can make use of a service like Zapier to process the override.
  • There is a link to download sample API XML for the selected form to assist with the development of your override handler. Your handler only needs to output XML for the parts of the form that you wish to override. If you only specify XML for one of the fields, only that field will be modified/overwritten.