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 email@example.com 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 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.
The graphic below gives an overview of how a Tray Embedded application is configured. 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':
- The Tray Embedded code behind the UI (in the dark box) which is built using our GraphQL APIs and can use our demo app and demo app structure 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:
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:
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:
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 (to keep it short we only show the Asana stage of the process here. The full Solution would include Salesforce authentications and choosing the Salesforce account type):
Developing Tray Embedded applications
Developing Tray Embedded applications is a matter of:
- In the Tray Embedded UI, create the workflows, projects and solutions which form the basis of your integrations:
- 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 their own instances
- Back End tasks such as creating Solution Instances and User Authentications
How to use this documentation
Chronologically! The best approach is to follow the left-hand menu in order:
Familiarizing yourself with our glossary is definitely recommended.
In User Interface guide you will find an explanation of how projects and solutions are used to manage your integrations.
Demo Solution takes you through the process of setting up a simple example workflow, adding it to a project, building a solution and making the relevant user config options available. Once you have a simple solution setup and ready to use, you can run our Demo app. To orientate yourself, it is important to run this successfully so that you know what the end result should look like! The demo uses a simple local server with a front end which can be used to register users, list available solutions and trigger the solution Configuration Wizard pop-up for the End User. When you run the demo app you will be asked to enter your Partner Name and Master Token and so the demo will be connected to your account in the Tray backend and thus have access to the solutions and solution releases configured for your company.
Intro to the APIs then gives a more detailed intro to the GraphQL API scheme we use, including a structural breakdown of an API, making basic calls and managing cursor-based pagination.
In Processes to be managed a detailed explanation is given of managing the basic process and also how to execute particular tasks such as importing external user data.