App‑to‑App Action Details

Most App‑to‑App actions have additional parameters that you use to define exactly what you want to happen on the TrueContext Mobile App. This topic describes the additional parameter details for each App‑to‑App action.

Info:We're now TrueContext.

Use truecontext:// or tcxt:// in your App‑to‑App calls.

To maintain existing integrations, TrueContext will continue to support prontoforms:// and the alternative https://prontofor.ms/.

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

Available on all tiers:

Essentials
Advanced
Enterprise

Info:Different identifiers apply at different stages in a workflow. When you build an App‑to‑App request, you must use valid combinations of identifier and location (Forms, Inbox, Drafts, or Search). The topic How to Use Form Identifiers in an App‑to‑App Call describes these combinations in more detail.

Contents

Note:Parameter names are case-sensitive.

launch parameters

The launch action has no additional parameters.

refresh parameters

The refresh action has no additional parameters.

list parameters

type

Description

Displays a specific area of the TrueContext Mobile App (Forms, Drafts, Inbox, or Sent).

Required

No

Default value

forms

Expected values

forms

drafts

inbox

sent

Example

Display the Inbox view of the TrueContext Mobile App.

truecontext://x-callback-url/list?type=inbox
tag
tag.list

Description

Display a list of forms based on one or more valid form tags.

Tip:Use the type parameter along with tag to specify the location of the forms within the app (Forms, Inbox, or Drafts). Without the type parameter, the results default to Forms.

tagOperator

By default, the Mobile App displays a list of forms that have all the specified tags. Use tagOperator=OR to list forms that have any one of the specified tags.

Tip:The tagOperator parameter is optional. If you want to keep the default behavior, you don’t need to include tagOperator=AND in the App‑to‑App call.
Limitations Supported on iOS, macOS, and Windows, and on Android versions 14.7 and later.

Examples

Display a list of forms that have the “install” tag.

truecontext://x-callback-url/list?tag=install

Display a list of forms that have both the “install” tag and the “checklist” tag. The tagOperator parameter in the second example is optional.

truecontext://x-callback-url/list?tag.list=[install,checklist]

or

truecontext://x-callback-url/list?tagOperator=AND&tag.list=[install,checklist]

Note:If there are no forms that have all specified tags, the app displays an empty list.

Display a list of forms that have at least one of the specified tags. In this example, the app displays forms with the “install” tag, the “checklist” tag, or both tags. Include tagOperator=OR in the App‑to‑App request.

truecontext://x-callback-url/list?tagOperator=OR&tag.list=[install,checklist]

Display a list of forms in the Inbox that have at least one of the specified tags.

truecontext://x-callback-url/list?tagOperator=OR&tag.list=[install,checklist]&type=inbox

open parameters

Open a form or a list of forms that match the specified parameters.

Tip:You can use multiple parameters to improve the precision of the results. For example, use the name and type=inbox parameters to open a list of matching forms in the user’s Inbox.

name

Description

Open a form or list of forms based on the form name. This parameter matches partial strings.

Note:You must enter the form name using URL encoding.

Example

Open a list of forms that have the words “asset” and “list” in the name.

truecontext://x-callback-url/open?name=asset%20list
type

Description

Use the type parameter to specify whether the form opens from the Forms, Inbox, or Drafts.

Default value

forms

Expected values

forms

inbox

drafts

Example

Open a form or a list of forms in the user’s Inbox that have the word “asset” in the name.

truecontext://x-callback-url/open?name=asset&type=inbox
tag
tag.list

Description

Open a form or a list of forms based on one or more valid form tags. If more than one form matches the tags, the TrueContext Mobile App displays a list of matching forms in the user’s Forms list.

Tip:Use the type parameter along with tag to specify the location of the forms within the app (Forms, Inbox, or Drafts). Without the type parameter, the results default to Forms.

tagOperator

By default, the TrueContext Mobile App matches forms that have all specified tags. Use the tagOperator=OR parameter to open a form that has any one of the specified tags.

Tip:The tagOperator parameter is optional. If you want to keep the default behavior, you don’t need to include tagOperator=AND in the App‑to‑App call.

