Use Field Service Mobile App Extensions to Open and Exchange Data with the TrueContext Mobile App

The Salesforce Field Service Mobile App can exchange data with the TrueContext Mobile App by means of deep link (App‑to‑App)Closed App‑to‑App communication is a way to exchange data between apps on a device, even if the device is offline. App‑to‑App communication includes both inbound requests to the TrueContext app and, on the Advanced and Enterprise tiers, outbound “callbacks” to an allowed domain or app. URLs. This recipe describes how to set up TrueContext and Salesforce Field Service Mobile App Extensions to exchange data between the two apps.

Info:We’re now TrueContext.

Available on the Advanced and Enterprise tiers:

Essentials
Advanced
Enterprise

Prerequisites

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

  • You must be a TrueContext Admin user.

  • You must have the correct Salesforce and Field Service permissions.

  • You must know how to set up Salesforce objects, records, and custom formula fields.

Scenario

Use Field Service Mobile App Extensions to Open and Exchange Data with the TrueContext Mobile App

Info:We’re now TrueContext.

App Extensions enable you to follow your standard dispatch and scheduling processes while using TrueContext for rich data collection. You can create a standard Work Order and dispatch a related Service Appointment to the Field Service Mobile App.

When a technician selects an App Extension from the Actions menu, the App Extension “calls” the TrueContext Mobile App. As part of that call, the Field Service Mobile App provides information about the Field Service object and record. The App Extension can also ask the TrueContext Mobile App to “call back” with data from the submitted form.

Tip:Organizations that use a work order management system can combine the offline functionality of App‑to‑App communication with the online functionality of a TrueContext cloud-based Data Destination. A Data DestinationClosed A Data Destination specifies where to send data from a submitted form. You can use Data Destinations to automate data sharing and storage, routing data to a specific service (such as email or cloud storage) in several different formats. is typically used to send detailed data to the back-office system of the source app. Data DestinationsClosed A Data Destination specifies where to send data from a submitted form. You can use Data Destinations to automate data sharing and storage, routing data to a specific service (such as email or cloud storage) in several different formats. enable full access to the data submitted from the TrueContext Mobile App, including photos.

This recipe shows you how to configure both Salesforce Field Service and TrueContext.

In Salesforce Field Service In TrueContext
1 Configure custom formula fields for the x-callback parameters. 3 Add Salesforce Field Service to the App‑to‑App allow list.
2 Configure the App Extension Launch Value. 4 (Optional) Configure a Data Source.
  5 Set up the form questions with the correct unique identifiers.
6 Define custom callback parameters to send data back to the Field Service Mobile App.
7 (Optional) Set up and add a Data Destination to upload attachments, documents, and other submitted data.

How the App Extensions work with TrueContext

Open and prepopulate a form in the TrueContext Mobile App

Each App Extension includes a Launch Value that you define as a deep link (App‑to‑App) URL. To use deep links with the TrueContext Mobile App, enter a Launch Value consistent with the TrueContext App‑to‑App URL Scheme.

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

Field Service Mobile App users launch the TrueContext Mobile App by selecting an App Extension from the Actions menu. In this example, the Maintenance Activity App Extension has a Launch Value of:

Copy
prontoforms://x-callback-url/open?name=Maintenance&Description={!$Description}&Asset={!$AssetName__c}&WorkOrderNumber={!$WorkOrderNumber}&WorkOrderID={!$Id}

where:

prontoforms://x-callback-url/open?name=Maintenance
Opens the TrueContext Mobile App and displays a form or a list of forms with the word “Maintenance” in the form name.
&Description={!$Description}&Asset={!$AssetName__c}&WorkOrderNumber={!$WorkOrderNumber}&WorkOrderID={!$Id}

Are parameters that define the TrueContext questions to prepopulate with values from the Work Order record.

Description, Asset, WorkOrderNumber, and WorkOrderID are the unique IDs of the questions in the form that you want to prepopulate.

Info:You can use the open action with any compatible parameters, such as name, tag, or type. The topic App‑to‑App Action Details describes all of the App‑to‑App actions and their associated parameters.

The technician uses the Field Service Mobile App to:

  1. Select the calendar icon to access the assigned service appointment.

  2. Select the appointment to access the work order details.

  3. Swipe up to display the Actions menu.

  4. Select an App Extension, in this example, Maintenance Activity.

On the Salesforce Field Service Mobile App, the list of Actions includes the action "Maintenance Activity" that the user selects to launch the ProntoForms app.

The following example shows the TrueContext Mobile App open on the user’s device with the Description, Work Order Number, Work Order ID, and Asset fields prepopulated.

Preventive Maintenance form that shows the Description, Work Order Number, Work Order ID, and Asset fields prepopulated with values from the Work Order.

Bring the user back to the Field Service Mobile App

You can include x-callback parameters in the Launch Value to:

  • Bring the user back to the Field Service App.

  • Send data from the TrueContext Mobile App back to the Field Service app, even when the user is offline.

In this example, the Launch Value includes x-success, x-cancel, and x-error callback parameters.

