ProcessDto

Overview #

ProcessDto is the data transfer object that flows through your connectors. It contains the input data, output data, headers, user context, and control flow information. Every connector receives a ProcessDto in its processAction() method and returns a modified version.

Purpose:

Carry data through the processing pipeline
Provide access to user and application context
Control processing flow (success, failure, retry, rate limiting)
Maintain headers for tracking and debugging

Location: orchesty-nodejs-sdk/lib/Utils/ProcessDto.ts

When to Use #

You work with ProcessDto in every connector:

Input: Get data from previous steps via getJsonData() or getData()
Output: Set results via setJsonData() or setData()
Context: Access user info via getUser()
Control: Set status codes for error handling, retries, etc.

Class Hierarchy #

AProcessDto<Data>
    ↓
ProcessDto<Data>

Type Parameter:

Data (optional): TypeScript type for your JSON data structure

Core Methods #

Data Methods #

getData() #

public getData(): string

Returns the raw data as a string.

Returns: string - Raw data content

Example:

const rawData = dto.getData();
console.log(rawData); // '{"name":"John","age":30}'

getJsonData() #

public getJsonData(): JsonData

Returns the data parsed as JSON object.

Returns: JsonData - Parsed JSON object

Example:

const data = dto.getJsonData();
console.log(data.name); // 'John'
console.log(data.age);  // 30

setData() #

public setData(data: string): this

Sets raw string data.

Parameters:

Parameter	Type	Description
`data`	`string`	Raw string data to set

Returns: this - Fluent interface

Example:

dto.setData('{"result":"success"}');

setJsonData() #

public setJsonData(body: unknown): this

Sets data by automatically converting object to JSON string.

Parameters:

Parameter	Type	Description
`body`	`unknown`	Object to be JSON-stringified

Returns: this - Fluent interface

Example:

dto.setJsonData({
    userId: 123,
    name: 'John Doe',
    status: 'active'
});

setNewJsonData() #

public setNewJsonData<T>(body: T): ProcessDto<T>

Sets data with a new TypeScript type.

Type Parameter: T - The new data type

Parameters:

Parameter	Type	Description
`body`	`T`	Typed object to set

Returns: ProcessDto<T> - DTO with new type

Example:

interface UserData {
    id: number;
    email: string;
}

const typedDto = dto.setNewJsonData<UserData>({
    id: 123,
    email: 'user@example.com'
});

// Now typedDto.getJsonData() returns UserData type

Header Methods #

getHeaders() #

public getHeaders(): IHttpHeaders

Returns all headers.

Returns: IHttpHeaders - Object containing all headers

getHeader() #

public getHeader(key: string): string | undefined
public getHeader(key: string, defaultValue: string): string

Gets a specific header value.

Parameters:

Parameter	Type	Description
`key`	`string`	Header name
`defaultValue`	`string` (optional)	Default value if header doesn't exist

Returns: string | undefined - Header value or default

Example:

const correlationId = dto.getHeader('correlation-id');
const nodeId = dto.getHeader('node-id', 'unknown');

setHeaders() #

public setHeaders(headers: IHttpHeaders): this

Replaces all headers.

Parameters:

Parameter	Type	Description
`headers`	`IHttpHeaders`	New headers object

Returns: this - Fluent interface

addHeader() #

public addHeader(key: string, value: string): this

Adds or updates a single header.

Parameters:

Parameter	Type	Description
`key`	`string`	Header name
`value`	`string`	Header value

Returns: this - Fluent interface

Example:

dto.addHeader('X-Custom-Header', 'my-value');

removeHeader() #

public removeHeader(key: string): this

Removes a specific header.

Parameters:

Parameter	Type	Description
`key`	`string`	Header name to remove

Returns: this - Fluent interface

User and Application Methods #

getUser() #

public getUser(): string | undefined

Returns the user identifier from headers.

Returns: string | undefined - User ID

Example:

const userId = dto.getUser();
console.log(`Processing for user: ${userId}`);

setUser() #

public setUser(value: string | undefined): this

Sets the user identifier.

Parameters:

Parameter	Type	Description
`value`	`string \| undefined`	User ID

Returns: this - Fluent interface

getCurrentApp() #

public getCurrentApp(): string

Gets the current application name.

Returns: string - Application name

setCurrentApp() #

public setCurrentApp(value: string): this

Sets the current application name.

Parameters:

Parameter	Type	Description
`value`	`string`	Application name

Returns: this - Fluent interface

Status and Flow Control Methods #

setSuccessProcess() #

public setSuccessProcess(message = 'Message has been processed successfully.'): this

Marks the processing as successful.

Parameters:

Parameter	Type	Default	Description
`message`	`string`	`'Message has been...'`	Success message

Returns: this - Fluent interface

Example:

