# Workflows: CMS and Website Builder integrations How workflows plug into Headless CMS entries and Website Builder pages: `api-headless-cms-workflows`, `app-headless-cms-workflows`, `api-website-builder-workflows` and `app-website-builder-workflows`. Paths are relative to `packages/`. Describes the code after phase 9c; the engine side is in `api.md`, the shared admin core in `app.md`. ## 1. What each package registers ### api-headless-cms-workflows - Entry: `src/index.ts` exports `CmsWorkflowsFeature` (`src/CmsWorkflowsFeature.ts`), registered once by `api-event-handler-core/src/registerApiRequestStack.ts` after the engine's `WorkflowsFeature`. It does not register the engine itself. - Licence gate: returns early unless the `advancedPublishingWorkflow` flag is on. - Registers: - The local `Workflows` feature (`src/features/Workflows/`): `DisallowUnpublishableModelsOnBeforeCreate` and `DisallowUnpublishableModelsOnBeforeUpdate` on the engine's workflow before-create and before-update events refuse a `cms.` that does not exist, is not readable by the caller, is private or is tagged `$publishing:false` (non-CMS namespaces are skipped; the store wrapper refuses those), with `field: "models"` on the `WorkflowValidationError` data (D165). - `CmsTargetFeature` (`src/features/target/`): `CmsModelReviewNamespace` (the `CmsEntryReviewNamespace` of public models, `cms.`; private models have none), `CmsEntryTargetReader`, `CmsEntryAccess`, `CmsEntryFolderExistsService`, and the engine ports `CmsEntryReviewTargetLoader`, `CmsEntryReviewTargetSync`, `CmsEntryReviewTargetReadAccess`, `CmsEntryReviewTargetFolderChain`, `CmsEntryReviewTargetEditor` (AI tools) and `CmsEntryReviewTargetLink` (notification links). - `CmsHooksFeature` (`src/features/hooks/`): the CMS event handlers and the model delete decorators (section 3). - `CmsWrappersFeature` (`src/features/wrappers/`): one wrapper use case per operation, with `CmsEntryReviewGuardService` for the checks every review action shares. - `CmsWorkflowsSchemaFactory` (every CMS workflow and review operation on the `cms` root of `/graphql`) and a `CmsGraphQLSchemaFactory` instance that adds `CmsEntrySystem.workflow: CmsEntrySystemWorkflow` to the CMS endpoints (`src/graphql/entrySystemSchema.ts`). - Utils: `utils/appName.ts` (`toCmsNamespace`, `getModelIdFromAppName`, `isCmsNamespace`, `getCmsNamespace`; regex `/^cms\.([a-zA-Z0-9_-]+)$/`), `utils/isBindableModel.ts` (public and without the `$publishing:false` tag), `utils/folderType.ts` (`cms:`). - Phase 8b wrappers: `GetCmsEntryReviewStepRun` (query `getCmsEntryReviewStepRun`, guard, then `editor` or `reassign`, D161) and `ListCmsEntryBlockingReviews` (query `listCmsEntryBlockingReviews`, D164). - Phase 9a: `listCmsEntryWorkflowModels` is the editor's model list (D116); it lists readable public models without the `$publishing:false` tag, sorted, with a search and a cursor. ### api-website-builder-workflows - Entry: `src/index.ts` exports `WebsiteBuilderWorkflowsFeature` (`src/WebsiteBuilderWorkflowsFeature.ts`), registered once by `registerApiRequestStack.ts`; same licence gate. - Registers `WebsiteBuilderPageSchemaFactory` (`WbPageSystem.workflow: WbPageSystemWorkflow`), `WebsiteBuilderWorkflowsSchemaFactory` (every pages operation on the `websiteBuilder` root), `WbTargetFeature`, `WbHooksFeature` and `WbWrappersFeature`. - `WbTargetFeature` (`src/features/target/`): `WbPageReviewNamespace` (maps the page model to `wb.page`, so the single CMS handlers for revision create and the save block cover pages, R51), `WbPageTargetReader`, `WbPageAccess`, `WbPageFolderExistsService`, and the ports `WbPageReviewTarget{Loader, Sync, ReadAccess, FolderChain, Editor, Link}`. - Constants: `WB_PAGE_NAMESPACE = "wb.page"`, `WB_PAGE_FOLDER_TYPE = "wb:page"` (`src/constants.ts`). - Phase 8b wrapper: `GetWebsiteBuilderPageReviewStepRun` (query `getWebsiteBuilderPageReviewStepRun`, guard `WbPageReviewGuardService`, then `editor` or `reassign`, D161). - Phase 9a: the app-mismatch guard sets `field: "models"` on its `WorkflowValidationError` data (D165); `listWebsiteBuilderPageWorkflows` gives the editor's single `Pages` row its bound workflow. ### app-headless-cms-workflows - Entry: `src/index.tsx` exports ``, mounted after `WorkflowsAdminApp` (`app-serverless-cms/src/Admin.tsx`), same feature flag gate. - `CmsReviewFeature` (`src/features/gateway/feature.ts`): `CmsReviewGateway` (GraphQL documents over the `cms` root; singleton, registered under the shared `ReviewAppGateway` token with `app` `cms` and `canHandle` true for `cms.`, so the shared use cases reach it through the routing `ReviewGateway`, D184), `CmsReviewContentAdapter` (`cms.` namespaces, entry URL, model label), `CmsReviewRowProvider`, the `CmsReviewNotificationHandler` and the `CmsReviewChangeMessageHandler` (subclass of the shared `ReviewChangeMessageHandler`, D160). - Editor: `CmsEntryReview` (editor session, `CmsEntryReviewImpl`) and `CmsEntryFormPresenterReviewDecorator` (which also builds the `CmsEntryContentReloader` over the undecorated presenter's `loadRevision`, D163); components `CmsEntryReviewBar` (decorates `ContentEntryFormContent`), `CmsEntryReviewFormLock` (decorates `ContentEntryForm`), `CmsEntryReviewBlockedActions` (the disabled Publish, wrapped in the shared `ReviewTooltip`; there is no standalone tooltip component), `CmsEntryReviewScheduleMenuItem` (decorates `MenuItemAction`), `CmsEntryReviewNewRevision`. - Lists and cache: `CmsReviewListEntriesFieldSelection`, `CmsReviewGetEntryFieldSelection`, `CmsReviewTableRowMapperDecorator`, `CmsReviewMoveEntryAction` (gates the list Move action while a review is in progress), `CmsReviewCacheSyncHandler` (a subclass of the shared handler) with `CmsReviewCacheWriter` (patches `ContentEntriesCacheProvider`, only the review's own revision). - Content Reviews: `CmsContentReviews` mounts the shared route `/cms/content-reviews`, menu `workflows.cms.contentReviews`, widgets `workflows.cms.review` and `workflows.cms.requested`; `CmsContentReviewsSidebarItem` adds the sidebar footer item; `CmsContentReviewsPresenter` (`CmsContentReviewsPresenterImpl.ts`) supplies the model namespaces and the content type filter. - Trash and delete: `features/trash` decorates `DeleteEntryUseCase`, `DeleteEntryRevisionUseCase`, `PermanentlyDeleteEntryUseCase` and the bulk delete presenter through the shared `ActiveReviewGuard` (D157); for all loaded rows the decorator pre-checks with `ListBlockingReviewsUseCase` per chunk of 200 ids and `confirmBlocking` (D164). - Workflow editor (9a): `features/editorGateway/` (`CmsWorkflowEditorGateway` with the documents over the `cms` root, registered by `CmsWorkflowEditorFeature` under the shared `WorkflowEditorAppGateway` token with `app` `cms`, D184); `features/editorMounting/` (`CmsWorkflowEditorAppAdapter`: `init` lists the models into the admin `ModelsCache`, `renderModelIcon` through `normalizeIcon` and the CMS icon component; `CmsWorkflowEditorMountingFeature`, which resolves only the adapter, as `app`); and the mount component `CmsWorkflowEditor` (`Routes/`), which renders the shared `WorkflowEditorRoute` and `WorkflowEditorMenu` of `app-workflows` at `/cms/workflows`. The menu item shows only with the workflows `editor` permission and the feature flag (D162); since 9c the route exists whenever the flag is on and shows the no-access view without `editor` (D178). Phase 9b: the gateway gained the `inspectRouting` and `folderExists` documents (`graphql/inspectCmsEntryRouting.ts`, `graphql/cmsEntryFolderExists.ts`; the bare model id and a `null` folder for the root), and the adapter gained `getFolderType` (`cms:`) and `listFolders` over `ListFoldersGateway` of `@webiny/app-aco`, which is a dependency of this package and is registered through `ListFoldersGqlGateway` in `editorMounting/feature.ts` (D173). ### app-website-builder-workflows - Entry: `src/index.tsx` exports `` (`Admin.tsx`), same gate. - `WbReviewFeature` (`src/features/gateway/feature.ts`): `WbReviewGateway` (documents over the `websiteBuilder` root; singleton, registered under `ReviewAppGateway` with `app` `wb` and `canHandle` true for `wb.page`; its `listBlockingReviews` returns an empty list without a request), `WbReviewContentAdapter` (`wb.page`, page editor URL), `WbReviewRowProvider`, the `WbReviewNotificationHandler` and the `WbReviewChangeMessageHandler` (D160). - Editor: `WbPageReview` (editor session, `WbPageReviewSessionImpl`); `PageEditorTopBar` renders the bar for every page status, `PageEditorLayout` makes the editor read-only from the review state, `PageEditorAutoSave` stops autosave while a review exists, `PageReviewBar` (which passes the `WbPageContentReloader` of `features/editorReview/` as the init params' `contentReloader`, D163) and `PageReadOnlySync` (the read-only flag and its reason), `PageNewRevisionDecorator` (hides the base New Revision button while a review is in progress), and the publish pieces `PageReviewPublishButton` and `PageReviewPublishAction` (`buttonWorkflowPublish`, so an approved page can be published although the editor is read-only), `DisabledPublishButton` (the disabled Publish inside the shared `ReviewTooltip`) and `PageBasePublishDecorator` (hides the base `buttonPublish` when the namespace has a workflow); a rejected page offers the base "Create new revision". - Lists and cache: `WbReviewListPagesFieldSelection`, `WbReviewGetPageFieldSelection`, `WbReviewTableRowMapperDecorator`, `WbReviewCacheSyncHandler` with `WbReviewPageCacheWriter` (only the review's own revision); the change-status action follows `reviewState`. - Content Reviews: `WbContentReviews` mounts the shared route `/website-builder/pages/content-reviews`, menu `workflows.wb.contentReviews`, widgets `workflows.wb.review` and `workflows.wb.requested`, and the sidebar footer item. - Trash and delete: `features/trash` decorates `DeletePageUseCase`, `DeletePageRevisionUseCase` and the bulk delete presenter (D157; no WB trash-bin hook: a trashed page cannot have an active review); the server side is `deletePageRevision` plus the workflows block (spec 9.6). - Workflow editor (9a): `features/editorGateway/` (the WB mirror of the CMS editor gateway, under `WorkflowEditorAppGateway` with `app` `wb`; `listModels` returns the single `wb.page` row `Pages`); `features/editorMounting/` (`WbWorkflowEditorAppAdapter`, `panelLabel` `Website Builder`, `init` a no-op; `WbWorkflowEditorMountingFeature`); and `WebsiteBuilderWorkflowsMenu` (`Routes/`), which renders the shared `WorkflowEditorRoute` and `WorkflowEditorMenu` at `/website-builder/workflows`. The menu item gained the `editor` gate it lacked (D162); since 9c the route exists whenever the flag is on and shows the no-access view without `editor` (D178). Phase 9b: the same two documents (`graphql/inspectWebsiteBuilderPageRouting.ts`, `graphql/websiteBuilderPageFolderExists.ts`; no model and no folder type), and the adapter's `getFolderType` (`wb:page`) and `listFolders` over `ListFoldersGateway`, with `@webiny/app-aco` as a dependency (D173). ## 2. How a workflow is bound to content - A workflow's `models` holds namespace ids: `cms.` for a CMS model, `wb.page` for all pages. v1 binds exactly one namespace per workflow (D15). The store wrappers refuse a namespace of another app (`CMS_MODELS_ONLY`, `WB_PAGES_ONLY` in `features/wrappers/shared/`) and never overwrite another app's workflow (R46). - `GetBoundWorkflowUseCase` answers which workflow binds a namespace, or `null`; the hooks ask it first, so unbound models never look up reviews. If two workflows bind one namespace (an accepted save race), the oldest wins. - Requesting a review (`requestCmsEntryReview(modelId, revisionId, title, picks)` or `requestWebsiteBuilderPageReview(revisionId, title, picks)`) needs write access to the revision. The engine snapshots the workflow's steps and name into the review, so later workflow edits do not change running reviews. A missing or empty title falls back to the content's title. - One active review per revision (`isActive`, D23); approved and rejected reviews stay active, cancelled ones do not. `targetRevisionId` is the revision id (`#000N`) for entries and pages alike (pages are CMS entries of a private model). - Denormalised copy: after every review save, the app's `ReviewTargetSync` writes `system.workflow = { workflowId, reviewState, stepId, stepName, stepState }` on the target revision through the CMS `UpdateEntrySystemUseCase`. A new revision starts with `system.workflow` cleared (`NullReviewStateOnRevisionCreate`, D59). The lists and the admin cache read this copy; the publish rules do not trust it (the update input can set it) and read the review instead. ## 3. Rules while a review is in progress ### API All rules act only on bound models and fail closed when a lookup fails. - Save block (`BlockUpdateWhileInReview`, CMS entries and pages): a revision with an active review cannot be updated, also when approved or rejected (`Workflows/Review/TargetLocked`). Only the automation runner and the AI tool `updateTargetFields` bypass it, through `WorkflowBypassService`. - Publish (`RequireApprovedReviewOnPublish`, `RequireApprovedReviewOnRepublish`, `RequireApprovedReviewOnPagePublish`): a revision publishes only with its active review approved (`Workflows/Review/PublishBlocked`); an approved revision that was unpublished can be published again (D121). Creating content as published is not a publish and stays allowed (D134). - Move (`BlockMoveWhileInReview`, `BlockFolderChangeWhileInReview` for updates that change the folder, `BlockPageMoveWhileInReview`): no folder move while any revision has a review in progress (D84). - Trash and delete (`BlockDeleteWhileInReview`, `BlockRevisionDeleteWhileInReview`, `BlockDeleteMultipleWhileInReview`, `BlockPageTrashWhileInReview`, `BlockPageDeleteWhileInReview`, `BlockPageRevisionDeleteWhileInReview`): refused while a review is in progress (`Workflows/Review/ActiveReviewOnTrash`). The admin confirms by calling `cancelCmsEntryReviewsForDelete` or `cancelWebsiteBuilderPageReviewsForDelete` (delete access, no cancel right needed) and repeating the action (D134). - Cleanup: after a permanent delete of an entry, a revision, `deleteMultiple` entries, a page or a page revision, the `DeleteReviewsOn*` handlers delete the reviews with their assignment records and kept tasks. Trash keeps them. Failures are logged, never thrown (R81). - Model delete: `DeleteModelBoundToWorkflowDecorator`, `FullyDeleteModelBoundToWorkflowDecorator` and `DeleteModelTaskBoundToWorkflowDecorator` refuse deleting a bound model by any path (`Workflows/Model/BoundToWorkflow`). - Folders: deleting a WB page folder that still holds pages is refused by `api-website-builder` (`features/folders/EnsurePageFolderIsEmptyOnDelete/`, bug B1). Re-parenting a folder or an ancestor is not blocked; routing evaluates the folder chain when a step is reached. ### Admin - CMS: `CmsEntryFormPresenterReviewDecorator` applies the review session's `allowsEditing` and `allowsPublishing` to `canSave` and `canPublish`; `CmsEntryReviewBlockedActions` shows the disabled Publish with the shared `ReviewTooltip`; `CmsEntryReviewScheduleMenuItem` gates scheduling; `CmsReviewMoveEntryAction` gates the list Move action; `features/trash` routes trash and delete through the shared `ActiveReviewGuard`. - WB: `PageEditorLayout` makes the editor read-only from the review state, `PageEditorAutoSave` stops autosave, `PageReviewPublishButton` / `PageReviewPublishAction` and `PageBasePublishDecorator` replace the base Publish when the namespace has a workflow, `PageNewRevisionDecorator` hides New Revision while a review is in progress; `features/trash` as in the CMS. - Details in section 1 and `app.md`. ## 4. Content metadata at review-request time - The app's `ReviewTargetLoader` loads the revision and produces the review title and a typed `TargetContext { folder, modelId, title, author }` (`toCmsReviewTarget`, `toWbPageReviewTarget`), stored on the review as `targetContext`. - `folder` is `{ id, type }` with the type `cms:` or `wb:page`, or `null` for the root folder. `modelId` is the CMS model id (the page model for pages). `author` is the revision's `createdBy`. - Routing reads the requester (the review's `createdBy`) and their teams, and the folder chain from `ReviewTargetFolderChain` (the folder and its ancestors), when a step is reached. Read access of candidates goes through `ReviewTargetReadAccess`. - Locale is not a routing dimension (CMS entries have none). ## 5. UI integration points - The shared review presenters and views live in `app-workflows` (`review/`); the apps pass their own use cases in. `EditorReviewSession` and `EditorReviewBar` give each editor one presenter, one bar and the details drawer; `ReviewListView` and the widgets serve Content Reviews and the dashboard. See `app.md` sections 2 and 4. - CMS entry editor: `CmsEntryFormPresenterReviewDecorator.loadRevision` inits the session with `{ namespace: cms., targetRevisionId, targetTitle, canRequest, isPublished }` for any revision status and applies `allowsEditing` and `allowsPublishing` to `canSave` and `canPublish`. Singleton models are skipped as before. - WB page editor: `PageEditorTopBar` inits the session with `{ namespace: "wb.page", targetRevisionId: page.id, ... }` for every page status and disposes on unmount; `PageEditorLayout` is the one source of the read-only flag. - Pages and entries lists: the field selections add `system.workflow { workflowId reviewState stepId stepName stepState }` and the row mappers read it; the cache writers keep it current after actions and incoming notifications. - Live change and reload (8b): each app subclasses the shared `ReviewChangeMessageHandler` (the silent `workflows.reviewChanged`, D160) and gives its editor an `IReviewContentReloader` (`contentReloader` of the init params, D163): the CMS one lives in the form presenter decorator, the WB one is `WbPageContentReloader`. See `app.md` sections 2 and 4. - Workflow editors (9a): each app mounts the shared `WorkflowEditorView` with its own `WorkflowEditorAppAdapter`; the editor use cases are shared, and each app registers its editor gateway under `WorkflowEditorAppGateway` (D184; see `app.md` section 3). CMS: the models come from `listCmsEntryWorkflowModels` (paged, server-searched, so the client no longer filters publishable models by literal tags). WB: the single item Pages. The menu item and the config queries show only with the `editor` permission; the route shows the no-access view without it (9c, D178). 9b: each app also supplies its folders to the editor through the adapter (`getFolderType`, `listFolders`), so `app-workflows` does not depend on `app-aco`; the People step's Assignment and Test routing tabs run on the per-app `inspectRouting` and `folderExists` operations. ## 6. Differences between the apps and known gaps - CMS and WB share the engine, the single CMS handlers (revision create, save block) and the admin review core; what differs is the adapter (namespace, target reader, folder type, links) and the operation names. The CMS has two queries WB lacks: `listCmsEntryWorkflowModels` (WB has one `Pages` row) and `listCmsEntryBlockingReviews` (the bulk trash pre-check of all loaded CMS rows, D164). - Bindable models: `isBindableModel` (`api-headless-cms-workflows/src/utils/`: not private, no `$publishing:false` tag) is the one rule; `ListCmsEntryWorkflowModelsUseCase` also leaves out singleton models (tag `CMS_MODEL_SINGLETON_TAG`) without changing `isBindableModel`, which `ListCmsEntryReviews` shares. - Pages are a private CMS model and not exposed through CMS GraphQL, so only programmatic CMS calls on the page model bypass the page rules. `DeletePage` is the only permanent page delete; a future trash-bin purge for pages must run the review cleanup too. - The route constant `Routes.Pages.WorkflowStateList` (`app-website-builder-workflows/src/routes.ts`) keeps its old name on purpose (R206). - Page experiments and variants are not covered by the review rules yet: `variants-review-gap.md`.