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, with more options on the Advanced and Enterprise tiers:

Essentials
Advanced
Enterprise

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

Info:Keep in mind that:
  • Different form 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).
  • On the Enterprise tier, a dispatched record might also be located in the Group Inbox.
  • Resources are always located in the resourcelibrary, regardless of the workflow.

Note:The list action for the Resource Library and Group Inbox is supported on TrueContext Mobile App versions 22.1 and later.

type

Description

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

Required

Not required for forms.

Required for the following Enterprise tier options:

Default value

forms

Expected values

forms

drafts

inbox

sent

groupinbox

resourcelibrary

Example

Display the Inbox view of the TrueContext Mobile App.

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

Display a list of records that were dispatched to a group or FormSpaceClosed FormSpaces are where forms are stored and organized in the TrueContext Web Portal. A TrueContext Team may have multiple FormSpaces, depending on their needs. Admins can set FormSpace permissions to control which users have access to the forms in that FormSpace.. Users can claim a record from the list displayed in the Group Inbox.

truecontext://x-callback-url/list?type=groupinbox

Display the list of resources in the Resource Library.

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

Description

Display a list of forms or resources that match the specified form tag or resource tag.

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.

  • For resources, you must include type=resourcelibrary.

  • For records dispatched to a group or FormSpace, you must include type=groupinbox.

    Info:The topic App‑to‑App Group Inbox Support describes how to set up App‑to‑App calls to the Group Inbox in more detail.

tagOperator

By default, the Mobile App displays a list of forms or resources that have all the specified tags. Use tagOperator=OR to list forms or resources 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 resources that have both the “install” tag and the “checklist” tag. The tagOperator parameter in the second example is optional.

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

or

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

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 forms or resources that match the specified parameters.

  • If only one form or resource is a match, that form or resource opens in the TrueContext Mobile App.

  • If more than one form or resource is a match, a list of matching items opens in the TrueContext Mobile App.

  • For the Group Inbox:

    • If only one record is a match, the Details view opens so that the user can claim the record.

    • If more than one record is a match, a list of matching records is displayed in the Group Inbox. Users can claim a record from the list.

Note:The open action for the Resource Library and Group Inbox is supported on TrueContext Mobile App versions 22.1 and later.

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 matching form in the user’s Inbox.

Info:You can use the open action to open a form and dispatch answers. The topic Use an App‑to‑App Request to Open a Form and Dispatch Answers provides a detailed example and instructions.

name

Description

Open forms or resources based on the name. This parameter matches partial strings.

Note:You must enter the name using URL encoding. For resources, you must include type=resourcelibrary.

Open forms or resources based on the name. This parameter matches partial strings.

Note:You must enter the name using URL encoding.
  • For resources, you must include type=resourcelibrary.
  • For records dispatched to a group or FormSpace, you must include type=groupinbox.

Example

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

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

Open a form or list of forms and dispatch a value, where “Job - Type” is the question unique ID and “Warranty” is the value.

truecontext://x-callback-url/open?name=asset%20list&Job%20-%20Type=Warranty

If more than one form is a match, the value is dispatched after the user opens a form from the list.

Open a record or list of records dispatched to a group or FormSpace and dispatch a value , where “Job - Type” is the question unique ID and “Warranty” is the value.

truecontext://x-callback-url/open?type=groupinbox&name=asset%20list&Job%20-%20Type=Warranty

The value is dispatched after the user claims and opens a record.

Info:You can dispatch multiple values, as described in the topic Use an App‑to‑App Request to Open a Form and Dispatch Answers.

Open a resource or list of resources that have the words “asset list” in the name.

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

Description

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

  • For a resource, use type=resourcelibrary.
  • For a record that was dispatched to a group or FormSpace, use type=groupinbox.

Default value

forms

Expected values

forms

inbox

drafts

groupinbox

resourcelibrary

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

Open a resource or list of resources that have the words “asset list” in the name.

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

Open a record or list of records dispatched to a group or FormSpace if the names contain the words “asset list”.

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

Description

Open forms or resources that match the specified form tag or resource tag.

  • If only one form or resource is a match, that form or resource opens in the TrueContext Mobile App.
  • If more than one form or resource is a match, a list of matching items opens in the TrueContext Mobile App.
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.

  • For resources, you must include type=resourcelibrary.

  • For records dispatched to a group or FormSpace, you must include type=groupinbox.

    Info:The topic App‑to‑App Group Inbox Support describes how to set up App‑to‑App calls to the Group Inbox in more detail.

tagOperator

By default, the TrueContext Mobile App matches forms or resources that have all specified tags. Use the tagOperator=OR parameter to open a form or resource 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 resource or list of resources that have both the “install” tag and the “checklist” tag. The tagOperator parameter in the second example is optional.

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

or

truecontext://x-callback-url/open?type=resourcelibrary&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]

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
resourceID

Info:The Resource Library must be set up for your team, and individual resources must be set to Visible in Resource Library. The topic Set Up the Resource Library describes the process in more detail.

Description

Open an image or document in the Resource Library.

Example

Open a resource that has a resourceID of “1234567891”.

truecontext://x-callback-url/open?type=resourcelibrary&resourceID=1234567891

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