dto.setJsonData(result);
dto.setSuccessProcess('Customer data fetched successfully');
return dto;

setStopProcess() #

public setStopProcess(status: ResultCode, reason: string): this

Stops processing with an error status.

Parameters:

Parameter	Type	Description
`status`	`ResultCode`	Error code (`STOP_AND_FAILED` or `DO_NOT_CONTINUE`)
`reason`	`string`	Error message

Returns: this - Fluent interface

Example:

dto.setStopProcess(
    ResultCode.STOP_AND_FAILED,
    'API returned 404: Customer not found'
);
return dto;

setLimitExceeded() #

public setLimitExceeded(reason: string): this

Indicates rate limit was exceeded.

Parameters:

Parameter	Type	Description
`reason`	`string`	Reason for limit exceeded

Returns: this - Fluent interface

Example:

dto.setLimitExceeded('API rate limit reached: 100 requests/minute');
return dto;

Limiter Methods #

setLimiter() #

public setLimiter(key: string, time: number, amount: number): this

Sets rate limiting for this processing.

Parameters:

Parameter	Type	Description
`key`	`string`	Unique identifier for the limit
`time`	`number`	Time window in seconds
`amount`	`number`	Maximum number of requests in the time window

Returns: this - Fluent interface

Example:

// Limit to 100 requests per 60 seconds per user
dto.setLimiter(
    `user-${userId}`,
    60,
    100
);

setLimiterWithGroup() #

public setLimiterWithGroup(
    key: string,
    time: number,
    amount: number,
    groupKey: string,
    groupTime: number,
    groupAmount: number
): this

Sets rate limiting with both individual and group limits.

Parameters:

Parameter	Type	Description
`key`	`string`	Individual limit key
`time`	`number`	Individual time window (seconds)
`amount`	`number`	Individual request limit
`groupKey`	`string`	Group limit key
`groupTime`	`number`	Group time window (seconds)
`groupAmount`	`number`	Group request limit

Returns: this - Fluent interface

Example:

// Individual: 100 req/min, Group: 1000 req/min
dto.setLimiterWithGroup(
    `user-${userId}`,
    60,
    100,
    `app-global`,
    60,
    1000
);

removeLimiter() #

public removeLimiter(): this

Removes rate limiting configuration.

Returns: this - Fluent interface

Repeater Methods #

setRepeater() #

public setRepeater(interval: number, maxHops: number, reason: string): this

Configures automatic retry logic.

Parameters:

Parameter	Type	Description
`interval`	`number`	Seconds between retries (must be >= 1)
`maxHops`	`number`	Maximum number of retries (must be >= 1)
`reason`	`string`	Reason for retry

Returns: this - Fluent interface

Throws: Error if interval or maxHops < 1

Example:

// Retry up to 5 times with 30 second intervals
dto.setRepeater(
    30,
    5,
    'Waiting for external system to process the request'
);
return dto;

removeRepeater() #

public removeRepeater(): this

Removes retry configuration.

Returns: this - Fluent interface

Force Followers Methods #

setForceFollowers() #

public setForceFollowers(...followers: string[]): this

Forces routing to specific downstream nodes.

Parameters:

Parameter	Type	Description
`...followers`	`string[]`	Names of nodes to route to

Returns: this - Fluent interface

Throws: Error if specified followers don't exist

Example:

// Route to specific error handling node
dto.setForceFollowers('error-handler', 'notification-sender');

removeForceFollowers() #

public removeForceFollowers(): this

Removes forced routing configuration.

Returns: this - Fluent interface

Usage Examples #

Reading Input Data #

public async processAction(dto: ProcessDto): Promise<ProcessDto> {
    // Get input as parsed JSON object
    const input = dto.getJsonData();
    console.log('Customer ID:', input.customerId);
    console.log('Action:', input.action);
    
    // Or get raw string data
    const rawData = dto.getData();
    console.log('Raw:', rawData);
    
    // Get user context
    const userId = dto.getUser();
    console.log('Processing for user:', userId);
    
    return dto;
}

Setting Output Data #

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

public async processAction(dto: ProcessDto): Promise<ProcessDto> {
    // Set output as object (automatically JSON-stringified)
    dto.setJsonData({
        test: 'ok',
        processed: Date.now().toString(),
        result: {
            success: true,
            recordsProcessed: 42
        }
    });
    
    return dto;
}

Working with Headers #

public async processAction(dto: ProcessDto): Promise<ProcessDto> {
    // Read headers
    const correlationId = dto.getHeader('correlation-id');
    const nodeId = dto.getHeader('node-id', 'unknown');
    
    // Add custom headers
    dto.addHeader('X-Processing-Time', Date.now().toString());
    dto.addHeader('X-Records-Count', '150');
    
    // Get all headers
    const allHeaders = dto.getHeaders();
    console.log('All headers:', allHeaders);
    
    return dto;
}

