Scenario Integration with Third-Party Systems

Owned by Mike Piska
Last updated: Mar 05, 2024
7 min read

This document describes the typical integration of WorkLink scenarios with a third-party system, the different approaches to accomplish that, and the work involved in setting this up.

In This Article

Glossary

There are several key terms relevant to the content described in this document.

Key Term

Description

Key Term

Description

GraphQL API

Method of retrieving a customer’s data via a single API endpoint.

Scenarios

Sets of work instructions pertaining to a specific physical device, to be completed by a user while using the Scope AR WorkLink app.

Scenario Sessions

A record of a scenario's run while using the Scope AR WorkLink app and the events performed during that run .

Scenario Catalogs

A set of related scenarios that can be presented to user as a collection to select one of them for execution.

Deep Links

Method of launching a scenario or catalog with the Scope AR WorkLink app via a structure URL.

Webhooks

Method of notifying integration code about key events that take place in the Scope AR platform for the purpose of triggering an integration script or middleware application.

Introduction

The WorkLink platform allows customers to integrate a wide variety of third-party systems to ensure that the operations completed within the WorkLink AR are known are recorded by other systems of record. This could be an MES, CMMS, LMS, or other systems.

There are two main approaches to this integration and which solution you choose will depend on the amount of business logic that needs to occur on that data before storing it in your third-party system. The following sections explain these two approaches.

Workflow Overview

At a high level, the interaction between WorkLink and your third-party system is very simple. The basic flow is that when a job order is created a deep link is generated in the third-party system that will launch the appropriate scenario content to accomplish the job order. After the scenario is complete, the WorkLink system will automatically report the results of that scenario run to the third-party system to be stored as part of that job order. The diagram below illustrates this.

image-20240228-174419.png

Required Third-Party System Capabilities

For a system to integrate with the WorkLink system, it needs to have some basic integration functionality. This functionality includes the ability to create a link to WorkLink and an API for WorkLink to report results. Let's discuss each of these in greater detail.

The third-party system must have the ability to assemble a custom deep link to WorkLink for each job order. This is simply an assembled URL that adds together the base link to WorkLink, the scenario that completes the work for that type of job order, and parameters that specify any of the necessary linking data that will be needed to report the results back to the third-party system and connect it to the correct job order. This is often just the job order ID but may include other data such as the equipment ID that the job is to be completed on or the person assigned to the work.

Creating this as a simple URL will work well to launch WorkLink on the same device that the job order is being viewed on, but many systems will also allow the ability to encode that link into a QR code so that WorkLink can be launched on a different device that the job order. For example, opening the order on a workstation and then scanning the QR code to load the WorkLink scenario on their mobile phone, tablet, or AR headset.

API to report job order results

The third-party system must also have an API that WorkLink can access and that allows WorkLink to report the results of the job order execution back to the third-party system. This can be a REST API or a GraphQL API and must allow for updating all the data on the job order that the customer wishes to retrieve from WorkLink and store in the third-party system.

Some customers will create custom fields on the job order that capture data specific to a WorkLink-based implementation of the work. The API must support updating those custom fields in order for the integration to be able to update them.

Integration Options

Given that the third-party system system meets the requirements above, there are two primary ways to accomplish this integration.

Integration using Built-in Integrations

This first way, and certainly the simpler option, is that you can use the built-in integration features of the WorkLink CMS. See below for the basic data flow diagram of how this integration works. In this diagram, it is assumed that the asset ID and the work order ID are the data fields needed to link the resulting execution back into the third-party system system. This may be more or less data than needed for your third-party system integration.

The steps of this flow entail:

  1. The user visits a deep link dynamically generated by the third-party system (see the section on this capability above).

  2. The WorkLink app launches and loads the scenario or catalog identified by the deep link’s asset query param.

