Skip to content

Serialize workflow_states, label contributed workflows, and fix @history permissions and bare review_state queries - #11

Merged
ericof merged 6 commits into
mainfrom
issues-7-8-9
Sep 13, 2026
Merged

ericof merged 6 commits into
mainfrom
issues-7-8-9

Conversation

@ericof

@ericof ericof commented Sep 13, 2026

Copy link
Copy Markdown
Member

What

Closes four issues in six commits:

Why

#7. Whenever another add-on included this one from its dependencies.zcml before Products.CMFEditions was configured, the instance failed at startup with a ComponentLookupError for CMFEditions.AccessPreviousVersions. A test layer based on the Plone fixture loads CMFEditions first, so the suite never showed it.

#8. review_state was the only state in the standard payloads. A client wanting every workflow's state had to call @workflow per object, or know to request the workflow_states metadata column on a search. The values are already computed for the catalog; returning them with the object and with each search result makes a listing one request. On the Volto side, StateBadge was meant for listings but needed a full @workflow chain entry, which a listing could only get with one request per item.

#9. A workflow's title is set in its GenericSetup definition, shared by every type and behavior using it, and translated only through the plone domain. A label declared beside the contribution lets the package contributing the workflow choose what users see, translated in its own domain.

#10. Bare state ids were qualified with the first workflow of the site's default chain. That answered correctly only for content types driven by that workflow, so a collection written before the add-on was installed could silently lose every item whose review_state comes from another workflow.

Changes

Backend reorganization (0f020a4)

  • collective.multiworkflow.utils.workflow holds the values of the workflow_states index: WORKFLOW_STATES, STATE_SEPARATOR, format_state, parse_state, and the new formatted_workflow_states.
  • indexers.workflow_states holds the indexer, and subscribers.reindex the transition subscriber that keeps it fresh.
  • The @workflow and @history services move to restapi.services, and the expandable workflow element to restapi.serializer.

collective.multiworkflow.indexers re-exports the four value helpers, so code importing them from there, as the 1.0.0a1 documentation showed, keeps working. The indexer itself is not re-exported: its name would shadow the submodule the ZCML registers it from.

Load the @history permission (#7, 73c7c94)

dependencies.zcml now includes the permission definitions:

<include package="Products.CMFEditions" file="permissions.zcml" />

Products.CMFEditions is already a dependency of Products.CMFPlone, so this adds no requirement.

workflow_states in serializations (#8, cc7431b)

The key sits beside review_state, in the same form and order as the catalog index:

"review_state": "private",
"workflow_states": [
    "simple_publication_workflow|private",
    "foundation_member_workflow|pending"
],
  • Content. SerializeToJson.__call__ is wrapped in place rather than overridden by a more specific adapter. An adapter is bypassed by every serializer registered for a more specific interface; wrapping the method reaches SerializeFolderToJson, SerializeCollectionToJson, and any add-on serializer derived from them through super(), whatever order the ZCML loads in. The patch follows the exportimport one: applied once, on import of the serializer subpackage, with the original reachable as __wrapped__.
  • Historical versions read the states from the version object, as core reads review_state.
  • Summaries. An IJSONSummarySerializerMetadata utility adds the workflow_states metadata column to the default fields, so @search results carry it without metadata_fields.

On a site with plone.volto, Document is folderish and Folder and Collection are not globally addable. The tests therefore cover SerializeToJson with a Link, SerializeFolderToJson with a Document, and SerializeCollectionToJson with a Collection created past the add constraints, plus a serializer derived from them. A spike test calls the unwrapped method and fails once plone.restapi returns the key itself, which is the signal to drop the patch.

A label on the additionalworkflows directive (#9, e3ee6fe)

<configure
    xmlns:plone="http://namespaces.plone.org/plone"
    i18n_domain="my.package"
    >

  <plone:additionalworkflows
      marker=".interfaces.IFoundationMember"
      workflows="foundation_member_workflow"
      label="Foundation membership"
      />

</configure>
  • Translatable. label is a MessageID field, so the label is a message id in the i18n_domain of the ZCML file declaring it.
  • Per workflow, not per marker. The directive registers the label as an IAdditionalWorkflowLabel utility named after the workflow id, and declaration.workflow_label() looks it up, falling back to the workflow's title.
  • Where it shows. The @workflow chain entry's title carries the label, translated. Every Volto component already shows that title, so none of them needs a code change for it. The vocabulary of the Review state collection criterion names the workflow's states with it too.
  • Validation. A label with more or fewer than one workflow id raises ConfigurationError, since nothing would say which workflow it names. Two directives labelling the same workflow raise ConfigurationConflictError, as any two utilities registered under one name do.

Without a label, both places keep using the workflow's title, exactly as before.

review_state criteria naming no workflow (#10, efa4024)

Query values Index Query
none qualified, such as published review_state untouched
all qualified workflow_states as given
a mix of both workflow_states bare ids qualified with the default workflow

A mixed query moves as a whole: the catalog intersects the results of different indexes, so splitting one criterion between the two would turn its any of into an all of. The collection editor offers only qualified values, so a criterion saved from it targets workflow_states from then on.

Volto add-on (#8 and #9, e9a0ba0)

import {
  StateBadge,
  getAdditionalWorkflowStates,
} from '@plone-collective/volto-multiworkflow';

function ListingStates({ item, titles }) {
  return (
    <>
      {getAdditionalWorkflowStates(item).map((value) => (
        <StateBadge key={value} value={value} label={titles[value]} />
      ))}
    </>
  );
}
  • Helpers mirroring the backend. getWorkflowStates, getAdditionalWorkflowStates, parseWorkflowState, and formatWorkflowState, with the WORKFLOW_STATE_SEPARATOR and WORKFLOW_STATES_VOCABULARY constants and the WorkflowStateValue, ParsedWorkflowState, and WithWorkflowStates types.
  • StateBadge from a value. It takes either a chain entry, as before, or a workflow_states value with an optional translated label, falling back to the state id. A value with no separator renders nothing.
  • Where the label comes from. The workflow states vocabulary, whose titles name a workflow by its declared label. @vocabularies checks only View for it, since it is not in plone.app.content's permission map. A hook fetching those titles is left out: Volto's token-title request serializes the token list in a way not verified against plone.restapi here.
  • Declared labels. The story fixtures gain a labelled membership workflow, used by new StateBadge and AdditionalWorkflowMenu stories and a StateBadge test.

Documentation

  • REST API reference: content serialization and summaries of catalog results, with generated request and response examples. The examples pin the object's UID and effective date, which would otherwise change between runs or between time zones. The chain entry's title now describes the label.
  • ZCML reference and the declaration how-to: the label attribute, what it registers, its errors, and the equivalent Python registration.
  • Catalog reference, concepts, and how-to guides: the metadata column, reading the states from a search request, when a review_state criterion moves, and how the criterion's vocabulary names a labelled workflow.
  • Volto reference, the customization how-to, and the frontend readme: the new helpers, constants, and types, and rendering StateBadge in a listing from workflow_states.
  • Python API reference: new pages for utils, subscribers, and restapi, plus workflow_label and IAdditionalWorkflowLabel; import paths updated throughout, including the tutorial.

News fragments

  • backend/news/: +reorganize.internal.md, 7.bugfix.md, 8.feature.md, 9.feature.md, 10.bugfix.md
  • news/: +reorganize.documentation.md, 8.documentation.md, 9.documentation.md, 10.documentation.md
  • frontend/packages/volto-multiworkflow/news/: 8.feature.md, 9.internal.md

Testing

The backend suite was run on each backend commit's tree before committing: 230, 230, 254, 261, and 272 passed. Everything else below is the final state.

Check Result
make test (backend) 272 passed
make mypy no issues
ruff check, ruff format --check, zpretty --check src clean
vitest run (frontend) 107 passed
pnpm lint, pnpm prettier clean
make html (clean build) build succeeded, no warnings
make vale 0 errors, 39 warnings
make linkcheckbroken exit 0

38 of the Vale warnings are the pre-existing set main passed with in #5. The new one is Microsoft.GeneralURL on reference/rest-api.md line 158 ("what GET on its URL returns"), kept because the page is written for developers.

The label's translation is tested end to end: TestDeclaredLabel registers a translation domain of its own, and the @workflow payload carries the translated text rather than the message id.

tsc --noEmit in the frontend package reports three errors, none in a file this PR touches: two in Volto core sources, one in stories.test.tsx. CI does not run it.

Closes #7
Closes #8
Closes #9
Closes #10

The backend is split into subpackages that each hold one kind of
component:

- collective.multiworkflow.utils.workflow holds the values of the
  workflow_states index: format_state, parse_state, WORKFLOW_STATES,
  STATE_SEPARATOR, and the new formatted_workflow_states.
- collective.multiworkflow.indexers.workflow_states holds the indexer,
  and collective.multiworkflow.subscribers.reindex the transition
  subscriber that keeps it fresh.
- The @workflow and @history services move to
  collective.multiworkflow.restapi.services, and the expandable
  workflow element to collective.multiworkflow.restapi.serializer.

collective.multiworkflow.indexers re-exports the four value helpers, so
code importing them from there, as the 1.0.0a1 documentation did, keeps
working. The indexer itself is not re-exported: its name would shadow
the submodule the ZCML registers it from.

The move left two ZCML factories and several relative imports pointing
at modules that no longer existed, which stopped the suite at
collection. Those are fixed, the tests import from the new modules, the
module docstrings lost with the old indexers package are restored, and
the Python API reference, the how-to guides and the tutorial point at
the new layout.
The @history service is registered with the
CMFEditions.AccessPreviousVersions permission, but nothing in this
package loaded the ZCML defining it. Whether it existed depended on
load order: when another package included this one from its own
dependencies.zcml before Products.CMFEditions was configured, the
instance failed at startup with a ComponentLookupError.

The same package loads fine in a test layer based on the Plone fixture,
so the suite never showed it.

dependencies.zcml now includes the permission definitions.
Products.CMFEditions is already a dependency of Products.CMFPlone, so
this adds no requirement.

Closes #7
The serialization of every Dexterity object now carries a
workflow_states key beside review_state: the object's state in every
workflow of its chain, in the same <workflow-id>|<state-id> form and
order as the catalog index. Summaries of catalog results carry it too,
through an IJSONSummarySerializerMetadata utility that adds the
workflow_states metadata column to the default fields.

The key is added by wrapping SerializeToJson.__call__ on plone.restapi's
own class rather than by registering a more specific adapter. An
adapter would be bypassed by every serializer registered for a more
specific interface; wrapping the method in place reaches
SerializeFolderToJson, SerializeCollectionToJson and any add-on
serializer derived from them through super(), and the order in which
the packages' ZCML is loaded no longer matters. The patch follows the
exportimport one: applied once, on import of the serializer subpackage,
with the original method reachable as __wrapped__.

Tests cover the patch installation, each of plone.restapi's serializer
classes and a derived one, a historical version, brain summaries and a
real HTTP request, plus a spike that fails once plone.restapi returns
the key itself. On a site with plone.volto, Document is folderish and
Folder and Collection are not globally addable, so the tests use a
Link, a Document, and a Collection created past the add constraints.

The REST API reference documents the key with generated examples,
which pin the object's UID and effective date: both would otherwise
change between runs or between time zones.

Closes #8
ReviewStateModifier moved every parsed review_state query onto
workflow_states and qualified bare state ids with the first workflow of
the site's default chain. That answered correctly only for content
types driven by that workflow: a collection written before the add-on
was installed silently lost every item whose review_state comes from
another workflow.

A query is now moved only when one of its values names a workflow.
Otherwise it is returned as it came, on review_state, whose index is
still maintained exactly as before. A query mixing bare and qualified
values still moves, with the bare ones qualified: the catalog
intersects the results of different indexes, so splitting one
criterion between the two would turn its "any of" into an "all of".

The collection editor offers only qualified values, so a criterion
saved from it targets workflow_states from then on.

The new query builder test goes through parseAndModifyFormquery:
parseFormquery alone does not apply IParsedQueryIndexModifier
utilities.

Closes #10
<plone:additionalworkflows /> accepts an optional label naming the
workflow in the user interface in place of its title. The attribute is
a MessageID field, so the label is a message id in the i18n_domain of
the ZCML file declaring it.

The label belongs to the workflow, not to the marker: the directive
registers it as an IAdditionalWorkflowLabel utility named after the
workflow id, and declaration.workflow_label() looks it up, falling back
to the workflow's title. Two places use it:

- the title of the workflow's @workflow chain entry, translated. Every
  Volto component already shows that title, so the frontend only gains
  an updated doc comment on the type;
- the vocabulary of the Review state collection criterion.

A directive with a label must list exactly one workflow, and raises
ConfigurationError otherwise, since nothing would say which workflow
the label names. Two directives labelling the same workflow conflict,
as any two utilities registered under one name do.

Closes #9
The backend now serializes workflow_states on every content object and
on each catalog summary, but the Volto add-on had no way to read them:
StateBadge, meant for listings, needed a full @workflow chain entry,
which a listing could only get with one request per item.

- New helpers mirroring the backend's utils.workflow:
  getWorkflowStates, getAdditionalWorkflowStates, parseWorkflowState
  and formatWorkflowState, with the WORKFLOW_STATE_SEPARATOR and
  WORKFLOW_STATES_VOCABULARY constants and the WorkflowStateValue,
  ParsedWorkflowState and WithWorkflowStates types.
- StateBadge takes either a chain entry, as before, or a
  workflow_states value with an optional translated label, falling
  back to the state id. A value with no separator renders nothing.

The label comes from the workflow states vocabulary, whose titles now
name a workflow by its declared label, and which anyone who can view
the context may read. A hook fetching those titles was left out:
Volto's token-title request serializes the token list in a way not
verified against plone.restapi here.

Declared labels need no code change, since the backend reports them
as the chain entry's title. The story fixtures gain a labelled
membership workflow, used by new StateBadge and AdditionalWorkflowMenu
stories and a StateBadge test, and the doc comments say where a title
comes from.

The Volto reference, the component customization how-to and the
package readme describe the new exports.

Refs #8
Refs #9
@ericof
ericof merged commit e9dd623 into main Sep 13, 2026
24 checks passed
@ericof
ericof deleted the issues-7-8-9 branch September 13, 2026 21:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant