Purpose of this Document
This document is a ‘How To’ guide for integrating XOi Vision with your Field Service Management (FSM) software. This integration is designed to fill a specific content need to the end customers of the MEP companies that your software is serving. XOi allows technicians from these companies to participate in ‘activities’ that organize and deliver content to their end customers.
We call this integration the ‘Foundational Integration’ because of its simplicity. You will POST to the provided XOi endpoint that will direct users to perform an XOi activity. After users are done in XOi you will ask them to confirm they completed their work and populate a URL that links to the customer-ready content.
There are several primary advantages this integration provides:
- End Customers with a shareable link that will show them photos, videos and comments about the work that took place.
- MEP Technicians using this integration will be able to link their work in XOi activities to your FSM to better connect with customers, improve visibility of their work and create value for their companies.
- MEP Companies will be able to integrate with XOi Vision which allows them to expand and grow their business and use of your FSM platform.
Endpoints and Parameters
You will POST to one important endpoint called the ‘share’ endpoint to start the user activity. There are two fields that are required to be included in your POST:
Partner Id - A unique Id provided to you by XOi to identify your integration.
Share Id - You will generate a separate unique Id for each activity. The generated Share Id should be immutable for subsequent requests for the same activity in cases where the activity must be accessed multiple times.
We do not recommend using sequential numbers for Share Ids because they become part of a URL that serves public content.
Creating your POST:
Base URL: https://vision.xoeye.io
POST to: /partners/$partnerId/share
shareId - The unique Id you generated
serviceTicket - The work order or service ticket number for work performed in the FSM
customer - The name of the end customer
location - The address where the work is taking place
tags - A repeatable parameter allowing you to assign one or more strings that will be added as tags to the new activity. Each new tag will be assigned as a separate parameter.
Linking to XOi Vision and Passing Parameters
Begin the integration by creating a button that will post to XOi at the endpoint ‘share’ passing in the given parameters. Note: Make sure that your POST is using url encoding
Example of a POST Using a HTML form:
<form name=”yourForm” method=”post” action=”https://vision.xoeye.io/partners/$partnerId/share”>
<input type=”hidden” name=”shareId” value=”123456789”>
<input type=”hidden” name=”serviceTicket” value=”12341312”>
<input type=”hidden” name=”location” value=”Address”>
<input type=”hidden” name=”customer” value=”Customer Name”>
<input type=”hidden” name=”tags” value=”tagValue1”>
<input type=”hidden” name=”tags” value=”tagValue2”>
When the XOi button is tapped it should open XOi Vision and pass the parameters that you have set into the activity:
Optional: Confirming the Activity is Complete
After the technician has finished organizing their activity content in XOi Vision and navigates back to your FSM, they should see an option like ‘Have you completed the workflow?’ with a Yes/No input. If the users selects ‘Yes’, then you should populate the share link.
If you always store the share link in your FSM without confirming with the user and they have not completed their activity, the URL you generate will point to incomplete content.
Generating the share URL:
$shareId = The share id that you generated for this activity in your original POST
Optionally, a simple Yes/No selection will determine whether the link is populated:
Providing the Share Link
The link attached in your FSM can now be shared with end customers who are receiving the service.
Placing the share link as a hyperlink on the receipt/invoice that is delivered to the end customer creates the most value for your MEP customer
By doing so you:
- Drive engagement with the end customer as they see accurate images and videos describing the work performed.
- Document the service ticket content for internal/historical uses.
The share link opens Customer Content as shown here:
- Obtain your PartnerId from XOi
- Generate unique ShareId
- Create a POST containing the required parameters (shareID, serviceTicket, location, customer)
- Optional: Add any additional ‘tag’ parameters to the POST
- Optional: Create confirmation to populate the URL for the activity
- Populate the generated URL in the location that best serves your customers