How to Handle a Background Task

Handling the Task Run

When you define the task, you need to provide the run method, as it is the method getting executed when the task is being executed. The run method receives an object parameter with the following variables, defined in the interface ITaskRunParams :

• context
• input
• response
• isCloseToTimeout()
• isAborted()
• store

ThecontextObject

Via the context object, you can access whole Webiny system. The base interface of the context object is Context, but you can pass your own, which must extend the base interface.

You can pass your own Ge interface/type of the context variable when defining the task:

TheinputObject

The input object is the input which was sent to the task when it was triggered.

By default, it is of plain object type Record<string, any>, but you can pass your own type/interface when defining the task:

TheresponseObject

The response object handles the output from the task run. Available methods are:

• done
• continue
• error
• aborted

ThedoneMethod

This method signalizes that the task has finished its job and that the Step Function will finish as well. It also signalizes that task status should be set to success. Optional message will be stored as well.

ThecontinueMethod

This method signalizes that the task has not finished its job and that the Step Function should continue running the Lambda handler.

Note that the continue method MUST receive some data, which is of same type as the input variable, as the first parameter.

Why? Because the data you send into continue is the data you will receive on the next iteration of the task run as the input variable.

The continue method accepts a second, optional, parameter via which you can set waiting time for the next task run. You can either send a seconds property, which takes a number, or a date property, which takes a Date object.

TheerrorMethod

This method signalizes that the task has finished its job with an error and that the Step Function will finish as well, in an error state. It also signalizes that task status should be set to error.

TheabortMethod

This method signalizes that the task was aborted by the user. Note that this is not an error, but a user triggered abort.

When you write your code, you must check if the task was aborted via the isAborted() method, and if it was, you must return the abort response. This is meant to be used while the task has some code which loops continuously, like reading a lot of records from the database, with paginating through the records.

TheisCloseToTimeoutMethod

The isCloseToTimeout method is a method which returns a boolean value, which tells you if the Lambda instance is close to the timeout. This is useful when you have a lot of code to run, or you have some idea that the code will take some time to execute, and you want to check if you have enough time to finish the code execution.

The isCloseToTimeout method accepts an optional parameter, which is a number of seconds under which will this method return true. The default is 180 seconds.

TheisAbortedMethod

The isAborted method is a method which returns a boolean value, which tells you if the task was aborted by the user.

ThestoreObject

The store object is of ITaskManagerStore interface type, which is defined here.

It is used for storing and retrieving data from the task run, including task logs.

Available methods on the object are:

• getTask
• getStatus
• updateTask
• updateInput
• getInput
• addInfoLog
• addErrorLog

Logging

Using the addInfoLog and addErrorLog methods, you can store some important log into the database.

Because the Background Task Lambda handler can be executed multiple times, depending on the developer response, the logging has been implemented on per iteration base.

It means that each of the execution iteration gets its own record, which contain individual logs from that execution iteration.