Open Navigation

Tray Embedded Overview

On This Page

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 at sales@tray.io and we will set one up for you.

Once an embedded partner account is enabled, from your app.tray.io dashboard you can:

  1. Create Workflows which act as the basis for your integrations
  2. Create Projects to group together related Workflows
  3. Use your Projects to create Solutions which End Users can then activate and configure as Solution Instances for their own use
  4. Generate a Master Token which grants the necessary API access for your applications

The following diagram illustrates this process:

embedded-diagram

The ultimate aim here is to enable an End User to configure a Solution Instance with everything (user logins, automated updating of Salesforce, Slack, etc.) specifically set for them.

When creating Projects you can create common config data which can be shared across the workflows within the project.

When creating Solutions you can configure how the configuration options appear for the End User in your external application UI. Solutions are also subject to revisions and Solution Releases if underlying project workflows change and you need to update the Solution.

Note: Tray Embedded is a distinct product offering. Therefore when you have a Tray partner account activated, it is strongly advised that you do not try to add previously-created workflows to your projects. You should create new workflows to add to your projects.

Main Process Overview

To integrate Tray into your own commercial products, you can make use of our demo app as a guideline for using our APIs to configure a user interface which presents users with available Solutions for them to select and configure as a Solution Instance for their own use:

  1. Register an end user - the createExternalUser API returns a Tray userId and the authorize API returns an access token which is valid for 2 days (for simple tasks such as listing available solutions).
  2. List the solutions available for an end user - List Solutions returns an ID for the available solutions. These would typically be displayed in a UI which allows the user to select which solution they wish to activate.
  3. Create a Solution Instance for the End User using the solutionId of the solution chosen by the user to obtain a solutionInstanceId
  4. Generate a user authorization code - the Authorization Code mutation (passing in the Tray userId) generates a one-time use authorizationCode which is needed to activate the pop-up Configuration Wizard for an End User (note that this is different to the access token generated in step 1!)
  5. Present the Tray Configuration Wizard in your application - in order to allow an end user to configure a solution instance from a solution they have access to, you must direct them to a link in the following format:
    https://app.tray.io/external/solutions/${partnerId}/configure/${solutionInstanceId}?code=${authorizationCode}
    In the pop-up Config Wizard the End User can enter their configuration details and generate a user authentication for the required services. We recommend opening this in an iframe or popup from your application.
    Note on Browser Compatibility: The Tray Config Wizard supports the major desktop and mobile browsers Chrome, Firefox, Safari (9.1+ desktop and 9.3+ iOS), Opera, Android (and Android UC) and Edge (version 14 and above). It does not support Internet Explorer.
  6. Enable the Solution Instance - once a Solution Instance has been created, the final step is to use the updateSolutionInstance mutation to set the status to 'enabled'.

The points introduced here are then expanded upon in Processes to be managed

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 workflows and solutions configured for your company.

Demo App Structure gives an overview of how the demo app sets up the APIs and endpoints and what files it uses to achieve the sequence of tasks.

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.

Full API reference then introduces you to our API playground, before listing all the available APIs with an example usage. Each example will show both a query that can be used in the API playground, and a Javascript example taken from our demo app.

Was this article helpful?
Yes
No
On This Page