You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Please review the following PR and provide a detailed review of the changes according the ./CONTRIBUTING.md provide results in markdown format.
75
+
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.
Copy file name to clipboardExpand all lines: docs/actions-and-automations/setup-backend/create-update-entity/create-update-entity.md
+108-2Lines changed: 108 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,3 +1,6 @@
1
+
import Tabs from "@theme/Tabs"
2
+
import TabItem from "@theme/TabItem"
3
+
1
4
# Create/update entity
2
5
3
6
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:
33
36
| `team` | The team/s this entity will belong to. |
34
37
| `icon` | The icon of the entity. |
35
38
| `properties` | The properties of the entity, in `"key":"value"` pairs where the key is the property's identifier, and the value is its value. |
36
-
| `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. |
39
+
| `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). |
37
40
38
41
### Use jq to map the entity
39
42
40
43
All fields in the `mapping` object can be mapped using `jq` expressions, by wrapping the value in double curly braces `{{ }}`.
41
44
42
45
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`:
43
46
44
-
```json
47
+
```json showLineNumbers
45
48
{
46
49
"identifier": "someTaskEntity",
47
50
"title": "Some Task",
@@ -55,3 +58,106 @@ For example, say we want to assign the initiator of the action to a new entity w
55
58
:::tip Test your mapping
56
59
You can use the `Test JQ` button in the bottom-left corner to test your mapping against the action's schema.
57
60
:::
61
+
62
+
## Map entity relations
63
+
64
+
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:
76
+
77
+
```json showLineNumbers
78
+
{
79
+
"identifier": "myServiceEntity",
80
+
"title": "My Service",
81
+
"properties": {},
82
+
"relations": {
83
+
"domain": "{{ .inputs.domain }}"
84
+
}
85
+
}
86
+
```
87
+
88
+
</TabItem>
89
+
90
+
<TabItemvalue="array">
91
+
92
+
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:
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.
107
+
:::
108
+
109
+
</TabItem>
110
+
111
+
<TabItemvalue="flexible">
112
+
113
+
For maximum flexibility, you can create a conditional mapping that handles both single entity and array entity inputs:
114
+
115
+
```json showLineNumbers
116
+
{
117
+
"identifier": "myProjectEntity",
118
+
"title": "My Project",
119
+
"properties": {},
120
+
"relations": {
121
+
"dependencies": "{{ .inputs.dependencies | if type == \"array\" then map(.identifier) else .identifier end }}"
122
+
}
123
+
}
124
+
```
125
+
126
+
This pattern automatically:
127
+
- Extracts identifiers from arrays when multiple entities are selected
128
+
- Uses the identifier directly when a single entity is selected
129
+
130
+
</TabItem>
131
+
132
+
</Tabs>
133
+
134
+
135
+
### Common use cases
136
+
137
+
Here are some typical scenarios for mapping array 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.
Copy file name to clipboardExpand all lines: docs/ai-agents/overview.md
+14Lines changed: 14 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -105,6 +105,20 @@ The data model of AI agents includes two main blueprints:
105
105
106
106
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.
107
107
108
+
## Relevant guides
109
+
110
+
Explore these guides to see AI agents in action and learn how to implement them in your organization:
111
+
112
+
-[Generate incident updates with AI](/guides/all/generate-incident-updates-with-ai)
113
+
-[Enrich tasks with AI-powered context](/guides/all/enrich-tasks-with-ai)
114
+
-[Setup PR enricher AI agent](/guides/all/setup-pr-enricher-ai-agent)
115
+
-[Setup service explorer AI agent](/guides/all/setup-service-explorer-ai-agent)
116
+
-[Setup platform request triage AI agent](/guides/all/setup-platform-request-triage-ai-agent)
117
+
-[Setup task manager AI agent](/guides/all/setup-task-manager-ai-agent)
118
+
-[Setup incident manager AI agent](/guides/all/setup-incident-manager-ai-agent)
119
+
-[Add RCA context to AI agents](/guides/all/add-rca-context-to-ai-agents)
120
+
-[Enrich security vulnerability using AI](/guides/all/enrich-security-vulnerability-using-ai)
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:
53
68
54
69
### Find information quickly
@@ -97,6 +112,11 @@ Receive assistance with common development and operational tasks, directly withi
97
112
98
113
99
114
115
+
### Find your own use cases
116
+
117
+
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"
118
+
119
+
100
120
## Using Port MCP
101
121
102
122
### Setup
@@ -367,6 +387,194 @@ Refer to the [Claude custom connector documentation](https://support.anthropic.c
367
387
</TabItem>
368
388
</Tabs>
369
389
390
+
### Prompts
391
+
392
+
In Port, you can centrally manage reusable prompts and expose them to your users via the MCP Server. Once defined in Port, these prompts become available in supported MCP clients (for example, Cursor or Claude) where developers and AI agents can discover and run them with the required inputs.
393
+
394
+
#### Common use cases
395
+
396
+
- Automate on-call runbooks and incident triage guidance
397
+
- Standardize code review or deployment checklists
1. Go to the [Builder page](https://app.getport.io/settings/data-model) of your portal.
403
+
404
+
2. Click on "+ Blueprint".
405
+
406
+
3. Click on the `{...}` button in the top right corner, and choose "Edit JSON".
407
+
408
+
4. Paste the following JSON schema into the editor:
409
+
410
+
411
+
412
+
<details>
413
+
<summary>Prompt blueprint JSON (click to expand)</summary>
414
+
415
+
```json showLineNumbers
416
+
{
417
+
"identifier": "prompt",
418
+
"title": "Prompt",
419
+
"icon": "Microservice",
420
+
"schema": {
421
+
"properties": {
422
+
"description": {
423
+
"type": "string",
424
+
"title": "Description"
425
+
},
426
+
"arguments": {
427
+
"items": {
428
+
"type": "object",
429
+
"properties": {
430
+
"name": {
431
+
"type": "string",
432
+
"description": "The name of the argument parameter"
433
+
},
434
+
"description": {
435
+
"type": "string",
436
+
"description": "A description of what this argument is for"
437
+
},
438
+
"required": {
439
+
"type": "boolean",
440
+
"description": "Whether this argument is required or optional",
441
+
"default": false
442
+
}
443
+
},
444
+
"required": [
445
+
"name",
446
+
"description"
447
+
]
448
+
},
449
+
"type": "array",
450
+
"title": "Arguments"
451
+
},
452
+
"template": {
453
+
"icon": "DefaultProperty",
454
+
"type": "string",
455
+
"title": "Prompt Template",
456
+
"format": "markdown"
457
+
}
458
+
},
459
+
"required": [
460
+
"description",
461
+
"template"
462
+
]
463
+
},
464
+
"mirrorProperties": {},
465
+
"calculationProperties": {},
466
+
"aggregationProperties": {},
467
+
"relations": {}
468
+
}
469
+
```
470
+
</details>
471
+
472
+
:::info Where prompts appear
473
+
Once this blueprint exists and you create entities for it, prompts will show up in supported MCP clients connected to your Port organization. In clients that surface MCP prompts, you’ll see them listed and ready to run with arguments.
474
+
:::
475
+
476
+
#### Create prompts
477
+
478
+
Create entities of the `prompt` blueprint for each prompt you want to expose. At minimum, provide `description` and `template`. Optionally add `arguments` to parameterize the prompt.
479
+
480
+
1. Go to the [Prompts page](https://app.getport.io/prompts) in your portal.
481
+
2. Click `Create prompt`.
482
+
3. Fill out the form:
483
+
- Provide a title and description.
484
+
- Write the prompt template (supports markdown).
485
+
- Define any `arguments` (optional) with `name`, `description`, and whether they are `required`.
486
+
487
+
488
+
489
+
:::info Template and placeholders
490
+
The `template` supports markdown and variable placeholders. Each argument defined in `arguments` is exposed by its `name` and can be referenced as `{{name}}` inside the template. When you run the prompt, the MCP Server collects values for required arguments and substitutes them into the matching `{{}}` placeholders before execution.
Summarize on-call context for a team over a time window.
533
+
534
+
```markdown showLineNumbers
535
+
Create an on-call handoff for {{team}} for the last {{timeframe}}.
536
+
537
+
Include:
538
+
- Active incidents and current status
539
+
- Top risks and mitigations
540
+
- Pending actions and owners
541
+
- Upcoming maintenance windows
542
+
```
543
+
544
+
Arguments to define: `team` (required), `timeframe` (required).
545
+
546
+
</TabItem>
547
+
</Tabs>
548
+
549
+
After creating entities, reconnect or refresh your MCP client; your prompts will be available to run and will prompt for any defined arguments.
550
+
551
+
#### See prompts in your client
552
+
553
+
<TabsgroupId="prompt-ui"queryString>
554
+
<TabItemvalue="cursor"label="Cursor">
555
+
556
+
In Cursor, type "/" to open the prompts list. You'll see all `prompt` entities; selecting one opens an input form for its arguments.
557
+
558
+
559
+
560
+
When you select a prompt, Cursor renders fields for the defined `arguments`. Required ones are marked and must be provided. The MCP Server substitutes provided values into the matching `{{}}` placeholders in the template at runtime.
561
+
562
+
563
+
564
+
</TabItem>
565
+
<TabItemvalue="claude"label="Claude">
566
+
567
+
In Claude, click the "+" button and choose the prompts option to view the list from your Port organization. Selecting a prompt opens a parameter collection flow.
568
+
569
+
570
+
571
+
Claude will ask for any required arguments before running the prompt, and the MCP Server will replace the corresponding `{{}}` placeholders in the template with the provided values.
572
+
573
+
574
+
575
+
</TabItem>
576
+
</Tabs>
577
+
370
578
## Troubleshooting
371
579
372
580
If you encounter issues while setting up or using the Port MCP Server, expand the relevant section below:
0 commit comments