Workflow::History(3)

💖 Workflow::History 💖

okay bestie, welcome to Workflow::History — the little object that keeps the receipts for everything your workflow does. Recorded work on a workflow action or workflow itself, no cap. 📝✨

This is part of the Workflow Perl docs, so if you're reading this in man, hi, you're doing great. 🫶

---

🌈 VERSION 🌈

This documentation describes version 2.09 of this package. Yes, that's the whole version section. She's brief but she's iconic. 💅

---

✨ SYNOPSIS ✨

here's the vibe, in your action:

# in your action
sub execute {
    my ( $self, $wf ) = @_;
    my $current_user = $wf->context->param( 'current_user' );
    # ... do your work with $ticket
    $wf->add_history(
        {
           action => 'create ticket',
           user   => $current_user->full_name,
           description => "Ticket $ticket->{subject} successfully created"
        });
}

# in your view (using TT2)
[% FOREACH history = workflow.get_history %]
   On:     [% OI.format_date( history.date, '%Y-%m-%d %H:%M' ) %]<br>
   Action: [% history.action %] (ID: [% history.id %])<br>
   by:     [% history.user %]<br>
   [% history.description %]
[% END %]

like, you drop a history entry in your action, and then your view (TT2 gang rise up 🌸) just loops over workflow.get_history and prints the date, the action, the ID, the user, and the description. that's the whole loop. cute, right? 🎀

---

💜 DESCRIPTION 💜

so every workflow can record its history. more appropriately — and this is the fun part — every action the workflow executes can deposit history entries into the workflow to be saved later. 🧚

and here's the lowkey genius bit: neither the action nor the workflow knows about how the history is saved. they just know that the history is available. separation of concerns said slay. 👑

---

🔥 METHODS 🔥

🌟 Public Methods 🌟

• new( \%params ) — creates a shiny new history object, filling it with properties from \%params. new object, who dis 💅
• set_new_state( $new_state ) — assigns the new state $new_state to the history, but only if the state isn't already assigned. so why does this exist? bestie, it's because of ✨timing✨. you generate a history request inside a Workflow::Action, but the workflow state is gonna change once the action has successfully completed. so in the action you create history without the state:

$wf->add_history(
    {
        action      => "Cocoa Puffs",
        description => "They're magically delicious",
        user        => "Count Chocula",
    }
);

and then, after the new state has been set but before the history objects are stored, the workflow sets the new state in all the unsaved history objects. teamwork, fr fr 🫶

• is_saved() — returns true (1) if this history object has been saved, false (0) if not. simple. honest. we respect her. 💖

🦋 Properties 🦋

• id — ID of history entry
• workflow_id — ID of workflow to which history is attached
• action — Brief description of action taken
• description — Lengthy description of action taken
• date — Date history noted, set to a DateTime object.
• time_zone — Time zone to pass to the DateTime object.
• user — User name (ID, login, or full name, up to you) taking action (may be blank)
• state — State of workflow as history was recorded.

and then, still hanging out down here with the properties:

• clear_saved — sets saved state to false and returns 0 🔄
• set_saved — sets saved state to true and returns 1 ✅

---

🌈 SEE ALSO 🌈

• Workflow

go read that one too, it's the main character of this whole saga. 👑

---

💀 COPYRIGHT 💀

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. (they're all listed over there, iykyk 💜)

---

and that's the whole page, bestie!! this was Workflow::History(3), generated by perl v5.42.0 on 2026-01-17. go forth and log your history, you're gonna eat 💅✨🎀