port-labs 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). Installing a new integration end-to-end — kind selection,
use-case discovery, and populating the catalog for the first time — is the nested
port-install-integration skill, not this one.
Prerequisites
- Go over the
port-getting-startedskill 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_sourcesfor 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.