Configure App‑to‑App Custom Callback Parameters

This topic describes how to use the ProntoForms Form BuilderClosed The Form Builder is the tool that form designers use to create forms. In the Form Builder, accessed from the ProntoForms Web Portal, form designers can add and edit pages, sections, and questions, as well as attach data destinations and configure the form's settings. to configure custom callback parametersClosed App‑to‑App custom callback parameters are user-defined parameters that indicate which answers and metadata to pass from the ProntoForms app to another app on a user’s device.. It describes in detail how to define parameter names and corresponding DRELClosed Data Reference Expression Language (DREL) is used to get form data and metadata and add it to a string, such as dates, usernames, or answers to questions in forms. expressions to retrieve and share form data and metadata between apps on a mobile device.

Supported on the Advanced and Enterprise tiers:

Essentials
Advanced
Enterprise

Prerequisites

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 TeamworkClosed ProntoForms Teamwork is an Enterprise tier feature that enables mobile users to transfer icomplete forms for other users to complete as part of a multi-user workflow. This can be useful for jobs that require someone else's expertise or that span multiple shifts.-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.

      App-to-App Callbacks section with four parameters and corresponding DREL expressions defined. For example, Parameter = JobStartDate (to match the source app) and %a[Job - start date], which returns the answer to the question with that unique ID

      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.