Programming with the wftk: tasks

Programmer's Guide to the wftk: working with tasks

[ wftk documentation home ] [ wftk programmer's guide home ]

Tasks

Tasks are the individual things which users do. A task involves the collection of data, but from the point of view of the workflow engine, a task is simply a place where we stop and wait for a human being. When we do so, we also activate the task in all listening task indices -- meaning that a record is written to a database that the user can then query.

For the convenience of wftk clients, wftk provides a list function to retrieve tasks in various modes; if the list is simply of tasks in a process, then the datasheet is consulted, but if the request is for tasks across processes which meet criteria, then wftk builds a query and goes to the database to get the information.

The internal representation of a task is (of course) an XML structure; the retrieval of a task is thus a little strange. First you have to build a task structure, then you ask wftk to fill it in for you. This makes sense after you use it a couple of times. Really.

Functions

int    wftk_task_list      (void * session, XML * list);
int    wftk_task_new       (void * session, XML * task);
XML  * wftk_task_retrieve  (void * session, XML * task);
int    wftk_task_update    (void * session, XML * task);
int    wftk_task_complete  (void * session, XML * task);
int    wftk_task_reject    (void * session, XML * task);
int    wftk_task_rescind   (void * session, XML * task);

Details

wftk_task_list returns int

void * session,
XML * list

Returns a specified list of tasks. The way this works is simple. You first use xml_create to create a list object:

xml_create ("list");

Then you fill in the attributes you know. For instance, if you want tasks pertaining to a certain process, you fill in the datasheet respository and ID of the process. A full account of what you can specify will have to wait for my next round of documentation; until then, see the code for the command-line interface.

At any rate, once you've called the function, the results are returned in the same structure, as subelements of type "task".

wftk_task_new returns int

void * session,
XML * task

Adds a new task to the system. If the dsrep and datasheet are filled in, the new task will be attached to that process. Otherwise, it will be a really ad-hoc to-do list entry and will appear only in the task index (database).

wftk_task_retrieve returns XML *

void * session,
XML * task

Retrieves a task definition. Like wftk_task_list, this function requires you to fill in an element and submit it. The library then fills in the details, including data required or referenced by the task.

wftk_task_update returns int

void * session,
XML * task

Writes a modified task back to the repositories, including all data values it contains.

wftk_task_complete returns int

void * session,
XML * task

Marks the given task as complete. Data values are written to the datasheet. Once the task is complete, the task is unblocked and the workflow interpreter invoked. As a result of this, any action may also occur.

wftk_task_reject returns int

void * session,
XML * task

Marks the given task as rejected.

wftk_task_rescind returns int

void * session,
XML * task

Rescinds the given task. This only works for ad-hoc tasks; you can't rescind tasks which were specified from workflow, even from arbitrary workflow, because there would be no way for the wftk to know what should come next. The best you can do is to reject workflow-specified tasks. Returns 0 if there's a problem.