History: Transition Handler

            Transitions are used to create workflow like behaviors inside Tiki. Group and category transitions. While they behave on different object types, they use the exact same logic.

((doc:Category transitions)) require the ((doc:Module category_transition)) to be used. On any object inside Tiki supporting the standard category variables, the module will generate a form with the available transitions. Each category is considered to be a state.

((doc:Group transitions)) are used through ((doc:Plugin memberlist)), which displays the selected set of groups and the controls that apply to them.

Transitions are defined as a link between two states. They can optionally preserve the previous state during the transition and specify guards on other states.

! Example
The following example creates a simple ((doc:document workflow)) for documents that require approval. The three main states are In Progress, In Review and Approved. The guards on the approval transition prevent the transition from being triggered unless the document was approved by both QA and Development. These two additional approvals can be granted by triggering transitions that preserve the review state.

When the guards are not met, the causes are detailed in the category transition module.

The example is incomplete because it does not specify the permissions. Using the object type ''transition'', ''tiki_p_trigger_transition'' can be granted on transitions. Additionally, permissions can be assigned to the categories to prevent anyone from changing them directly and enforce the workflow.

{CODE(caption=>YAML)}
preferences:
 feature_category_transition: y
 feature_categories: y
objects:
 -
  type: module
  data:
   name: category_transition
   position: right
   order: 1
 -
  type: category
  ref: progress
  data:
   name: In Progress
   items:
    - [ wiki page, HomePage ]
 -
  type: category
  ref: pending
  data:
   name: Pending Approval
 -
  type: category
  ref: approved_by_dev
  data:
   name: Approved by DEV
 -
  type: category
  ref: approved_by_qa
  data:
   name: Approved by QA
 -
  type: category
  ref: approved
  data:
   name: Approved
 -
  type: transition
  data:
   name: Request Review
   type: category
   from: $progress
   to: $pending
 -
  type: transition
  data:
   name: Approve
   type: category
   from: $pending
   to: $approved
   guards:
    - [ exactly, 2, [ $approved_by_dev, $approved_by_qa ] ]
 -
  type: transition
  data:
   name: Reject
   type: category
   from: $pending
   to: $progress
 -
  type: transition
  data:
   name: OK Dev
   type: category
   from: $pending
   to: $approved_by_dev
   preserve: y
 -
  type: transition
  data:
   name: OK QA
   type: category
   from: $pending
   to: $approved_by_qa
   preserve: y
{CODE}

!! Transition Object
||__Field Name__|__Mandatory__|__Value__
name |yes | Name of the transition as it will be displayed
type |yes | category or group
from |yes | Point of origin. Either a group name or a category id.
to | yes | Destination. Same format as from.
preserve | | y or n, if the origin state of the transition should be kept
guards | | List of guards, specifying the guard type (exactly, atLeast, atMost), the amount of states required and the list of participating states.
||