Configure App‑to‑App Custom Callback Parameters

This topic describes how to use the TrueContext Form Builder to configure custom callback parameters. 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.

Available 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 sectionClosed A Repeatable Section is a subform that contains a set of related questions. The data captured is “repeating”, because the field user can complete the same subform more than once, which creates multiple entries..

  • 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 TrueContext Mobile App.
    %r[pfStatus]

    The form’s current status on the device (Saved, Sent, or Outbox).

    Status Description
    Saved A TrueContext 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 TrueContext server.
    Incomplete

    A mobile user transferred an incomplete TrueContext TeamworkClosed TrueContext Teamwork is an Enterprise tier feature that enables mobile users to transfer incomplete 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 TrueContext server or assigned to another user’s Inbox. The form is in this state until a user makes changes to it.
    Saved

    A TrueContext Mobile App user opened a form and made changes to it. The form might be saved in the Drafts or Inbox folder.

  • Callback parameters apply only to form actions, not to resource actions. The TrueContext system doesn’t send any callback parameters for calls that list or open resources in the Resource Library.

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 Forms & Integrations menu, navigate to the form you want to set up.

  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 TrueContext 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.