Element Templates Runtime Versions support

[jarekdanielak]

Related to camunda/camunda-modeler#4530
Related to https://github.com/camunda/product-hub/issues/2368 (epic)

Proposed Changes

The goal of this pull request is to ensure that served element templates are compatible (best to our knowledge) with current runtime environment.

Modelers will be able to pass their engines configuration to elementTemplates. If templates have information about compatible engines in their schema (introduced with camunda/element-templates-json-schema#146), compatibility will be verified and relevant templates will be provided.

If runtime environment changes dynamically, it can be adjusted with elementTemplates#setEngines API.

Bunch of enhancements to support element templates runtime versions:

• Add engines configuration to ElementTemplates module.
• Add API to set engines config.
• Add API to check if template is compatible with currently set engines.
• Verify compatibility when setting templates and only serve compatible templates as latest.
• Introduce new "Not compatible" state in properties panel element templates group to differentiate between not found and not compatible templates.
• Add linting for incompatible template.
• Clean up commits
• (optional) Console warning if templates provide compatibility info, but modeler didn't provide runtime version.

Test locally

npx @bpmn-io/sr bpmn-io/bpmn-js-element-templates#engines

Checklist

To ensure you provided everything we need to look at your PR:

• Brief textual description of the changes present
• Visual demo attached
• Steps to try out present, i.e. using the @bpmn-io/sr tool
• Related issue linked via Closes {LINK_TO_ISSUE} or Related to {LINK_TO_ISSUE}

[barmac]

Architecture sketch done in the session with @niku:

[nikku]

@jarekdanielak I updated the PR as per today morning s discussions.

All test cases are green, and a few stub cases remain that I'd ask you to implement.

[jarekdanielak]

@nikku filled the tests and fixed small things on the way.

I moved Validator tests from cloud-element-templates to base as the engines validation happens in the base Validator.

[nikku]

Turns out we did not add validation for cloud* templates, and also no test coverage.

Via 07b580e I made sure that we have both in there, and tests are available for both element-template variants.

I find d66afd3 interesting @jarekdanielak. You add this to the manual test bed, but don't add it as an integration test?

What would be the expected behavior if only incompatible templates are provided? We don't test cover this (yet).

[jarekdanielak]

I find d66afd3 interesting @jarekdanielak. You add this to the manual test bed, but don't add it as an integration test?

It's covered here. Or do you mean engine version zero?

What would be the expected behavior if only incompatible templates are provided? We don't test cover this (yet).

First version (first provided in templates array) will be set as latest. elementTemplates#set doesn't validate compatibility if template is not yet in the templatesById dictionary. We later detect this as incompatibility in ElementTemplatesGroup, but should we not set it in the first place?

[nikku]

First version (first provided in templates array) will be set as latest. elementTemplates#set doesn't validate compatibility if template is not yet in the templatesById dictionary. We later detect this as incompatibility in ElementTemplatesGroup, but should we not set it in the first place?

Exactly, cf. f37ae0e.

[nikku]

2ab8f11 marks only compatible templates as latest.

[nikku]

I suggest you @jarekdanielak and @lmbateman checkin and fine-tune the UI of the update buttons.

You can find my proposal here, which includes a "yellow", "warning" state that signals "you may better do something about this (but don't have to). I'm resistant to show incompatibility as 🔴, cf. this conversation and following:

[nikku]

@jarekdanielak What do you think of the following: We add elementTemplates as a default provided engine, pinned to the bpmn-js-element-templates version.

Why? Because this allows environments to specify: "compatible with element templates >= xyz", so older Desktop Modeler versions would be able to safely ignore templates that are tagged for incompatible element template run-times.

[nikku]

If we expose another public API then we need to test this.

[jarekdanielak]

Added with 54da72d

[jarekdanielak]

Updated with linting and UI changes discussed in the Slack thread.

Since we want compatibility to lint with warning level, I extracted it to a new rule and reorganized linting code to make it easier to navigate and extend (36cf7a5).

---

I consider this now ready for review: @barmac, @philippfromme

@lmbateman you can run it and check all the element templates states we now have with:

npx @bpmn-io/sr bpmn-io/bpmn-js-element-templates#engines.

Please give me your thumbs up or comments on the final design.

---

What do you think of the following: We add elementTemplates as a default provided engine, pinned to the bpmn-js-element-templates version.

@nikku let's discuss tomorrow.

[jarekdanielak]

Summary of discussion with @nikku about adding current version of bpmn-js-element-templates as a default engine:

Providing elementTemplates engine will allow template authors to make sure old modelers (using old version of bpmn-js-element-templates) don't load new, incompatible templates.

Let's build it. 👍

In the example below, it's clear that Template Version 2 relies on some new bpmn-js-element-templates features and shouldn't be used with older versions.

[jarekdanielak]

@nikku ready for review. ✅

[nikku]

This now looks good to me. Performed another minor cleanup, with minor changes:

• Do not leak semver internals via elementTemplates#getEngines, this is now a Record<string, string> object, and we have proper test coverage for it, too
• Additional tests to verify linting compatibility in the absence of executionPlatform, removed injection of camundaDesktopModeler through XML parsing (ad8897e). Looking at last exporter is dangerous, as this field indicates the last, not necessarily the current editor.
• Simplified injection of elementTemplates version, preventing leak of package.json into bundled file (6e04e56), simplified extaction at lint time (2c95fc5)

Please double-check, consider to squash 6e04e56 and ad8897e, and we're good to merge.

[barmac]

To fix: the template removal does not update the UI and allows to delete the model o.O
This is broken for any template (not only new buttons), and works fine on main:

Screen.Recording.2024-12-12.at.10.49.23.mov

[barmac]

Wondering if this is related to the identified dependency of the properties panel on element templates (https://github.com/bpmn-io/hour-of-code/pull/8)

[jarekdanielak]

The problem only happened in the Example test and is now fixed. Good catch. 👍

[nikku]

The example test bed is broken now, after the fixes for #132 (comment):

We can follow-up with the fix after merging this PR, but my question would be: What is our stable pattern to hook up engine changes (in XML) and elementTemplates.setEngines()? I don't see how/why we want to do it differently from this in the actual editors that implement a version chooser:

const ChangeEnginesModule = {

  __init__: [ function(bpmnjs, eventBus, elementTemplates) {

    eventBus.on([
      'import.done',
      'elements.changed'
    ], function() {
      const executionPlatformVersion = bpmnjs.getDefinitions().get('executionPlatformVersion');

      elementTemplates.setEngines({
        camunda: executionPlatformVersion
      });
    });
  } ]
};

[nikku]

Fixed "everything" at last, via 7f81766 and ensure the integration pattern works.

[nikku]

This works as expected, let's go forth and merge and release.