← Atlas Journey · Docs

Frozen document. Dates and status refer to its original source. Private resources and unreviewed images are unavailable.

Contentful form contract and release lifecycle

Status: accepted architecture and locale scope. The owner accepted the form design and explicitly added US Spanish, confirming en-US and es-US. The authoritative decision is Decide the Contentful form contract and publishing lifecycle. Inputs are the accepted demo scope, role matrix, record ownership, fictional rules, and completed Contentful/Camunda research. This document is a design contract, not the final implementation spec.

Rendering and authoring

Use a custom React renderer with an allowlisted component registry. Author forms as linked Contentful entries for forms, sections, fields, option groups, and instructional copy. Compile those entries into a versioned JSON form definition for the renderer. Portal copy and configurable content blocks also come from Contentful; routing, authentication, component implementations, and business actions remain code-defined.

Atlas uses server-driven UI for workflow screens and forms. Contentful holds supported component selection, section and field order, display conditions, input constraints, localized validation messages, and configurable page content. The BFF compiles and pins the published content, then returns a screen model for the actor's current journey or Camunda task. The SPA renders that model through its component registry; it does not choose a form from hardcoded product or task branches. Navigation and reusable shell controls may remain code-defined, but customer-facing workflow copy and configurable content must come from Contentful releases.

The initial component vocabulary covers text, multiline text, dates, numeric/currency inputs, selects/radio groups, checkboxes/declarations, repeatable groups, authorized record selectors, document-upload controls, and read-only summaries. File-upload controls exchange authorized document references; private bytes do not pass through Contentful or become task variables.

Content authors can change labels, help text, field order/grouping, options, and supported conditions within the approved answer/binding schema. New fields supported by that schema can be released without changing renderer code. New component types, new canonical business bindings, or changed domain rules require the corresponding code/API contract to support them before release. Authors cannot introduce executable JavaScript, arbitrary HTML, arbitrary API endpoints, or new workflow actions.

Use a small declarative condition vocabulary, such as equality, membership, presence, and all/any combinations. No authored executable expressions. The compiled definition includes stable field keys, value types, conditions, constraints, error-copy keys, and declared data bindings. Display conditions never grant access to data. The backend supplies only fields the actor may see and accepts only fields/actions the actor may submit.

Field validation authored in Contentful includes requiredness, supported length/range/pattern constraints, option membership, cross-field conditions within the approved declarative vocabulary, and en-US/es-US error copy. Release compilation rejects unsupported or contradictory rules. The BFF evaluates the pinned rules on save and submit and returns stable field error codes and parameters; the SPA may evaluate the same rules for early feedback. Saving an incomplete draft remains possible: requiredness and task-completion rules apply when the user submits or completes that step, while shape, type, permission, and revision checks also apply on save. Server-owned security, workflow eligibility, submission-contract checks, and domain invariants still apply and cannot be weakened by CMS content.

Support US English (en-US) and US Spanish (es-US) in the initial demo, with en-US as the default. Both locales are part of acceptance coverage. Require keyboard operation, semantic labels/groups, accessible error summaries and focus behavior, and responsive layouts in both languages. Exact accessibility qualification belongs to the verification decision.

Locale contract

Use field-level localization for authored labels, instructions, help, option labels, declarations, and validation copy. Stable field keys, business bindings, option values, conditions, identifiers, and rule outcomes are language-independent. The same field has translated presentation, not a separate Spanish business definition.

Each immutable release bundle contains both locale variants and their required messages and dependencies. Validate explicit translation completeness for both before activation. Contentful fallback output must not be mistaken for a completed Spanish translation. A partial locale publication or missing translation blocks the new Atlas release; it does not affect an existing complete release. The adapter must respect the publishing mode available in the selected Contentful environment and verify locale-specific published content. Do not assume account access to an optional locale-based publishing feature.

Offer an English/Español selector and persist an explicit choice for the user, with session preference before sign-in and profile preference after sign-in. With no saved choice, use en-US. Support exactly en-US and es-US as the initial content locales; unknown locale requests resolve to the default with a visible language choice, not a new content locale. No browser-language detection is required for this first contract.

Switching languages re-renders the same pinned release and preserves answers, record identifiers, process/task state, and permissions. It does not start a new application or switch to a newer release. Persist the locale used at submission alongside the release identity so the displayed wording can be reproduced later. Human-entered free text and uploaded documents remain in the language supplied; language switching does not translate customer evidence.

Localize the Atlas shell, form copy, task/status labels, validations, and confirmations. Follow the selected locale for date/number/currency display while submitting canonical typed values; locale changes never convert currency or alter an amount. Backend errors use stable codes and safe parameters that the UI maps to localized messages. Authentication/MFA screens must honor the same supported language choice; IAM-specific configuration is part of the identity decision.

Complete release validation removes the need for silent field-by-field language fallback in applicant forms. If required localized content from a pinned release is unavailable or corrupt, show a recoverable error in the selected language and preserve the draft rather than mixing declaration/instruction languages. Technical diagnostics remain separate from customer-facing messages.

Documentation checked for this extension: Contentful supports selecting locales and retrieving explicit locale maps, and may return fallback content when a translation is absent. The release validator must therefore inspect explicit locale values. Delivery API localization. Where locale-based publishing is enabled, delivery behavior can respect per-locale publishing state; the exact account/API configuration remains a setup check. Locale publishing API update. These are vendor facts; the completeness and switching behavior above are Atlas design choices.

Authoring alternative

Native Camunda Forms/form-js remains a feasible alternative, but Atlas uses a custom Contentful schema and React renderer to keep Contentful's structured authoring and the Atlas component system as the UI contract. Camunda supplies task/process context and custom form references; it does not render these Contentful forms. A freeform JSON-only editing model would reduce entry references but give content authors a less structured editing experience. Neither alternative is selected for the initial form architecture.

