From 8bab7da7671c56efa93049aca8d54d533ca678ea Mon Sep 17 00:00:00 2001 From: Nico Rehwaldt Date: Fri, 31 Oct 2025 10:29:24 +0100 Subject: [PATCH 1/5] feat(modeler/element-templates): add details for `deprecated` property --- .../element-templates/template-metadata.md | 34 +++++++++++++++++-- .../element-templates/template-metadata.md | 32 ++++++++++++++++- 2 files changed, 63 insertions(+), 3 deletions(-) diff --git a/docs/components/modeler/element-templates/template-metadata.md b/docs/components/modeler/element-templates/template-metadata.md index f1c58ce32c7..f92f174679e 100644 --- a/docs/components/modeler/element-templates/template-metadata.md +++ b/docs/components/modeler/element-templates/template-metadata.md @@ -202,7 +202,7 @@ A property can be assigned to a group by setting the [`group` key](./template-pr ```json { - ..., + ..., "groups": [ { "id": "definition", @@ -231,7 +231,33 @@ A property can be assigned to a group by setting the [`group` key](./template-pr ## Deprecating a template: `deprecated` -Indicates whether the element template is deprecated. +- `deprecated` is an optional key + +Use `deprecated` to mark a [template as deprecated](https://github.com/bpmn-io/element-templates/blob/main/docs/LIFE_CYCLE.md#deprecation). + +:::info +By deprecating an element template you prevent its _future use_. Users will no longer see the template when choosing a template, changing an element's type, or creating a new element. Existing uses continue to work, with a deprecation hint shown in the modeler UI. +::: + +The `deprecated` property can be an object or a boolean. If an object, it has the following attributes: + +- `message: String`: A message to display to the user +- `documentationRef : String`: A link to documentation, i.e., to describe upgrade migration procedures + +This information allows users to make sense of the deprecation and understand how to migrate to an undeprecated template: + +```json +{ + ..., + "deprecated": { + "message": "Migrate to My Other Custom Task", + "documentationRef": "https://localhost/migrate-to-other" + }, + ... +} +``` + +When `deprecated` is a boolean (`true`), a deprecation hint appears in the properties panel without further help for the user: ```json { @@ -240,3 +266,7 @@ Indicates whether the element template is deprecated. ... } ``` + +:::tip +Review the [upstream documentation](https://github.com/bpmn-io/element-templates/blob/main/docs/LIFE_CYCLE.md#overview) to learn more about template evolution and the template lifecycle. +::: diff --git a/versioned_docs/version-8.8/components/modeler/element-templates/template-metadata.md b/versioned_docs/version-8.8/components/modeler/element-templates/template-metadata.md index 0184ba2b75c..f92f174679e 100644 --- a/versioned_docs/version-8.8/components/modeler/element-templates/template-metadata.md +++ b/versioned_docs/version-8.8/components/modeler/element-templates/template-metadata.md @@ -231,7 +231,33 @@ A property can be assigned to a group by setting the [`group` key](./template-pr ## Deprecating a template: `deprecated` -Indicates whether the element template is deprecated. +- `deprecated` is an optional key + +Use `deprecated` to mark a [template as deprecated](https://github.com/bpmn-io/element-templates/blob/main/docs/LIFE_CYCLE.md#deprecation). + +:::info +By deprecating an element template you prevent its _future use_. Users will no longer see the template when choosing a template, changing an element's type, or creating a new element. Existing uses continue to work, with a deprecation hint shown in the modeler UI. +::: + +The `deprecated` property can be an object or a boolean. If an object, it has the following attributes: + +- `message: String`: A message to display to the user +- `documentationRef : String`: A link to documentation, i.e., to describe upgrade migration procedures + +This information allows users to make sense of the deprecation and understand how to migrate to an undeprecated template: + +```json +{ + ..., + "deprecated": { + "message": "Migrate to My Other Custom Task", + "documentationRef": "https://localhost/migrate-to-other" + }, + ... +} +``` + +When `deprecated` is a boolean (`true`), a deprecation hint appears in the properties panel without further help for the user: ```json { @@ -240,3 +266,7 @@ Indicates whether the element template is deprecated. ... } ``` + +:::tip +Review the [upstream documentation](https://github.com/bpmn-io/element-templates/blob/main/docs/LIFE_CYCLE.md#overview) to learn more about template evolution and the template lifecycle. +::: From 9e7df0434c96dffcfe65bac9a634bd4bca9a942d Mon Sep 17 00:00:00 2001 From: Nico Rehwaldt Date: Mon, 3 Nov 2025 14:34:22 +0100 Subject: [PATCH 2/5] Update docs/components/modeler/element-templates/template-metadata.md Co-authored-by: Leah Bateman <148087642+lmbateman@users.noreply.github.com> --- docs/components/modeler/element-templates/template-metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/components/modeler/element-templates/template-metadata.md b/docs/components/modeler/element-templates/template-metadata.md index f92f174679e..5f05ec66102 100644 --- a/docs/components/modeler/element-templates/template-metadata.md +++ b/docs/components/modeler/element-templates/template-metadata.md @@ -231,7 +231,7 @@ A property can be assigned to a group by setting the [`group` key](./template-pr ## Deprecating a template: `deprecated` -- `deprecated` is an optional key +- `deprecated` is an optional key. Use `deprecated` to mark a [template as deprecated](https://github.com/bpmn-io/element-templates/blob/main/docs/LIFE_CYCLE.md#deprecation). From fa84cd9e87926797840fde63faaba9cffc0b022a Mon Sep 17 00:00:00 2001 From: Nico Rehwaldt Date: Mon, 3 Nov 2025 14:34:36 +0100 Subject: [PATCH 3/5] Update docs/components/modeler/element-templates/template-metadata.md Co-authored-by: Leah Bateman <148087642+lmbateman@users.noreply.github.com> --- docs/components/modeler/element-templates/template-metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/components/modeler/element-templates/template-metadata.md b/docs/components/modeler/element-templates/template-metadata.md index 5f05ec66102..ffdd6f04742 100644 --- a/docs/components/modeler/element-templates/template-metadata.md +++ b/docs/components/modeler/element-templates/template-metadata.md @@ -236,7 +236,7 @@ A property can be assigned to a group by setting the [`group` key](./template-pr Use `deprecated` to mark a [template as deprecated](https://github.com/bpmn-io/element-templates/blob/main/docs/LIFE_CYCLE.md#deprecation). :::info -By deprecating an element template you prevent its _future use_. Users will no longer see the template when choosing a template, changing an element's type, or creating a new element. Existing uses continue to work, with a deprecation hint shown in the modeler UI. +By deprecating an element template, you prevent its _future use_. Users will no longer see the template when choosing a template, changing an element's type, or creating a new element. Existing uses continue to work, with a deprecation hint shown in the modeler UI. ::: The `deprecated` property can be an object or a boolean. If an object, it has the following attributes: From 603ba6f987fa1ffabea110adf0a6cd0a09136095 Mon Sep 17 00:00:00 2001 From: Nico Rehwaldt Date: Mon, 3 Nov 2025 14:34:46 +0100 Subject: [PATCH 4/5] Update versioned_docs/version-8.8/components/modeler/element-templates/template-metadata.md Co-authored-by: Leah Bateman <148087642+lmbateman@users.noreply.github.com> --- .../components/modeler/element-templates/template-metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versioned_docs/version-8.8/components/modeler/element-templates/template-metadata.md b/versioned_docs/version-8.8/components/modeler/element-templates/template-metadata.md index f92f174679e..6d32a73652d 100644 --- a/versioned_docs/version-8.8/components/modeler/element-templates/template-metadata.md +++ b/versioned_docs/version-8.8/components/modeler/element-templates/template-metadata.md @@ -236,7 +236,7 @@ A property can be assigned to a group by setting the [`group` key](./template-pr Use `deprecated` to mark a [template as deprecated](https://github.com/bpmn-io/element-templates/blob/main/docs/LIFE_CYCLE.md#deprecation). :::info -By deprecating an element template you prevent its _future use_. Users will no longer see the template when choosing a template, changing an element's type, or creating a new element. Existing uses continue to work, with a deprecation hint shown in the modeler UI. +By deprecating an element template, you prevent its _future use_. Users will no longer see the template when choosing a template, changing an element's type, or creating a new element. Existing uses continue to work, with a deprecation hint shown in the modeler UI. ::: The `deprecated` property can be an object or a boolean. If an object, it has the following attributes: From 9b43d66350b3c9673aaeef117f5cacbcbf0f364e Mon Sep 17 00:00:00 2001 From: Nico Rehwaldt Date: Mon, 3 Nov 2025 14:34:53 +0100 Subject: [PATCH 5/5] Update versioned_docs/version-8.8/components/modeler/element-templates/template-metadata.md Co-authored-by: Leah Bateman <148087642+lmbateman@users.noreply.github.com> --- .../components/modeler/element-templates/template-metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versioned_docs/version-8.8/components/modeler/element-templates/template-metadata.md b/versioned_docs/version-8.8/components/modeler/element-templates/template-metadata.md index 6d32a73652d..ffdd6f04742 100644 --- a/versioned_docs/version-8.8/components/modeler/element-templates/template-metadata.md +++ b/versioned_docs/version-8.8/components/modeler/element-templates/template-metadata.md @@ -231,7 +231,7 @@ A property can be assigned to a group by setting the [`group` key](./template-pr ## Deprecating a template: `deprecated` -- `deprecated` is an optional key +- `deprecated` is an optional key. Use `deprecated` to mark a [template as deprecated](https://github.com/bpmn-io/element-templates/blob/main/docs/LIFE_CYCLE.md#deprecation).