Call Integration with Third-Party Systems

Owned by Mike Piska
Mar 09, 2024
7 min read

This document describes the typical integration of WorkLink calls 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 calls made within the WorkLink AR are known are recorded by other systems of record. This could be an MES, CMMS, LMS, or other systems. In this particular document, we will assume that the the third-party system is launching a call as part of a service request, which is the most common use case for this type of integration.

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 service request is created, a deep link is generated in the third-party system that will initiate a call to accomplish the service request. After the call is complete, the WorkLink system will automatically report that call to the third-party system to be stored as part of that service request.

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 deep link to WorkLink and an API for WorkLink to report results. Let's discuss each of these in greater detail.

Ability to create a link to launch WorkLink.

The third-party system must have the ability to assemble a custom deep link to WorkLink for each service request. This is simply an assembled URL that adds together the base link to WorkLink, the contact or contact group that the call is being initiated to, 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 service request. This is often just the service request 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 service request 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 than the service request is opened on. For example, opening the request on a workstation and then scanning the QR code to initiate the WorkLink call on their mobile phone, tablet, or AR headset.

API to report service request results

The third-party system must also have an API that WorkLink can access and that allows WorkLink to report the results of the service request 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 service request that the customer wishes to retrieve from WorkLink and store in the third-party system.

Some customers will create custom fields on the service request 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 service request ID is the primary data field 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 initiates a call or opens contact list identified by the deep link’s query parameters.

  1. If the user needs to select a contact from the contact list, then the call is initiated once a contact is selected. All data about the call 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 CallSession data identified by the Webhook payload resource_id.

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

  5. The WorkLink integration then stores the retrieved Call Session data against the associate service request 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:

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 contact or contact list identified by the deep link’s asset query param.

  3. The user selects a contact and begins a call 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 CallSession 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 Call Session data against the associate service request 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 CallSessions. 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 service request? 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 service request through an API?

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

  4. Does your third-party system have fields for all the collected WorkLink data in the service request 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