Tip:
  • To improve efficiency and provide an optimal user experience, we recommend that you include all three x‑callback parameters in your requests.

  • In Salesforce Field Service, the deep link URLs for App Extensions only allow up to 255 characters. We recommend that you use “formula fields” whenever possible to save characters.

Copy
prontoforms://x-callback-url/open?name=Maintenance&Description={!$Description}&Asset={!$AssetName__c}&WorkOrderNumber={!$WorkOrderNumber}&WorkOrderID={!$Id}&x-success={!$x_success__c}&x-cancel={!$x_cancel__c}&x-error={!$x_error__c}

where:

&x-success={!$x_success__c}

References a formula field that contains the x-success value triggered when a user saves or submits a form, or transfers a 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:

"com.salesforce.fieldservice://v1/sObject/" & Id & "/edit?"

where

com.salesforce.fieldservice://

is the supported Salesforce scheme

v1

is the current deep link version

sObject

represents the instance of the Salesforce object

Id

is the Record ID sent in the App‑to‑App request

edit

is the action used as per the Salesforce deep-linking scheme

This formula opens the Field Service Mobile app in edit mode to update the calling Work Order record with submitted form data.

Info:As per the Field Service Mobile App deep linking schema, the Id is concatenated in the callback URL. This brings the user back to the root Work Order after they submit the form.

The x-success callback sends data from any custom callback parameters defined in the TrueContext Form Builder.

&x-cancel={!$x_cancel__c}

References a formula field that contains the x-cancel value:

"com.salesforce.fieldservice://?"

This formula returns the user to the Field Service Mobile App when the user discards changes.

&x-error={!$x_error__c}

References a formula field that contains the x-error value:

"com.salesforce.fieldservice://?"

This formula returns the user to the Field Service Mobile App when there’s an error. For example, an error can occur when an inbound App‑to‑App request interrupts an active TrueContext Mobile App reconcile.

Tip:Configure a Salesforce Data Destination to update the Work Order record with additional details, including images and documents.

Limitations of Mobile App Extensions

  • The App‑to‑App call can’t contain more than 255 characters. This is a Salesforce limitation.

  • Salesforce does not have a dedicated Windows application for Field Service. You must select iOS or Android to open a form in the TrueContext Mobile App.

Field Service setup

  1. Configure custom fields for the x-success, x-cancel, and x-error callback parameters. This ensures that users always return to the Field Service Mobile App.

    In this example, enter the x-callback parameter names as the Field Label for each custom field.

    Work Order object Custom Field "x-success" with the formula defined as "com.salesforce.fieldservice://v1/sObject/" & Id & "/edit?"

  2. To configure the App Extensions, navigate to the Field Service Mobile Settings:

    Setup > Feature Settings > Service > Field Service > Field Service Mobile > Field Service Mobile Settings

    Tip:You can also enter Field Service Mobile Settings in the Quick Find box, and then select Field Service Mobile Settings from the left navigation.

  3. Select one of the mobile settings rows.

    Result: The system displays the mobile settings details.

  4. In the App Extensions section:

    • To add a new extension, select Add.

    • To edit an existing extension, select Edit next to a row.

  5. Select the Type of each App Extension, either iOS or Android.
  6. Enter the Launch Value. This field is where you add the App‑to‑App call, including the x-callback parametersClosed As part of an App‑to‑App call to the TrueContext app, x-callback parameters provide a way to launch and send data to the calling app. These include x-success, x-cancel, and x-error parameters.. In this example, enter the following:

    Copy
    prontoforms://x-callback-url/open?name=Maintenance&Description={!$Description}&Asset={!$AssetName__c}&WorkOrderNumber={!$WorkOrderNumber}&WorkOrderID={!$Id}&x-success={!$x_success__c}&x-cancel={!$x_cancel__c}&x-error={!$x_error__c}
  7. To create a global App Extension for users to activate from any type of record, leave the Scoped To Object Types field empty.

    Tip:If you want to make the extension available for specific object types, enter the object names as comma-separated values with no spaces.

  8. Save the extension.

The following example shows the App Extension configuration for this example.

Salesforce Field Service Setup that shows App Extension configuration with Type=iOS, Launch Value=prontoforms://x-callback-url..., Label=Maintenance Activity, and Name=MaintenanceActivityWithCallback.

Info:The Salesforce Field Service help pages provide more detailed information about the Field Service setup.

Salesforce also provides details about the Field Service Mobile App deep linking schema.

TrueContext setup

  1. Add Salesforce Field Service to the list of apps that can receive data from the TrueContext Mobile App.

    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.

    1. Username > Team SettingsClosed The Team Settings page is the page where an admin can manage their team's account and edit certain information, such as assigning a Problem Contact Email Address, toggling push notifications, and viewing the account's billing information. > Security > App-to-App Allow List > Update.

    2. Add com.salesforce.fieldservice:// to the list of allowed URLs.

  2. Configure one or more Salesforce Data Sources to prepopulate data in the form with values from the Salesforce Field Service records. This example uses a “Cases” Salesforce Query Data SourceClosed Data sources, also known as "Lookups", are external sources of data that you upload or connect to TrueContext. You can reference this data in a form to populate answers or answer options. Data sources save typing, reduce errors, and make it easy to provide mobile users with only the relevant, most current data. with the following SOQL query:

    SELECT CaseNumber, Id, AccountId, Account.Name, Contact.Name, ContactPhone, ContactEmail, Account.Street__c, Account.City__c, Account.State_Province__c, Account.Country__c, Account.Zip_Postal_Code__c FROM Case
  3. For questions that the App Extension Launch Value sends data to, configure the corresponding unique identifiers.

    1. Go to Manage Forms > List Forms > Create Form or

      Manage Forms > List Forms > FormName > Edit Form or Continue Editing.

    2. In this example, set up the following unique IDs:

      • Description

      • WorkOrderNumber

      • WorkOrderID

      • Asset

    3. Set up the question unique identifiers for any additional fields that send data back to the Field Service Mobile App. You’ll add these to the list of custom callback parameters in the next step. In this example, set up the following ID:

      • Subject

  4. Configure the custom callback parameters. These parameters specify the questions that send data back from TrueContext to the Field Service Mobile App.

    Note:The parameter payload sent from the TrueContext Mobile App must be URL‑encoded. When you use the Form Builder to define custom callback parameters, the payload is automatically URL-encoded.

    1. Go to Settings > Workflow Settings > App-to-App Callbacks.

    2. Map the Field Service parameter names to data from the submitted form. Use a DREL expressionClosed 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. to define the data and metadata that you want to send from the TrueContext Mobile App.

      App-to-App Callbacks section with a list of Field Service parameter names "Subject", "Description", and "Last_Checklist_Activity__c". This also shows the DREL Expressions that map questions from the form to the Field Service parameters: "%a[Subject] (In Progress)", "%a[Description]", and "%u[name] Modified the %f form on %d".

      In this example, the first and third 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 include static text:

      The DREL Expression Resolves to
      %a[Subject] (In Progress) The technician’s entry in the Subject question followed by the static text (In Progress).
      %a[Description] Changes to the Description field that the user entered.
      %u[name] modified the %f form on %d
      • Name of the user who submitted, saved, or transferred the form

      • Static text modified the

      • Form name

      • Static text form on

      • Date the form was submitted, saved, or transferred

  5. To upload attachments, documents, and submitted data to Salesforce Field Service when the user is online, configure a Salesforce Data Destination.

    Note:A Data Destination is not required to send data directly between the TrueContext Mobile App and the Field Service Mobile app.

    This example uses a Salesforce Standard, Custom, or Big Object destination to update the Work Order record.

    1. On the Salesforce Object Fields tab, enter the object API name WorkOrder.

    2. Map the Salesforce fields that you want to update.

      Tip:Use the Describe Salesforce Object option to get Field and API names from your Salesforce org.

    3. On the Update Query tab, set up a query to find the matching Work Order record. In this example, the App Extension Launch Value sends the Id to the question with unique identifier WorkOrderId.

      Query Option section that shows the Salesforce Field or API Name "Id" mapped to the Value Expression "%a[WorkOrderID]". Use the Describe Salesforce Object option to get field and API Names from your Salesforce org.

  6. Add the Data Destination to the form.

    1. Go to Manage Forms > List Forms > FormName > Edit Form or Continue Editing.

    2. On the Destinations tab, select Add a Data Destination.

    3. Select the Salesforce destination that you configured in step 5.

    4. Save and Deploy the form.

  7. Advise users to Sync and ReconcileClosed The term "reconcile" refers to a send/receive action between the mobile app and the TrueContext server. This synchronizes new form versions, data sources, and dispatches from the Web Portal to the mobile app to ensure that mobile users are working with up-to-date resources. This also synchronizes new form submissions from the mobile app to the Web Portal to ensure that work completed by a mobile user gets properly submitted and sent through data destinations. A reconcile can be manually or automatically initiated and requires network connectivity. both the Field Service Mobile App and the TrueContext Mobile App.

    Result: When a user saves, transfers, or submits the form, the x-success callback defined in the App Extension Launch Value executes. In this example, the callback:

    • Re-launches the Field Service Mobile App.

    • Takes the user to the corresponding Work Order record in the Field Service Mobile App, in edit mode.

    • Updates the values in the Work Order with the values sent from the custom callback parameters.

    The following example shows the Work Order record updated with the values entered in the TrueContext Mobile App by the technician.

  8. Work order updated with Subject="Inspection" and Last Checklist Activity="User Name modified the Preventive Maintenance form on 2021-12-15. These are the values either entered by the technician or the metadata values from the submitted form.

  9. In this example, the Work Order opens in “edit” mode. To update the Work Order, the user must Save the values sent back from the TrueContext Mobile App.

    Tip:In the Field Service Mobile App, the user might see a prompt to confirm the launch action. To hide this prompt, follow the instructions provided by Salesforce.

After the Data Destination executes successfully, you can find the uploaded attachments and documents linked to the Work Order record.