It is sometimes useful for a form to navigate a user to another form. That form may then wish to navigate back to the original form. This can create workflows where smaller forms can be re-used between different larger forms. For instance, consider the case where many forms may wish to use a common lookup form. Rather than design UI and code that will need to be repeated across multiple other forms, a single lookup form can be created and maintained that other forms open to perform the lookup. Then upon finding the data needed, the original calling form is re-opened. The code below will follow this type of example.


First, let's suppose we have a form called "Inspection Form". On this inspection form, we need to lookup a contact. To do this, we're going to launch another form called "Contact Lookup Form". Once a user looks up a contact within that form, we'll return that information back to the form session that originally launched the lookup form.


Let's assume there's a hotspot on the Inspection Form called "LookupContact". Its event handler might look something like this:


// Triggered when a hotspot is pressed
function EH_HotspotPressed(fieldName) {
    if (fieldName == "LookupContact")
    {
        const CONTACT_SEARCH_FORMID = "253548";
        var returnData = {
            ReturnSession: _form.getLocalSessionId(),
        };
        _form.closeAndChangeLocation({ 
            formId: CONTACT_SEARCH_FORMID, 
            sessionParams: { data: returnData }, 
            preventSync: true
        });
    }
}


There are a few things we should take a look at in that code as follows:

  • We need to know the ID of the Contact Lookup Form. In this case we've hard coded it as "253548". There are other form script APIs we could use to find this, but once a form ID has been assigned at design time it's unlikely to change.
  • Next, we need to provide a way for the Contact Lookup Form to know to return to this instance of the Inspection Form. We do that by creating an object called returnData and setting the ReturnSession property of it to the unique session ID of this session. Note that there's no need to call this property ReturnSession, you can call it anything you'd like, but there must be a field on the Contact Lookup Form that has this name. 
  • Lastly, we need to figure out what to do with the Inspection Form. In this case, since we want to return to it, we call _form.closeAndChangeLocation(). This means the form will be saved on the local device and closed. If we wanted to finish or discard this form, there are equivalent methods for doing so. Note that we pass preventSync as true here just to prevent Mi-Apps from syncing between form close and open. This can save a little time when changing forms.


Now, on the Lookup Contact Form we need to have a way of returning to the Inspection Form. Let's assume that there's a hotspot named "ReturnContact" on this form. Let's look at the code that would be used to return to the Inspection Form:


// Triggered when a hotspot is pressed
function EH_HotspotPressed(fieldName) {
    if (fieldName == "ReturnContact")
    {
        var returnData = {
            ContactLastName: _form.getValue("LastName"),
            ContactFirstName: _form.getValue("FirstName")
        };
        var returnSessionUuid = _form.getValue("ReturnSession");
        _form.discardAndChangeLocation({ 
            sessionUuid: returnSessionUuid,
            sessionParams: { data: returnData }
        });
    }
}


Again, let's look at this code in a little more depth:

  • This code assumes that the Contact Lookup Form has the fields "LastName" and "FirstName". It also assumes that the Inspection Form has the fields "ContactLastName" and "ContactFirstName". It's going to pass the values of its own fields back to the Inspection Form by creating the returnData object.
  • Next, it retrieves the session ID of the form session it needs to re-open by getting the value of the ReturnSession field.
  • Lastly, since the Contact Lookup Form isn't meant to be submitted as actual data (it's really just a work sheet), it chooses to discard itself and return to the session that called it. Note that here we're passing a sessionUuid parameter whereas above we passed a formId parameter. This makes the distinction between opening a form session or a form template.