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) 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 parameters 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:

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

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

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.

   

   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.

   

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)

   

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

   • x‑callback‑url action to open the form

   • the Work Order Number and Record ID values to send to the TrueContext Mobile App

   • other values to send, such as the name of the form to be opened or prepopulated answers from the Work Order record itself, and

   • x‑callback parameters 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. to send the data back from the TrueContext Mobile App to ServiceMax Go when the form is submitted, transferred, or saved. The x-success parameter in this example references the custom formula field that you created in step 4.

     Info: The topic App‑to‑App x-callback parameters describes how the x-callback parameters work and the default metadata that the x-success callback parameter sends back.

   

   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 Portal 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 list 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 Settings 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 parameters 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.

      

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

      For the data-source parameter 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. 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 ID 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 Reconcile 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.