Examples

Open a form or list of forms that have the “install” tag.

truecontext://x-callback-url/open?tag=install

Open a form or list of forms that have both the “install” tag and the “checklist” tag. The tagOperator parameter in the second example is optional.

truecontext://x-callback-url/open?tag.list=[install,checklist]

or

truecontext://x-callback-url/open?tagOperator=AND&tag.list=[install,checklist]

Open a form or list of forms that have at least one of the specified tags. Include tagOperator=OR in the App‑to‑App request.

truecontext://x-callback-url/open?tagOperator=OR&tag.list=[install,checklist]

For any device, open a matching form or list of forms in the Inbox.

truecontext://x-callback-url/open?tagOperator=OR&tag.list=[install,checklist]&type=inbox
formID

Description

Open a form or list of forms based on the form ID. This is the unique identifier of an empty form.

Examples

Open a form with ID of “99999999”.

truecontext://x-callback-url/open?formID=99999999

Open and prepopulate the form with the customer name and work order number. This is an example of a “dispatch” type request.

truecontext://x-callback-url/open?formID=99999999&CustomerName=Best%20Pianos&WorkOrderID=1234

Note:The TrueContext Mobile App ignores any question unique IDs that are not defined in the form.
formIterationID

Description

Open a form or list of forms based on the form iteration ID. This is the unique identifier of a specific version of a form.

Examples

Open an active form with the version (iteration) of “98765432”.

truecontext://x-callback-url/open?formIterationID=98765432

Open and prepopulate the form with the customer name and work order number.

truecontext://x-callback-url/open?formIterationID=formIterationID&CustomerName=Best%20Pianos&WorkOrderID=1234
dataRecordID

Description

Open a dispatched form based on its form submission ID (the “data record” ID assigned when the TrueContext server sends a form or receives a submitted form). The form can only be in the Inbox. The form can be

  1. a dispatched form

  2. a completed form sent for editing, or

  3. an assigned 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.

Example

Open a dispatched form with a form submission ID of “123456789”.

truecontext://x-callback-url/open?dataRecordID=123456789
clientDataRecordID

Description

Open a form that’s in a user’s Drafts.

This parameter is usually used for a previously opened form that the user saved in Drafts. Any previous App‑to‑App requests that have the x-success parameter included return the clientDataRecordID when the user saves the form to Drafts.

Example

Open a saved form with a form clientDataRecordID of “A1A1A1A1-AAAA-1111-AAAAAA111111”.

truecontext://x-callback-url/open?clientDataRecordID=A1A1A1A1-AAAA-1111-AAAAAA111111

_lang

Info:This parameter is for use with Multi-Language Forms only.

Description

Open a form in one of the languages that’s set up for the form.

This works the first time the form opens, not when a form has already been:

  • Opened

  • Saved

  • Dispatched with a preselected language

  • Sent for edit, or

  • Transferred

Example

Open a blank form in Spanish that has the words “asset” and “list” in the form name.

Tip:The form name in the App‑to‑App call is the original name that the Form Designer entered when they built the form.

truecontext://x-callback-url/open?name=asset%20list&_lang=es

Note:The _lang parameter value must be a language code for one of the Supported Languages for the Multi-Language Feature.
Behavior

The following table describes how the behavior on the Mobile App varies based on whether the App‑to‑App call:

  • Results in a list of matching forms.

  • Specifies a language that’s set up for the form.

  • Includes x-callback parameters.

  • References a form that already had a language selected.

If… And… Then…
More than one form matches the specified parameters The selected form opens in the specified language.
The language specified in the App‑to‑App call is not set up for the specified form The call does not include any x-callback parameters The Mobile App displays an error.
The call does include one or more x-callback parameters

The callback returns a 1020 error.

A language was previously selected for:

  • A dispatched form saved to the Inbox

  • A dispatched form with the language preselected

  • A form saved to Drafts

 The Mobile App displays an error.

  • The _lang parameter specifies a different language

  • The call does include one or more x-callback parameters

The callback returns a 1021 error.
Note:When you use the open action to prepopulate (dispatch) a form, make sure that the answers match the supported question and data types.

