Merge branch 'main' into PORTN-3395-refactor-section-on-entity-relation

Author: hadar-co

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

docs/ai-agents/overview.md

@@ -89,6 +89,20 @@ The data model of AI agents includes two main blueprints:
 
 2. **AI invocations** - Each interaction made with an AI agent is recorded as an invocation. This acts as a log of everything going through your AI agents so you can monitor and improve them over time. Learn more in our [Interact with AI agents](/ai-agents/interact-with-ai-agents) guide.
 
+## Relevant guides
+
+Explore these guides to see AI agents in action and learn how to implement them in your organization:
+
+- [Generate incident updates with AI](/guides/all/generate-incident-updates-with-ai)
+- [Enrich tasks with AI-powered context](/guides/all/enrich-tasks-with-ai)
+- [Setup PR enricher AI agent](/guides/all/setup-pr-enricher-ai-agent)
+- [Setup service explorer AI agent](/guides/all/setup-service-explorer-ai-agent)
+- [Setup platform request triage AI agent](/guides/all/setup-platform-request-triage-ai-agent)
+- [Setup task manager AI agent](/guides/all/setup-task-manager-ai-agent)
+- [Setup incident manager AI agent](/guides/all/setup-incident-manager-ai-agent)
+- [Add RCA context to AI agents](/guides/all/add-rca-context-to-ai-agents)
+- [Enrich security vulnerability using AI](/guides/all/enrich-security-vulnerability-using-ai)
+
 ## Frequently asked questions
 
 <details>

docs/ai-agents/port-mcp-server.md

@@ -14,7 +14,7 @@ import TabItem from "@theme/TabItem"
     style={{borderRadius:'4px'}}
     width="568"
     height="320"
-    src="https://www.youtube.com/embed/hxUTTPSApQs" 
+    src="https://www.youtube.com/embed/WrVgQ-whBiE" 
     title="YouTube video player" 
     frameborder="0" 
     allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" 
@@ -49,6 +49,21 @@ The Port MCP Server directly enables these kinds of valuable, in-context interac
 
 ## Key capabilities and use-cases
 
+<center>
+<div className="video-container">
+  <iframe 
+    style={{borderRadius:'4px'}}
+    width="568"
+    height="320"
+    src="https://www.youtube.com/embed/hxUTTPSApQs" 
+    title="YouTube video player" 
+    frameborder="0" 
+    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" 
+    allowfullscreen>
+  </iframe>
+</div>
+</center>
+
 The Port MCP Server enables you to interact with your Port data and capabilities directly through natural language within your chosen LLM-powered tools. Here's what you can achieve:
 
 ### Find information quickly
@@ -97,6 +112,11 @@ Receive assistance with common development and operational tasks, directly withi
 
 ![Getting instructions for new service setup](/img/ai-agents/MCPClaudeServiceSetup.png)
 
+### Find your own use cases
+
+You can use Port's MCP to find the use cases that will be valuable to you. Try using this prompt: "think of creative prompts I can use to showcase the power of Port's MCP, based on the data available in Port"
+
+
 ## Using Port MCP
 
 ### Setup