Run any Skill in Manus with one click

port-integrations

Stars0

Forks1

UpdatedJuly 8, 2026 at 09:21

Configure and troubleshoot Port integrations: mapping YAML, resources, selectors, JQ-based entity mappings, relations, and advanced options like createMissingRelatedEntities and itemsToParse. Use when asked to 'write a Port mapping', 'map API or tool data to a Port blueprint', 'configure an Ocean integration mapping', 'add a relation to a Port mapping', 'parse an array into separate Port entities', 'fix a Port mapping JQ error', or 'why isn't my Port integration syncing the right entities or properties'.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

port-labs

port-labs/port-skills

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

File Explorer

5 files

SKILL.md

readonly

More from this repository

same repository

port-getting-started

port-labs/port-skills

Set up Port and connect it to your coding agent: sign up for a Port account, install Port's MCP server, and optionally the Port CLI. Use when asked to 'get started with Port', 'set up Port', 'connect Port MCP', 'install the Port MCP server', 'how do I use Port from Claude Code/Cursor/VS Code', or before using any other skill in this repo for the first time.

2026-07-140

port-skill-creator

port-labs/port-skills

Author a new Agent Skill for this repo (port-labs/port-skills): scaffold the skills/port-<name>/ directory, write valid frontmatter, structure the body as a short router into references/ and assets/, validate it, and regenerate the README index. Use when asked to create a new Port skill, add a skill to this repo, help me write a SKILL.md, contribute a skill, port an internal Port AI skill to this repo, or fix a skill that fails validate-skill.js.

2026-07-080

port-blueprints

port-labs/port-skills

Model a Port context lake data model using blueprints, defining identifiers, titles, icons, properties, relations, and calculation, mirror, or aggregation properties, then author them with the raw Port API. Use when asked to create a Port blueprint, define a Port data model, add a property to a blueprint, relate two blueprints, add a calculation property, add a mirror property, or add an aggregation property.

2026-07-080

port-context-lake

port-labs/port-skills

Design and build a Port context lake: a connected, semantically-rich data model of blueprints, relations, and mirror/aggregation properties that AI agents, scorecards, and workflows can query and act on, not just a plain software catalog. Use when asked to 'build a context lake', 'design a Port data model for AI agents', 'set up the engineering intelligence data model', 'connect services to teams and orgs in Port', 'model our org hierarchy in Port', or 'why can't Port AI answer questions about our org structure'.

2026-07-080

port-dashboard-plugins

port-labs/port-skills

Scaffold, implement, and audit Port custom plugin widgets: self-contained React/TypeScript iframe apps built on @port-labs/plugins-sdk and uploaded with @port-labs/port-plugins-cli. Covers the postMessage host bridge (PLUGIN_DATA, PORT_TOKEN), the React-hooks-before-early-return rule that causes blank iframes, upload-params.json design (blueprint params vs runtime API calls), theming, webpack/CSP upload safety for chart libraries, and versioning. Use when asked to "build a custom Port widget", "create a Port plugin", "why is my Port plugin blank in the iframe", "add a params.json blueprint param to a Port plugin", or "upload a Port plugin with port-plugins-cli". For Port's built-in dashboard widgets (table, number chart, pie chart, and so on, no custom code), use the parent `port-dashboards` skill instead.

2026-07-080

port-dashboards

port-labs/port-skills

Build and update Port dashboard pages: widgets (table, number chart, pie chart, bar chart, multi-line chart, markdown, iframe, links, action card, action-runs table, entity details, AI agent), the 12-column row layout, sidebar placement, and private-page rules. Covers dataset filter syntax so a widget shows the entities you expect instead of an empty or wrong result. Use when asked to "build a Port dashboard", "add a widget to a dashboard page", "create a number chart / pie chart / table widget in Port", "why is my Port widget empty", "make this dashboard page private", or "where should this dashboard go in the sidebar". For building a custom plugin widget (your own React iframe), use the nested `port-dashboard-plugins` skill instead.

2026-07-080

name	port-integrations
description	Configure and troubleshoot Port integrations: mapping YAML, resources, selectors, JQ-based entity mappings, relations, and advanced options like createMissingRelatedEntities and itemsToParse. Use when asked to 'write a Port mapping', 'map API or tool data to a Port blueprint', 'configure an Ocean integration mapping', 'add a relation to a Port mapping', 'parse an array into separate Port entities', 'fix a Port mapping JQ error', or 'why isn't my Port integration syncing the right entities or properties'.
license	MIT
compatibility	Claude Code, Cursor, Codex CLI, GitHub Copilot
metadata	{"version":"1.0.0","author":"port-labs","repository":"https://github.com/port-labs/port-skills","tags":"port,integrations,mapping,ocean,jq,mcp-powered","summary":"Configure and troubleshoot Port integration mapping"}

Port integrations

This skill teaches you how to author, edit, and debug the mapping configuration for a Port integration: the YAML that tells an Ocean-based integration (or any Port integration) which API objects to fetch and how to turn them into Port entities, using JQ expressions.

Use this skill when

Writing a new mapping for an integration (resources, selector, port.entity.mappings).
Adding or fixing a relation between two blueprints inside a mapping.
Splitting an array field into multiple entities with itemsToParse.
A mapping test fails, or entities sync with missing/wrong data.

Out of scope: creating the blueprints and relations themselves (a mapping can only map into fields that already exist on a blueprint), and general JQ language tutorials beyond what mapping needs (see references/mapping.md for the patterns that come up most).

Prerequisites

Go over the port-getting-started skill first if this is your first time working with Port.
A Port account, with the target blueprint(s) already created.
An installed integration (hosted or self-hosted Ocean integration, or any other Port integration that exposes a mapping) whose kinds you're mapping from. If none is installed yet, see the Ocean custom integration overview first: this skill assumes the integration exists and can return data.
Port's MCP server connected is optional. When connected, use it to fetch live blueprints and raw data, apply the mapping directly, and test it before saving. When it isn't connected, every step below has a documented fallback using the Port UI or public API. Never treat a missing MCP connection as a hard stop. Search search_port_knowledge_sources for anything this skill doesn't cover.

Step 1 - Identify the target blueprint and source kind

Precondition: you know which Port blueprint the data should land in, and which API object (kind) the integration exposes for it. Action: if MCP is connected, call list_blueprints to confirm the blueprint exists and read its exact property and relation identifiers (mapping into a property that doesn't exist fails validation). Check the integration's documentation for its supported kinds. Fallback: open the blueprint in Port's data model page to read its schema, and check the integration's page under sync data to catalog for its supported kinds.

Step 2 - Get a raw data sample for the kind

Precondition: you need a real (or representative) example of what the API returns for this kind, to write correct JQ paths. Action: if MCP is connected, call get_integration_kinds_with_examples for the integration to get real raw data. Write JQ expressions against the actual field names and nesting shown there, not assumptions. Fallback: use Test examples in the mapping's YAML editor (+ Add kind) in the Port UI, paste a real payload from the source API's own documentation, or capture one request to the API directly.

Step 3 - Write the resource, selector, and query filter

Precondition: you know the data source and which items should be ingested versus skipped. Action: add a resources entry with the kind, then a selector block. Use integration-specific selector keys to narrow the API request itself (cheaper, faster), and the query JQ expression to filter the response ("true" ingests everything). Order resources so a relation's target blueprint is ingested first. See assets/simple-mapping.yaml. Fallback: not applicable, this step has no external dependency.

Step 4 - Write the entity mappings

Precondition: the resource and selector from step 3 are in place. Action: under port.entity.mappings, set identifier, title, blueprint, and properties as JQ expressions evaluated against each item. Wrap hyphenated property or identifier names in bracket notation (.properties["my-field"], not .my-field, which JQ parses as subtraction). See references/mapping.md for common transformations. Fallback: not applicable, this is static authoring.

Step 5 - Add relations, if any

Precondition: the target blueprint of the relation is ingested by an earlier resource (or already exists in the context lake). Action: use a direct identifier reference (relations: { serviceOwner: .owner.id }) when the API returns the related entity's identifier directly, or a search query rule (combinator/rules) when you only have one of its properties. Relations are replaced on every sync, an empty array clears the relation. See assets/mapping-with-relations.yaml. Fallback: skip the relation in the mapping and assign it manually in the Port UI if you want to manage it outside the integration entirely.

Step 6 - Set advanced options, if needed

Precondition: related entities referenced by this mapping may not exist yet, or you're exploding an array into multiple entities. Action: add root-level createMissingRelatedEntities: true to auto-create missing relation targets, deleteDependentEntities: true when a required relation means the source entity must be deleted alongside its target, or itemsToParse (plus optional itemsToParseName and itemsToParseTopLevelTransform) to turn one array field into several entities. Fallback: not applicable, these are static YAML keys.

Step 7 - Validate the mapping

Precondition: you have a draft mapping and a raw data example from step 2. Action: if MCP is connected, call test_integration_mapping with the mapping and the example from get_integration_kinds_with_examples, and iterate until it returns the expected entity with no errors. Fallback: use Test mapping in the Port UI's YAML editor against the same example, or save the mapping, trigger a resync, and inspect the result: get_integration_event_logs if MCP is connected, otherwise the sync's logs in the data sources page. For self-hosted Ocean integrations, you can also run the integration locally in dry-run mode before pointing it at production.

Step 8 - Diagnose a failing or incomplete sync

Precondition: entities are missing, incomplete, or a test/resync reports errors. Action: work through references/troubleshooting.md, which covers the five common root causes (mapping errors, missing data, relation issues, permission issues, filter issues), each with an MCP-powered diagnostic path and a UI/API fallback. Fallback: not applicable, this step is itself the fallback path.

Common pitfalls

Symptom	Likely cause	Fix
`must NOT have additional properties` on test	Typo'd YAML key, wrong nesting level	Compare against configure-mapping.md structure
`Blueprint with identifier "X" was not found`	Blueprint doesn't exist, or identifier typo	Confirm with `list_blueprints` or the data model page
A relation silently disappears after sync	JQ for the relation evaluated to an empty array	Relations are replaced, not merged, every sync. Return the full desired set
`.my-property` mapping returns nothing	Hyphen parsed as subtraction by JQ	Use `.properties["my-property"]` bracket notation
Entity never appears despite valid JQ	`selector.query` evaluates to `false` for that item	Test the query alone against the sample data first
Related entity never gets created	Related blueprint's resource runs after this one, or doesn't exist yet	Reorder resources, or set `createMissingRelatedEntities: true`

Quick reference

A mapping is: root-level advanced options (createMissingRelatedEntities, deleteDependentEntities), then a resources list. Each resource has a kind, a selector (query plus integration-specific keys), and port.entity.mappings (identifier, title, blueprint, properties, relations), with itemsToParse on port when one array field should become several entities.

Two complete, copy-pasteable starting points:

assets/simple-mapping.yaml - one resource, no relations.
assets/mapping-with-relations.yaml - two resources, a direct-identifier relation, a search-query relation, and createMissingRelatedEntities.

See references/mapping.md for mapping guidance and JQ recipes, and references/troubleshooting.md for the diagnostic playbook. Full concept reference: configure-mapping.md.