Tray Embedded Overview
Welcome to the Tray Embedded documentation!
Here you will learn how to add Tray's app and data integration to your own commercial products whilst maintaining your own branding.
If you wish to open a Tray Embedded Partner Account, please contact us and we will set one up for you.
What is Tray Embedded?
The main Tray Platform is primarily used to enable you to automate your internal processes, to help reduce the administrative burden on your organisation and accelerate the execution of mission-critical tasks such as lead enrichment, subscriptions/contract management, syncing sales and marketing data between CRMs and apps, etc.
Tray Embedded, on the other hand, is aimed at putting the power of Tray.io in the hands of the End Users of your platform, whether they are external customers or internal admin staff. A typical use case for this would be if your platform features a range of integrations (or Solutions as we call them) involving your own product and a number of third party services (Zendesk, Slack, Salesforce, Marketo, etc.) and you wish to use Tray Embedded to enable your End Users to:
- Very quickly authenticate themselves with each service involved
- Enter Config Data which makes any further necessary personal configurations so that the integration works specifically for them (e.g. what Slack channel do they subscribe to, or what Salesforce contact type do they work with)
This can all be done in a properly 'white-labelled' sense - i.e. the fact that you are using Tray Embedded to automate these integrations is invisible to your End Users.
How to use this documentation
After reading through the rest of this overview, the key sections in this documentation are:
The Integration Walkthrough takes you through the end-to-end process of creating a very simple demo solution and all of the API calls involved. This is your 'quick start' which will give you a good overview of how an integration is built
Building Integrations is the key section to familiarize yourself with all of the components involved in putting integrations together, including how to roll out updates
Core Topics contains all of the detailed information and 'extra stuff' you can do with things like managing authentications, importing external data, managing your application CSS etc.
Building Tray Embedded integrations
Building Tray Embedded integrations is a matter of:
In the Tray Embedded UI, create the workflows, projects and solutions which form the basis of your integrations:
Workflows contain the intelligence which drives your integration - including the required Tray.io and service connectors, authentications and Config Data.
A Project can contain multiple workflows, and pulls together the Config Data shared across the workflows.
A Solution then makes a Project configurable for an End User (via the Config Wizard) by pulling all of the Config Data and Authentications contained in your project and making them available as Config Slots and Authentication Slots. These are populated with Config and Authentication values when the End User runs the Config Wizard, to create their own Solution Instances.
Build your app and make use of the Tray Embedded API to manage:
- Front End tasks such as displaying available solutions and allowing users to click to activate the Config Wizard
- Back End tasks such as creating Users and Solution Instances
The graphic below gives a quick snapshot of a Tray Embedded application. It shows a setup whereby you have several Solutions available for your End Users and an End User has clicked to activate a Solution which automatically creates Asana tasks for them when Salesforce accounts of a certain type are created.
Note: The Platform Interface depicted in the centre of the graphic is a mock-up of how you might present your Tray Embedded Solutions within your own application. This is not a Tray.io component and the styling and presentation of this is up to you:
In the diagram there are 4 'layers':
- Your application code behind the UI (in the dark box) which is built using our GraphQL APIs and can use our demo app as a guide. The example shows sample code which would trigger the
createSolutionInstanceAPI when a user clicks to configure a Solution for their own use.
- Your Application Interface (not a Tray.io component). This represents the main window of your interface where you present the Solutions available for your End Users to configure for their own use (rememember that this is a simple mock-up and how this is configured is entirely up to you! The key point is that you use our APIs to help you display available Solutions and control what happens when an End User clicks to activate them).
- The Tray Customizable Configuration Wizard (this is a Tray.io component!) which is activated when an End User clicks to configure a Solution. This is represented in two parts:
- The Tray Config Wizard URL (in the yellow box) which accepts the ID of the Solution Instance being created and the one-time authorization code for the End User
- The individual screens (4 in this example) of the Configuration Wizard (these can be customized in our Solution Editor) which allow the End User to create their own authentications for the services involved (Salesforce and Asana in this example) and enter their own Config Data which means the Solution Instance will work for them as an individual.
- At the very bottom of the graphic you can also see the Config Data values of
$.config.asana-projectwhich link back to the source workflow which specified that these fields would be available in the Config Wizard.
As well as the fact that End Users need to set their own authentications, the most important point to grasp in the above example is that the End User has used Config Data to set the Salesforce Account Type and Asana Project so that the syncing of tasks only happens when new accounts of a certain type are created ('Prospect') and only syncs to the Asana Project they have specified ('My Prospects').
How Config Data is set
The following set of visual tabs illustrates how Config Data is managed in 3 steps:
1 - Set Config Data
First of all, you specify that certain fields are Config Data by entering
$.config. jsonpaths in the source workflow. In this example we are using
$.config.asana-project for the Projects field in the Asana Create Task operation:
2 - Add prompts in Solution Editor
When you have created a Solution based on your source workflows you can then use the Solution Editor (found in the Tray Embedded UI) to add prompts for the End User to create their authentications and set their Config Data:
3 - End User activates Config Wizard
The end result is that the End User can then, in the Config Wizard (a Tray.io component) create their own authentications and set their Config Data: