Opal Workflows API

## Workflows Overview In 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 for Workflow on Moments which means there will be a period of time during which the Phase Items API remains the API for Content Workflows.* ### Workflow / Phase Items Translations The 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_. ### Context Workflows from the v2 Workflow API have an optional `context` relationship. These contexts tie workflows to the resources against which 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 broadly in more than one context. Although a workflow can conceptually be created without a context, it must be given a context before it can be started. Currently, the capabilities supported by contextless workflows are not built out in the Opal Platform. API requests should be made to create 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 must request 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 retrieve details for that Moment. See the documentation on [`POST` **Create a Context**](#tag/Workflows/operation/CreateContextV2) for more information. ### Resources A `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 user of the workflow -- For a Moment Workflow, perhaps the due date is the `scheduled_date` of the Moment, or perhaps the exact date is not important. Assignments are completed by `POST`ing `response`s. Circuit breakers and tasks can be completed and approvals can be approved 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 with the most recent response representing the current state of the assignment. #### Circuit Breaker Circuit breakers generally just contain one assignment. When the assignment is completed, the circuit breaker is completed and the following stage becomes active. Circuit breakers allow workflows to pause between any two stages and they are used to create the initial pause before a workflow is started (giving users time to build a workflow out before beginning work against it). #### Approval Approval stages can contain any number of approval `assignment`s. They can be configured such that all of those approvals must be given for the workflow to progress (`metadata.completion_rules.all`) or they can be configured such that the workflow progresses after any one of the approvals is given (`metadata.completion_rules.one`). ##### Approval Response Each 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 state of the approval: approved, declined, or in the absence of a response, simply incomplete. #### Task Task stages can contain any number of task `assignment`s. A task stage is complete after all assignments within it have been completed. ##### Task Response Each 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 the task: complete or incomplete. ### Templates Creation of a new workflow often involves creating a handful of the same resources every time. For this reason, there are templates the allow you to create one of two types of workflows more easily. You always get a `circuit_breaker` with one assignment at the start and 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. ### Rewinding Workflows 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 approval stages (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 the workflow 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.