social-media/docs/FEATURES/approval-workflow.md

Approval Workflow

Status

Draft

Goal

Define how a workspace decides whether a ContentItem is approved.

Approval workflow is one part of the normal ContentItem lifecycle:

Production -> Approval -> Publication

Approval workflow is separate from production workflow. Production covers how content is planned, created, revised, and prepared before approval. Publication may later become its own workflow for scheduling, publishing, and post-publish corrections.

User Stories

• As a workspace owner, I want to configure the approval mode for my brand workspace so that approval fits the way my organization works.
• As a manager, I want to require approval before content can be scheduled or published so that unapproved content does not go out.
• As a manager, I want optional approval for simpler workflows so that teams can collect sign-off without blocking publication.
• As a manager, I want multi-level approval steps so that different people or groups can approve content in sequence.
• As an approver, I want to review the content, discuss changes, and approve when ready so that the approval decision is clear.
• As a collaborator, I want approval discussions with mentions so that I can involve the right people without changing the approval state.
• As an internal team member, I want team-only comments so that internal discussion can happen without exposing it to client users.
• As a publisher, I want to be notified when final approval is complete so that I can schedule or publish the content.
• As a workspace owner or admin, I want to reopen approval after changes so that approval history remains intact while edge cases can still be handled.
• As an external approver, I want to review and approve a specific content item through a secure magic link so that I do not need a full workspace account.

Reviewable Object

The object being approved is a ContentItem.

Approval decisions, comments, mentions, notifications, timestamps, audit history, and approved content snapshots must remain traceable to the ContentItem.

A ContentItem can have only one active approval workflow instance at a time.

When approval completes, the approval workflow instance remains attached to the ContentItem as history. If an admin reopens approval later, a special approval step is appended to the same history instead of deleting prior approval history or restarting the workflow.

Approval workflow history is visible to all users who can view the ContentItem. Approval actions remain permission-gated.

Lifecycle States

ContentItem uses a fixed set of lifecycle states:

• Draft
• In production
• In approval
• Approved
• Scheduled
• Published

Lifecycle state meanings:

• Draft: the content item exists after a client or team orders, requests, or creates the publication.
• In production: the content item is in production workflow. This applies when authored media or preparation work is required, such as video, photos, copywriting, design, or other production tasks.
• In approval: the content item is in approval workflow.
• Approved: the approval workflow is complete.
• Scheduled: the content item is on the calendar and ready to be published at its scheduled date and time.
• Published: the content item was successfully published to all intended channels.

Production workflow is optional for a ContentItem. Simple content can move from Draft directly to In approval when no full production workflow is needed.

Workspace Configuration

Approval behavior is configured per workspace.

A workspace is the brand boundary. The approval workflow configuration is workspace-wide in v1.

Configuration changes apply to new content and to existing content currently in approval workflow. Content that is already Approved, Scheduled, or Published is not recalculated.

When configuration changes affect existing content in approval:

• previous approval decisions are preserved in history
• current required approval steps are recalculated from the new configuration
• if preserved approvals already satisfy the new requirements, the workflow completes and the ContentItem becomes Approved
• if recalculation creates a new pending current step, that step's approvers are notified immediately

Approval Modes

Each workspace supports these approval modes in v1:

• None: no approval workflow is used. Content skips only the approval workflow and can become Approved without approval actions. This does not bypass production workflow when production work is required.
• Optional: a basic one-step approval workflow is created automatically. Approval actions are available, but approval is not required before publication workflow.
• Required: a basic one-step approval workflow is created automatically. At least one approval is required from any workspace member with approve content permission before the item can become Approved or Scheduled.
• Multi-level: approval is split into one or more ordered steps, and each step defines who can approve that step.

Optional and Required use one approval step. More flexible approver targeting only applies to Multi-level. If a workspace needs custom approver targeting, it should use Multi-level with one or more steps.

Approval Steps

Approval steps have their own status:

• Pending
• Approved

Multi-level is step-based and sequential. Later steps cannot be approved until earlier steps are complete.

Each multi-level step can target:

• Role: a named workspace role with a set of permissions, such as Writer, Contributor, or Approver.
• Membership: a workspace membership category, such as Team or Client.
• Member: one specific workspace user.

For Role and Membership targets, the user must match the step target and have approve permission. Membership alone does not grant approval permission; for example, a Client member may be a contributor or an approver depending on their permissions.

For Member targets, the selected user can approve that step because they were explicitly assigned.

By default, one matching approver can complete a step. When a step targets a role or membership group, the workspace can optionally configure how many matching approvers are required for that step.

Admins can approve any approval step.

Approval Decisions

Approval workflow supports one formal decision in v1:

• Approve

