Kinds and selectors

Kinds are the resource types your integration syncs (for example project or issue). Each kind can have a resync handler and, optionally, custom fields in the mapping YAML that control how you call the third-party API.

When you can skip this page

If every kind uses fixed API parameters and you do not need user-defined filters in the mapping, you can skip custom selectors. Declare kinds in .port/spec.yaml and implement @ocean.on_resync handlers only.

Layers

Layer	Role
Selector	User-facing fields for one kind (filters, expand flags, field lists).
ResourceConfig	Binds a selector to a kind literal.
PortAppConfig	Lists the resource configs your integration accepts.
BaseIntegration subclass	Wires your PortAppConfig into Ocean via integration.py.

Example

integration.py

from typing import Literal

from port_ocean.core.handlers.port_app_config.api import APIPortAppConfig
from port_ocean.core.handlers.port_app_config.models import (
    PortAppConfig,
    ResourceConfig,
    Selector,
)
from port_ocean.core.integrations.base import BaseIntegration
from pydantic import Field


class ProjectSelector(Selector):
    expand: str | None = Field(
        default=None,
        description="Optional expand parameter passed to the third-party API",
    )


class ProjectResourceConfig(ResourceConfig):
    kind: Literal["project"]
    selector: ProjectSelector


class MyPortAppConfig(PortAppConfig):
    resources: list[ProjectResourceConfig | ResourceConfig] = Field(
        default_factory=list
    )


class MyIntegration(BaseIntegration):
    class AppConfigHandlerClass(APIPortAppConfig):
        CONFIG_CLASS = MyPortAppConfig

Users can then set the selector in mapping YAML:

resources:
  - kind: project
    selector:
      query: "true"
      expand: "description"
    port:
      entity:
        mappings:
          identifier: .id
          title: .name
          blueprint: '"project"'
          properties: {}

In the resync handler, read event.resource_config and pass selector values into your client. See handle resyncs.

Mapping reference

For entity mapping fields (identifier, title, properties, relations, itemsToParse, and related options), see configure mapping. Your integration should keep yielding raw API objects; the mapping decides how those objects become catalog entities.