> For the complete documentation index, see [llms.txt](https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/get-started/developer-platform/port-io.md).

# Port.io

Connect Port.io to import your software catalog — applications, teams, tiers, and ownership — into Heeler.

Heeler integrates with [Port.io](https://www.getport.io/) to import your software catalog and keep your security platform aligned with your internal developer portal. Once connected, Heeler auto-creates applications and teams from your Port blueprints.

## What Heeler imports

<table><thead><tr><th width="230">Capability</th><th>What it does</th></tr></thead><tbody><tr><td><strong>Application auto-creation</strong></td><td>Applications from Port product/software blueprints, with repositories linked automatically.</td></tr><tr><td><strong>Team sync</strong></td><td>Port teams synced with metadata (portfolio, domain, Slack channel).</td></tr><tr><td><strong>Tier mapping</strong></td><td>Port criticality (e.g. <code>mission-critical</code>) maps to Heeler tiers.</td></tr><tr><td><strong>Ownership propagation</strong></td><td>Tech leads and security leads flow through to applications and services.</td></tr><tr><td><strong>Annotation enrichment</strong></td><td>Lifecycle, domain, and portfolio propagate as annotations on repositories and services.</td></tr></tbody></table>

## Before you start

* A Port.io account with API access.
* A **Client ID** and **Client Secret** from **Port.io → Settings → Credentials**.
* **Administrator** in Heeler.

## Step 1 — Add the Port integration

Go to **Administration → Integrations → Add Integration → Port**, then enter:

<table><thead><tr><th width="200">Field</th><th>Value</th></tr></thead><tbody><tr><td><strong>Integration Name</strong></td><td>A descriptive name (e.g. <code>Port Production</code>).</td></tr><tr><td><strong>Client ID</strong></td><td>From Port → Settings → Credentials.</td></tr><tr><td><strong>Client Secret</strong></td><td>From Port → Settings → Credentials.</td></tr><tr><td><strong>Region</strong></td><td><strong>US</strong> or <strong>EU</strong> — Heeler uses this to reach the matching Port API host.</td></tr></tbody></table>

Save; Heeler begins harvesting your Port data (typically a few minutes).

## Step 2 — Select blueprints

Open the **⋯** menu on the Port connection → **Settings**, and under **Blueprints** select what Heeler should harvest.

{% hint style="warning" %}
At minimum, select your **software/service** blueprint **and** any repository blueprints (e.g. `githubRepository`, `gitlabRepository`) — without them, Heeler can't link Port entities to your source code.
{% endhint %}

## Step 3 — Configure mapping

With data harvested, set the **Source** to Port.io in Connection Mapping, then map each Heeler field to a Port attribute.

### Applications

Go to [**Applications**](/mrecEO40m5D6bt7Pq5pE/get-started/map-your-organization/applications.md) → set **Source** to Port.io → **Configure Mapping**, and pick the blueprint that represents your applications (e.g. `software`, `application`, or `product`). Then map the attributes:

<table><thead><tr><th width="200">Application field</th><th width="250">Recommended Port attribute</th><th>What it sets</th></tr></thead><tbody><tr><td><strong>Name</strong></td><td><code>title</code></td><td>The entity's display name becomes the application name.</td></tr><tr><td><strong>Description</strong></td><td><code>properties.description</code></td><td>Populates the application description.</td></tr><tr><td><strong>Tier</strong></td><td><code>properties.criticality</code></td><td>Maps criticality levels to Heeler tiers.</td></tr><tr><td><strong>Tech Lead</strong></td><td><code>relations.tech_lead</code></td><td>Assigns the technical owner.</td></tr><tr><td><strong>Security Lead</strong></td><td><code>relations.security_lead</code></td><td>Assigns the security owner.</td></tr><tr><td><strong>Repositories</strong></td><td><code>relations.repository</code></td><td>Links associated repositories to the application.</td></tr></tbody></table>

For **Tier**, use the **Supported Values** column to filter which criticality levels are included, or let all values pass through. Click **Preview Mapping Results** to verify the applications that would be created, then **Save** — Heeler runs the mapping processor and applications appear within a few minutes.

### Teams

If your catalog includes team entities, go to [**Teams**](/mrecEO40m5D6bt7Pq5pE/get-started/map-your-organization/teams.md) → set **Source** to Port.io → **Configure Mapping**, pick your team blueprint, and map:

* **Name** → `title` or `name`
* **Slack Channel** → `properties.slack_channel_name`
* **Portfolio** → `properties.portfolio` or `relations.portfolio`
* **Domain** → `properties.domain` or `relations.domain`

## Harvest and mapping cadence

Heeler harvests blueprints, entities, teams, and users from the Port API (harvesters run about every 12 hours; the mapping processor about every 6 hours) and maps them to Heeler applications, tiers, ownership, and annotations using **set-diff** — only additions and removals are written. A bulk-removal safeguard skips destructive changes if Port returns incomplete data.

## Troubleshooting

<table><thead><tr><th width="300">Symptom</th><th>Fix</th></tr></thead><tbody><tr><td>Applications show 0 repositories</td><td>Your software blueprint's relation to repository entities isn't populated in Port.</td></tr><tr><td>Teams aren't appearing</td><td>Confirm the Teams source is Port.io, team blueprints are harvested, and teams link to repository-bearing entities.</td></tr><tr><td>Properties missing from dropdowns</td><td>Heeler populates dropdowns from harvested data — wait for the next scheduled harvest. If the properties are still missing, check the connection health and contact Heeler Support.</td></tr></tbody></table>

## Related

* [Map Your Organization](/mrecEO40m5D6bt7Pq5pE/get-started/map-your-organization.md) — where Port data becomes teams and applications.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/get-started/developer-platform/port-io.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.