Reject and explicit Request changes decisions are not part of v1. Approvers should use comments, discussions, and mentions to coordinate changes until the current step can be approved.

Approval decisions must record:

• actor
• decision
• timestamp
• related ContentItem
• approval-controlled content version or snapshot that was approved

A pending step must not be treated as approved.

Approval-Controlled Content

Approval-controlled content includes:

• caption, copy, and text
• attached media and assets
• selected channels and networks
• content title or name
• production output and revisions

Approval-controlled content excludes:

• scheduling date and time
• internal comments and discussions

If approval-controlled content is edited while the item is In approval or Approved, the approved status is removed from the current approval step and the step becomes pending again. If the item was Approved, it moves back to In approval.

When an edit invalidates approval, the current step's approvers are notified immediately.

If content is Scheduled, only an admin or workspace owner can change approval-controlled content. This scheduled-content edit policy needs validation with SaaS customers.

If content is Published, approval-controlled content is read-only except for admin or workspace owner corrections. Corrections to published content likely require an immediate force or push update through publication workflow.

Approval Options

Each workspace can configure these approval options:

• schedule posts automatically on approval
• lock content after approval
• send automatic reminders for pending approvals

If schedule posts automatically on approval is enabled, final approval moves the ContentItem to Scheduled when it already has a planned publish date and time. If no planned publish date and time exists, the item remains Approved.

If lock content after approval is enabled, approval-controlled content is locked after final approval. Scheduling fields remain editable.

If automatic reminders for pending approvals is enabled, the current step's approvers are reminded daily while the step is pending. Daily reminders start after the original approval notification.

Reopening Approval

Users with admin permission can reopen approved content for approval.

Reopening approval appends a special approval step to the existing workflow history. The special reopen step is approved by an admin. Admins can use comments and mentions to coordinate with the needed people before closing the approval workflow again.

Discussions And Mentions

Approval comments and discussions are attached to the overall approval workflow instance, not to a specific step.

Any workspace user with access to the ContentItem can participate in approval discussions. Approval actions remain limited to the current step's approvers and admins.

Approval comments can be visible to everyone with access to the ContentItem or marked as team-only. Team-only comments are visible only to users with Team membership and are hidden from Client membership users.

Approval comments should support direct mentions, such as mentioning a person or group with @, to notify them directly.

Mentions must respect comment visibility. A comment cannot mention a user or group that cannot see that comment.

Notifications

Notification rules:

• when a ContentItem enters In approval, the current approval step's approvers are notified immediately
• when an approval step is approved and another step remains, the next step's approvers are notified
• when the final approval step is approved, users with publish permission for the workflow are notified
• when configuration recalculation creates a new pending current step, that step's approvers are notified immediately
• when an edit invalidates approval, the current step's approvers are notified immediately
• when automatic reminders are enabled, the current step's approvers are reminded daily while the step is pending
• when a comment mentions a user or group, mentioned users are notified if they can see the comment

Magic Approval Links

Approval workflow supports magic approval links for external approvers.

Magic links are intended for Optional and Required approval modes. They act on the current approval step when the link is opened.

A magic approval link:

• grants access only to the specific ContentItem for which the link was created
• does not grant broader workspace access
• allows the recipient to approve and comment on that approval workflow
• is created for a specific recipient email address
• is sent automatically by the app
• expires after 3 days
• expires immediately after it is used to approve
• is not consumed by commenting
• can be revoked by admins or workspace owners before it expires or is used to approve

Possession of a valid, unexpired magic approval link is sufficient to access the linked approval page. The recipient does not need to create an account.

For comment visibility, magic link recipients are treated as Client membership users. They cannot see or create team-only comments.

Magic link activity must record at least the recipient email for audit history.

Magic approval link events are recorded in approval workflow history, including created, sent, revoked, expired, and used events.

Magic approval links can be created or sent by users with publish permission, workspace owners, or admins.

Business Rules

• Approved must come from explicit workflow rules, not optimistic UI state.
• Approval requirements are scoped to the workspace.
• A ContentItem has at most one active approval workflow instance.
• Approval mode None creates no approval workflow instance.
• Approval mode Optional creates a basic approval workflow instance but does not block publication workflow.
• Approval mode Required blocks approval and scheduling until its single approval step is approved.
• Approval mode Multi-level blocks approval and scheduling until every configured step is approved.
• Approval history must remain visible after revision, approval, scheduling, or publishing.
• Approval-controlled content changes must invalidate affected approval while the item is In approval or Approved.

Open Questions

• Should publishing behavior become a separate PublishingWorkflow feature?
• What is the exact data model for approval step configuration?
• How should scheduled-content edit policy work after validation with SaaS customers?
• What publication-system behavior is required for correcting already published content?