Workflow Triggers

From KnowledgeTree Community

Workflow triggers are a new component in version 3.1. They make it possible to prevent workflow transitions when necessary or to perform actions when a transition is followed. A few ideas for workflow triggers are:

• a "review" guard trigger, which prevents the document from following a transition until a sufficient number of users have "signed off" on it.
• a website syncronisation trigger, which adds or updates a document in a different system when a "publish" step is taken

There are lots of other ways that triggers can be used, many of which will be related to integrating KT with other systems.

Contents 1 Basic Design of Workflow Triggers 2 Major API points 2.1 allowTransition 2.2 precheckTransition 2.3 performTransition 2.4 displayConfiguration 2.5 saveConfiguration 2.6 getConfigDescription 3 Putting it all together

Basic Design of Workflow Triggers

Good code examples for workflow triggers can be found in the KTCore module, in /plugins/ktcore/KTWorkflowTriggers.inc.php. The basic idea behind workflow triggers is that any given trigger has two parts:

1. a class that handles all the logic of the trigger (performing the action, indicating whether the transition can be performed). This is the component that you need to develop.
2. a KTEntity that handles configuration storage for the trigger.

To create a workflow trigger, you would subclass the KTWorkflowTrigger class (/lib/workflow/workflowtrigger.inc.php) and override the functions you need to. As described below in "Major API points" each plugin has a "config" array which is persisted in the database. This can be used to store any details required by an instance of the trigger.

Major API points

• variables: these are typically set at the start of the subclass definition.
  • var $sNamespace = 'ktcore.workflowtriggers.abstractbase'; // the namespace entry - unique across all plugins and triggers.
  • var $sFriendlyName; // set in the constructor for your subclass. Used in lists of triggers for adding.
  • var $sDescription; // a short description.
  • var $aConfig = array(); // set by the workflow machinery on each trigger, allows you to get access to configuration.
  • var $bIsGuard = false; // is this a guard trigger? mostly only a UI consideration.
  • var $bIsAction = false; // is this an action trigger? mostly only a UI consideration.
  • var $bIsConfigurable = true; // is there any configuration associated?
• functions to override
  • function allowTransition($oDocument, $oUser)
  • function precheckTransition($oDocument, $oUser)
  • function performTransition($oDocument, $oUser)
  • function displayConfiguration($args)
  • function saveConfiguration()
  • function getConfigDescription()

allowTransition

This function should return either true or false, based on whether the user should be allowed to perform the transition.

precheckTransition

This function is called to establish whether or not the transition will be successful. It should return a raiseError if the transition will fail. This exists in order to prevent situations where most of the triggers succeed, but one fails because (for example) it can't connect to an external system.

performTransition

Should return either true or a raiseError. This code should perform a $oDocument->update() if it makes changes to the active document.

displayConfiguration

Called to display a page where the user can set whatever configuration is required. $args is an array of "name" => "value" pairs which should be added as hidden input variables in the form on the page - this ensures that the correct trigger instance is updated when the actual submit occurs.

saveConfiguration

Each trigger will have an "oTriggerInstance" property, that can be access from the trigger via $this->oTriggerInstance. This should be given the config array for the trigger, and then updated. From the permissions guard:

       $config = array();
       $config['perms'] = $aFinalPerms;
       
       $this->oTriggerInstance->setConfig($config);
       $res = $this->oTriggerInstance->update();
       
       return $res

If a raiseError is returned (e.g. from $res = $this->oTriggerInstance->update();) then the system will not commit the transaction, and display the error's message in a notification flash.

getConfigDescription

Return a short string explaining what the configuration of this trigger is. By convention this would also clearly indicate what occurs if no configuration is set (e.g. the permissions guard says "no permissions are required to perform this transition").

Putting it all together

Once you've coded a new workflow trigger, you can add it in your plugin code's setup method. An example of this is:

function setup() {
       // workflow triggers
       $this->registerWorkflowTrigger('ktcore.workflowtriggers.permissionguard', 'PermissionGuardTrigger', 'KTWorkflowTriggers.inc.php');
       $this->registerWorkflowTrigger('ktcore.workflowtriggers.roleguard', 'RoleGuardTrigger', 'KTWorkflowTriggers.inc.php');
       $this->registerWorkflowTrigger('ktcore.workflowtriggers.groupguard', 'GroupGuardTrigger', 'KTWorkflowTriggers.inc.php');        
       $this->registerWorkflowTrigger('ktcore.workflowtriggers.conditionguard', 'ConditionGuardTrigger', 'KTWorkflowTriggers.inc.php');        
       
       $this->registerWorkflowTrigger('ktcore.workflowtriggers.copyaction', 'CopyActionTrigger', 'KTWorkflowTriggers.inc.php');        
}

Where the signature for $oPlugin->registerWorkflowTrigger is:

   function registerWorkflowTrigger($sNamespace, $sTriggerClassName, $sFilename = null)