Your first custom node

This page walks through writing the smallest useful node: it receives a message, attaches a timestamp, and forwards it. By the end you'll have a node available in the Admin UI's topology editor.

For background on what a "node" is, read Concepts: Topologies. For the full custom-node API, see Reference: Node.js / ACommonNode (or PHP / CommonNodeAbstract) and Development: Custom nodes.

The example below uses the Node.js SDK because the worker starter is Node.js today. The PHP SDK exposes the equivalent class (CommonNodeAbstract) and works the same way; see Full-stack setup / first custom node for the side-by-side example.

1. Create the node file #

Create src/MyTimestamp/AddTimestampNode.ts:

import ACommonNode from '@orchesty/nodejs-sdk/dist/lib/Commons/ACommonNode';
import ProcessDto from '@orchesty/nodejs-sdk/dist/lib/Utils/ProcessDto';

export default class AddTimestampNode extends ACommonNode {
    public getName(): string {
        return 'add-timestamp';
    }

    public async processAction(dto: ProcessDto): Promise<ProcessDto> {
        const data = dto.getJsonData() as Record<string, unknown>;
        dto.setJsonData({
            ...data,
            receivedAt: new Date().toISOString(),
        });
        return dto;
    }
}

2. Register it in the worker #

Open src/index.ts and add the import + registration:

import AddTimestampNode from './MyTimestamp/AddTimestampNode';

function prepare(): void {
    initiateContainer();
    container.setNode(new AddTimestampNode());
}

Custom nodes that don't authenticate against an external service are registered with no second argument (no application).

3. Restart the worker #

npm start

The Admin UI now exposes add-timestamp as a draggable node in the topology editor.

4. Use it in a topology #

1. Open the Admin UI -> Topologies -> New.
2. Drop a Start node and add-timestamp from the Custom Nodes panel.
3. Connect Start -> add-timestamp, save, and publish.
4. Trigger the topology with a JSON payload of your choice.