After Custom Recipe Collection Templates are published through the admin portal, it is possible to subsequently update them by uploading a new ckbk file, or by pulling latest changes from Github. Multiple workspaces might already have an instance of this Activity when the update is applied, i.e. they had this assigned to their workspace, either directly or through the industry they came from, and they have created an Activity using this option or had it automatically created.
This article outlines how the instances of the updated Activity template get updated.
The update begins immediately after the new template version is saved. Some basic validation tests are done on the new json before saving it, so e.g. illegal json will not be saved on the template, and all collections will remain on their original version.
Once validation is done and the template is saved, recipe execution will be temporarily paused across all FrontlineCloud workspaces, and the update will begin. Every instance of this Activity will be updated, with the outcome reported in the Queue Broker section of the admin portal.
Once all updates are completed, recipe execution is resumed.
Rules that govern the update of various Template components
The logic that is applied during updates is currently:
- Recipes are updated according to their "collectionRole" field: if the old template had a certain collectionRole, any recipe with the same collectionRole in the updated json will be treated as an update to the existing recipe. This means that queued future events that were going to trigger this recipe will continue to do so after the update is completed. Where an old collectionRole no longer exists in the update, the old recipe is deleted, and anything queued to run against it will be skipped
- UserData follows a slightly more complex logic. Full details are available in the implementation ticket, but the summary version is that if the user updated a UserData value from it's original (default) value, this will not be overwritten. In all other cases, the new value from the import is saved
- Recipe Collection Statistics are maintained in the original collection.
- Charts from the old template are all deleted and replaced with the new ones. Because statistics are maintained, if the charts have not changed between the two versions, there is no visible effect to the end user in the update.
- All collection metadata like type, description, introText is updated to the new version
What happens in failed updates
If for any reason an update fails, the Queue Broker admin section will show the list of collection instances where the update failed, and a brief (technical) explanation of the error. As described above, most common causes of failure would have been intercepted before the new json is saved to the template.
In the event of a failure in import, the workspaces where the update failed will roll back to the previous version, and it will continue to function as normal. This however leaves an inconsistent state, where some users are on the new version and others on a previous one, so it should be rectified immediately with a new cookbook upload that addresses the issue (or if the issue is with the engine rather than with the ckbk, this should be fixed with urgency by the dev team).
Note that the list of updates in the Queue Broker UI is cleared after a restart of FrontlineCloud, though developers with access to logs can look up the outcome of past updates.
Scenarios of interest, and best practice
- When a recipe is updated (i.e. a recipe in the new ckbk shares collectionRole with an existing old recipe), delayed actions that were queued to run on that recipe will still trigger on the target recipe. This means a given trigger can execute some old code, then be delayed, and trigger new code after the delay, if an update happened in between. This means that your new changes need to be backwards compatible, and if this is not desired, you can avoid this by changing the collectionRole of recipes that have delayed triggers
- Statistics are not altered during updates, so if you change the statistic key/groupIdentifier in an UpdateStatisticsAction and update the chart that cares about these, make sure chart config is backward compatible or your legacy data won't be shown on it. Also remember that if you add new statistics that are now intended to work in pairs (e.g if you previously had a "number of people who finished this query" and you then add "number of people who started this query"), there may be incongruous results because of the legacy data (e.g. more people finishing than there are who started).