End of Form Navigation

When you build your CommCare application, you can define the screen that will direct users after they submit a form instead of returning to the home screen. This feature is called End of Form Navigation, and it offers four options for users to choose from, depending on the application configuration: Home Screen, First Menu, Previous Screen, and Link to another form or menu.

Table of Contents:

Overview

Here's an overview of each option:

• Home Screen: This takes the user to the start screen on Android or the module list on feature phones.

• First Menu: The user will be directed to the module menu within the application they are working on.

• Menu: If the user selects this option, the screen they would see when clicking on a module name will be displayed. 

  • If the application is configured such that the case list comes before the form list, this will take the user to the case list. 

  • If the application is configured such that the form list comes before the case list, this will take the user to the form list. However, if the menu mode of the module is set to "Display only forms," the user will be returned to the home screen, not the module screen.

  • Previous Screen: This option returns the user to the last screen before the form was opened. Depending on the application's configurations, this could be a case details screen, a form list, or a child case list.

• Link to other form or menu:  This allows for conditionally linking another form or menu, which we'll call target. This means when the user submits a form, let's refer to this as the source form, another screen in the app will be automatically loaded.

How to configure End of Form Navigation

Below are the steps to configure the end of form navigation:

Step-1: While editing your form, select the option to manage a case. 

Open

Step-2: Activate the option to show the logic, allowing you to configure the end of form navigation..

Open

Step-3: Select the desired option from the menu.

If you select "Link to another form or menu" you will need to specify a target form and may need to set up a conditional expression to determine whether the form should be presented to the user. Here's how:

Target Form

Specify the form that will open once the user submits the current form.

Linking Data

If the target form is located in a module that caters to a different case type than the current form, you may need to specify the case_id of the case that CommCare will need to load. In most scenarios, if the case_id is the same as the current form, Commcare can manage this independently, and no user intervention is required.

Conditional expression

If the decision to link to the target form is dependent on a condition being met, you will need to specify a conditional expression. This expression must return a boolean value (true or false). Note that in the context of the form link conditional expression, form content is unavailable, so the expression must rely solely on case properties.

In the context of the form link conditional expression, form content is not available, so something like /data/some_question=’yes’ wouldn’t work. The expression below is an example of a expression that could be accepted if the property link_form is saved to the case. This expression gets the case from the case database (casedb), based on the ID stored in the user session, and verifies whether the property link_form is equal to ‘Yes’. If the expression returns 'true', the target form will be presented to the user, otherwise Commcare will move to the next condition, if applicable, or fallback to one of the default options.

Navigation fallback - select where the user should navigate to if that form is not available (for example, if the form is hidden for that case, if the form is hidden for that user, or if the the data needed for the form to open has not been provided). For example, let's say there's a registration form that links to a follow-up form right after it. But only supervisor can do follow-up. If there is a display condition that hides the follow-up form form the normal user and the normal user finishes a registration form, CommCare can’t follow through with the end of form navigation, so it sill fall back on any menu or page you specified in the Navigation Fallback setting. If a supervisor finishes a registration, the form is accessible and end of form navigation happens.

Note: The Case ID is not always referenced in the session as case_id, this varies depending on the form and module configurations. 

Advanced Concepts

Form linking is conditional on a case property being met, the XPath Expression must reference the specific case from the casedb.

• The default XPath reference to a case_id that's been loaded into a form context is instance('commcaresession')/session/data/case_id. You can reference case properties from this case by using the following example syntax:

  • instance('casedb')/casedb/case[@case_id = instance('commcaresession')/session/data/case_id]/link_form = 'yes'

• It's possible to load multiple cases into the same form. This means that there is no default syntax for referencing these cases. To see what data exists in your session hash, you can: 1) Go to App Preview, 2) Open the form you're linking from, 3) Click on "Menu" and select "Evaluate XPath", 4) Type instance('commcaresession')/session. This will display all the data that you can reference from the session hash. See the following example syntax:

  • instance('casedb')/casedb/case[@case_id = instance('commcaresession')/session/data/case_id_new_qi_report_0]/next_step = 'indicateurs'

Limitations

There are some limitations to End of Form Navigation:

• Menus and Linking Data - Menus typically do not require data. The few that do, like menus with a parent menu, do not allow you to customize what data is passed. Even more rarely, a menu may not be available because it requires data, and HQ cannot determine what data it needs. This is likely to happen only with parent-child menu workflows that use different case types than the form you're linking from.

• Registration from the Case List - It is not recommended to set up End of Form Navigation anywhere except the home screen for forms being used as Case List Registration forms. This can lead to unexpected behavior in the Case List Registration workflow. However, despite the warning message displayed when form linking is attempted, it can still work for most use cases. Just make sure to thoroughly test it on Formplayer and mobile.

• Display Only Forms - If you're linking to a menu, not a form, the menu cannot use the display-only forms setting. This is because these menus do not have their own dedicated "screen," and their forms are displayed in the home screen or their parent menu's screen (if there is a parent).

• Formplayer - There have been reports of form linking not fully working on FormPlayer (live preview or webapps), especially when manual form linking is used. Make sure to test it on mobile and report any inconsistencies.