Tray Embedded / Building Integrations / Updating Solutions and Instances

Updating Solutions and Instances

Read first

Make sure you have read the following sections before proceeding:

Introduction

When you make changes to Workflows which form the basis of Solutions and Solution Instances which have been activated by your End Users, then the Solution Instances will need to be updated for each End User.

The process here is:

1 - Update Workflow

Make any necessary changes to your Workflow(s) (new connector steps, use of config data etc.)

2 - Edit and publish new Solution Release

Make any necessary edits (add new screens etc.) to the Solution in the UI and publish a new release of the Solution which contains the Workflow:

3 - Updating / Upgrading Solution Instances

Automatic (lazy) updates

When a new version of a Solution is published it will be rolled out automatically to End Users if no extra configuration is required from them.

This will work as a 'lazy update', with a delay of approx 2 minutes from release. If a source workflow runs on a scheduled trigger it won't happen until the next scheduled run.

Non-automatic updates (upgrades)

If there is new config required, this is considered an 'upgrade', and you will need to follow one of the two steps outlined below.

Authentication changes requiring upgrade

An upgrade is required if one or more of the following conditions are true:

  • The authentication linked to the auth slot has been updated and it has additional scopes
  • The authentication linked to the auth slot is linked to a new service version or environment (e.g. a connector's version used in a step has been changed and it uses a different service version).
  • The authentication linked to the auth slot has been re-created for a different service environment

Config changes requiring upgrade

An upgrade is required if one or more of the following conditions are true:

  • The config slot type property has changed

  • DDL properties have changed (e.g. uses a different operation)

  • The config slot is a DDL and the linked auth slot ID has changed

    1.) To manually upgrade Solution Instances you will need to manually notify your End Users that they will need to run the Configuration Wizard again (if there is new config input required from the End User (i.e. you have added new config values to the Solution which require input from the user in order for the Solution Instance to work for them, or if the Authentication has changed as mentioned above)

    2.) If the new config data is hidden from the End User (as detailed in Importing external data) you can bypass the Config Wizard and use the upgradeSolutionInstance mutation to add values for any new config data that was not included in the previous version of the Solution.

You cannot use the updateSolutionInstance mutation for this purpose.

In the example below, this mutation was used to add a value for the external_support-email which is a piece of external config that was not included in the previous version of the Solution (please see Upgrade a Solution Instance for a more detailed example):

mutation {
upgradeSolutionInstance (input: {
solutionInstanceId:"5f85b697-xxx-xxx-xxx-5d7dabe22634",
configValues: [{ externalId: "external_support-email" , value: "\\"support@example.com\\"" }]
})
{
solutionInstance {
id
}
}
}

Instance flags to indicate a new Solution version is available

When using the solutionInstance query to list an End User's Solution Instances, you can use solutionVersionFlags to indicate if a new solution release is available and if an instance upgrade might be required.

In the below sample query and response, you can see the following flags are available:

hasNewerVersion: if True this indicates that a new version of a Solution is available. This will run as a 'lazy update' (no action required) unless one of the other flags also returns true

requiresUserInputToUpdateVersion: if True this indicates that new config or auth data is available which requires the End User to run the Config Wizard again

requiresSystemInputToUpdateVersion: if True this indicates that new config or auth data is available which is hidden to the End User and must be imported with upgradeSolutionInstance as per the external_support-email example above.

In the sample query below remember that, if using a master token, instances can be filtered by owner, original solutionId, or both. If a user token is used the results will only return instances belonging to that user.

It also shows how you can query the parent solution as a node, in order to return the solutionId so as to use List Solutions to pick up the external ids required for importing external data and/or authentications.

For all criteria, input and returned data options please see List Solution Instances

Sample query

query {
viewer {
solutionInstances (criteria: {
owner: "ccfbbxxx-xxx-xxx-xxx-xxx0aee5c"
}){
edges {
node {
id
name
enabled
created
solutionVersionFlags {
hasNewerVersion
requiresUserInputToUpdateVersion
requiresSystemInputToUpdateVersion
}
solution {
id
}
}
}
}
}
}

Sample response

{
"data": {
"viewer": {
"solutionInstances": {
"edges": [
{
"node": {
"id": "68b645xxx-xxx-xxx-xx0319bf354f",
"name": "Slack channel > Trello > Dropbox Project",
"enabled": false,
"created": "2019-09-26T10:03:28.902Z",
"solutionVersionFlags": {
"hasNewerVersion": true,
"requiresUserInputToUpdateVersion": false,
"requiresSystemInputToUpdateVersion": false
},
"solution": {
"id": "83674exxx-xxx-xx-xxx-xxb61c2d3a407"
}
}
}
]
}
}
}
}