Use an App‑to‑App request to open a form and dispatch answers

This recipe shows you how to create and send an App‑to‑App request from your source app to:

  1. Open a specific form in the ProntoForms mobile app.

  2. Provide the technician with some answers already filled in (dispatched).
  3. Re-launch the source app on the technician’s device.

Note:Remember to check the Prerequisites for Using App‑to‑App Communication.

Open a form and dispatch answers

Supported on all tiers:

Essentials
Advanced
Enterprise

Info:This example uses a proprietary ProntoForms test app called pftest.

Copy
prontoforms://x-callback-url/open?name=Universal%20Work%20Order&Job%20-%20Type=Warranty&Job%20-%20Work%20Order%20%23=1234567

The following table describes the request structure.

prontoforms:// ProntoForms custom URL scheme.
x-callback-url Specification that we use for App‑to‑App communication.
open?name=Universal%20Work%20Order

Action to launch the ProntoForms app and open the form named “Universal Work Order”.

%20 replaces the space character in URL encoding.

Note:You must use URL encoding for all App‑to‑App requests. Use UTF-8 based percent encoding for all special characters other than parentheses ( ).

&Job%20-%20Type=Warranty
&Job%20-%20Work%20Order%20%23=1234567

Prepopulates two questions:

  • & is a separator for the “arguments” that form part of the request.

  • Job%20-%20Type=Warranty prepopulates the question with unique ID “Job - Type” with the answer “Warranty”.

  • &Job%20-%20Work%20Order%20%23=1234567 is another argument that prepopulates the question with unique ID “Job Work - Order #” with the answer “1234567”.

    Note:The # special character is URL-encoded as %23.

The form opens on the user’s device with the two questions prepopulated, as shown in the following example:

"Universal Work Order" form open with "Service type" and "Work Order #" prepopulated

Tip:The question text in the form can be different from the question unique ID. In this example, the unique ID in the request is Job%20-%20Work%20Order%20%23 but the question text is Work Order #.

Re-launch the source app and return data from the form

Supported on the Advanced and Enterprise tiers:

Essentials
Advanced
Enterprise

The second part of the request contains the callback actions. In this example, the request includes all three App‑to‑App x-callback Parameters:

Copy
prontoforms://x-callback-url/open?name=Universal%20Work%20Order&Job%20-%20Type=Warranty&Job%20-%20Work%20Order%20%23=1234567&x-success=pftest://success&x-cancel=pftest://cancel&x-error=pftest://error

The following table describes the x-callback action structure.

&x-success=pftest://success

Tells the ProntoForms mobile app what to do when the user saves, sends, or transfers the form. In this example, the ProntoForms mobile app launches the app pftest and carries out the success action.

Tip:If you’ve configured any custom callback parameters, the ProntoForms mobile app returns these as part of the x-success callback.

&x-cancel=pftest://cancel Tells the ProntoForms mobile app what to do when the user cancels an action, such as discarding form changes.
&x-error=pftest://error

Tells the ProntoForms mobile app what to do when there’s a problem, such as a dialog box blocking an inbound App‑to‑App request. An error can also occur when a requested item, such as a specific form or draft, cannot be found.

Our test app, pftest, shows the results of each x-callback parameter as shown in the following examples.

  • The user successfully submits the form:

    x-success callback returns the pfStatus, clientDataRecordID, and the serverDataRecordID

    Tip:If you’ve configured any custom callback parameters, the ProntoForms mobile app returns these as part of the x-success callback.

  • The user discards changes without saving:

    x-cancel callback returns no response parameters

  • An inbound App‑to‑App request interrupts an active reconcile on the device, or an active dialog box blocks an inbound App‑to‑App request:

    x-error callback returns an error message