Deep Linking
NOTE: This documentation is aspirational. Not everything outlined here is available yet.
The following examples document the current integrations available as deep links integration points in the Vision mobile app.
Generally speaking, each deep link integration consists of a URL and accompanying query variables,
like any other URL. Every deep link, unless specified, requires a payload
query parameter which
is simply a URL-encoded JSON string of a plain JavaScript object. Some integrations may also accept
a returnTo
parameter used to supply the Vision mobile app with a destination after a completing
action has occurred.
View a job
xoi-vision://activity/view?payload=<URL-encoded JSON>&returnTo=<URL-encoded link>
Parameters
URL Parameters | Description |
---|---|
payload |
URL-encoded JSON string of JS object |
returnTo (optional) |
A URL-encoded deep link for returning to the FSM app |
Details of payload
JS object
Key | Type | Description |
---|---|---|
jobId Optional if no integrationEntityId |
String | Job identifier |
integrationEntityId Optional if no jobId |
Object | Alternative job identifier consisting of two keys: |
- id
(String) - The actual ID of an entity in your system that maps to a Job in XOi Cloud
- namespace
(String) - Minimum of 10 characters. Should be unique to your integration, and consistent for every job you create.
These two keys will be combined to create a unique identifier. |
Example:
xoi-vision://activity/view?payload=%7B%22jobId%22:%20%22job-1234%22%7D&returnTo=yourApp://path
Decoded JSON string:
{ "jobId": "job-1234" }
Caveats
- If the user is offline and the job is not cached on their device, they will encounter an error
- Return deep link to FSM will be a future enhancement
Create / edit a job
xoi-vision://my-work/edit?payload=<URL-encoded JSON>
Parameters
URL Parameters | Description |
---|---|
payload |
URL-encoded JSON string of JS object |
Details of payload
JS object
Key | Type | Description |
---|---|---|
jobId Optional if no integrationEntityId |
String | Job identifier |
jobLocation |
String | Job location string from FSM |
integrationEntityId Optional if no jobId |
Object | Alternative job identifier consisting of two keys: - id (String)- namespace (String - minimum of 10 characters)These two keys will be combined to create a unique identifier. |
workOrderNumber |
String | Work order string from FSM |
owner |
String | Technician email |
customerName |
String | Customer name string from FSM |
supportsMultipleWorkflows (optional) |
Bool | Specifies whether this job supports multiple workflows |
Example:
xoi-vision://my-work/edit?payload=%7B%integrationEntityId%22:%20%7B%22namespace%22:%22XOi-integration%22,%22id%22:%22FA27-RT457%22%7D,%22owner%22:%22info@xoi.io%22,%22jobLocation%22:%22BNA%22,%22customerName%22:%20%22Customer%22,%22workOrderNumber%22:%22WO-1234%22%7D
Decoded JSON string:
{
"integrationEntityId": { "namespace": "XOi-integration", "id": "FA27-RT457" },
"owner": "info@xoi.io",
"jobLocation": "BNA",
"customerName": "Customer",
"workOrderNumber": "WO-1234"
}
Caveats
- If the job’s owner and current user do not match the technician will encounter an error
- If the namespace is fewer than 10 character, the technician will encounter an error
Searching for jobs in Activity tab
xoi-vision://activity/search?payload=<URL-encoded JSON>
Parameters
URL Parameters | Description |
---|---|
payload |
URL-encoded JSON string of JS object |
Details of payload
JS object
Key | Type | Description |
---|---|---|
exactMatchAllTags |
Array of strings | Keywords |
Example:
xoi-vision://activity/search?payload=%7B%22exactMatchAllTags%22:%5B%22Dallas%22,%228675309%22%5D%7D
Decoded JSON string:
{ "exactMatchAllTags": ["Dallas", "8675309"] }
Navigate to Team tab
xoi-vision://team
Caveats
- If the user does not have access to Virtual Service Center an alert is displayed
Navigate to Knowledge tab and initiate a search
xoi-vision://knowledge?searchKnowledgebaseContent=<URL-encoded JSON>
Parameters
URL Parameters | Description |
---|---|
searchKnowledgebaseContent |
URL-encoded JSON string of JS object |
Details of payload
JS object
Keys | Type | Description |
---|---|---|
search |
String | Keywords |
exactMatchFilters optional |
Object | Consists of one key: - makes (Array of strings) |
Example:
xoi-vision://knowledge?searchKnowledgebaseContent=%7B%22search%22:%2230rap%22,%22exactMatchFilters%22:%7B%22makes%22:%5B%22Carrier%22%5D%7D%7D
Decoded JSON string:
{ "search": "30rap", "exactMatchFilters": { "makes": ["Carrier"] } }