Workflo...ersister(3)

📦
version 2.09 · 2 versions
, in fedora 44

💖 Workflow::Persister — the base class for workflow persistence, bestie 💖

okay so. welcome to the Workflo...ersister(3) page, from your friends in the User Contributed Perl Documentation corner of the world. sit down, grab a boba, we're learning about persisters. no cap, it's actually slay.

✨ VERSION ✨

this doc? it's describing version 2.09 of this package. periodt. 🎀

🌸 SYNOPSIS 🌸

here's the vibe, in code:

# Associate a workflow with a persister in workflow.yaml
type: Ticket
persister: MainDatabase
state:
...

# Declare a persister in persister.yaml
persister:
- name: MainDatabase
  class: Workflow::Persister::DBI
  driver: MySQL
  dsn: DBI:mysql:database=workflows
  user: wf
  password: mypass

# Declare a separate persister in other_persister.yaml
persister:
- name: FileSystem
  class: Workflow::Persister::File
  path: /path/to/my/workflow

like… she's just a lil config girlie. iconic. 💅

🦋 DESCRIPTION 🦋

so this is the base class for persisting workflows. and here's the tea: it does not implement anything itself. it's giving abstract. actual implementations are supposed to subclass it so they can fulfil the contract. it's giving interface energy, fr fr.

and what's the job of a persister, you ask? bestie, the job is:

  • create, update and fetch the workflow object
  • plus any data associated with the workflow
  • and it also creates and fetches workflow history records

that's the whole gig. not me describing an entire responsibility set in one breath 😭

👑 SUBCLASSING 👑

⭐ Methods ⭐

create_workflow( $workflow )

this one's a stub, and the stub's whole personality is warning you that the method should be overwritten in the derived Persister. because — say it with me — this is a SUPER class. ✨

what it's supposed to do: generate an ID for the workflow, serialize the workflow data (that's the ID and the state), and set the ID in the workflow.

returns: the ID for the workflow. 🎀

update_workflow( $workflow )

another stub, another warning that you should overwrite it in the derived Persister. because this is a SUPER class. yes we're doing this every time, it's a bit 💀

what it does: updates the workflow state, which includes serializing the workflow context.

returns: literally nothing. nothing at all. 🫶

fetch_workflow( $workflow_id )

stub alert 🚨 warns you that the derived Persister should overwrite it. since — you guessed it — this is a SUPER class.

what it does: retrieves the workflow data that corresponds to $workflow_id.

  • if it's not found, return undef
  • if it is found, return a hashref with at least the keys "state" and "last_update" (and "last_update" is a DateTime instance, fancy)

and if the workflow has associated serialized context? then return the deserialized hash value in the "context" key. the keys in that hash get made available through the "param" method in the workflow's context (which you reach through the "context" method). iykyk. 🌈

create_history( $workflow, @history )

stub, warning, overwrite it in the derived Persister, SUPER class, you know the drill bestie 💖

what it does: serializes all objects in @history so they can be retrieved later.

returns @history — that's the list of history objects — with the history "id" and "saved" values set according to the saved results.

fetch_history( $workflow )

stub, warning, overwrite, SUPER class. ok but actually the derived class method here should return a list of hashes containing at least the id key. those hashes get used by the workflow object to instantiate Workflow::History objects (or a derived class of it). cute, right? 🍓

assign_generators( \%params )

assigns the proper generators based on initialization. see "init". ✨

commit_transaction

commits the current transaction if the persister supports transactions. and good news: this stub does not have to be overridden. 🎉

but heads up — it is not executed if autocommit is on. 🙈

rollback_transaction

rolls back the current transaction if the persister supports transactions. and again, this stub does not have to be overridden. 💜

and again — it is not executed if autocommit is on.

init

the method to initialize the persister based on configuration. that's it, that's the whole girl. 🌸

init_random_generators( \%params )

initializes random id generators. it takes the following named parameter:

  • length — of random id to be generated

returns two identical random id generator objects in list context. twins!! 👯

init_uuid_generators( \%params )

initializes UUID generators. takes no parameters.

returns two identical UUID generator objects in list context. twins again, but make it UUID. 🦋

💀 TODO 💀

the maintainers left us a little list of things they're side-eyeing:

  • refactor init_random_generators, returns two similar objects?
  • refactor init_uuid_generators, returns two similar objects?
  • refactor init_uuid_generators, takes no parameters, even though we shift parameters in?

not me reading the third one twice 😭 the self-awareness is highkey unmatched.

🔥 SEE ALSO 🔥

  • Workflow::Factory
  • Workflow::History

go read those too, bestie, they're the supporting cast. 👑

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

okay that's the whole page!! and a lil cute sign-off for you: this lovely thing is from perl v5.42.0, dated 2026-01-17, and yeah it's filed under Workflo...ersister(3) — that truncated name is not a typo, that's just how the manpage wears it. slay, go subclass something responsibly 🫶✨💅

📦 where this page comes from