Connectors

A connector is the node type that makes a single HTTP call to a third-party service. It is always paired with an Application. The Application provides credentials and the getRequestDto() helper; the connector chooses the URL, the method, and what to do with the response.

For background see Concepts: Connectors and Applications.

Class to extend #

Minimal example #

A connector that lists Hubspot contacts:

// worker/src/Hubspot/Connector/HubspotListContacts.ts
import AConnector from '@orchesty/nodejs-sdk/dist/lib/Connector/AConnector';
import ProcessDto from '@orchesty/nodejs-sdk/dist/lib/Utils/ProcessDto';
import { HttpMethods } from '@orchesty/nodejs-sdk/dist/lib/Transport/HttpMethods';

export default class HubspotListContacts extends AConnector {
    public getName(): string {
        return 'hubspot-list-contacts';
    }

    public async processAction(dto: ProcessDto): Promise<ProcessDto> {
        const application = this.getApplication();
        const install = await this.getApplicationInstallFromProcess(dto);

        const requestDto = application.getRequestDto(
            dto,
            install,
            HttpMethods.GET,
            'https://api.hubapi.com/crm/v3/objects/contacts',
        );

        const response = await this.getSender().send(requestDto, [200]);
        dto.setJsonData(response.getJsonBody());
        return dto;
    }
}

Anatomy of a connector #

1. Get the Application with getApplication(). This is the instance you registered the connector against.
2. Resolve the install with getApplicationInstallFromProcess(dto). This loads the credentials for the user whose process is currently running.
3. Build the request with application.getRequestDto(...). The Application owns the auth header.
4. Send it with this.getSender().send(requestDto, [200, 201]). The second argument is the list of HTTP status codes that count as success; everything else turns the message into a failed step.
5. Write the response back into the DTO. The next node in the topology reads from dto.getJsonData().

Retry policy #

Every connector should decide which failures are worth retrying. The platform doesn't infer this for you — you express it in code by throwing OnRepeatException (with interval and max-hops) for transient errors, and STOP_AND_FAILED (or letting the exception propagate) for deterministic ones. When you use getSender().send(...), the SDK already applies a sensible default classification by HTTP status code.

import OnRepeatException from '@orchesty/nodejs-sdk/dist/lib/Exception/OnRepeatException';

if (response.getResponseCode() === 429) {
    throw new OnRepeatException(30, 5, 'Rate limited by upstream');
}

For the full mechanism, defaults, and per-call overrides see Error handling and retries.

Register the connector against the Application #

const hubspotApp = new HubspotApplication();
container.setApplication(hubspotApp);
container.setNode(new HubspotListContacts(), hubspotApp);

Common patterns #

• Pagination. When the response carries a next cursor, prefer a batch node so the platform can persist the cursor and resume after a crash. See Patterns: Pagination and batch.
• Rate limiting. When the API enforces request quotas, use the platform Limiter instead of setTimeout.
• Webhook callbacks. When the API delivers updates by webhook, see Patterns: Webhooks.

See also #

• Concepts: Connectors and Applications
• Custom nodes
• Batch nodes
• Error handling and retries
• Reference: Node.js / AConnector
• Reference: PHP / ConnectorAbstract