Result Agent

import { ResultAgent } from "@fstnetwork/loc-logic-sdk";

Finalise a JSON object as the task result data. If the trigger is synchronized API route or message queue, it will be returned to the trigger, otherwise stored in LOC to be retrieved later.

Task results woulbe be embedded in an execution result from a trigger unless the trigger's encapsulation is turned off. Be noted that manual trigger also only returns task results.

Availability

• ✗ Generic logic
• ✓ Aggregator logic

Finalise Result

ResultAgent.finalize(value: object)

value has to be a JSON object (a JavaScript object without methods).

tip

The result agent can be used in both run and handleError functions and does not need await.

See Tips on Error Handling for how to utilise result agent for error handling.

Example

ResultAgent.finalize({
    status: "ok",
    taskId: ctx.task.taskKey,
    data: {
        name: "Arthur Dent",
        age: 42,
    },
});

Be noted that status: "ok" is not the HTTP response code, but an user-defined field that indicates the task has been executed without issues.

The finalised data (task result) will be

{
    "status": "ok",
    "taskId": {
        "executionId": "...",
        "id": "..."
    },
    "data": {
        "name": "Arthur Dent",
        "age": 42
    }
}

Seperate multiple task results in the same execution

If you are planning to execute multiple data processes from the same trigger, be adviced not to use shared task result field names (for example, status and data), for the result of one data process would be overwritten by another.

You can wrap results with different topmost keys:

aggregator 1

ResultAgent.finalize({
    result_data_process_a: {
        status: "ok",
        taskId: ctx.task.taskKey,
        data: {
            name: "Arthur Dent",
            age: 42,
        },
    },
});

aggregator 2

ResultAgent.finalize({
    result_data_process_b: {
        status: "ok",
        taskId: ctx.task.taskKey,
        data: {
            name: "Ford Perfect",
            age: 200,
        },
    },
});

The returned task results in the execution result would thus be

{
    "result_data_process_a": {
        "status": "ok",
        "taskId": {
            "executionId": "...",
            "id": "..."
        },
        "data": {
            "name": "Arthur Dent",
            "age": 42
        }
    },
    "result_data_process_b": {
        "status": "ok",
        "taskId": {
            "executionId": "...",
            "id": "..."
        },
        "data": {
            "name": "Ford Perfect",
            "age": 200
        }
    }
}

Specify HTTP Status Code

It is possible to set the HTTP status code for the task result. If the data process is invoked by an API route trigger, the HTTP code will be applied in the HTTP response.

ResultAgent.httpStatusCode(statusCode: number)

If httpStatusCode() is not called, by default the task result's HTTP code will be 200 (or 202 if the execution has timed out, 405 if HTTP method is incorrect for the API route, and 400 if API route does not exist).

tip

Combining with setting an API route's encapsulation to false (do not include execution metadata), you can create a true RESTful response for the data process.

Example

ResultAgent.finalize({
    status: "ok",
    taskId: ctx.task.taskKey,
    data: {
        name: "Arthur Dent",
        age: 42,
    },
});

ResultAgent.httpStatusCode(200);

Since both finalize() and httpStatusCode() returns the ResultAgent itself, you can chain them like this:

ResultAgent.finalize({
    // task result
}).httpStatusCode(200);

or

ResultAgent.httpStatusCode(200).finalize({
    // task result
});

info

HTTP Status Code Priority

If a task contains multiple data processes, the HTTP code with the highest priority (the largest number) will be chosen for the final execution response (with all task results aggregated):

HTTP Code	Priority
5xx	Highest
4xx
3xx
2xx	Lowest

For example, if data process A returns 200 and data process B returns 400, the execution result would choose 400.

If one returns 503 and another returns 500, then 503 would be chosen.