45.2 Workflow configuration

LedgerSMB uses the concept of workflows to manage object 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. E.g. in case of the invoice there may be a Post action when it’s saved or to E-mail it when it’s posted. Actions may cause the document to change state: if the Post action is executed on a saved invoice, its new state will be posted. E-mailing an invoice does not change its state: it remains posted. Instead, a new workflow is created which manages state of the e-mail.

Actions belonging to a state may (or may not) be available. This is 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”. When the condition evaluates to false, the action is not available.

Workflows are configurable. Configurations list the following aspects:

1. 1.

   A list of states

2. 2.

   A list of allowable actions per state

3. 3.

   A list of conditions per action

4. 4.

   A mapping of actions to Perl code

5. 5.

   A mapping of conditions to Perl code

With these ingredients, the software’s behavior can be changed. E.g. by adding a new state and action in the invoice, an extra reviewing pairs of eyes can be added to the posting process. By adding a condition on this action, it can be made required for invoices over 100.000 USD (but not for other invoices).

By changing association of the save action with its code, the application will act differently when saving the invoice. Customizations may associate new behaviors with existing actions or create new ones entirely. The behavior does not need to be known by the application developers, as the association may point to code added to the local installation. This way, a remind action can be added to posted invoices, triggering a text (SMS) message to the customer.

Workflows are stored in the ./workflows/ directory. Each workflow consists of several files, prefixed with the name of the workflow (e.g. ar-ap. for ’AR/AP’ workflows):

ar-ap.actions.xml

(optional) names the list of available transitions in the workflow naming Perl code to be executed

ar-ap.conditions.xml

(optional) names the list of conditions to be used in the workflow naming Perl code to evaluate

ar-ap.persisters.xml

(optional) defines the Perl mechanism to load and store workflow instances

ar-ap.workflow.xml

(required) defines the life cycle by combining states with the actions and conditions listed in the respective configuration files. Each state lists the allowable actions with the conditions to enable the action and a resulting state.

Customized versions of workflow definition files must be stored in ./customized_workflows/¹¹ 1 See Section 17.4.1 on page 17.4.1 on how to configure these paths. Files stored in this directory will be used to override those in the standard location: 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 Workflow²² 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.