Note that when the app launches a scenario, it will launch a new session of the scenario to complete this work. If there is a partially completed session for that job order, it will not resume that session. That partially completed session can be opened and completed from within the WorkLink scenario list.

  1. The user selects a scenario and begins a scenario session (causing all additional query parameters passed by the deep link to be stored in the WorkLink app). All data about the session is sent to the CMS, including the parameters included in the deep link.

  2. The WorkLink integration module receives Webhook event notifications from the CMS that there is new data that the application is interested in.

  3. The WorkLink integration queries the Scope AR GraphQL API to retrieve the ScenarioSession data identified by the Webhook payload resource_id.

  4. The WorkLink integration inspects the data retrieved and gets all the session data that is required to send to the third-party system system.

  5. The WorkLink integration then stores the retrieved Scenario Session data against the associate job order in the third-party system using the third-party system’s available APIs.

In this solution the WorkLink integration module is being triggered by the webhook, retrieving the data, doing some simple transformation of the data into the format expected by the third-party system API, connecting to the third-party system API, and then sending the data. This is done using customizable JavaScript scripts in the integration configuration screens. These scripts can be very simple or relatively complex based on the amount of transformation that the data needs.

Some customers that have programming expertise in-house will have these internal resources write these integration scripts. Others will hire Scope AR to create these integration scripts for them.

Integration using a Middleware App

In some cases, the built-in integration scripting is not sufficient for the level of integration that is needed. This may happen when the data transformation requires a lot of business logic, data retrieval from other systems, or batching and aggregation of the WorkLink data. In these cases, a more complex integration may be required. When that is the situation, then a middleware app can be used instead of the built-in integration.

This means that a standalone, customer-hosted service would replace the built-in integration scripting. This would change the workflow to look as follows:

Workflow with custom middleware app

The steps of this flow entail:

  1. The user visits a deep link dynamically generated by the third-party system (see the section on this capability above).

  2. The WorkLink app launches and loads the scenario or catalog identified by the deep link’s asset query param.

  3. The user selects a scenario and begins a scenario session (causing all additional query parameters passed by the deep link to be stored in the WorkLink app). All data about the session is sent to the CMS, including the parameters included in the deep link.

  4. The customer’s custom application receives Webhook event notifications from the Scope AR platform that there is new data that the application is interested in.

  5. The customer’s custom application queries the Scope AR GraphQL API to retrieve the ScenarioSession data identified by the Webhook payload resource_id

  6. The customer’s custom application inspects the data retrieved and gets all the session data that is required to send to the third-party system system.

  7. The customer’s custom application then stores the retrieved Scenario Session data against the associate job order in the third-party system using the third-party system’s available APIs.

The customer’s custom application receives ALL Webhook notifications, not just create and update events pertaining to ScenarioSessions. The application needs to inspect the Webhook’s payload event and data.resource_type values in order to determine which notifications to act on.

Scope AR Development and Support

If this type of integration is needed, then customers will need to evaluate if assistance from the Scope AR team is needed to accomplish this integration based on the level of expertise of their in-house resources. Scope AR has services available to either complete or assist the development of scripting using the built-in integration capabilities or a custom middleware app. This can be done on either an hourly or project basis.

To provide pricing for this support, there would need to be some discussions and discovery of the capabilities of your third-party system and the requirements of the integration you desire. The general questions that would need to be answered are:

  1. Does your third-party system have the required capabilities to create a deep link for each job order? Please provide documentation on the capabilities of the third-party system to create a deep link

  2. Does your third-party system have the required capabilities to accept updates to a job order through an API?

  3. What data would you like to be collected from the WorkLink platform into your job order?

  4. Does your third-party system have fields for all the collected WorkLink data in the job order record?

  5. How does the third-party system’s API support updating all those fields?

Reference Documentation

For further details on the integration capabilities of WorkLink, please refer to the following links:

https://scopearcloud.atlassian.net/wiki/spaces/API/pages/1671987201/Using+Deeplinks

https://scopearcloud.atlassian.net/wiki/spaces/API/pages/1270448421/Using+WebHooks