Merge branch 'main' into PORT-15928-track-status-of-ai-driven-pull-requests

Author: PeyGis

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,15 +36,15 @@ 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
 
 All fields in the `mapping` object can be mapped using `jq` expressions, by wrapping the value in double curly braces `{{ }}`.  
 
 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",
@@ -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.
 :::
+
+## 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.
+
+
+<Tabs groupId="relation-mapping" defaultValue="single" values={[
+{label: "Single Entity", value: "single"},
+{label: "Array Entity", value: "array"},
+{label: "Flexible Mapping", value: "flexible"}
+]}>
+
+<TabItem value="single">
+
+For a single entity relation, map the entity identifier directly:
+
+```json showLineNumbers
+{
+  "identifier": "myServiceEntity",
+  "title": "My Service",
+  "properties": {},
+  "relations": {
+    "domain": "{{ .inputs.domain }}"
+  }
+}
+```
+
+</TabItem>
+
+<TabItem value="array">
+
+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 showLineNumbers
+{
+  "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.
+:::
+
+</TabItem>
+
+<TabItem value="flexible">
+
+For maximum flexibility, you can create a conditional mapping that handles both single entity and array entity inputs:
+
+```json showLineNumbers
+{
+  "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
+
+</TabItem>
+
+</Tabs>
+
+
+### Common use cases
+
+Here are some typical scenarios for mapping array relations:
+
+**Mapping skills to a user:**
+```json showLineNumbers
+"relations": {
+  "skills": "{{ .inputs.selectedSkills | map(.identifier) }}"
+}
+```
+
+**Mapping team members to a project:**
+```json showLineNumbers
+"relations": {
+  "members": "{{ .inputs.teamMembers | map(.identifier) }}"
+}
+```
+
+**Mapping dependencies between services:**
+```json showLineNumbers
+"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.
+:::