Clarify the task and decision
This guide turns drupal implementation guide into a reviewable operating workflow. It connects domain decisions, ownership, evidence, and acceptance so the result continues to work in production.
Use Drupal revisions, content moderation, and permissions to separate generation, specialist review, and publication.
Practical workflow
- 1
Inventory source types, identifiers, fields, locales, owners, and publication states.
- 2
Choose the delivery pattern from volume, latency, editorial control, and failure tolerance.
- 3
Map the source record to a separate language-version record with durable linkage.
- 4
Add authentication, idempotency, retry, cache invalidation, logging, and access controls.
- 5
Test publication, source changes, unavailable results, rollback, keyboard operation, and monitoring before release.
Worked example or tool
A moderated content type shows fields, roles, revisions, delivery, and rollback. In the tool, also record the baseline, owner, decision, evidence, open issue, and approval date. Use a real page or transaction so the team sees dependencies, exceptions, and the maintenance work that follows release.
| Decision point | Record | Acceptance criterion |
|---|---|---|
| Baseline | Observed current state | Source and date recorded |
| Decision | Selected option and rationale | Risk and audience considered |
| Evidence | Test, document, or measure | Reviewable and version-specific |
| Approval | Name, role, and date | All mandatory criteria met |
Create a content model that preserves provenance
Create an accessible-language content type or a structured entity with an entity reference to the authoritative source. Include source revision ID, locale, language mode, result ID, review state, glossary version, risk level, approvers, and next review trigger. Use paragraphs or structured fields for headings, lists, links, notices, downloads, and contact information. A single unrestricted rich-text field makes field-level validation, reuse, and safe rendering more difficult.
Choose deliberately between Drupal’s translation relation and a separate related entity. Standard translation works when field structure and editorial lifecycle remain equivalent. A separate entity is safer when the accessible version combines, reorders, or explains source fields and needs different moderation. In either case, keep the source revision immutable for the transformation and display stale status when the current source no longer matches it.
| Design choice | Use when | Required safeguard |
|---|---|---|
| Content translation | Structure and lifecycle remain equivalent | Revision translation affected and moderation tested |
| Related entity | Structure, ownership, or review differs | Explicit source reference and reciprocal navigation |
| Paragraph mapping | Source contains reusable structured blocks | Unsupported bundle blocks or flags generation |
Separate creation, specialist review, and publication
Configure Content Moderation states such as requested, generating, draft, subject review, language review, approved, published, stale, and failed. Define transitions for dedicated roles and verify them with Drupal permissions and access handlers. The API integration account can create and update a draft but cannot approve or publish. A subject reviewer cannot approve their own high-risk generation unless the documented risk policy permits it.
Enable revisions and ensure every transformation, comment resolution, status transition, and source rebase creates a revision with author and timestamp. Build a review view that shows source and draft, differences, warnings, links, and the rendered result. If the source changes, mark the active draft and published version appropriately and block publication until a reviewer resolves the mismatch.
- 1
Configure entity fields, validation, revisions, and source relationship.
- 2
Create moderation states and role-specific transitions.
- 3
Generate a draft through a restricted queue worker.
- 4
Complete subject and language reviews on one identified revision.
- 5
Publish, index, and retain the source-to-release audit trail.
Deliver with Drupal cacheability and accessibility intact
Attach cache tags for the source entity, source revision relationship, language entity, referenced paragraphs and media, glossary configuration, and renderer. Use cache contexts for locale and any legitimate access variation, but do not make approved public pages depend on user-specific generation state. Invalidate affected pages through entity changes or queue completion, and keep the last approved revision visible while a replacement is reviewed.
Render language navigation as ordinary links through Drupal routing and language-aware URL generation. Add reciprocal source links, alternate-language metadata, breadcrumbs, and sitemap entries. Verify heading hierarchy, link purpose, focus order, status messages, and form error association in the final theme. Sanitise API output through allowed structured fields and Drupal’s rendering system. Never mark generated HTML safe merely because it came from a trusted server.
Cache tags cover source, language version, components, media, glossary, and renderer.
Queue processing cannot publish content or clear the last approved result prematurely.
Language routes and source links work without JavaScript.
Text formats and render arrays prevent unsafe markup.
Search indexes only the approved revision and removes retired routes.
Prove permissions, revisions, and rollback
Kernel and functional tests should cover field validation, access control, moderation transitions, revision creation, stale-source detection, queue retries, cache invalidation, route access, and rendering of every supported component. Test Drupal cron and external queue runners, including overlapping workers and repeated jobs. Browser tests should exercise the complete editorial workflow with each role and keyboard-only frontend use.
Release with configuration management, update hooks, credential rotation, queue dashboards, failed-job replay, log minimisation, database backup, and a rollback runbook. Import configuration into a production-like environment and confirm that existing bundles, translations, permissions, and views remain intact. Acceptance includes restoring a previous approved revision, rebuilding caches and indexes, and confirming that public URLs and audit records remain correct.
Roles, evidence, and approval
Keep generation separate from publication. A successful response is a draft, not an approval. Store the source identifier and version, transformation settings, result identifier, review state, approver, and publication time. When the source changes, mark the language version for review instead of silently replacing approved content. This makes rollback and audit possible across platforms.
Operations and maintenance
The work does not end at publication. Link the language version or configuration to its source, monitor quality and service measures, and define concrete review triggers. Triggers include source changes, legal changes, new audience needs, recurring support questions, technical changes, and incidents. A named owner evaluates the trigger, opens a new revision when needed, and records renewed approval.
Release checklist
The integration uses durable source identifiers.
Credentials are stored server-side and rotated.
Timeout, retry, and rate-limit behavior are defined.
Repeated requests are idempotent.
Generated content enters a review state.
Source changes invalidate or reopen the version.
Language navigation works by keyboard and assistive technology.
Monitoring covers failures, queues, latency, and stale content.