Change management (Embedded)

Any new versions of your Solutions can be imported programatically via API, unless there are new or modified authentications:

• Any new services introduced to your workflows will need to be authenticated.

  For example, if the first version of your solution only contained Slack as a third party service, but you introduced Gmail as another service in the next version, then when importing the next version to production you will need to create / select a new Gmail authentication

• Any modified auths (changed scopes etc) for existing services will need to be re-authenticated

Rolling back changes​

Copy

• If breaking change due to auths, manual rollback only

• Always need to publish new version manually in solution editor

Updating Solution Instances​ and breaking changes

Copy

When a new version of a Solution has been tested in your dev environment and then imported and published in production, the Solution Instances that have been activated by your End Users will need to be updated for each End User.

The basic Solution Instance update process​

Copy

The process here is:

1. Update workflow(s) (dev only)

Make any necessary changes to your workflow(s) (new connector steps, new/edited auths, config data etc.)

This step is only required in dev as the edits will be included in the project which you export and import to production.

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:

When you hit the 'Publish draft' button, you will get one of the two popups shown below, depending on the edit you made in the solution.

3. Update / upgrade Solution Instances

The Solution Instance will then be:

• Automatic (lazy) updated if there are no breaking changes, when there is no impact at all to solution slots:

  

• 'Upgraded' if there have been breaking changes (new/edited auths and/or config data requirements):

  

The sections below explain this in more detail:

Automatic (lazy) updates

Copy

When the new version of the Solution is published it will be rolled out automatically to End Users, as 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.

Breaking changes and non-automatic updates (upgrades)​

Copy

Breaking changes require an 'upgrade', and you will need to follow one of the two steps outlined below.

What comprises a breaking change:

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. the Salesforce connector has been updated to a new version)

• The authentication linked to the auth slot has been re-created for a different service environment (e.g. a new OAuth app has been created for whitelabelling purposes)

Auto-upgrade Solution Instances for breaking auth changes

Project

Universal

Intermediate

Run this template to re-sync auth slots between dev and prod in your Embedded integrations an auto-upgrade all Solution Instances

DetailsUse Template

View all templates

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

Sometimes, the new config data might be hidden from the End User (as detailed in Importing config data on behalf of End Users).

To upgrade Solution instances, check whether you will 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.)

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 the 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 the Upgrade Solution Instance API docs 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
}

Decision table for solutionVersionFlags

Copy

You can decide the course of action for every solution instance using the table below: