AConnector

Overview #

AConnector is the base class you extend when creating a connector in the Orchesty SDK. A connector is a reusable component that performs a specific action, such as fetching data from an API, processing information, or sending data to an external service.

Purpose:

  • Provides the foundation for building custom connectors
  • Handles data flow through ProcessDto
  • Provides access to HTTP client, database, and application credentials
  • Integrates with the Orchesty platform's processing pipeline

Location: orchesty-nodejs-sdk/lib/Connector/AConnector.ts

When to Use #

You create a connector when you need to:

  • Fetch data from an external API
  • Transform or process data
  • Send data to an external service
  • Perform any reusable action in your integration workflow

Common use cases:

  • "Get customer data from CRM"
  • "Create invoice in accounting system"
  • "Send notification to Slack"
  • "Transform data format"

Class Hierarchy # 

ANode
    ↓
ACommonConnector
    ↓
ACommonNode
    ↓
AConnector (You extend this)
    ↓
YourCustomConnector

Key inherited capabilities:

  • From ANode: Access to application, database, and application install
  • From ACommonConnector: Access to HTTP client (CurlSender)
  • From ACommonNode: Integration with Orchesty processing pipeline

Abstract Methods You Must Implement #

processAction() # 

public abstract processAction(dto: ProcessDto): ProcessDto | Promise<ProcessDto>

This is the main method where you implement your connector's logic. The SDK calls this method automatically when the connector is executed in a workflow.

Parameters:

ParameterTypeDescription
dtoProcessDtoContains the input data, headers, and user context

Returns: ProcessDto | Promise<ProcessDto> - The same DTO object with modified data (usually the result of your processing)

Pattern:

public async processAction(dto: ProcessDto): Promise<ProcessDto> {
    // 1. Get input data
    const inputData = dto.getJsonData();
    
    // 2. Perform your logic (API calls, transformations, etc.)
    const result = await this.doSomething(inputData);
    
    // 3. Set output data
    dto.setJsonData(result);
    
    // 4. Return the modified DTO
    return dto;
}

getName() # 

public abstract getName(): string

Returns the unique identifier for your connector. This name is used to register and retrieve the connector from the DI container.

Returns: string - Unique connector identifier (lowercase, no spaces)

Example:

public getName(): string {
    return 'hubspot-get-contact';
}

Inherited Methods You Can Use #

getSender() # 

protected getSender(): CurlSender

Returns the HTTP client used to make API requests. Use this to communicate with external services.

Returns: CurlSender - HTTP client for making requests

Example:

const requestDto = new RequestDto(
    'https://api.example.com/users',
    HttpMethods.GET,
    dto
);
const responseDto = await this.getSender().send(requestDto);
const data = responseDto.getBody();

getApplication() # 

protected getApplication<T extends IApplication>(): T

Returns the application instance associated with this connector. Use this to access application-specific methods.

Returns: T extends IApplication - The application instance

Example:

const app = this.getApplication<MyCustomApplication>();
const apiUrl = app.getBaseUrl();

getApplicationInstall() # 

protected async getApplicationInstall(
    user?: string,
    enabled: boolean | null = true,
    deleted?: boolean
): Promise<ApplicationInstall>

Retrieves the application installation containing user-specific settings and credentials.

Parameters:

ParameterTypeDefaultDescription
userstring | undefined-User identifier (optional)
enabledboolean | nulltrueFilter by enabled status
deletedboolean | undefined-Include deleted installs

Returns: Promise<ApplicationInstall> - Application installation with credentials

getApplicationInstallFromProcess() # 

protected async getApplicationInstallFromProcess(
    dto: AProcessDto,
    enabled: boolean | null = true,
    deleted?: boolean
): Promise<ApplicationInstall>

Convenient method to get application install using the user from ProcessDto. This is the most common way to access credentials in a connector.

Parameters:

ParameterTypeDefaultDescription
dtoAProcessDto-Process DTO containing user info
enabledboolean | nulltrueFilter by enabled status
deletedboolean | undefined-Include deleted installs

Returns: Promise<ApplicationInstall> - Application installation with credentials

Example:

// Get the application credentials for the current user
const appInstall = await this.getApplicationInstallFromProcess(dto);
const apiKey = appInstall.getSettings()['authForm']['api_key'];

getDbClient() # 

protected getDbClient(): DatabaseClient

Returns the database client for accessing repositories and stored data.

Returns: DatabaseClient - Database client instance

Usage Examples #

Basic Connector Example #

From: orchesty-nodejs-sdk/test/Connector/TestConnector.ts

import { ApplicationInstall } from '../../lib/Application/Database/ApplicationInstall';
import AConnector from '../../lib/Connector/AConnector';
import RequestDto from '../../lib/Transport/Curl/RequestDto';
import { HttpMethods } from '../../lib/Transport/HttpMethods';
import ProcessDto from '../../lib/Utils/ProcessDto';

export default class GetUserDataConnector extends AConnector {

    public getName(): string {
        return 'get-user-data';
    }

    public async processAction(dto: ProcessDto): Promise<ProcessDto> {
        // Set the output data
        dto.setJsonData({
            success: true,
            message: 'Data processed',
            timestamp: Date.now()
        });

        return dto;
    }

}

Connector with Authentication # 

import { ApplicationInstall } from '../../lib/Application/Database/ApplicationInstall';
import AConnector from '../../lib/Connector/AConnector';
import RequestDto from '../../lib/Transport/Curl/RequestDto';
import { HttpMethods } from '../../lib/Transport/HttpMethods';
import ProcessDto from '../../lib/Utils/ProcessDto';
import CoreFormsEnum from '../../lib/Application/Base/CoreFormsEnum';

export default class HubspotGetContactConnector extends AConnector {

    public getName(): string {
        return 'hubspot-get-contact';
    }

    public async processAction(dto: ProcessDto): Promise<ProcessDto> {
        // Get application credentials
        const appInstall = await this.getApplicationInstallFromProcess(dto);
        const settings = appInstall.getSettings();
        const apiKey = settings[CoreFormsEnum.AUTHORIZATION_FORM]['api_key'];

        // Get input data
        const input = dto.getJsonData();
        const contactId = input.contactId;

        // Make authenticated API request
        const url = `https://api.hubapi.com/contacts/v1/contact/vid/${contactId}/profile`;
        const requestDto = new RequestDto(url, HttpMethods.GET, dto);
        requestDto.setHeaders({
            'Authorization': `Bearer ${apiKey}`
        });

        const responseDto = await this.getSender().send(requestDto);
        const contactData = JSON.parse(responseDto.getBody());

        // Set output data
        dto.setJsonData({
            contact: contactData,
            retrievedAt: new Date().toISOString()
        });

        return dto;
    }

}

Making HTTP Requests #

From: orchesty-nodejs-sdk/test/Connector/TestConnector.ts

export default class FetchUsersConnector extends AConnector {

    public getName(): string {
        return 'fetch-users';
    }

    public async processAction(dto: ProcessDto): Promise<ProcessDto> {
        // Make multiple parallel requests
        await Promise.all(
            [1, 2, 3].map(async (page) => {
                const requestDto = new RequestDto(
                    `https://api.example.com/users?page=${page}`,
                    HttpMethods.GET,
                    dto,
                    '',
                    { 'X-Custom-Header': 'value' }
                );
                
                requestDto.setDebugInfo(dto);
                const responseDto = await this.getSender().send(requestDto);
                const data = responseDto.getBody();
                
                // Process the response
                console.log(`Page ${page}:`, data);
            })
        );

        dto.setJsonData({
            message: 'All users fetched successfully'
        });

        return dto;
    }

}

Registration # 

// In your main application file
import DIContainer from './DIContainer/Container';
import GetUserDataConnector from './connectors/GetUserDataConnector';
import HubspotGetContactConnector from './connectors/HubspotGetContactConnector';

const container = new DIContainer();

// Register your connectors
const getUserConnector = new GetUserDataConnector();
const hubspotConnector = new HubspotGetContactConnector();

container.setConnector(getUserConnector);
container.setConnector(hubspotConnector);

// The connectors are now available in the Orchesty platform

Common Patterns #

Pattern 1: Simple Data Transformation # 

public async processAction(dto: ProcessDto): Promise<ProcessDto> {
    const input = dto.getJsonData();
    
    // Transform the data
    const output = {
        ...input,
        processed: true,
        transformedAt: new Date().toISOString()
    };
    
    dto.setJsonData(output);
    return dto;
}

Pattern 2: API Request with Error Handling # 

public async processAction(dto: ProcessDto): Promise<ProcessDto> {
    try {
        const appInstall = await this.getApplicationInstallFromProcess(dto);
        const apiKey = appInstall.getSettings()['authForm']['api_key'];
        
        const requestDto = new RequestDto(
            'https://api.example.com/data',
            HttpMethods.GET,
            dto
        );
        requestDto.setHeaders({ 'Authorization': `Bearer ${apiKey}` });
        
        const responseDto = await this.getSender().send(requestDto);
        dto.setData(responseDto.getBody());
        
        return dto;
    } catch (error) {
        // Handle error and set error status
        dto.setStopProcess(
            ResultCode.STOP_AND_FAILED,
            `Failed to fetch data: ${error.message}`
        );
        return dto;
    }
}

Pattern 3: Accessing Application Methods # 

public async processAction(dto: ProcessDto): Promise<ProcessDto> {
    // Get the application to access its methods
    const app = this.getApplication<HubspotApplication>();
    
    // Use application-specific methods
    const requestDto = await app.getRequestDto(
        dto,
        await this.getApplicationInstallFromProcess(dto),
        HttpMethods.GET,
        '/contacts/v1/lists/all/contacts/all'
    );
    
    const responseDto = await this.getSender().send(requestDto);
    dto.setData(responseDto.getBody());
    
    return dto;
}

See Also #

© 2025 Orchesty Solutions. All rights reserved.