> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

Handle resyncs

A resync asks your integration to fetch current data for one or more kinds. You implement that with @ocean.on_resync handlers in main.py.

Ocean calls your handler for each matching kind in the mapping. You yield batches of raw objects. Port applies the mapping and updates the catalog. For when resyncs are triggered and which listener types exist, see event listeners and resync triggers.

Resync handler pattern​

main.py
from port_ocean.context.ocean import ocean
from port_ocean.core.ocean_types import ASYNC_GENERATOR_RESYNC_TYPE

from client import MyClient


@ocean.on_resync("project")
async def on_resync_projects(kind: str) -> ASYNC_GENERATOR_RESYNC_TYPE:
    client = MyClient()
    async for projects in client.get_paginated_projects():
        yield projects

Requirements:

  • The kind string matches a kind in your mapping and in spec.yaml.
  • Each yield is a list of objects (dicts), not a single object.
  • Prefer async generators so Ocean can stream batches as you fetch them.

Kind-specific handlers​

Use an enum for kind names and register one handler per kind (or a generic handler when the client API is uniform):

from enum import StrEnum

from port_ocean.context.event import event
from port_ocean.context.ocean import ocean
from port_ocean.core.ocean_types import ASYNC_GENERATOR_RESYNC_TYPE


class ObjectKind(StrEnum):
    PROJECT = "project"
    ISSUE = "issue"


@ocean.on_resync(ObjectKind.PROJECT)
async def on_resync_projects(kind: str) -> ASYNC_GENERATOR_RESYNC_TYPE:
    client = MyClient()
    async for batch in client.get_paginated_projects():
        yield batch

Use selector config during resync​

If you defined custom selectors in integration.py, read them from event.resource_config while the resync runs:

from typing import cast

from port_ocean.context.event import event

from integration import ProjectResourceConfig


@ocean.on_resync(ObjectKind.PROJECT)
async def on_resync_projects(kind: str) -> ASYNC_GENERATOR_RESYNC_TYPE:
    client = MyClient()
    selector = cast(ProjectResourceConfig, event.resource_config).selector
    async for batch in client.get_paginated_projects(expand=selector.expand):
        yield batch

See kinds and selectors.

Startup hook​

Use @ocean.on_start() for one-time setup, such as registering webhooks in the third-party system. Skip webhook registration when the listener is ONCE (CI-style single resync).

@ocean.on_start()
async def on_start() -> None:
    if ocean.event_listener_type == "ONCE":
        return
    await MyClient().ensure_webhook()

Next steps​