Task processor class [VF 21.3 AgSDK]
In case your business logic does not trigger message boundary events you use the ITaskProcessor<> interface. The class that implements this interface - called task processor class - must have a defined name
Task processor class name |
public class <task name>Processor : ITaskProcessor<…> |
and it must be attributed with the TaskContract attribute to define a display name, a description, a unique GUID (see special remarks in the section TaskContract) and a version.
Note that the <task name> of the class and the version property of the TaskContract attribute must align with the class' namespace (see section C# namespace).
Logging
It is highly recommended that you write log messages in your task processor to allow error analysis. For this the Agent SDK provides a dedicated interface (see section ILogger<>).
Assuming that the task processor class is called DoSomethingTaskProcessor you could add something like
Allow logging in task processor |
private readonly ILogger<DoSomethingTaskProcessor> _logger; |
to your class definition. This ensures that all log messages you write via the _logger field will be processed by VidiFlow's logging stack and finally be shown in Kibana.
Task progress
The Agent SDK also allows to publish a task progress that can be displayed in the VidiFlow Monitor. This is especially useful for long running tasks but in fact recommended for all tasks.
The task progress is indicated as a floating point value between 0 (processing not started yet) and 1 (processing completed independent if it was successful or not).
Depending on the type of the task there are two different implementations available in the Agent SDK (see sections IEventPublisher or IEventPublisher<>).
Note that the task processor is responsible for sending all task progress updates even for the start of the task (progress = 0) and the end (progress = 1).
Exception handling
There are three different ways to handle exceptional situations in the task processor
- Complete the task normally
- Throw a C# exception
- Raise an interrupting message boundary event
All methods lead to a different signaling for the BPMN workflow.
Catching an exception in the Process(…) method of the task processor will lead to a normal (successful) task completion in the BPMN workflow. Throwing a C# exception in the Process(…) method of the task processor will send an intermediate error boundary event to the workflow engine while raising an interrupting message boundary event will send the dedicated intermediate boundary event to the workflow.
Recommendation |
To allow proper signaling for the BPMN workflow make sure that the Process(…) method of the task processor does not catch any exception that indicates an exceptional situation of the task processor. A normal completion of the Process(…) method will always be treated as a successful task completion. See also the following paragraph and section Task processor class for message boundary events. |
Task cancelation
In case the cancelation token indicates that the task processing shall be canceled, you should throw a System.Threading.Tasks.TaskCanceledException.
Catching exceptions in task processor |
Note that in order to actually cancel task processing in case of an activated cancelation token, the Process(…) method of the task processor must not catch the generic C# Exception class, or, if it does, must have a dedicated catch handler for the TaskCanceledException and re-throw this exception. |