Configure App‑to‑App Custom Callback Parameters

Supported on the Advanced and Enterprise tiers:

Prerequisites

• Your ProntoForms Team must be on the Advanced or Enterprise tier.

• You must be an Admin user or a User with Can Create FormSpace permissions.

  Tip:If you’re not an Admin user, you should have the following permissions so that you can thoroughly test your forms:

  • Can Test
  • Can View
  • Can Submit

• ProntoForms returns the user-defined custom callback parameters as part of the x‑success callback. You must configure the source app to use an x‑success callback parameter as part of the URL, as shown in the following example.

  prontoforms://x‑callback‑url/open?name=formName&x‑success=sourceApp://success

  where formName, sourceApp, and success are placeholders for your actual values.

  Info:The topics App‑to‑App Callback Actions and App‑to‑App x-callback Parameters provide detailed information about how to construct App‑to‑App requests.

Limitations

The following limitations apply to custom callback parameters:

• You can define up to five custom callback parameters.

• Each parameter name must be unique.

• The maximum length of the x-success callback—including parameter names and values after UTF-8 percent encoding—is 1000 characters.

• DREL expressions can only reference top-level questions, not questions in a repeatable section.

• User-defined custom callback parameters apply to x‑success callbacks only.

• If the DREL expression does not resolve to a value, the callback returns the parameter with an empty string as the value.

• You can use the following DREL references and properties:

  DREL reference	Returns
  %a[questionUniqueID]	The information a user submitted as an answer to the question with the specified questionUniqueID.
  %t	The time that a user submitted a form.
  %d	The date that a user submitted a form.
  %r[id]	The submitted form’s serverDataRecordID.
  %r[clientDataRecordId]	The ID assigned by the ProntoForms app.
  %r[pfStatus]	The form’s current status on the device (Saved, Sent, or Outbox). Status Description Saved A ProntoForms mobile app user opened a form from the Forms box or Inbox, and then saved it. Outbox A submitted form is still processing on the user’s device and has not yet been uploaded to the server. This can happen when a device is offline, for example. Sent A submitted form was uploaded to the server.
  %r[state]	The state of a submitted or saved form. State Description Complete A mobile user sent a completed form. The submitted form might be in the user’s outbox, or it might have been uploaded to the ProntoForms server. Incomplete A mobile user transferred an incomplete ProntoForms Teamwork-enabled form. The form might be unassigned on the ProntoForms server, or reassigned to another user’s Inbox. The form is in this state until a user makes changes to it. Saved A ProntoForms mobile app user opened a form and made changes to it. The form might be saved in the Drafts or Inbox folder.

Info:The DREL expression can contain multiple DREL references, static text, or a plain text string, such as JSON.

Steps to configure App‑to‑App custom callback parameters

1. From the Manage Forms menu, navigate to the form you want to configure.

2. Select Edit Form, and then select Settings > Workflow settings.

3. In the App‑to‑App Callbacks section, define up to five parameter names and associated DREL expressions.

   The following example shows custom parameters that return the

   • answers to two of the questions on the form

   • unique identifier of the form on the mobile user’s device (clientDataRecordId), and

   • date and time that the user submitted the form.

     

     Tip:

     • The DREL expression can contain multiple DREL references, static text, or a plain text string, such as JSON.
     • You can use DREL properties to define the format of form submission dates and times.
     • If you want to rename a standard parameter that’s returned by default with the x‑success callback, you can include it in the custom parameters. In this example, the clientDataRecordID value is returned as the custom callback parameter “RecordID”.

   Info:The topic DREL Quick Reference provides information about how to construct a DREL Expression.

4. Save the form or continue editing.

   The x‑success callback is triggered when the mobile device user saves or sends a form, or transfers a ProntoForms Teamwork-enabled form. The x‑success callback opens the success URL and returns the standard and custom callback parameter names and values:

   sourceApp://pfStatus=Sent&serverDataRecordID=12345678912
   &clientDataRecordID=A1A1A1A1-AAAA-1111-AAAAAA111111
   &FormSubmissionTime=2020-090-2311:31:20&JobStartDate=2020-09-23T15:31:00Z&RecordID=A1A1A1A1-AAAA-1111-AAAAAA111111

   Tip:In this example, the clientDataRecordID value is passed twice, once with the standard parameter name and also as a custom callback parameter with the name RecordID.