Tray Embedded / Building Integrations / Solution Instances

Solution Instances

Read first

Make sure you have read the following sections before proceeding:



A Solution Instance is an instance of a Solution which an End User has activated for their own use - having used the Configuration Wizard to authenticate with the services included in the Solution and entered any personalized Config Data.

The above screenshot shows a simple mockup of how you might display an End User's Solution Instances (exactly how you do this is up to you).

It is important to know that, after a user has completed the Config Wizard, the Solution Instance is not yet enabled (this is to allow you to make any checks or changes before an Instance is activated). So it will need to be enabled

A Solution Instance is also subject to updates in that, when you want to add new application features, fix bugs etc. you will have to edit the Source Workflow(s) in the underlying Solution and publish a new version of that Solution.

These updates will then need rolled out to your End Users' Solution Instances. As in the above mock application screenshot, this may be enabled with an 'Update' or 'Edit' button on your End Users' list of Instances which re-triggers the Configuration Wizard. It is also possible to run these updates 'invisibly' to the End User. Instructions on both approaches can be found in Updating Solution Instances.

It is important to note that each End User will have their own Workflow Instance for each workflow that is contained within the Solution, whereby the data which passes through that workflow instance will be specific to that End User (i.e. it will show how many times their activated Instance has been triggered, what data has been affected in their Salesforce, Dropbox etc.)

Key data

Some of the key data available for a Solution Instance is:

  • id is the unique id of that Solution Instance, which is returned when an instance is first created. It is needed for the Config Wizard url and when enabling, updating and deleting Instances

  • authValues is a list of the authentications the End User has made for each service in this Instance, including an authId for each one

  • configValues is a list of the Config Data that has been set by the End User, to personalize the Instance for their own use

  • enabled is a True / False value which indicates if the Instance has been enabled or disabled

  • owner is the unique id of the End User the Instance belongs to

  • solutionVersionFlags indicates if a new version of the original Solution is available which will require updating

Viewing Solution Instances and Workflow Instances in

An End User's Solution Instances can be viewed at any time by going to the Users section of the dashboard:


Clicking on the Debug link for any workflow will take to you to a read-only version of that user's Workflow Instance:


Any data you see in the logs/debug panel will then be the data associated with that particular End User.

Please see our docs on and for more information on how to handle problems which may arise with workflows.

APIs connected to Solution Instances

  • The createSolutionInstance mutation is primarily for when an End User clicks to configure a Solution - it will return an Instance id which is required when composing the Config Wizard url${embeddedId}/configure/${solutionInstanceId}?code=${authorizationCode}

  • The GraphQL solutionInstances query can be used to list Solution Instances

  • The updateSolutionInstance mutation is primarily for enabling a Solution Instance once the End User has finished with the Config Wizard. It can also be used for updating the values of existing auth settings and config data

  • The upgradeSolutionInstance mutation is used when a Solution contains new auth settings and / or config data and you don't want the End User to have to run the Config Wizard again

Connected topics

The next page in this section discusses enabling Solution Instances: