Send Data from TrueContext to ServiceMax Go

The ServiceMax Go app can receive data from a third-party app—such as the TrueContext Mobile App—in the form of a 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. URL. This topic describes how you set up ServiceMax to generate the URL and how to configure the corresponding Custom callback parametersClosed App‑to‑App custom callback parameters are user-defined parameters that indicate which answers and metadata to pass from the TrueContext app to another app on a user’s device. in TrueContext.

Available on the Advanced and Enterprise tiers:

Essentials
Advanced
Enterprise

How the App‑to‑App call to the TrueContext Mobile App works

Send Data from TrueContext to ServiceMax Go

The ServiceMax Go app “calls” the TrueContext Mobile App and provides information about the ServiceMax object and record. As part of that call, ServiceMax Go asks the TrueContext Mobile App to “call back” with data to update the record.

ServiceMax Go generates this call for you when you set up

The process of sending a call to and receiving a callback from the TrueContext Mobile App happens in the following order.

  1. A ServiceMax Go Custom Action opens a form in the TrueContext Mobile App.

  2. The App‑to‑App call sends the Work Order Number and Record ID to the TrueContext Mobile App as answers to questions in the form (optional).

  3. The user works on and saves, transfers, or submits the form.

  4. The x-success callback parameterClosed 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. tells the TrueContext Mobile App to:

    1. Send the form data specified in the custom callback parameters to update the ServiceMax Go record.

    2. Relaunch the ServiceMax Go app.

Example of an App‑to‑App call

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

ServiceMax generates the call to the TrueContext Mobile App—also known as a deep link URL—when a user executes a Custom Action. The call uses the x-callback-url specification and might look something like this.

truecontext://x-callback-url/open?name=Inspection%20Checklist&WorkOrderNumber=WorkOrderNumberValue&RecordID=recordIDValue&x-success=https://go.servicemax.io/sfm/SFM ID/Record ID&x-cancel=https://go.servicemax.io&x-error=https://go.servicemax.io?data=

where SFM ID and Record ID represent the actual values of those identifiers.

The following sections describe each part of this App‑to‑App call and how to set it up in ServiceMax Go and TrueContext.

ServiceMax setup

Info:The ServiceMax help pages provide detailed information about the ServiceMax setup.

Your ServiceMax setup must include the following configuration for the parent object (such as a Work Order). This configuration generates the App‑to‑App call (deep link URL) to the TrueContext Mobile App and tells it what to send back to ServiceMax.

Tip:This example shows you how to configure ServiceMax to update dynamically the record that initiates the App‑to‑App call. You can also specify a static ID to update a specific record.

  1. Create or edit an SFM Transaction. Specify the fields that you want to update with data from the TrueContext Mobile App. You do this on the Layout Editor tab, in the Parent Object Sections.

    The following example shows an SFM Transaction for the Work Order object, with the Order Status, Inspection Start Time, and Inspection End Time fields added.

    In ServiceMax, shows the SFM Transaction Designer with the "Work Order" parent object and, in the Layout Editor view, the "Order Status", "Inspection Start Time", and "Inspection End Time" fields added to be updated by TrueContext.

    Note:Each field that you add in the SFM Transaction must match a question unique identifier in the TrueContext Mobile App form.

  2. For the target object, create an SFM wizard step and specify the SFM Transaction from step 1.

    Example of an SFM wizard step that shows the Step ID

  3. Configure a custom field with a formula to convert the 15-digit record ID to an 18-digit ID referenced by the ServiceMax API. Enter the following formula:

    CASESAFEID(Id)

    Shows the formula field with the formula CASESAFEID(Id) to convert the record ID to 18 digits dynamically

  4. Configure a second custom formula field to concatenate the SFM Transaction ID and the Record ID. In this example, this second custom field is called Callback Parameter. Enter the following formula:

    "https://go.servicemax.io/sfm/SFM ID/" & FieldApiName & "?"

    where

    https://go.servicemax.io/

    is the ServiceMax Go URL scheme.

                                        
                                            sfm/SFM ID
                                    

    specifies the SFM Transaction ID.

    &

    concatenates values.

                                        FieldApiName
                                    

    is the API name of the formula field that you configured in step 3. This is the formula to get the Record ID.

    "?"

    is a formatting requirement that marks the beginning of the parameters defined in the TrueContext Form Builder, including data-source (mandatory) and mode (optional).

  5. Define a custom App-to-App action to open the TrueContext Mobile App. This is where you define the App‑to‑App call, which includes the

    Shows the Custom Action configured as App-to-App, with the URL scheme "prontoforms", the action x-callback-URL/open. The parameters include a combination of field names and static values.

    Note:Each Parameter Name defined in the Custom Action must match a question unique identifier in the TrueContext Mobile App form.

    To make sure that the user always returns to the ServiceMax Go app, we recommend that you define all of the x-callback parameters: x-success, x-error, and x-cancel.

TrueContext setup

  1. In the TrueContext Web PortalClosed The TrueContext Web Portal is a web application used to manage security settings, forms, FormSpaces, other users, Data Sources, and Data Destinations., define a custom App‑to‑App allow listClosed An App‑to‑App allow list is a list of URLs and third-party applications that can receive data from TrueContext in a callback. to manage the apps that can receive data from TrueContext.

    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. In the TrueContext Form Builder, set up questions with unique IDs that match the Parameter Names in your ServiceMax Custom Action and the field names in your SFM Transaction.

    Forms & Integrations > List Forms > Create Form or Edit Form

    For this example, set up the following question unique IDs:

    • WorkOrderNumber

    • RecordID

    • OrderStatus

    • InspectionStartTime

    • InspectionEndTime

  3. Configure the Custom callback parametersClosed App‑to‑App custom callback parameters are user-defined parameters that indicate which answers and metadata to pass from the TrueContext app to another app on a user’s device.. These parameters specify the data to send back from the TrueContext Mobile App to the ServiceMax Go app.

    Note:The parameter payload sent from TrueContext must be in JSON format and URL‑encoded. When you use the Form Builder to define custom callback parameters, TrueContext automatically URL-encodes the payload.

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

      Shows the App‑to‑App callback configuration in the TrueContext Form Builder, with the mandatory "data-source" parameter configured in JSON format and the optional "mode" parameter as "bg".

    2. The data-source parameter is used to pass data to the target SFM Transaction.

      For the data-source parameter 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. Expression, create a string that contains

      • the parent object API name, and

      • a series of key:value pairs, one for each field in the SFM Transaction that has data you want to use to update ServiceMax Go.

      {"SVMXC__Service_Order__c": [{"Order_Status__c": "%a[OrderStatus]", "Inspection_Start_Time": "%a[InspectionStartTime]", "Inspection_End_Time": "%a[InspectionEndTime"}]}

      Info: The topic DREL Quick Reference provides an overview of how you can use DREL to pull submitted data from TrueContext.

      Value Description
      SVMXC__Service_Order__c API name of the Work Order object
      Order_Status__c API name of a field specified in the SFM Transaction
      %a[OrderStatus] Unique IDClosed A Unique ID refers to the specific identifier of a question, form page, form section, or Data Destination. Unique IDs are used as reference points when pulling data for conditional logic, Analytics projects, Data Destinations, and Documents. of the “Order Status” question in your form
      Inspection_Start_Time__c API name of another field specified in the SFM Transaction
      %a[InspectionStartTime] Unique ID of the “Inspection Start Time” question in your form
      Inspection_End_Time__c API name of another field specified in the SFM Transaction
      %a[InspectionEndTime] Unique ID of the “Inspection End Time” question in your form

      Note:You must define the data-source parameter to send data back from the TrueContext Mobile App to the ServiceMax Go app.

    3. You can configure other, optional parameters, such as mode, for example.

    4. Save and Deploy the form.

  4. 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 ServiceMax Go and TrueContext Mobile Apps.

    Result: The x-success callback executes when a user opens the TrueContext Mobile App from a ServiceMax Go Custom Action and saves, transfers, or submits a form. The x-success callback defined in this example

    • re-launches the ServiceMax Go app

    • redirects the user to the original record in the ServiceMax Go app, and

    • updates the ServiceMax Go values specified in the data-source parameter.