From 8a7fba2501d647d28f774f12d67285868cbc9214 Mon Sep 17 00:00:00 2001 From: kodjomiles Date: Fri, 1 Aug 2025 16:18:40 +0000 Subject: [PATCH 1/5] Enhance documentation for create/update entity with relation mapping examples and clarify relation handling for single and multiple entities. --- .../create-update-entity.md | 108 +++++++++++++++++- 1 file changed, 107 insertions(+), 1 deletion(-) diff --git a/docs/actions-and-automations/setup-backend/create-update-entity/create-update-entity.md b/docs/actions-and-automations/setup-backend/create-update-entity/create-update-entity.md index a76b048536..e504cf3c9f 100644 --- a/docs/actions-and-automations/setup-backend/create-update-entity/create-update-entity.md +++ b/docs/actions-and-automations/setup-backend/create-update-entity/create-update-entity.md @@ -1,3 +1,6 @@ +import Tabs from "@theme/Tabs" +import TabItem from "@theme/TabItem" + # Create/update entity In some cases, we don't want to run complex logic via a workflow or pipeline, but rather want our backend to simply create or update an entity in our software catalog. @@ -33,7 +36,7 @@ To use this backend type, you will need to define the following fields: | `team` | The team/s this entity will belong to. | | `icon` | The icon of the entity. | | `properties` | The properties of the entity, in `"key":"value"` pairs where the key is the property's identifier, and the value is its value. | - | `relations` | The relations of the entity, in `"key":"value"` pairs where the key is the relation's identifier, and the value is the related entity's identifier. | + | `relations` | The relations of the entity, in `"key":"value"` pairs where the key is the relation's identifier, and the value is the related entity's identifier (for single relations) or an array of identifiers (for many relations). | ### Use jq to map the entity @@ -55,3 +58,106 @@ For example, say we want to assign the initiator of the action to a new entity w :::tip Test your mapping You can use the `Test JQ` button in the bottom-left corner to test your mapping against the action's schema. ::: + +## Mapping entity relations + +When creating or updating entities, you often need to establish relations with other entities. The mapping approach depends on whether you're dealing with single or multiple entity inputs. + + + + + + +For a single entity relation, map the entity identifier directly: + +```json +{ + "identifier": "myServiceEntity", + "title": "My Service", + "properties": {}, + "relations": { + "domain": "{{ .inputs.domain }}" + } +} +``` + + + + + +When your action accepts [array entity inputs](/docs/actions-and-automations/create-self-service-experiences/setup-ui-for-action/user-inputs/entity.md#array), you need to extract the identifiers from the array using the `map(.identifier)` pattern: + +```json +{ + "identifier": "myUserEntity", + "title": "My User", + "properties": {}, + "relations": { + "skills": "{{ .inputs.skills | map(.identifier) }}" + } +} +``` + +:::info Array entity inputs +When users select multiple entities from an [entity array input](/docs/actions-and-automations/create-self-service-experiences/setup-ui-for-action/user-inputs/entity.md#array), the input contains an array of entity objects. Each object includes both `identifier` and `title` properties, but relations can only reference entity identifiers. +::: + + + + + +For maximum flexibility, you can create a conditional mapping that handles both single entity and array entity inputs: + +```json +{ + "identifier": "myProjectEntity", + "title": "My Project", + "properties": {}, + "relations": { + "dependencies": "{{ .inputs.dependencies | if type == \"array\" then map(.identifier) else .identifier end }}" + } +} +``` + +This pattern automatically: +- Extracts identifiers from arrays when multiple entities are selected +- Uses the identifier directly when a single entity is selected + + + + + + +## Common use cases + +Here are some typical scenarios for mapping array relations: + +**Mapping skills to a user:** +```json +"relations": { + "skills": "{{ .inputs.selectedSkills | map(.identifier) }}" +} +``` + +**Mapping team members to a project:** +```json +"relations": { + "members": "{{ .inputs.teamMembers | map(.identifier) }}" +} +``` + +**Mapping dependencies between services:** +```json +"relations": { + "dependsOn": "{{ .inputs.dependencies | map(.identifier) }}" +} +``` + + +:::info Entity titles in relations +Relations can only reference entity **identifiers**, not titles. Even though entity objects contain both `identifier` and `title` properties, you must always use `.identifier` when mapping to relations. +::: From 12ef77845717c57927c784fbf64057ec0bd02428 Mon Sep 17 00:00:00 2001 From: Jaden Kodjo Miles <87667954+kodjomiles@users.noreply.github.com> Date: Thu, 14 Aug 2025 12:48:36 +0000 Subject: [PATCH 2/5] Update docs/actions-and-automations/setup-backend/create-update-entity/create-update-entity.md Co-authored-by: hadar-co --- .../setup-backend/create-update-entity/create-update-entity.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/actions-and-automations/setup-backend/create-update-entity/create-update-entity.md b/docs/actions-and-automations/setup-backend/create-update-entity/create-update-entity.md index e504cf3c9f..7fd6f18e1d 100644 --- a/docs/actions-and-automations/setup-backend/create-update-entity/create-update-entity.md +++ b/docs/actions-and-automations/setup-backend/create-update-entity/create-update-entity.md @@ -36,7 +36,7 @@ To use this backend type, you will need to define the following fields: | `team` | The team/s this entity will belong to. | | `icon` | The icon of the entity. | | `properties` | The properties of the entity, in `"key":"value"` pairs where the key is the property's identifier, and the value is its value. | - | `relations` | The relations of the entity, in `"key":"value"` pairs where the key is the relation's identifier, and the value is the related entity's identifier (for single relations) or an array of identifiers (for many relations). | + | `relations` | The relations of the entity, in `"key":"value"` pairs where the key is the relation's identifier, and the value is the related entity's identifier (for single relations) or an array of identifiers (for "many" relations). | ### Use jq to map the entity From 0b7a7241535b141663e4bdaabfdaf17c5ed25426 Mon Sep 17 00:00:00 2001 From: Jaden Kodjo Miles <87667954+kodjomiles@users.noreply.github.com> Date: Thu, 14 Aug 2025 12:54:13 +0000 Subject: [PATCH 3/5] Update create-update-entity.md --- .../create-update-entity/create-update-entity.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/actions-and-automations/setup-backend/create-update-entity/create-update-entity.md b/docs/actions-and-automations/setup-backend/create-update-entity/create-update-entity.md index 7fd6f18e1d..ebd1f40756 100644 --- a/docs/actions-and-automations/setup-backend/create-update-entity/create-update-entity.md +++ b/docs/actions-and-automations/setup-backend/create-update-entity/create-update-entity.md @@ -44,7 +44,7 @@ All fields in the `mapping` object can be mapped using `jq` expressions, by wrap For example, say we want to assign the initiator of the action to a new entity when it is created, we can take his email from the action run object and assign it to a property named `assignee`: -```json +```json showLineNumbers { "identifier": "someTaskEntity", "title": "Some Task", @@ -74,7 +74,7 @@ When creating or updating entities, you often need to establish relations with o For a single entity relation, map the entity identifier directly: -```json +```json showLineNumbers { "identifier": "myServiceEntity", "title": "My Service", @@ -91,7 +91,7 @@ For a single entity relation, map the entity identifier directly: When your action accepts [array entity inputs](/docs/actions-and-automations/create-self-service-experiences/setup-ui-for-action/user-inputs/entity.md#array), you need to extract the identifiers from the array using the `map(.identifier)` pattern: -```json +```json showLineNumbers { "identifier": "myUserEntity", "title": "My User", @@ -112,7 +112,7 @@ When users select multiple entities from an [entity array input](/docs/actions-a For maximum flexibility, you can create a conditional mapping that handles both single entity and array entity inputs: -```json +```json showLineNumbers { "identifier": "myProjectEntity", "title": "My Project", @@ -137,21 +137,21 @@ This pattern automatically: Here are some typical scenarios for mapping array relations: **Mapping skills to a user:** -```json +```json showLineNumbers "relations": { "skills": "{{ .inputs.selectedSkills | map(.identifier) }}" } ``` **Mapping team members to a project:** -```json +```json showLineNumbers "relations": { "members": "{{ .inputs.teamMembers | map(.identifier) }}" } ``` **Mapping dependencies between services:** -```json +```json showLineNumbers "relations": { "dependsOn": "{{ .inputs.dependencies | map(.identifier) }}" } From 26e5cfd5dba0ab4cd87c0515854f0123cc733f5c Mon Sep 17 00:00:00 2001 From: hadar-co Date: Thu, 14 Aug 2025 16:20:57 +0300 Subject: [PATCH 4/5] Update docs/actions-and-automations/setup-backend/create-update-entity/create-update-entity.md --- .../setup-backend/create-update-entity/create-update-entity.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/actions-and-automations/setup-backend/create-update-entity/create-update-entity.md b/docs/actions-and-automations/setup-backend/create-update-entity/create-update-entity.md index ebd1f40756..93fbc2484e 100644 --- a/docs/actions-and-automations/setup-backend/create-update-entity/create-update-entity.md +++ b/docs/actions-and-automations/setup-backend/create-update-entity/create-update-entity.md @@ -59,7 +59,7 @@ For example, say we want to assign the initiator of the action to a new entity w You can use the `Test JQ` button in the bottom-left corner to test your mapping against the action's schema. ::: -## Mapping entity relations +## Map entity relations When creating or updating entities, you often need to establish relations with other entities. The mapping approach depends on whether you're dealing with single or multiple entity inputs. From dd3e0e668541b64a61bc5ffbdf1e8770370ef8d4 Mon Sep 17 00:00:00 2001 From: hadar-co Date: Thu, 14 Aug 2025 16:21:30 +0300 Subject: [PATCH 5/5] Update docs/actions-and-automations/setup-backend/create-update-entity/create-update-entity.md --- .../setup-backend/create-update-entity/create-update-entity.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/actions-and-automations/setup-backend/create-update-entity/create-update-entity.md b/docs/actions-and-automations/setup-backend/create-update-entity/create-update-entity.md index 93fbc2484e..521e83a733 100644 --- a/docs/actions-and-automations/setup-backend/create-update-entity/create-update-entity.md +++ b/docs/actions-and-automations/setup-backend/create-update-entity/create-update-entity.md @@ -132,7 +132,7 @@ This pattern automatically: -## Common use cases +### Common use cases Here are some typical scenarios for mapping array relations: