Skip to main content
Version: 1.0.6

Basic connector

Connector's job is mainly to communicate with another services. This tutorial shows how to create a connector fetching data from a REST API. In case of successful request, connector sends data to next node for further processing.

An important responsibility of the connector is to evaluate the response and handle error conditions. Orchesty offers a number of options for setting the behavior of call error conditions. All are described on the Response results page. Here we list the main ones:

  • Repeat - to retry the same process again after specified time delay
  • Stop - to stop processing with either success of failure state
  • Limit - in case of 'Too many requests' return message into Limiter
  • Ignore - force process to continue

Prerequisites​

Creating Connector​

First we create a new class, which will for simplicity extends AConnector. This abstract contains prepared method for using CurlSender used for calling REST API.

import AConnector from '@orchesty/nodejs-sdk/dist/lib/Connector/AConnector';
import ProcessDto from '@orchesty/nodejs-sdk/dist/lib/Utils/ProcessDto';

export const NAME = 'jsonplaceholder-get-users';

export default class GetUsersConnector extends AConnector {
    public getName(): string {
        return NAME;
    }

    public async processAction(dto: ProcessDto): Promise<ProcessDto> {
        return dto;
    }
}

tip

It's also a good idea to prefix names by category, which can be for example a name of 3rd party service it's interacting with: jsonplaceholder-get-users.

Next we'll implement a process method calling JsonPlaceholder.

import { HttpMethods } from '@orchesty/nodejs-sdk/dist/lib/Transport/HttpMethods';
import RequestDto from '@orchesty/nodejs-sdk/dist/lib/Transport/Curl/RequestDto';

export default class GetUsersConnector extends AConnector {

    // ...
    public async processAction(dto: ProcessDto): Promise<ProcessDto> {
        const request = new RequestDto(
            'https://jsonplaceholder.typicode.com/users',
            HttpMethods.GET,
            dto,
        );

        const response = await this.getSender().send(request);
        dto.setData(response.getBody());

        return dto;
    }

}

Error handling​

Last step is error case handling. In this example we'll check result code and if it's 300 or above, we'll re-try request after 30 seconds up to 5 times.

OnRepeatException is the simplest way to set a repeater. Another way is via setting headers which will be discussed in later tutorials.

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

export default class GetUsersConnector extends AConnector {

    // ...

    public async processAction(dto: ProcessDto): Promise<ProcessDto> {
        // ...

        const response = await this.getSender().send(request);
        if (response.getResponseCode() >= 300) {
            throw new OnRepeatException(30, 5, response.getBody());
        }

        dto.setData(response.getBody());

        return dto;
    }

}

Whole code of connector​

import AConnector from '@orchesty/nodejs-sdk/dist/lib/Connector/AConnector';
import OnRepeatException from '@orchesty/nodejs-sdk/dist/lib/Exception/OnRepeatException';
import RequestDto from '@orchesty/nodejs-sdk/dist/lib/Transport/Curl/RequestDto';
import { HttpMethods } from '@orchesty/nodejs-sdk/dist/lib/Transport/HttpMethods';
import ProcessDto from '@orchesty/nodejs-sdk/dist/lib/Utils/ProcessDto';

export const NAME = 'jsonplaceholder-get-users';

export default class GetUsersConnector extends AConnector {

    public getName(): string {
        return NAME;
    }

    public async processAction(dto: ProcessDto): Promise<ProcessDto> {
        const request = new RequestDto(
            'https://jsonplaceholder.typicode.com/users',
            HttpMethods.GET,
            dto,
        );

        const response = await this.getSender().send(request);
        if (response.getResponseCode() >= 300) {
            throw new OnRepeatException(30, 5, response.getBody());
        }

        dto.setData(response.getBody());

        return dto;
    }

}

Registering into SDK container​

Last step is to register connector into container. This is done in index.ts file located in root of src directory.

// ...
import { container } from '@orchesty/nodejs-sdk';
import CoreServices from '@orchesty/nodejs-sdk/dist/lib/DIContainer/CoreServices';
import CurlSender from '@orchesty/nodejs-sdk/dist/lib/Transport/Curl/CurlSender';
import GetUsersConnector from './GetUsersConnector';
// ...

export default async function prepare(): Promise<void> {
    // ...
    const curlSender = container.get<CurlSender>(CoreServices.CURL);

    const getUsers = new GetUsersConnector()
        .setSender(curlSender);
    container.setConnector(getUsers);
    // ...
};

Building topology​

Now we can create a new topology in Admin to test the new connector. In the topology, we will use the connector and user task to view the downloaded data.

New connector

We publish and activate the new topology and run it with empty data. In the User Tasks tab, we should now see a report with the data we got from the remote service.