Merge branch 'main' into PORTN-3057-create-a-guide-to-map-hibob-user-to-port-user

Author: kodjomiles

.github/workflows/claude-pr-reviewer.yml

@@ -1,12 +1,12 @@
 name: Claude Docs PR Reviewer
 on:
-  pull_request:
-    types:
-      - synchronize
-      - reopened
-      - opened
-    branches:
-      - main
+  # pull_request:
+  #   types:
+  #     - synchronize
+  #     - reopened
+  #     - opened
+  #   branches:
+  #     - main
   workflow_dispatch:
 
 jobs:
@@ -17,7 +17,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: 1
 
@@ -40,7 +40,7 @@ jobs:
       id-token: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: 1
 
@@ -72,5 +72,5 @@ jobs:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           allowed_tools: "Bash(git:*),Bash(gh:*),Bash(jq:*),Bash(yq:*),View,GlobTool,GrepTool,BatchTool"
           direct_prompt: |
-           Please review the following PR and provide a detailed review of the changes according the ./CONTRIBUTING.md provide results in markdown format.
+           Please review the following PR and provide a detailed review of the changes according the ./CONTRIBUTING.md provide results in markdown format. Ignore all image files.
           timeout_minutes: "15"

.github/workflows/sync-docs-with-mapping-config.yml

@@ -13,20 +13,20 @@ jobs:
 
     steps:
       - name: Checkout port-docs (automation tools)
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           path: port-docs
 
       - name: Checkout ocean-test (YAML configs source)
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           repository: ${{ github.repository_owner }}/ocean-test
           token: ${{ secrets.MAPPING_PAT }}
           path: ocean-test
           ref: main
 
       - name: Checkout Port-monorepo (TypeScript source)
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           repository: ${{ github.repository_owner }}/Port-monorepo
           token: ${{ secrets.MAPPING_PAT }}

.github/workflows/updateApiSpec.yaml

@@ -16,7 +16,7 @@ jobs:
     steps:
     # Step 1: Checkout the repository
     - name: Checkout repository
-      uses: actions/checkout@v4
+      uses: actions/checkout@v5
       with:
         fetch-depth: 0  # Fetch all history for accurate diff
 

.github/workflows/verify-docs-build.yml

@@ -18,7 +18,7 @@ jobs:
     runs-on: ubuntu-latest
     name: Test successful production build
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           persist-credentials: true
       - name: Install dependencies

.gitignore

@@ -24,4 +24,7 @@ yarn-error.log*
 .vscode
 
 #workflow cache
-.github/script/__pycache__
+.github/script/__pycache__
+
+# Generated guide metadata
+src/components/guides-section/guide-metadata.json

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.
+:::