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 DREL 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:

Prerequisites

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

• You must be an Admin user or a User with Can Create FormSpace permissions FormSpace Permissions control the permissions that a user group has in a particular FormSpace. These are primarily used to control the forms (and the state of form) users can access on their mobile devices. Less commonly, FormSpace permissions give non-admin Users some administrative access to a particular FormSpace without giving them full Admin access to all FormSpaces..

  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

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

  Info:We're now TrueContext.

  To support both new and existing integrations, the TrueContext App‑to‑App URL scheme will remain prontoforms:// with alternative https://prontofor.ms/.

  For more detailed information about what’s changing, visit https://support.truecontext.com/hc/en-us/articles/19516168513556

  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 Actions and App‑to‑App x-callback parameters provide detailed information about how to construct App‑to‑App requests.

• Your allow list must include the URLs and apps that you want to receive data from TrueContext.

  The default allow list settings depend on when your team was created:

  • For teams created before February 23, 2021, the allow list defaults to all callbacks allowed.

  • For teams created after February 23, 2021, the allow list defaults to no callbacks allowed.

  Note:In both cases, we recommend that you configure a custom App‑to‑App allow list.

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 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 Teamwork 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 reassigned 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.

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

     

     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.