Preview, publish, release

Separate draft preview, Contentful publication, and activation of an Atlas form release:

  1. An authorized content author previews draft content with synthetic fixtures. Preview/management credentials stay server-side; previews cannot read customer drafts or evidence.
  2. The author publishes the required Contentful entries. Publication alone does not switch active applications to that content or deploy a BPMN process.
  3. A release operation resolves the full published reference graph, checks for missing/unpublished/cyclic references or changes during capture, and validates component support, schema/binding rules, and compatibility with the declared workflow and submission contracts. Incomplete or incompatible content does not become a release.
  4. Store an immutable, fully resolved release bundle, including the content dependencies required to reproduce it. Required authored assets must have retained immutable representations/references. A release registry records its identity and compatibility manifest; this is a derived published-content artifact, not a second authoring authority or a customer-record store.
  5. Activate the validated release for new work. The content author role already has publishing authority; the initial demo does not add a second approval role. A simple release action/check is sufficient; this design does not assume a paid Contentful workflow feature.

Use the existing backend deployment to host the release resolver/registry as a separate logical module. Contentful remains the authoring source. Its ordinary entry revision or environment alias alone is not the release identity. The completed research explains why historical entry snapshots do not freeze the entire linked content graph.

Pinning and compatibility

Pin a form bundle when the first persistent draft or business case is created. The bundle covers the forms needed by the chosen workflow version, including forms used by later tasks. A submitted draft starts only a compatible process version and keeps its form release; task activation must not silently resolve a newer published template.

Record the release ID, renderer-schema version, compatible process definition/version, submission-contract version, and business-rule version. Exact platform keys are resolved server-side; client-supplied references are not authority. The backend retains the compatible schema/bindings and the renderer supports active releases. Unsupported or missing releases produce a recoverable error while preserving answers; there is no fallback to the latest form.

New content affects new work. Existing drafts and processes retain their pinned release. Retiring a release stops new use but does not delete definitions needed by active work. Automatic migration of existing drafts/processes is deferred. Any future migration needs an explicit compatibility/data-conversion decision.

Runtime binding and validation

The SPA requests an authorized form context through the BFF. The server resolves the actor, business record, employer/personal context, process/task where present, pinned release, current record revision, permitted bindings, and allowed actions. It returns a definition and only authorized business data. The browser does not call privileged Camunda or CMS management APIs directly.

The BFF selects a logical screen/form from the authorized journey and draft state before process start, or from the active Camunda task reference and state after start. It resolves that reference within the case's pinned bundle. A task cannot switch to the latest Contentful form, and the browser cannot supply a different form ID to gain fields or actions. The response includes the resolved component tree, current permitted values, validation metadata, localized content, task and record revisions, and allowed actions. Task completion rechecks the current Camunda task and business record state before applying the submitted action.

The SDUI contract must be proven with a narrow change that needs no SPA page edit: publish a supported field or validation-constraint change in Contentful, activate a compatible release, then show that a new draft uses the new definition while an existing draft keeps its earlier one. Once Camunda is connected, move a case to a request-for-information task and show the BFF returns that task's screen and allowed actions from the same pinned bundle. Verify that a stale or unauthorized task cannot obtain that screen or submit its action.

On save/submit, the server validates the release and record/task relationship, current revision, action, input shape, field applicability, and domain rules. Client validation helps the user correct errors but is not authoritative. CMS-required flags cannot weaken backend business requirements. Private author-preview data and arbitrary extra fields are never accepted as business inputs.

Conditional fields that become inapplicable do not contribute stale answers to the active submission. The server recomputes applicability and applies the approved answer contract. Preserve previously submitted revisions where required by the later audit/retention decision; do not let hidden browser values authorize a domain update.

Drafts and answers persist with the business owner, not in Contentful. A record revision detects conflicting edits; a stale or already-completed task produces a clear conflict rather than a silent overwrite or duplicate action. Exact endpoint/error/idempotency contracts belong to the API/workflow decisions. Return field-level errors and an accessible summary; do not include sensitive server diagnostics in customer messages.

Illustrative contract shape

This example defines the agreed separation, not final endpoint names, Contentful IDs, or Camunda versions. Identifiers below are illustrative.


{

  "release": {

    "formId": "life-application",

    "releaseId": "life-intake-release-1",

    "rendererSchemaVersion": 1,

    "submissionContractVersion": "life-application-v1",

    "businessRuleVersion": "atlas-demo-rules-v1",

    "workflowBinding": {

      "processDefinitionReference": "server-resolved-definition",

      "processVersion": "server-resolved-version"

    },

    "defaultLocale": "en-US",

    "supportedLocales": [

      "en-US",

      "es-US"

    ]

  },

  "definition": {

    "sections": [

      {

        "key": "coverage-request",

        "fields": [

          {

            "key": "requestedCoverage",

            "component": "currency",

            "label": {

              "en-US": "Requested coverage",

              "es-US": "Cobertura solicitada"

            },

            "binding": "application.requestedCoverage"

          }

        ]

      }

    ]

  },

  "context": {

    "businessRecordId": "application-example",

    "recordRevision": 3,

    "taskReference": null,

    "allowedActions": [

      "saveDraft",

      "submit"

    ],

    "locale": "en-US"

  },

  "data": {

    "application": {

      "requestedCoverage": null

    }

  }

}

A draft may have no task yet. Once a task exists, the server verifies it against the business record and permitted actor. Submission sends editable answers, the release/record/revision references, and the intended action; it does not grant authority to rewrite definitions, permissions, or workflow bindings.

Required behavioral examples for later specs