Workflows

Loads all the user's workflow templates, including any the user has been given access to.

The workflow templates are ordered with the user's own first.

Workflows returned from this method do not contain any detailed metadata like; workflow steps. To obtain these details, see Workflows.load.

See:

• Workflows.owned
• Workflows.shared

Creates a workflow template or single-use workflow.

For clarity, the description below mentions "staggered workflows" - staggered workflows are workflows that have mandatory or gatekeeper roles - which both prevent the workflow from continuing to the next step until those users have clicked their "FINISHED" button within the app. This means that you can control who sees the proof and when. But be careful with this feature, as often times people make a whole bunch of users "mandatory", which causes the workflow to only continue once ALL the users have clicked their "FINISHED" button. Which often times slows down the reviewing process if any number of those users never take a look at the proof.

Workflows always need an approver - thus, the approver option is required for all workflows. The approver option takes WorkflowUserDefinition (without a role, as their role is assumed approver).

The reviewers option expects a list of WorkflowUserDefinition which are all added to a single workflow step. This option is shorthand for providing a single step as the steps option.

The steps option expects a list of WorkflowStepDefinitions. This allows you to create much more advanced workflows (like staggered workflows). It also allows you to name your steps.

For single-use workflows, you only need to provide the approver, and optionally any other reviewers who need to see it. Simply pass the Workflow object that resolves from this method to the Proofs.create method to create a proof with a custom workflow.

In some cases you want to be able to create a workflow to be used when creating a proof (like a single-use workflow), but at the same time, save it as a template so it can be quickly used later. In this case simply set the save option to true. This will create a workflow template, and immediately clone it so you can pass it to Proofs.create. You must also provide a title so the user can easily find the workflow template in-app.

For workflow templates simply provide a title, an approver and any other reviewers/steps. If you want to use the workflow template for a proof, at a later stage, call Workflows.use which will give you workflow you can pass to Proofs.create.

There are a few steps needed to create & configure a workflow, and if any one of them fails, the SDK will automatically clean up after itself.

Example:

const workflow = await client.workflows.create({
  name: 'My multi-step staggered workflow',
  steps: [
    {
      users: [
        { email: 'first-reviewer@example.com' },
        { email: 'another@example.com' },
        { email: 'somebody-important@example.com', role: 'mandatory' },
      ],
    },
    {
      name: 'This step has a name!',
      users: [
        { email: 'must-wait@example.com' },
        { email: 'another-vip@example.com', role: 'mandatory' },
      ],
    },
  ],
  approver: {
    email: 'my-approver@example.com',
  },
});

const workflow = await client.workflows.create({
  name: 'Just a bunch of reviewers, and an approver',
  reviewers: [
    { email: 'first-reviewer@example.com' },
    { email: 'another@example.com' },
  ],
  approver: {
    email: 'my-approver@example.com',
  },
});

const workflow = await client.workflows.create({
  name: 'Reviewers with the permission to invite others',
  reviewers: [
    {
      email: 'first-reviewer@example.com',
      role: 'mandatory', // ensures the reviewer has the chance to invite who they need before the proof is sent to the approver for review
      permissions: {
        inviter: true,
      },
    },
    { email: 'another@example.com' },
    { email: 'just-one-more@example.com' },
  ],
  approver: {
    email: 'my-approver@example.com',
  },
});

const workflow = await client.workflows.create({
  save: true,
  name: 'The workflow name',
  reviewers: [
    { email: 'user-by-email@example.com' },
    { id: 'ULVRHSLLP69ACHCT' },
    { email: 'mandatory-reviewer@example.com', role: 'mandatory' },
  ],
  // or
  steps: [
    {
      users: [
        { email: 'user-by-email@example.com' },
        { id: 'ULVRHSLLP69ACHCT' },
        { email: 'mandatory-reviewer@example.com', role: 'mandatory' },
      ],
    },
    {
      users: [
        { email: 'a-gatekeeper@example.com', role: 'gatekeeper' },
        { email: 'default-role@example.com', role: 'reviewer' },
        {
          email: 'an-inviter-gatekeeper@example.com',
          role: 'gatekeeper',
          permissions: {
            inviter: true,
          },
        },
      ],
    },
  ],
  approver: {
    email: 'my-approver@example.com',
    // or
    id: 'UUHRC2X2JMR7WC7S',
    permissions: {
      inviter: true,
    },
  },
});

See:

• Workflows.use

Deletes a workflow template.

Duplicates a workflow template and returns the duplicated Workflow.

Loads a workflow/workflow template (by it's id).

Returns a fully populated Workflow object, containing the steps, and users in those steps. If the workflow does not exist, the promise is rejected. This only happens if a workflow template is deleted by the owner.

Loads all the user's own workflow templates.

Workflows returned from this method do not contain any detailed metadata like; workflow steps. To obtain these details, see Workflows.load.

Loads all the workflow templates.

Workflows returned from this method do not contain any detailed metadata like; workflow steps. To obtain these details, see Workflows.load.

Creates a workflow from a workflow template, which can be used when creating a proof.

Example:

const proof = await client.proofs.create({
  // ...
  workflow: await client.workflows.use('W8VN0H4UYFVV1VQL'), // where "W8VN0H4UYFVV1VQL" is the workflow template id
});