Updating vs Upgrading instances

Read first

Copy

• Tray Embedded Overview

• Main components diagram

• Solution building basics

• User Management

• Displaying Solutions

• Config Wizard

• Solution Instances

Introduction

Copy

After publishing the solutions, You can edit them to fix some bug, provide additional functionality in the integration or could just optimize the current solution. In any case, you would need to edit the workflows that form the solution or add new workflows.

Whenever you publish a new version of the solution, the Solution Instances of this solution that have been activated by your End Users will need to be updated for each End User.

The entire process with the steps you need to take has been explained in this tutorial:

The process here is:

1 - Update Workflow

Copy

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

2 - Edit and publish new Solution Release

Copy

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:

When you hit the 'Publish draft' button, you could get one of the two popups as shown in the next step, depending on the edit you made in the solution.

3 - Updating / Upgrading Solution Instances

Copy

Automatic (lazy) updates

Copy

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)

Copy

A breaking changes, requires an 'upgrade', and you will need to follow one of the two steps outlined below.

What comprises a breaking change:

- Authentication changes requiring upgrade

Copy

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

Copy

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

Sometimes, the new config data might be hidden from the End User (as detailed in Importing external data). To upgrade Solution instances, check whether you would be needing new configs and auth as mentioned above from the end user.

If Yes:

1. Query all the instances of the solution using Get Solution Instances

2. Loop and upgrade each one using the upgradeSolutionInstance mutation (pass the solutionInstanceId parameter only as the end user would be running the wizard to provide config and auth values.)

3. Notify the end users of these instances to run the config wizard

If No:

1. Query all the instances of the solution using Get Solution Instances

2. Loop and upgrade each one using the upgradeSolutionInstance mutation (pass values for any new config data as part of configValues object)

Here, you have essentially bypassed the Config Wizard as you didn't need inputs from your end user.

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):

1
mutation {
2
 upgradeSolutionInstance (input: {
3
  solutionInstanceId:"5f85b697-xxx-xxx-xxx-5d7dabe22634",
4
  configValues: [{ externalId: "external_support-email" , value: "\"support@example.com\"" }]
5
 })
6
  {
7
   solutionInstance {
8
   id
9
 }
10
 }
11
}

Instance flags to indicate a new Solution version is available

Copy

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 the 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

Copy

1
query {
2
  viewer {
3
   solutionInstances (criteria: {
4
   owner: "ccfbbxxx-xxx-xxx-xxx-xxx0aee5c"
5
  }){
6
    edges {
7
     node {
8
      id
9
      name
10
      enabled
11
      created
12
      solutionVersionFlags {
13
       hasNewerVersion
14
       requiresUserInputToUpdateVersion
15
       requiresSystemInputToUpdateVersion
16
      }
17
      solution {
18
       id
19
      }
20
     }
21
    }
22
    }
23
   }
24
  }

Sample response

Copy

1
{
2
 "data": {
3
  "viewer": {
4
   "solutionInstances": {
5
    "edges": [
6
     {
7
      "node": {
8
       "id": "68b645xxx-xxx-xxx-xx0319bf354f",
9
       "name": "Slack channel > Trello > Dropbox Project",
10
       "enabled": false,
11
       "created": "2019-09-26T10:03:28.902Z",
12
       "solutionVersionFlags": {
13
        "hasNewerVersion": true,
14
        "requiresUserInputToUpdateVersion": false,
15
        "requiresSystemInputToUpdateVersion": false
16
       },
17
       "solution": {
18
        "id": "83674exxx-xxx-xx-xxx-xxb61c2d3a407"
19
       }
20
      }
21
     }
22
    ]
23
   }
24
  }
25
 }
26
}