Error Handling #

public async processAction(dto: ProcessDto): Promise<ProcessDto> {
    try {
        const input = dto.getJsonData();
        
        // Validate input
        if (!input.customerId) {
            dto.setStopProcess(
                ResultCode.STOP_AND_FAILED,
                'Missing required field: customerId'
            );
            return dto;
        }
        
        // Fetch data
        const customer = await this.fetchCustomer(input.customerId);
        
        if (!customer) {
            dto.setStopProcess(
                ResultCode.STOP_AND_FAILED,
                `Customer ${input.customerId} not found`
            );
            return dto;
        }
        
        // Success
        dto.setJsonData(customer);
        dto.setSuccessProcess('Customer fetched successfully');
        
        return dto;
        
    } catch (error) {
        dto.setStopProcess(
            ResultCode.STOP_AND_FAILED,
            `Error fetching customer: ${error.message}`
        );
        return dto;
    }
}

Rate Limiting #

public async processAction(dto: ProcessDto): Promise<ProcessDto> {
    const userId = dto.getUser();
    
    // Set rate limit: 100 requests per 60 seconds per user
    dto.setLimiter(`user-${userId}`, 60, 100);
    
    // Or use group limits
    // Individual: 10 req/min, Global: 1000 req/min
    dto.setLimiterWithGroup(
        `user-${userId}`,
        60,
        10,
        'global-api-limit',
        60,
        1000
    );
    
    // Make API call
    const result = await this.callExternalAPI();
    dto.setJsonData(result);
    
    return dto;
}

Retry Logic #

public async processAction(dto: ProcessDto): Promise<ProcessDto> {
    try {
        const result = await this.checkJobStatus();
        
        if (result.status === 'pending') {
            // Job still processing - retry every 30 seconds, up to 10 times
            dto.setRepeater(
                30,
                10,
                'Waiting for job to complete'
            );
            dto.setJsonData({ status: 'waiting', jobId: result.jobId });
            return dto;
        }
        
        if (result.status === 'completed') {
            // Success - remove repeater and continue
            dto.removeRepeater();
            dto.setJsonData(result.data);
            dto.setSuccessProcess('Job completed successfully');
            return dto;
        }
        
    } catch (error) {
        dto.setStopProcess(
            ResultCode.STOP_AND_FAILED,
            `Error checking job status: ${error.message}`
        );
        return dto;
    }
    
    return dto;
}

Common Patterns #

Pattern 1: Transform and Pass Through #

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

Pattern 2: Typed Data Handling #

interface InputData {
    customerId: string;
    action: 'fetch' | 'update';
}

interface OutputData {
    customer: CustomerDetails;
    timestamp: string;
}

public async processAction(dto: ProcessDto<InputData>): Promise<ProcessDto> {
    const input = dto.getJsonData(); // TypeScript knows this is InputData
    
    const customer = await this.fetchCustomer(input.customerId);
    
    const typedDto = dto.setNewJsonData<OutputData>({
        customer,
        timestamp: new Date().toISOString()
    });
    
    return typedDto;
}

Pattern 3: Conditional Processing #

public async processAction(dto: ProcessDto): Promise<ProcessDto> {
    const input = dto.getJsonData();
    
    if (input.skipProcessing) {
        // Skip and route elsewhere
        dto.setForceFollowers('skip-handler');
        return dto;
    }
    
    // Normal processing
    const result = await this.process(input);
    dto.setJsonData(result);
    
    return dto;
}

Next Steps #

Now that you understand ProcessDto, explore related topics:

RequestDto - Learn how to make HTTP requests
ApplicationInstall - Access user credentials
AConnector - Create connectors using ProcessDto
ResultCode - Status codes reference

ProcessDto

Overview #

When to Use #

Class Hierarchy #

Core Methods #

Data Methods #

getData() #

getJsonData() #

setData() #

setJsonData() #

setNewJsonData() #

Header Methods #

getHeaders() #

getHeader() #

setHeaders() #

addHeader() #

removeHeader() #

User and Application Methods #

getUser() #

setUser() #

getCurrentApp() #

setCurrentApp() #

Status and Flow Control Methods #

setSuccessProcess() #

setStopProcess() #

setLimitExceeded() #

Limiter Methods #

setLimiter() #

setLimiterWithGroup() #

removeLimiter() #

Repeater Methods #

setRepeater() #

removeRepeater() #

Force Followers Methods #

setForceFollowers() #

removeForceFollowers() #

Usage Examples #

Reading Input Data #

Setting Output Data #

Working with Headers #

Error Handling #

Rate Limiting #

Retry Logic #

Common Patterns #

Pattern 1: Transform and Pass Through #

Pattern 2: Typed Data Handling #

Pattern 3: Conditional Processing #

Next Steps #

See Also #