Integrate with ServiceMax

Available on the Advanced and Enterprise tiers:

Essentials
Advanced
Enterprise

Estimated Effort ~ 1-2 hours

Learning Objectives

After completing this unit, you will be able to:

  • Configure a connection between TrueContext and ServiceMax

  • Configure a User Defined Custom Action in ServiceMax

  • Launch the TrueContext Mobile App from the ServiceMax App, complete a form, updating the Work Order details in ServiceMax

Prerequisites 

In order to configure an integration between TrueContext and ServiceMax, you will require:

  • An active ServiceMax subscription

  • The ServiceMax Go or ServiceMax FSA App installed on mobile devices

  • An active TrueContext account

  • The TrueContext Mobile App installed on mobile devices

  • A target form in TrueContext that will receive data from ServiceMax

  • A Work Order dispatched to your user in ServiceMax

Getting Started with ServiceMax

ServiceMax is the global market-leader in Service Execution Management, providing a cloud-based software platform that improves the productivity of complex, equipment-centric service execution for OEMs, operators, and 3rd-party service providers. ServiceMax FSM optimizes execution of both short cycle operations - emergency work, meter services, compliance jobs, maintenance and inspection-and long cycle operations, such as outage management, that encompass multiple days, tasks, and people.

Step-by-Step

Your Use Case - Launch a form in the TrueContext Mobile App that’s populated with data from ServiceMax

Here is a common use case: A technician who has been assigned a work order in ServiceMax must complete an extensive checklist in the TrueContext Mobile App.

In TrueContext

  1. Create a Salesforce Connection between TrueContext and your ServiceMax org by navigating to Forms & Integrations > ConnectionsClosed A Connection is an integration point that's used to link a TrueContext Data Source or Data Destination to an external service to import or export data. Data Destinations and Data Sources that share the same external service can also share the same Connection. > Create Connection.

  2. Name the Connection, and select the 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. where the form to be dispatched to can be found.

  3. Establish your connection by clicking Connect, and entering your ServiceMax Admin user credentials.

  4. Navigate to the form which you would like to DispatchClosed The term "dispatch" refers to the act of sending a form to a mobile user or customer. Typically, a dispatched record includes some information pre-filled to give the recipient context for the work to be done. Dispatch can be manual or automated (using a Dispatch Data Destination or the TrueContext REST API). from the ServiceMax App. (Form > Pages & Questions Tab > Label column). You will need to reference the Question Unique IDs when setting up your User Defined Custom Action in ServiceMax.

In ServiceMax

  1. Navigate to ServiceMax Setup in the ServiceMax Admin menu.

  2. Navigate to Service Flow Manager > SFM Custom Actions.

  3. Manage Customer Actions For > Select Work Order from the dropdown menu.

  4. In User-defined Custom Actions click the New button.

  5. Select your Action Type:
    To integrate with the ServiceMax Go or FSA applications, proceed to a. App-to-App. If you are running ServiceMax in a browser on Windows and calling the TrueContext Mobile App Windows application, proceed to b. URL.

    1. App-to-App.

      • Action Title: <Name your action>

      • Action ID: <Give your action an ID>

      • Scheme Name: truecontext

        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

        mceclip0.png

      • Path: x-callback-url/open

    2. URL.

      • Action Title: <Name your action>

      • Action ID: <Give your action an ID>

      • Open URL in: Existing Window

      • URL to Launch: truecontext://x-callback-url/open

        mceclip2.png

  6. Define your Parameters Next, define the list of parameters to be sent from the ServiceMax app to the TrueContext Mobile App. The name parameter is required, and should be used to identify the correct form to be opened in the TrueContext Mobile App. In the example below, the form to be opened is called Inspection Checklist. All other parameters are mapped based on what data you wish to dispatch into the form, from the relevant Work Order in ServiceMax. The Parameter Name on the left hand side is the question 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..

    mceclip4.png

    In this example, the Record ID (question Unique ID: RecordID, ServiceMax work order parameter value: Record ID) will be mapped to the question Work Order ID.

    Screen_Shot_2019-11-06_at_3.32.37_PM.png

    To send strings of text, select Value as the Parameter Value Type. To send the value which is stored within a field in the given Work Order in ServiceMax, select Field Name as the Parameter Value Type, and then select the ServiceMax field you wish to map.

    Exclusively for use in App‑to‑App configurations, configure x-success, x-cancel, and x-error parameters with parameter value svmx://x-callback-url to bring the originating ServiceMax application back to the foreground upon a success, error or cancel event in the TrueContext Mobile App.

    Note: These callback parameters are not compatible with a URL configuration. To return to ServiceMax, users must manually return to their browser.

  7. When you have completed the mapping of your parameters, ensure that you Save & Close the page.

In ServiceMax - Add a new SFM Wizard Step

  1. Navigate to ServiceMax Setup in the ServiceMax Admin menu.

  2. Navigate to Service Flow Manager > SFM Wizards.

  3. Select Object > Work Order.

  4. Under the Custom SFM Wizards, select the Wizard which applies to your users, and click Edit.

  5. Navigate to the Manage Wizard Steps tab, and click on the New Step button.

    • Wizard Step Type select Others.

    • Step Name select your action, as named in the Action Title above.

    • Title, enter the name of the step as you would like it to show up for your users in the ServiceMax app.

  6. When you have completed the set-up of your FSM Wizard Step, ensure that you Save & Close the page.

In ServiceMax Go

  1. Ensure that your configuration has synced to your device. Open the ServiceMax Go app, press More, in the bottom right hand corner. Sync > Run Configuration Sync.

  2. Navigate to a Work Order assigned to the user you are logged in as. Open the Work Order, press the Work Order number to see the Work Order overview.

  3. Open the burger menu in the bottom right hand corner. Your new User Defined Custom Action will appear in the Actions menu with the step name as defined by you in step 6 above.

  4. Selecting the action will open the TrueContext Mobile App, taking you directly into the app, and dispatching the work order details, as per your configuration.

Troubleshooting Tips

A common approach to troubleshooting involves creating a new SFM custom action with only the truecontext://x-callback-url/open parameter configured. If the app launches successfully, then you can continue building from there. For more information on App‑to‑App communication, see the topic App‑to‑App Communication.