For example:

  • To prepopulate a question that has an “Integer” data type, you must send an integer in your URL.

  • To prepopulate a dropdown question, you must send an answer that’s defined as an option for that question.

send parameters

Note:The type and at least one form identifier are required for the send request.

name

Description

Send a form based on the form name. This parameter matches partial strings.

Note:You must enter the form name using URL encoding.

Example

Send a form from the Inbox that has the words “asset list” in the name.

truecontext://x-callback-url/send?name=asset%20list&type=inbox

If more than one form matches the search string, the user selects the form to send from a list.
type

Description

Specify the location of the form to send from the TrueContext Mobile App to the TrueContext server.
Required? Yes
Default value

None (you must provide a value)

Note:An unspecified or invalid value triggers the x-error callback. If the x-error is triggered but isn’t included in the request, the end user receives an error message.
Expected values

forms

drafts

inbox

Example

Send a form that a user started and saved to Drafts in the TrueContext Mobile App.

truecontext://x-callback-url/send?type=drafts&clientDataRecordID=A1A1A1A1-AAAA-1111-AAAAAA111111
tag
tag.list

Description

Send a form based on one or more valid form tags. If more than one form matches the tags, the TrueContext Mobile App displays a list of matching forms.

Tip:Use the type parameter along with tag to specify the location of the forms within the app (Forms, Inbox, or Drafts). Without the type parameter, the results default to Forms.

tagOperator

By default, the TrueContext Mobile App matches forms that have all the specified tags. Use the tagOperator=OR parameter to send a form that has any one of the specified tags.

Tip:The tagOperator parameter is optional. If you want to keep the default behavior, you don’t need to include tagOperator=AND in the App‑to‑App call.

Examples

Send a form from the Inbox that has the “install” tag.

truecontext://x-callback-url/send?tag=install&type=inbox

Send a form from the Inbox that has both the “install” tag and the “checklist” tag. The tagOperator parameter in the second example is optional.

truecontext://x-callback-url/send?tag.list=[install,checklist]&type=inbox

or

truecontext://x-callback-url/send?tagOperator=AND&tag.list=[install,checklist]&type=inbox

Send a form that has at least one of the specified tags. Include tagOperator=OR in the App‑to‑App request.

truecontext://x-callback-url/send?tagOperator=OR&tag.list=[install,checklist]&type=inbox
formID

Description

Open, populate, and send a form from the TrueContext Mobile App to the TrueContext server based on the form ID. This is the unique identifier of a form.

Example

Open a form, populate an answer that triggers Conditional Logic to populate other answers, and send a form. This process requires no user interaction.

truecontext://x-callback-url/send?type=forms&formID=99999999&ServiceType=Warranty
formIterationID

Description

Open, populate, and send a form from the TrueContext Mobile App to the TrueContext server based on the form iteration ID. This is the unique identifier of a specific version of a form.

Example

Open, populate, and send a form with the version (iteration) of “98765432”.

Note:On an iOS device, the user might have to select OK to confirm and send the form. To avoid this, in the TrueContext Mobile App settings, switch the Confirm Send option off.

truecontext://x-callback-url/send?type=forms&formIterationID=98765432&ServiceType=Warranty
dataRecordID

Description

Send a dispatched, transferred, or completed form based on its form submission ID (the “data record” ID assigned when the TrueContext server receives the submitted form).

Note:The term transferred only applies to TrueContext Teamwork-enabled forms.

Example

Open and send a form from the user’s Inbox with a dispatched form ID of “123456789”.

truecontext://x-callback-url/send?type=inbox&dataRecordID=123456789
clientDataRecordID

Description

Send a form already opened by your source app and saved by the TrueContext Mobile App user in their Drafts.

You can find the clientDataRecordID in any previous App‑to‑App requests that have the x-success parameter included. An x-success callback returns the clientDataRecordID when the user saves the form to Drafts.

Example

Open and send a saved form with a clientDataRecordID of “A1A1A1A1-AAAA-1111-AAAAAA111111”.

