Programming with the wftk: actions

Programmer's Guide to the wftk: working with actions

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

Actions

The action functionality of wftk is really very powerful. To use it, you first build an action structure, which (like everything else in the wftk) is an XML element. The action structure encodes what is effectively a function call; an action adaptor handles the actual processing of the action. But before it's passed to the action adaptor, the action is compared to a permissions database along with the current userid. The permissions database specifies one of three permission levels for that action for that user: full permission (the action is processed immediately), no permission (the action is denied), or subject to approval. If the action is subject to approval, then the permissions database specifies a process to be started in order to get that approval.

The key is this: the action is attached to the approval process. So when the process completes successfully, the action will be processed automatically. If the process doesn't complete (i.e. it's rejected at some point) then the action is naturally not processed.

So the action functionality presents a very powerful and flexible way to control actions taken. You can easily specify and parameterize an action as an arbitrary request, then build and change permission structures as necessary as your needs change.

Action structure

The action structure is simple, so I'll just give you an example:

<action action="procadhoc" handler="wftk" process="42">
  <task ...>
</action>

The procadhoc action of the wftk action handler attaches ad-hoc workflow to the identified process. The content of an action structure is arbitrary; the action handler should do with it whatever is appropriate. Many actions will have no content:

<action action="procstart" handler="wftk" process="chair"/>

As of this writing (May 17, 2001) I've got two action handlers; the wftk handler encapsulates some of the wftk API itself, and the system handler encapsulates system calls. The system handler is very raw. Anyway, neither of them is well-documented, so that's yet another thing I need to come back to later. Please bother me about it if you would. Thanks.

Functions

int wftk_action (void * session, XML * action);

Details

wftk_action returns int

void * session,
XML * action

Not a lot needs to be said about the actual function beyond what you see above. You build an action structure using the XMLAPI, you allocate a session, and you call the function. The return code of the function is nonzero on success, and the action structure itself will be decorated with diagnostic information in the status and status.reason attributes. The status attribute will be "ok" if the action was taken with no approval necessary, "no" if no action was permitted, or "deferred" if an approval process was started. The status.reason is supplied in the permissions database and is arbitrary but a nice thing for user interfaces to display.

If the action is deferred, then the action structure is further decorated with attributes dsrep and process, which encode the actual process started.