5.6. Specifying Workflows

To specify a workflow state, use the following syntax:

[stateName]
label                                                                 = "stateLabel"
transitions.targetStateName.label                                     = "transitionLabel"
transitions.targetStateName.conditions[]                              = "conditionClass"
transitions.targetStateName.conditions.conditionId.condition          = "conditionClass"
transitions.targetStateName.conditions.conditionId.conditionOption    = "optionValue"
transitions.targetStateName.conditions.conditionClass.conditionOption = "optionValue"
transitions.targetStateName.actions[]                                 = "actionClass"
transitions.targetStateName.actions.actionId.action                   = "actionClass"
transitions.targetStateName.actions.actionId.actionOption             = "optionValue"
...

The stateName is required. Each state can specify zero or more transitions with zero or more conditions, and zero or more actions.

stateName: An identifier for the state that must be unique among the states in this workflow. Valid characters include letters and numbers.
targetStateName: The identifier for the target state, the destination of the transition.
label: A friendlier name for the state (example: "Draft").
transitionLabel: A friendlier name for the transition, which may include the target transition's name (example: "Demote to Draft").
conditionClass: The class name of the condition to be evaluated for this transition. (example: "False").
conditionId: An identifier for the condition that must be unique among the conditions for this state. This identifier is used when a specific condition class needs be used more than once per transition. Valid characters include letters and numbers.
conditionOption: The name of an option to be used during the condition's evaluation.
actionClass: The class name of the action to be invoked for this transition. (example: "SendEmail").
actionID: An identifier for the action that must be unique among the actions for this state. This identifier is used when a specific action class needs to be used more than once per transition. Valid characters include letters and numbers.
actionOption: The name of an option to be used during the action's invocation.
optionValue: The value of an option provided to a condition or action.

For example, the following is a specification of an example workflow:

[draft]
label                                   = "Draft"
transitions.review.label                = "Promote to Review"
transitions.review.actions.email.action = "SendEmail"
transitions.review.actions.email.toRole = "reviewers"
transitions.published.label             = "Publish"

[review]
label                                   = "Review"
transitions.draft.label                 = "Demote to Draft"
transitions.published.label             = "Publish"
transitions.published.conditions[]      = "False"

[published]
label                                   = "Published"
transitions.review.label                = "Demote to Review"
transitions.draft.label                 = "Demote to Draft"

	Dead End States
	If a state has no defined transitions, then it is considered to be a dead end. If a content entry enters this workflow state, it is not possible to transition it to another state until the workflow is modified to include a valid transition. This could affect your ability to publish content, or take published content through your workflow for further editing.

	Condition and Action Class Short Names
	Conditions and actions are typically expressed by their short name, such as False or SendEmail respectively. This may lead to a name conflict if multiple modules provide conditions with the same short name. In this case, the most recently loaded module's definition (which can vary) is used during workflow processing.

5.6.1. Provided Conditions

You can use the following condition classes to control transitions:

Table 5.1. Conditions

Condition Class	Description, Example, Options
Contains	Checks whether the content entry contains the specified text in at least one element. The available options are: fields Specify which content elements to include in the search (by default, all elements are searched). All non-text elements are automatically excluded. string Specify a search string for a literal match (case insensitive). pattern Specify a Perl-compatible regular expression for a pattern expression match. The following example specifies that the string "example" must be exist in the title or body elements: transitions.example.conditions.Contains.fields = "title" transitions.example.conditions.Contains.fields = "body" transitions.example.conditions.Contains.string = "example"
False	A condition that always returns false. This is useful if you need to disable a transition for a period of time. Simple remove the condition or replace it with another condition that can succeed to re-enable transitions. transitions.example.conditions[] = "False"

Condition Class

Description, Example, Options

Contains

Checks whether the content entry contains the specified text in at least one element. The available options are:

fields: Specify which content elements to include in the search (by default, all elements are searched). All non-text elements are automatically excluded.
string: Specify a search string for a literal match (case insensitive).
pattern: Specify a Perl-compatible regular expression for a pattern expression match.

The following example specifies that the string "example" must be exist in the title or body elements:

transitions.example.conditions.Contains.fields = "title"
transitions.example.conditions.Contains.fields = "body"
transitions.example.conditions.Contains.string = "example"

False

A condition that always returns false. This is useful if you need to disable a transition for a period of time. Simple remove the condition or replace it with another condition that can succeed to re-enable transitions.

transitions.example.conditions[] = "False"

	Negative Conditions
Any condition may be negated by providing the negate option. For example: transitions.example.conditions.Contains.string = "dangerous" transitions.example.conditions.Contains.negate = true

Negative Conditions

Any condition may be negated by providing the negate option. For example:

transitions.example.conditions.Contains.string = "dangerous"
transitions.example.conditions.Contains.negate = true

5.6.2. Provided Actions

You can use the following action classes to invoke during transitions:

Table 5.2. Actions

Action Class Description, Example, Options

SendEmail

Sends an email message regarding the transition. The available options are:

to: A list of site usernames and/or email addresses. Can be a comma-separated string, or one entry per line.
toRole: A list of roles that is expanded to a list of email addresses of the member users. Can be a comma-separated string, or one entry per line.
subject: The subject for the email message. A default subject is generated if one is not provided.
template: The name of a view script template that is rendered into the HTML body of the email. If not specified, the template send-email-template.phtml provided by the Workflow module is used.
message: A string that gets prepended to the email message body.

The following example would cause an email message having the subject "Subject" and beginning with "Check it out." followed by the body rendered from the template custom-email-template.phtml, would be sent to the users, administrator, editor, and to the email address reviewer@another.site, as well as any users within the reviewers, editors, and members roles.

transitions.example.actions.SendEmail.to[]     = "administrator"
transitions.example.actions.SendEmail.to[]     = "editor, reviewer@another.site"
transitions.example.actions.SendEmail.toRole[] = "reviewers"
transitions.example.actions.SendEmail.toRole[] = "editors, members"
transitions.example.actions.SendEmail.subject  = "Subject"
transitions.example.actions.SendEmail.template = "custom-email-template.phtml"
transitions.example.actions.SendEmail.message  = "Check it out."

	Sending E-Mail
	In order to send email messages with this action, one or both of to or toRole must be specified. Also, sendmail or a compatible sendmail wrapper must be installed on the server.

	Where to Place the Email Template
	The email template can be placed in a few places: in the current theme's `views` folder. Be aware that if a different theme is subsequently used, your template will not be found and the default Workflow template is used instead. Copy/move your template to the now-current theme's `views` folder to re-instate it. in the Workflow module's `views/scripts` folder.