docs(components/tool/taskManager): Add execution methods table and ex… #596
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
ToolTaskManager
How can TaskManager help me?
This component provides a set of tools and methods to register and run async tasks. It is specially useful in situations where heavy tasks need to be executed, or when a task is composed by many differentiated steps or actions that could depend between them.
TaskManager not only offers an API to run these kind of jobs, but also provides a system and a user interface to manage them. TaskManager can take care of making some specific actions when a task is completed, cancelled, or when an error occurs. It can also take care of retrying a specific job a number of times, or log errors to a third-party logging system.
Additionally, as each task needs to match the shape expected by the TaskManager API's, the usage of TaskManager enforces having a more structured task definition, which at the end contributes to a more readable and maintainable application.
Main entities
TaskManager mainly works with two entities, which are the followings:
Task
A task is an undivisible set of actions which represent a transaction. The sum of the successful execution of these actions, which can depend between them, leads to a fully completed transaction.
Within the whole TaskManager system, these actions that compose a task are called
work
.Therefore, a
task
can be considered just a group ofwork
items that will only be completed, once all of itswork
is sucessfully executed. If one singlework
from a task fails or is cancelled, the transaction is not fully completed, so thetask
execution is not considered sucessful.Alongisde with this set of
work
items, some metadata is defined, like a name, a unique identifier, among others.Work
As it is previoustly mentioned, a
work
is a specific action which belongs to atask
.For example, updating an ad from a digital marketplace could be a kind of transaction: It is composed by many operations that need to be successfully executed in order to consider that the ad has been properly updated.
In this example, the
task
would be updating a specific ad, and its work items may be hipothetically composed by:As stated before, this example meets two main conditions:
task
(updating an ad) is successfully executed once all thesework
items are finished. If some of them fails or is cancelled, the wholetask
unit cannot be considered as finshed, as the ad would not be completelly updated.work
items, as maybe it is not possible to upload new photos until the old ones are removed. Therefore, we can describe thework
number three as dependant on thework
number two. It cannot be executed until the previous one finishes with success.Basic usage
Installation
Render the component
The TaskManager component requires two main elements to be rendered in order to work:
Note that the ToolTaskManager component can be rendered in a hidden mode. This is intended to allow using the TaskManager system in webapps where a task managing UI is not required. This way, TaskManager system can be required and used in a "silent" mode that won't be perceived by the end-user and won't have impact on the interface.
Import the styles (Sass)
Working with the API
The first requirement to have access to the TaskManager API is to get the context available data:
Then, inside the component's render function, the context value can be accessed:
Each of these methods allows to perform a specific interaction with the system, let's see them on detail.
Available methods
taskId: string, workId: string
taskId: string, workId: string, log: string
{ name: string, work: Work[] }
{ name: string, onComplete: function, onError: function, start: function }
taskId: string, workId: string, percentage: number
taskId: string, workId: string
runTask
Runs a complex
task
composed by one or morework
.Each
work
needs to have at least an entry point defined. The entry point must be a callbackfunction
contained within thestart
property.Please note how in the previous example, the
start
function represents the entry point of the work. It receives the wholework
object so it can be later referenced when invoking thefinishWork
method in case thework
successfully completes, or thesetPercentage
method to reportwork
execution progress.Once the work successfully finishes, the task will be automatically marked as finished too. In case of having more than one work (it could be done just by adding another element into the array), the system will then execute the next runnable
work
from the queue.Additionally, note that it is possible to invoke different methods inside the
start
entry point. For example, if an error occurs, the start method should report it by invoking theerrorWork
method in a way similar to this:errorWork(work.taskId, work.id, 'Include here any available log information. Leave it undefined to include no-logs.')
runSimpleTask
Some tasks may not have multiple works. In fact, when migrating an already existing system to the TaskManager, we could have a lot of simple tasks composed just by one
work
.In these cases, the ideal approach is to add new simple tasks by using the
runSimpleTask
method, which will create a simpletask
with one singlework
, and as little props as possible.If you do not need to include some specific callback (i.e.
onComplete
orinError
, just leave it undefined. The only mandatory callback is thestart
function, as it acts as thework
entry point)