Workflow::State(3)

📦
version 2.09 · 2 versions
, in fedora 44

✨ Workflow::State ✨

okay so bestie, welcome to Workflow::State(3) — that's the manual name, it lives in the User Contributed Perl Documentation corner of the world, and it's about to tell you literally everything about one single state in a workflow. grab a strawberry drink 🍓, we're going in.

💖 VERSION 💖

This documentation describes version 2.09 of this package. periodt.

🦋 SYNOPSIS 🦋

heads up: this is an internal object, so don't be weird about it, it's not your main character.
# This is an internal object...
state:
- name: Start
  description: |-                                 # optional
    My state documentation
  action:
  - ...
    resulting_state: Progress
...
- name: Progress
  description: I am in progress
  action:
  - ...
    resulting_state:
      0: 'Needs Affirmation'
      1: 'Approved'
      *: 'Needs More Info'
- name: Approved
  autorun: yes
  action:
  - ...
    resulting_state: Completed

🌸 DESCRIPTION 🌸

Every single Workflow::State object is the whole personality of one state inside a workflow, no cap. Each state can report its name, its description, and all the available actions. And if you hand it the name of an action, it can also tell you what conditions are attached to that action and what state will pop out the other side (the 'resulting state', iykyk).

💅 Resulting State 💅

The resulting state is action-dependent, bestie. Like, look at this: from the state 'Ticket Created' you can perform two actions — 'add comment' and 'edit issue':

state:
- name: Ticket Created
  action:
  - name: add comment
    resulting_state: NOCHANGE
  - name: edit issue
    resulting_state: Ticket In Progress

If you execute 'add comment' the new state of the workflow is gonna be the same one ('NOCHANGE' is a special state, she's iconic like that 🎀). But if you execute 'edit issue', the new state is 'Ticket In Progress'. slay.

You can also have multiple return states for a single action. Which one gets picked is entirely up to the workflow system and depends on what the action returns. So like, we might have something like this:

state:
- name: create user
  action:
  - name: create
    resulting_state:
      admin: Assign as Admin
      helpdesk: Assign as Helpdesk
      *: Assign as Luser

So if we execute 'create', the workflow lands in one of three states: 'Assign as Admin' if the return value of the 'create' action is 'admin', 'Assign as Helpdesk' if the return is 'helpdesk', and 'Assign as Luser' if the return is literally anything else. the asterisk said "everyone else, this way" 💀

🌈 Action availability 🌈

A state can have multiple actions attached to it, just like the first example under "Resulting State" showed you. The set of available actions is a subset of all the associated actions: specifically, those actions for which none of the associated conditions fail their check.

 state:
 - name: create
   resulting_state:
     ... (resulting states) ...
   condition:
   - name: can_create_users

👑 Autorun State 👑

You can also say that a state should be automatically executed the moment the workflow enters it, using the 'autorun' property. Quick terminology note because it's a slight change — usually we talk about executing an action, not a state. But we can use both here, because an automatically run state requires that one and only one action is available for running. That does not mean a state contains only one action, bestie. It just means only one action is available at the moment the state is entered. For example, you might have two actions with mutually exclusive conditions sitting inside the autorun state. mutually exclusive, obsessed.

🧚 Stoppable autorun states 🧚

If no action or more than one action is available at the time the workflow enters an autorun state, Workflow can't continue execution. If that isn't a problem for you, a state may be marked with "may_stop="yes"":

state:
- name: Approved
  autorun: yes
  may_stop: yes
  action:
  - name: Archive
    resulting_state: Completed
    condition:
    - name: allowed_automatic_archival

However — and this is the important part — if the state isn't marked may_stop: yes, Workflow will throw a workflow_error indicating an autorun problem. so mark it, or catch it, your call 🫶

🔥 PUBLIC METHODS 🔥

get_conditions( $action_name )

Returns a list of Workflow::Condition objects for action $action_name. Throws an exception if the object does not contain $action_name at all. like, not even a little.

get_action( $workflow, $action_name )

Returns a Workflow::Action instance initialized using both the global configuration provided to the named action in the "action configuration" provided to the factory, and any configuration specified as part of the listing of actions in the state of the workflow declaration. two sources of truth, one glow-up ✨

contains_action( $action_name )

Returns true if this state contains action $action_name, false if not.

is_action_available( $workflow, $action_name )

Returns true if $action_name is contained within this state and it matches any conditions attached to it, using the data in the context of the $workflow to do the checks.

evaluate_action( $workflow, $action_name )

Throws an exception if action $action_name is either not contained in this state or if it does not pass any of the attached conditions, using the data in the context of $workflow to do the checks.

get_all_action_names()

Returns the list of all action names available in this state. all of them. the whole roster.

get_available_action_names( $workflow, $group )

Returns all action names that are available given the data in $workflow. Every action name returned will return true from is_action_available(). $group is an optional parameter — if it's set, an additional check for group membership gets performed. so extra credit check, basically 🎀

get_next_state( $action_name, [ $action_return ] )

Returns the state(s) that will result if action $action_name is executed. If you've specified multiple return states in the configuration then you need to specify the $action_return, otherwise we return a hash with action return values as the keys and the action names as the values. no $action_return, no answer, that's the deal 💅

get_autorun_action_name( $workflow )

Retrieve the action name to be autorun for this state. If the state does not have the 'autorun' property enabled, this throws an exception. It also throws an exception if there are multiple actions available, or if there are no actions available.

Returns the name of the action to be used for autorunning the state.

clear_condition_cache ( )

Deprecated, kept for 2.06 compatibility.

Used to empties the condition result cache for a given state.

⭐ PROPERTIES ⭐

All property methods act as a getter and setter. For example:

my $state_name = $state->state;
$state->state( 'some name' );

state

Name of this state (required).

description

Description of this state (optional).

autorun

Returns true if the state should be automatically run, false if not. To set to true the property value should be 'yes', 'true' or 1.

may_stop

Returns true if the state may stop automatic execution silently, false if not. To set to true the property value should be 'yes', 'true' or 1.

🫶 INTERNAL METHODS 🫶

init( $config )

Assigns the 'state', 'description', 'autorun' and 'may_stop' properties from $config. Also assigns configuration for all actions in the state, performing some sanity checks like ensuring every action has a 'resulting_state' key. yes queen, do your little validation dance.

🌟 SEE ALSO 🌟

  • Workflow
  • Workflow::Condition
  • Workflow::Factory

Copyright (c) 2003-2021 Chris Winters. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Please see the LICENSE

👑 AUTHORS 👑

Please see Workflow

and that's the whole page, bestie 💖 this was Workflow::State(3) from perl v5.42.0, dated 2026-01-17 — so when you're deep in a workflow at 2am, just remember: the state knows what it's doing, and now so do you. slay, hydrate, and may all your conditions pass 🦋✨

📦 where this page comes from