workflow

package module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 11, 2026 License: MIT Imports: 26 Imported by: 0

README

Editorial workflow

An editorial workflow for Kosatka: states of content (draft, in review, approved, published, archived - or your own) and the transitions between them by role - who sends to review, who approves, who publishes - with the editorial queue and editing locks.

The Editorial workflow module (workflow) lets content go through review before it is published. An item of a content type following the workflow is in one of its states - a draft, in review, approved, published, archived - and moves between them by transitions: Send to review, Return to the author, Approve, Publish. Each transition is for some roles. Whether the item is on the site depends on its state.

Install

A site with modules from outside the engine builds its own binary (kosatka.Main); app module add adds this one to it:

app module add github.com/kosatka-cms/kosatka-module-workflow
go build -o app .

Then enable Editorial workflow on the site's Modules page: it installs its tables and starter rows. See Using modules.

A new site built with it gets it with app install -modules workflow,… (or -modules all).

Enabling it installs the states above and six transitions: those four, Archive (published to archived) and Back to work (archived to draft). Only Send to review is given to a role, signed-in users; the others are for who has full access until you give them roles. No content type follows the workflow yet.

Setting it up

Configuration → Editorial workflow (/admin/config/workflow):

  • States - a name, a machine name (set once), whether an item in it is on the site, a colour, which one is initial (a new item's). The last row adds a state. An item whose state is deleted counts as in the initial one (or in the first on the site, if it is published).
  • Transitions - the states it goes from (one or several), the state it goes to, the button's text, the roles that may make it, and whether it asks for a comment: optional, required (such as Return to the author, telling what to fix) or none. Who has full access may make every transition. A transition is made on an item of a type that follows the workflow, by someone who may edit that item.
  • Content types - the ones following the workflow. When a type joins, its published items get the first state that is on the site, those on moderation the first state neither initial nor on the site (In review) and leave moderation, the others the initial one. A type that doesn't follow it publishes as before, by its New content setting.

The settings page needs the Access administration (/admin) permission.

Published, on moderation and the states

An item is on the site, as before, when it is published and not on moderation: that is what search, the sitemap and a View's status filter look at. The workflow sets it: a transition to a state that is on the site publishes the item, to another one unpublishes it, and either takes it off moderation - waiting for review is a state (In review), the editorial queue lists it.

So the type's own ways of publishing don't apply to its items: its New content setting (a new item is in the initial state), the form's Published and On schedule, the item page's Publish and Unpublish, the content list's bulk publishing and moderation actions (they leave such items out, saying why), and a schedule set before the type joined (when its time comes, it is cleared and changes nothing). The moderation page doesn't get them either.

In the content form

For a type following the workflow, the form's side card shows the item's state instead of Published, a Comment for whoever is next, and a button per transition the user may make; Save keeps the state. The publishing checkboxes and the schedule aren't there: the transitions publish and unpublish.

When the last transition left a comment (Return to the author with what to fix), the form shows it over the fields.

The editorial queue

Content → Editorial (/admin/content/workflow) lists the items by state, a tab each with how many there are, opening on the first state neither initial nor on the site; the last saved first, with their type, author and last save. A column's header sorts the tab by it - the title, the type, the author, the last save - and again the other way. Each row has the transitions the user may make from that state: one that requires a comment opens a page for it, the others are made at once, without one. The number by the menu item is how many items wait for a transition of yours (in a state neither initial nor on the site). The queue needs the Access administration (/admin) permission; an editor without it makes the transitions in the content form.

Every transition is kept, with its comment, in the workflow's own record (the form shows the latest comment, above). One that publishes or unpublishes the item is also in the action log and, when its type keeps one, in the item's history.

Editing lock

While an item of a type following the workflow is open in its form, it is locked: another editor opening it sees who edits it and since when, over a read-only form, and can't save it. The lock is released when the item is saved or its form closed; by itself after some time without activity in the form (typing, clicking) - 30 minutes unless set otherwise.

Who has the Take over another's editing lock permission (and full access) sees Take over editing in that notice: the form becomes theirs. The one who had it learns it in their form, at the latest when saving: their changes aren't saved, the form comes back with them, read-only, to copy.

The queue shows by an item who edits it now. Editing → Editing lock in the settings turns locking off or sets the time: 15, 30, 60 or 120 minutes.

In Views

A content View (see Views) can use the workflow:

  • the filter Workflow state - the items in one state or in several (or with none: of types not following it); exposed, visitors pick the state from a list;
  • the field Workflow state - the state's name on its colour;
  • the sort criterion In the workflow state since - when the item came to its state.

A View lists whatever its filters match, unpublished items too (see Choosing the content), and its page is open to everyone. So a public View with the state filter keeps status = 1, unless it shows unpublished items on purpose - Approved ones announced ahead, say. For the editors' list of what waits for review, use the editorial queue.

Not there yet

  • Editing a published item while the site shows the published version until the new one is approved.

Development

Its strings are translated in translations/<lang>.json.

The module is built on the engine's module SDK only (github.com/kosatka-cms/kosatka/modulekit, pkg/*).

go test ./...
# with MySQL and PostgreSQL (the engine's docker-compose.test.yml):
KOSATKA_TEST_MYSQL_DSN="root:test@tcp(127.0.0.1:33306)/?parseTime=true" \
KOSATKA_TEST_POSTGRES_DSN="postgres://postgres:test@127.0.0.1:35432/postgres?sslmode=disable" \
  go test -tags dbintegration ./...

A schema change: edit ent/schema, go generate ./ent, then go run ./cmd/migrations -name <name> (both test databases running) - it writes the next migration for MySQL and PostgreSQL into ent/migrations; go run ./cmd/migrations -check fails while the files are behind the schema. See Write a module.

License

MIT

Documentation

Overview

Package workflow - the editorial workflow module: content items of the types following it move between states (draft, in review, …) by transitions the roles may make; a state publishes or unpublishes the item.

Index

Constants

View Source
const (
	QueueSortUpdated = "updated"
	QueueSortType    = "type"
	QueueSortAuthor  = "author"
	QueueSortTitle   = "title"
)

The queue's sort columns (QueueSort.Key, its "sort" parameter).

View Source
const DefaultLockMinutes = 30

DefaultLockMinutes - LockMinutes until the settings are saved.

Variables

View Source
var Assets embed.FS

Assets - the module's templates/, built into the binary (modules.Assets, paths.SetModuleAssets): a site runs without the module's source directory.

Functions

func RegisterRoutes

func RegisterRoutes(r modulekit.Mux, c *Controller, admin, signedIn func(http.Handler) http.Handler)

RegisterRoutes registers the settings and the queue with its actions (behind admin), an item's lock's actions (behind signedIn: its editors).

func Wire

func Wire(d modulekit.Deps) modulekit.Parts

Wire - the workflow publishing its content types' items through their forms (SetNodeWorkflow), its settings and the editorial queue, the count of what waits for the user by the queue's menu item; the state's filter, field and sort criterion in content Views.

Types

type Config

type Config struct {
	States      []State
	Transitions []Transition
	Types       []string
	LockMinutes int
}

Config - the workflow; LockMinutes - how long an item's form stays locked without its editor's activity (0 - items aren't locked).

func (Config) FirstPublished

func (c Config) FirstPublished() string

FirstPublished - the first published state ("" - none).

func (Config) Initial

func (c Config) Initial() State

Initial - a new item's state.

func (Config) State

func (c Config) State(name string) (State, bool)

State - the state named name (false - none such).

func (Config) Waiting

func (c Config) Waiting() State

Waiting - the first state neither initial nor published (in review, say), else the initial one: an item on moderation when its type joins.

type Controller

type Controller struct {
	*modulekit.BaseController
	// contains filtered or unexported fields
}

Controller - the workflow's settings and the editorial queue.

func NewController

func NewController(base *modulekit.BaseController, db *sql.DB, w *Workflow, nodes modulekit.NodesRepository, types modulekit.ContentTypeService, users users, roles interface {
	Roles(ctx context.Context) (modulekit.Roles, error)
}) *Controller

NewController creates a Controller.

func (*Controller) KeepLock

func (c *Controller) KeepLock(w http.ResponseWriter, r *http.Request)

KeepLock handles POST /workflow/lock/{nid}: the form still edited - its lock kept, or got again if free; JSON lockState.

func (*Controller) Queue

func (c *Controller) Queue(w http.ResponseWriter, r *http.Request)

Queue renders GET /admin/content/workflow?state=…: the items in a state (the first waiting one - not initial, not published - by default), the longest waiting first, with the transitions the user may make from it.

func (*Controller) ReleaseLock

func (c *Controller) ReleaseLock(w http.ResponseWriter, r *http.Request)

ReleaseLock handles POST /workflow/lock/{nid}/release: the form closed unsaved - the user's lock removed.

func (*Controller) SaveSettings

func (c *Controller) SaveSettings(w http.ResponseWriter, r *http.Request)

SaveSettings handles POST /admin/config/workflow: the states and transitions as the form lists them (indexed fields; a row without a label - none, "delete" - dropped), the content types, the locking.

func (*Controller) Settings

func (c *Controller) Settings(w http.ResponseWriter, r *http.Request)

Settings renders GET /admin/config/workflow: the states (a blank row adds one), the transitions (so), the content types following it.

func (*Controller) TakeLock

func (c *Controller) TakeLock(w http.ResponseWriter, r *http.Request)

TakeLock handles POST /workflow/lock/{nid}/take: the lock taken over (PermTakeOver), the form opened.

func (*Controller) Transition

func (c *Controller) Transition(w http.ResponseWriter, r *http.Request)

Transition handles POST /admin/content/workflow/{nid}/{tid}: the item moved by the transition (with its comment, when it takes one), its publishing changed with the item's history; back to the queue.

func (*Controller) TransitionPage

func (c *Controller) TransitionPage(w http.ResponseWriter, r *http.Request)

TransitionPage renders GET /admin/content/workflow/{nid}/{tid}: the transition's confirmation with its comment.

type HistoryEntry

type HistoryEntry struct {
	Nid     int
	From    string
	To      string
	UID     int
	Comment string
	At      time.Time
}

HistoryEntry - a transition made.

type Lock

type Lock struct {
	Nid       int
	UID       int
	LockedAt  time.Time
	TouchedAt time.Time
}

Lock - an item edited by UID in its form since LockedAt, last active at TouchedAt (workflow_locks).

type NodeState

type NodeState struct {
	Nid       int
	State     string
	ChangedAt time.Time
	ChangedBy int
}

NodeState - an item's recorded state.

type QueueItem added in v0.1.1

type QueueItem struct {
	NodeState
	Updated time.Time
}

QueueItem - an item of the queue: its state and when its content was last saved.

type QueueSort added in v0.1.1

type QueueSort struct {
	Key  string
	Desc bool
}

QueueSort - the queue's order: a column (QueueSort*) and its direction.

type Repo

type Repo struct {
	// contains filtered or unexported fields
}

Repo - the module's tables (Backfill reads the core's nodes). A built-in module, tested with the engine, may read the core's tables in its SQL; a module of its own repository goes through the SDK's services instead (docs/modules/sdk.md): the core's columns aren't its API.

func NewRepo

func NewRepo(db *sql.DB) *Repo

NewRepo creates a Repo on the site's database.

func (*Repo) AcquireLock

func (r *Repo) AcquireLock(ctx context.Context, nid, uid int, now, since time.Time) (Lock, error)

AcquireLock locks nid for uid at now - its own lock touched, a lock inactive since before since taken over - unless another's active lock holds it: the lock holding nid after.

func (*Repo) AddHistory

func (r *Repo) AddHistory(ctx context.Context, h HistoryEntry) error

AddHistory records a transition of nid.

func (*Repo) Backfill

func (r *Repo) Backfill(ctx context.Context, types []string, states joinStates, now time.Time) ([]int, error)

Backfill records a state for the items of types without one (a type joining the workflow) by states, and returns those on moderation: their publishing is to follow their state.

func (*Repo) Config

func (r *Repo) Config(ctx context.Context) (Config, error)

Config - the workflow: its states and transitions in order, the content types following it.

func (*Repo) Counts

func (r *Repo) Counts(ctx context.Context) (map[string]int, error)

Counts - the number of items in each state.

func (*Repo) History

func (r *Repo) History(ctx context.Context, nid, limit int) ([]HistoryEntry, error)

History - nid's transitions, the newest first (limit 0 - all).

func (*Repo) InState

func (r *Repo) InState(ctx context.Context, state string, sort QueueSort, limit, offset int) ([]QueueItem, int, error)

InState - a page of the items in state in sort's order (an unknown key - the last saved first), with how many there are.

func (*Repo) Lock

func (r *Repo) Lock(ctx context.Context, nid int) (Lock, bool, error)

Lock - nid's lock (false - none).

func (*Repo) Locks

func (r *Repo) Locks(ctx context.Context, ids []int, since time.Time) (map[int]Lock, error)

Locks - the locks of the items among ids active since since, by id.

func (*Repo) NodeState

func (r *Repo) NodeState(ctx context.Context, nid int) (NodeState, bool, error)

NodeState - the state recorded for nid (false - none yet).

func (*Repo) ReleaseLock

func (r *Repo) ReleaseLock(ctx context.Context, nid, uid int) error

ReleaseLock removes uid's lock of nid (none - nothing to do).

func (*Repo) SaveConfig

func (r *Repo) SaveConfig(ctx context.Context, cfg Config) error

SaveConfig replaces the workflow's states, transitions and content types with cfg's (in ctx's transaction).

func (*Repo) SetNodeState

func (r *Repo) SetNodeState(ctx context.Context, nid int, state string, uid int, now time.Time) error

SetNodeState records nid's state, since now, by uid.

func (*Repo) States

func (r *Repo) States(ctx context.Context, ids []int) (map[int]NodeState, error)

States - the recorded states of the items among ids, by id.

func (*Repo) TakeLock

func (r *Repo) TakeLock(ctx context.Context, nid, uid int, now time.Time) error

TakeLock locks nid for uid at now, whoever held it.

type State

type State struct {
	ID        int
	Name      string
	Label     string
	Color     string
	Published bool
	Initial   bool
	Weight    int
}

State - a state of an item (workflow_states).

func (State) Hex

func (s State) Hex() string

Hex - the state's colour.

type Transition

type Transition struct {
	ID      int
	From    []string
	To      string
	Label   string
	Roles   []string
	Comment string
	Weight  int
}

Transition - a move between states (workflow_transitions): from one of From to To, by the button Label, for Roles; Comment - manifest's Comment*.

type Workflow

type Workflow struct {
	// contains filtered or unexported fields
}

Workflow - the workflow's settings (read once, kept until saved) and moving items between its states.

func NewWorkflow

func NewWorkflow(repo *Repo, nodes modulekit.NodesRepository, auth modulekit.AuthService) *Workflow

NewWorkflow creates a Workflow.

func (*Workflow) Allowed

func (w *Workflow) Allowed(ctx context.Context, user *modulekit.User, state string) ([]Transition, error)

Allowed - the transitions from state user may make: one of its roles is the transition's, or the user has full access.

func (*Workflow) Config

func (w *Workflow) Config(ctx context.Context) (Config, error)

Config - the workflow's settings.

func (*Workflow) Handles

func (w *Workflow) Handles(ctx context.Context, contentType string) bool

Handles - contentType's items follow the workflow.

func (*Workflow) Make

func (w *Workflow) Make(ctx context.Context, node modulekit.Node, from State, t Transition, user *modulekit.User, comment string) error

Make moves node from its state by t (by user, with comment): records it, sets the node's publishing by the new state (in ctx's transaction: the caller tracks the change).

func (*Workflow) SaveConfig

func (w *Workflow) SaveConfig(ctx context.Context, db *sql.DB, cfg Config) error

SaveConfig saves the workflow's settings; the items of a type newly following it get a state (Repo.Backfill): those on moderation the waiting one, unpublished and off moderation as it is - a change of the site's, not an edit: their last save stays (SetPublishing).

func (*Workflow) StateOf

func (w *Workflow) StateOf(ctx context.Context, node modulekit.Node) (State, error)

StateOf - node's state: its recorded one, else what its publishing says (on moderation - the waiting state, published - the first published one, else the initial one).

Directories

Path Synopsis
cmd
migrations command
Command migrations writes the module's next migration (kosatka.GenerateMigrations), run from the module's root with the two test databases running:
Command migrations writes the module's next migration (kosatka.GenerateMigrations), run from the module's root with the two test databases running:
ent
Package ent - the workflow module's own ent schema (schema/), its generated client (generated/, go generate) and migration files (migrations/<dialect>/, cmd/migrations writes them), apart from the core's: the module's set of migrations (Schema).
Package ent - the workflow module's own ent schema (schema/), its generated client (generated/, go generate) and migration files (migrations/<dialect>/, cmd/migrations writes them), apart from the core's: the module's set of migrations (Schema).
schema
Package schema - the workflow module's own ent schema: its states and transitions, which content types follow it, each item's state and the transitions made.
Package schema - the workflow module's own ent schema: its states and transitions, which content types follow it, each item's state and the transitions made.
Package manifest declares the editorial workflow module (its registry entry): states of content items and the transitions between them by role, publishing what reaches a published state.
Package manifest declares the editorial workflow module (its registry entry): states of content items and the transitions between them by role, publishing what reaches a published state.
Package translations holds the workflow module's interface catalogs (<lang>.json, see pkg/i18n): the strings only the module's code uses.
Package translations holds the workflow module's interface catalogs (<lang>.json, see pkg/i18n): the strings only the module's code uses.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL