Solution instances

What is a Solution Instance?​

Copy

A Solution Instance is an instance of a Solution that 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 configuration, 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. Read more on 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​

Copy

As per the Get Solution Instances API 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 / debugging Solution Instances in the Tray UI

Copy

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 Debugging and Error Handling for more information on how to handle problems which may arise with workflows.

Creating Solution Instances​

Copy

There are two ways of creating and configuring solution instances:

Creating in the Tray dashboard​

Copy

Once you have published a Solution, you will be able to create instances from the dashboard:

This will activate the Config Wizard which will allow you to create the auths and config data necessary for that End User's instance.

Creating in your native application

Copy

You can make use of our Embedded APIs to build your own 'integrations marketplace'

The application can use the createInstance mutation when the user clicks configure button for a Solution.

Our demo Integration Marketplace app can be set up in minutes to get you started.

You can either customize this application to follow your branding schema and embed this in your portal or build your own Marketplace app.

There are three options to choose from when building end-user experience:

• Config wizard experience: This is the standard way of building an experience where users can provide auths and configs.

• Auth-only dialog experience: Ideal when you only want the end user to provide auth and data mappings and configs are static.

• Custom Form experience: Your custom wizard where you can leverage Tray's auth dialog for capturing auths and Call Connector API to build config dropdowns.

You can decide which experience to present to your End Users as per your Integration use case you can also have a combination of these experiences by choosing a suitable type for each Integration/solution that you build. Check the decision table on this page here.

Enabling Solution Instances​

Copy

Enabling in the Tray dashboard​

Copy

Navigate to the project you want to enable instances for. Open the project and click on the Solution Instances tab.

You will find all Solution Instances linked to this project:

You can click on enable as shown above and the instance would be enabled.

Once an instance has been enabled you will find a 'disable' option, if needed.

Enabling in your native application

Copy

You can provide an option to end users to enable the instance using the updateSolutionInstance - Enable (User token) mutation.

Note that it is best practice to set errorOnEnablingWithMissingValues to true when passing the arguments with this mutation:

1
 updateSolutionInstance(input: {
2
   solutionInstanceId: $solutionInstanceId,
3
   instanceName: $instanceName,
4
   errorOnEnablingWithMissingValues: true,
5
   enabled: true
6
 }) 

This will prevent you from enabling misconfigured Instances.

When using config wizard experience, You can also enable the instance for them by immediately calling the above API right after the wizard is completed.

For this, You can listen for the tray.configPopup.finish event to know when was the wizard finished successfully. Check other config wizard events to handle any errors.

If you are using a custom form experience, you will have to use your own workaround.

Retrieving webhook URLs

Copy

For cases when it is necessary to directly send messages to a specific Workflow in an End User's Solution Instance (e.g. when using Amazon SQS), it is possible to retrieve the webhook URL for the Workflow Instances which underlie their Solution Instance.

When talking about a Workflow in an End User's Solution Instance, it is important to understand that there are effectively two Workflows:

1. The original Source Workflow which you built in the UI (in Dashboard > Create New Workflow). It can be found in the url when using the workflow editor https://app.tray.io/workflow/<sourceWorkflowId>/edit/ In the API example results below this is identified by sourceWorkflowId

2. The End User-specific copy of the Workflow (the Workflow Instance) which exists within their Solution Instance (in the UI you can see this by going to Users > Click 'Instances' for End User > Click 'See Workflows' for Instance > Click 'Debug Workflow' for the relevant Workflow) In the API example results below this is identified by id

Before using the GraphQL mutations below you should identify the sourceWorkflowId of the workflow you want to pinpoint for a specific user. This is so that, in your external application, you can filter out the other workflows in the solution which you are not concerned with.

The ultimate aim here is to get the triggerUrl for the relevant End User-specific Workflow Instance.

Retrieving webhook URL when creating a Solution Instance

Copy

When using Create Solution Instance you can expose the webhook urls for a Solution Instance by including workflows as data to be returned:

1
mutation {
2
 createSolutionInstance(input: {
3
   solutionId: "2bexxx-xxxx-xxxx-xxxx-xxxxxxf3491",
4
   instanceName: "some instance name",
5
   authValues: [{ externalId: "external_sqs_authentication", authId: "aaa67786-xxx-xxx-xxx-97dedd1519b3" }],
6
   configValues: [{ externalId: "external_user-email" , value: "\\"me@example.com\\"" }]
7
 }) {
8
  solutionInstance {
9
   id
10
   name
11
   enabled
12
   created
13
   workflows {
14
    edges {
15
     node {
16
      id
17
      triggerUrl
18
      sourceWorkflowId
19
     }
20
    }
21
   }
22
  }
23
 }
24
}

This will produce a result such as:

1
{
2
 "data": {
3
  "createSolutionInstance": {
4
   "solutionInstance": {
5
    "id": "625xxx-xxx-xxx-xxx-xxx111f",
6
    "name": "Gene Slack star instance 2",
7
    "enabled": false,
8
    "created": "2019-02-25T11:02:21.884Z",
9
    "workflows": {
10
     "edges": [
11
      {
12
       "node": {
13
        "id": "98099de2-xxx-xxx-xxx-xxxxxb8ff7",
14
        "triggerUrl": "https://6a4xxx-xxx-xxx-xxx-xxx-xxxe8eaa2.trayapp.io",
15
        "sourceWorkflowId": "378xxx-xxx-xxx-xxx-xxx-xxx4fd6"
16
       },
17
       "node": {
18
        "id": "83774e4-xxx-xxx-xxx-xxxxxvur88f",
19
        "triggerUrl": "https://9s3xxx-xxx-xxx-xxx-xxx-xxxe5iuu2.trayapp.io",
20
        "sourceWorkflowId": "593xxx-xxx-xxx-xxx-xxx-xxx9du4"
21
       }
22
      }
23
     ]
24
    }
25
   }
26
  }
27
 }
28
}

Retrieving webhook URL after Instance creation

Copy

After a Solution Instance has been created it is also possible to return the webhook url with a list instances query (remember you must use the End User's token for this query):

1
query {
2
  viewer {
3
   solutionInstances {
4
    edges {
5
     node {
6
      id
7
      name
8
      enabled
9
      created
10
      workflows{
11
       edges {
12
        node {
13
         id
14
         triggerUrl
15
         sourceWorkflowId
16
        }
17
       }
18
      }
19
     }
20
    }
21
   }
22
  }
23
 }

Updating Instances​

Copy

Updating in the tray dashboard​

Copy

Once you have published a Solution, you will be able to update instances from the dashboard.

Navigate to the project you want to update instances for. Open the project and click on the Solution Instances tab. You will find all Solution Instances linked to this project.

You can click on update as shown above and it will open a modal with options to run config wizard either by yourself or through a shareable link with the end user

Updating in your native application

Copy

Your application can call the updateSolutionInstance mutation when the user clicks update button for an Instance.

Solution Instances and change management

Copy

Please see the docs on Change management for full guidance on rolling out updates to your integrations, and ensuring all End User Solution Instances stay up-to-date.