Tray Embedded / Building Integrations / Solution building basics
Solution building basics
Make sure you have read the following sections before proceeding:
Naming Conventions Guide
Before you proceed with creating a workflow or project, check out the following video on Best practices for naming conventions.
This is what we recommend but you are free to follow your organisation's naming standards.
The first building block of an Embedded solution is a Workflow
Workflows are what you use to build the logic which drives your Embedded Solution, using the required third-party services (Salesforce, Slack, Google Sheets, Hubspot, etc.) in conjunction with the Tray.io core and helpers connectors which can carry out the necessary data manipulation and processing tasks for you.
You may need to create several workflows to act as the basis for your Solution, as your Solution may be made up of several different components involving different services. It may also be necessary to use Callable Workflows so that gathered data can be sent for sub-processing, which will prevent your main workflow from becoming overly complex, and will vastly improve efficiency.
Please be sure to drop into the Tray Academy to learn the basics of building workflows in Tray.io.
The main page of your dashboard lists your workflows and clearly indicates whether they are already part of a project:
At any point you can click 'Create new workflow' to begin creating the workflow(s) required for your Solution.
Authentications and Config Data
Two key parts of a workflow are:
The authentications for any services that are used in the workflow. The above screenshot shows the 'Mike H Dropbox 1' authentication which is used for all Dropbox steps in the workflow.
Note that the authentications you use when building and testing your workflow are not the authentications which will be used by the End Users of your Solution.
When an End User activates a Solution Instance for their own use, they will use the Config Wizard to create their own authentications, so the Instance is personalized for them.
Config Data is also used to allow an End User to make any further necessary personal configurations when activating their Instance:
In this case
$.config.department has been used to allow the End User to specify their department in the Config Wizard, so that their Dropbox files will be added to their department folder.
Setting Auth Scopes for End Users
When you are creating a workflow which will act as the basis for Solution Instances activated by your End Users, if the service uses OAuth2, then the scopes that you select for your test auth will be the scopes available to your End Users.
A Project can contain multiple workflows, and pulls together the Config Data shared across the workflows.
In your dashboard Projects are created in order to group together the workflows which will ultimately make up your Solution (i.e. workflows that make up different components of your Solution, or callable workflows which communicate with each other to efficiently process data)
A key thing to note about Projects is that Config Data can be shared across workflows, so you can use shared values for email addresses, shared folders in external services, external database tables, and any other pieces of important data.
You cannot add a workflow to more than one Project
Creating a Project
From the screenshot below you can see that two projects have been created, each with one source workflow:
When creating a project you can name it, give it a description and add tags which will help you to filter projects in your dashboard:
Adding workflows to a Project
You will then be asked what workflows you wish to add to it (remember that you cannot add the same workflow to more than one project):
Checking / Editing Project Config
And you can see and edit the Config Data which is available for use in the workflows in that project:
Here you will see the Config Data which you have already set in the workflows being imported. You can add more Config Data at this stage if need be.
Once you are ready to present your integration to your End Users, you can turn your Project into a Solution.
A Solution 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 values and Authentication values when the End User runs the Config Wizard, to create their own Solution Instances.
Turn a Project into a Solution
From any Project, you can make a Solution:
At this point all of the Config Data and Authentications contained in your project workflows are pulled into the Solution as Config Slots and Authentication Slots.
You can choose exactly how you present these to your End Users in the Config Wizard, in order for them to set their own config and authentications.
The Solution Editor
Tags and Custom Fields
In the General Settings screen of the Solution Editor you can add Tags to the Solution which can then be used to filter and categorize Solutions in your external application when using the List Solutions API.
One of the main uses of Custom Fields is to add an 'icon-url' which would become the icon of this solution in your external application, as shown in Managing CSS:
Arranging the Config Wizard
When making a solution you can use a drag-n-drop interface to specify exactly what the End User will see when they activate the pop-up Configuration Wizard, and enter prompts as to why they are being asked to enter values for their Config Data:
The Configuration Wizard is where the End User is prompted to enter the necessary details to activate their own instance of the solution (i.e. authenticate their accounts and set their own values for any Config Data). It can be previewed from within the Solution Editor:
Hiding the Authentication button
If you wish to reduce the number of clicks an End User has to make it is possible to hide the 'New Authentication' button in the Config Wizard so that they go straight to the service authentication dialog.
This is done in the UI. When you are setting up the Configuration Wizard screens, it is possible to use the 'Skip CTA' option for any authentications:
Displaying webhook urls
If the End User needs to see the webhook URL for a workflow in their Solution Instance so they can configure it with an external service, it is possible to make this visible in the Solution Editor as the Public Url Label:
The 'Workflow Id' will ultimately be translated into the webhook URL in the End User's Configuration Wizard.
Note that this will be for the End User-specific copy of the Workflow which exists within their Solution Instance.
Note that this can also be retrieved during and after Solution Instance creation, using our API, as detailed here
Saving and Publishing a Solution
When you have finished making the solution, click 'Save and Publish' will make it live and ready for use.
The next page in this section will introduce you to the basics of creating and managing End Users of your application: