LedgerSMB uses the concept of workflows to manage the document life cycle. An invoice for example may be saved, posted or reversed. These are states in the life cycle of the invoice. Each state may have associated actions. In case of the invoice an example may be to Post it when it’s saved or to E-mail it when it’s posted.
Actions associated with a state may be available or not determined by one or more conditions. Examples are “is the posting date of the transaction in a closed period” and “is the current user allowed to post transactions”.
Workflows are stored in the ./workflows/ directory. Each workflow consists of several files, prefixed with the name of the workflow (e.g. ar-ap.):
(optional) names the list of available transitions in the workflow naming Perl code to be executed
(optional) names the list of conditions to be used in the workflow naming Perl code to evaluate
(optional) defines the Perl mechanism to load and store workflow instances
(required) defines the life cycle (states, actions and conditions) with the allowed transitions per state (actions).
Customized versions of workflow definition files must be stored in ./customized_workflows/11 1 See Section 17.4.1 on page 17.4.1 on how to configure these paths. Files stored in this location will be used to override the ones in the standard location ./workflows/: the file ./custom_workflows/ar-ap.workflow.xml will replace the built-in workflow from ./workflows/ar-ap.workflow.xml used for invoices and AR/AP transactions. No changes should be made directly to the standard files because of the risk that those files will be overwritten on upgrade – loosing the changes.
Next to the per-workflow files, there is a generic definition file for actions, conditions and persisters. Elements defined in these files can be used in all workflows; those elements defined in the per-workflow files can only be used in the specific workflow.
The engine driving workflow state management is the Workflow22 2 https://metacpan.org/pod/Workflow library. See its documentation on MetaCPAN as well as the built-in workflows as examples of how to define one’s own.
Particularly interesting is the concept of observers: this functionality allows the application to be extended based a specific action occurring without changing the life cycle. An example could be to create a PayPal payment request when an invoice is posted: an observer could be “listening” to “AR/AP” workflow events which at some point will flag the state of the invoice becoming posted.
The actions in the workflows order-quote, ar-ap and gl are hard coded33 3 This is not a permanent situation, but rather a consequence of these workflows being used in old code . This means that the list of actions is restricted to those defined in the files order-quote.actions.xml, ar-ap.actions.xml and gl.actions.xml. It’s not necessary to use all actions in the workflow, but additional ones cannot be created – contrary to what is in the Workflow documentation.
The class attribute for most actions in these workflows is set to the value LedgerSMB::Workflow::Action::Null. This means it does nothing. Rather, it doesn’t do anything in addition to what the action already does in its hard coded implementation. Setting the action’s class attribute to some other value allows the developer to add behavior on top of what’s hard coded.