Opal Workflows API

## Workflows OverviewIn Opal, a workflow is an arrangement of tasks and approvals required to progress through the lifecycle of a StoryFirst resource. **Historical Note:***The v2 Workflows API will supersede the v2 [Phase Items](#tag/Phase-Items) API, although initial rollout will only include support forWorkflow on Moments which means there will be a period of time during which the Phase Items API remains the APIfor Content Workflows.*### Workflow / Phase Items TranslationsThe following resources described below for the v2 Workflows API have fairly direct translations to the older Phase Items API.- A _workflow_ was known as a _phase group_.- A _stage_ was known as a _phase_.- An _assignment_ was known as a _phase item_.### ContextWorkflows from the v2 Workflow API have an optional `context` relationship. These contexts tie workflows to the resources againstwhich the workflow is being performed. Currently only the **Moment** context is supported.A workflow without a `context` is a reasonable thing to think about: Such a workflow might have common stages that apply broadlyin more than one context. Although a workflow can conceptually be created without a context, it must be given a context before it canbe started.Currently, the capabilities supported by contextless workflows are not built out in the Opal Platform. API requests should be made tocreate contexts for all workflows before building them out or starting them.**Important:** Contexts tie workflows to resources from neighboring services; although Opal has one coherent v2 API, a client mustrequest StoryFirst resources (like `moment`s) from other services rather than `including` them on Workflow requests. For example,a Workflow might have a `context` with a `moment_id` of `'3432'`; the client would make a request to `moments/v2/3432` to retrievedetails for that Moment.See the documentation on [`POST` **Create a Context**](#tag/Workflows/operation/CreateContextV2) for more information.### ResourcesA `workflow` is arranged into `stage`s, each of which is a `circuit_breaker`, an `approval` stage, or a `task` stage.All stages can optionally specify a `due_date`, but if `null` then the due date is left up to interpretation of the userof the workflow -- For a Moment Workflow, perhaps the due date is the `scheduled_date` of the Moment, or perhapsthe exact date is not important.Assignments are completed by `POST`ing `response`s. Circuit breakers and tasks can be completed and approvals can beapproved or declined. An approved response can be superseded by a following declined response on the same assignment.Similarly, tasks can be "undone" after being marked complete by sending a follow-up response. Responses are a ledger withthe most recent response representing the current state of the assignment.#### Circuit BreakerCircuit breakers generally just contain one assignment. When the assignment is completed, the circuit breaker is completedand the following stage becomes active. Circuit breakers allow workflows to pause between any two stages and they are usedto create the initial pause before a workflow is started (giving users time to build a workflow out before beginning workagainst it).#### ApprovalApproval stages can contain any number of approval `assignment`s. They can be configured such that all of those approvalsmust be given for the workflow to progress (`metadata.completion_rules.all`) or they can be configured such that the workflowprogresses after any one of the approvals is given (`metadata.completion_rules.one`).##### Approval ResponseEach approval `response` can be either `approved` or `declined` and it can optionally contain a message from the approver.As noted above, any number of responses can be given on a single assignment; the most recent response represents the stateof the approval: approved, declined, or in the absence of a response, simply incomplete.#### TaskTask stages can contain any number of task `assignment`s. A task stage is complete after all assignments within it have beencompleted.##### Task ResponseEach task `response` can be either _complete_ (`complete: true`) or _incomplete_ (`complete: false`).As noted above, any number of responses can be given on a single task; the most recent response represents the state of thetask: complete or incomplete.### TemplatesCreation of a new workflow often involves creating a handful of the same resources every time. For this reason, there are templatesthe allow you to create one of two types of workflows more easily. You always get a `circuit_breaker` with one assignment at the startand then you get either an `approval` or a `task` `stage` next, again with one assignment. All assignments start out unassigned.See the documentation on [`POST` **Create a Workflow**](#tag/Workflows/operation/CreateWorkflowsV2) for more information.### RewindingWorkflows can be "rewound" to undo some portion of them. **The big caveat being:** You are not allowed to rewind back to the start of (or before) a completed final approvel stage. Final approvalstages (i.e. the last approval stage in a workflow) are special because they can have side effects that cannot be taken back --if workflow completion resulted in publishing to a third party platform, for example, then rewinding back to an unapproved state for theworkflow would leave the workflow unrepresentative of the fact that something had already been published.See the documentation on [`PATCH` **Rewind a Workflow**](#tag/Workflows/operation/RewindWorkflowV2) for more information.