truecontext://x-callback-url/send?type=drafts&clientDataRecordID=A1A1A1A1-AAAA-1111-AAAAAA111111
_lang

Info:This parameter is for use with Multi-Language Forms only.

Description

Send a form in one of the languages that’s set up for the form.

This works the first time the form opens, not when a form has already been:

  • Opened

  • Saved

  • Dispatched with a preselected language

  • Sent for edit, or

  • Transferred

Example

Send a blank form in Spanish that has the words “asset” and “list” in the form name.

Tip:The form name in the App‑to‑App call is the original name that the Form Designer entered when they built the form.

truecontext://x-callback-url/send?name=asset%20list&_lang=es

Note:The _lang parameter value must be a language code for one of the Supported Languages for the Multi-Language Feature.
Behavior

The following table describes how the behavior on the Mobile App varies based on whether the App‑to‑App call:

  • Results in a list of matching forms.

  • Specifies a language that’s set up for the form.

  • Includes x-callback parameters.

  • References a form that already had a language selected.

If… And… Then…
More than one form matches the specified parameters

  • The user selects a Multi-Language Form from the list of forms. The list includes only the forms that are set up with the specified language.

 The selected form sends in the specified language.
The language specified in the App‑to‑App call is not set up for the specified form The call does not include any x-callback parameters The Mobile App displays an error.
The call does include one or more x-callback parameters

The callback returns a 1020 error.

A language was previously selected for:

  • A dispatched form saved to the Inbox

  • A dispatched form with the language preselected

  • A form saved to Drafts

 The Mobile App displays an error.

  • The _lang parameter specifies a different language

  • The call does include one or more x-callback parameters

The callback returns a 1021 error.

search parameters

Note:The search action works when the TrueContext Mobile App user is online, belongs to a TrueContext team with Search enabled, and has access to Search-enabled forms.

Tip:For TrueContext Teamwork-enabled forms (Enterprise tier only), use the search action when you want to display a list of incomplete forms that a user can claim.

searchText

Description

Open a list of form submissions based on the form submission name. This parameter matches part of the form submission name, so that the user can select from a list of matching forms.

Note:You must enter the form submission name using App‑to‑App URL Encoding.

Example

Open a list of form submissions that have the words “asset list” in the name.

truecontext://x-callback-url/search?searchText=asset%20list
stateFilter

Description

Open a list of forms based on the form submission state.
Default value Any
Expected values

For all types of Mobile App forms:

Any

AllComplete

For TrueContext Teamwork-enabled forms only:

AllIncomplete

IncompleteUnassigned

Example

Open a list of incomplete TrueContext Teamwork-enabled forms that are available for a user to claim.

truecontext://x-callback-url/search?stateFilter=IncompleteUnassigned
dateSearchType

Description

Open a list of forms based on the date the form was last submitted. You can choose to search on a date range or date period.
Default value

AnyDate

Returns a list of forms submitted within the last 365 days.
Expected values

AnyDate

DatePeriod

DateRange

Additional parameters

  • The DatePeriod defaults to 7 days. To change the default value, you must also specify the datePeriod:

    • Today

    • Yesterday

    • ThisWeek

    • ThisMonth

    • LastHour

    • TwentyFourHours

    • SevenDays

    • ThirtyDays

  • The DateRange has no default—you must specify the dateRangeStart and dateRangeEnd values in the following ISO 8601 format:

    YYYY-MM-DDTHH:mm:ssZ, for example, 2021-06-16T04:00Z

    Note:In the ISO 8601 format, Z specifies the date and time in UTC. In the search results, the TrueContext Mobile App converts and displays the search date and time in the time zone set on the device.

Examples

Open a list of incomplete TrueContext Teamwork-enabled forms that were submitted this week.

truecontext://x-callback-url/search?stateFilter=AllIncomplete&dateSearchType=DatePeriod&datePeriod=ThisWeek

Open a list of forms that were submitted during a specific date range.

truecontext://x-callback-url/search?dateSearchType=DateRange&dateRangeStart=2021-06-16T04:00Z&dateRangeEnd=2021-06-18T04:00Z