Skip to main content
Guide · workflows

Use when

The person wants a job written as steps with its cost known first, such as reading new Files and extracting what they say. They may then want it run.

Looking for something else?

A one-time extraction or crawl, which you run directly (recipe Extract entities from Files). Changing a Shape (recipe Change a Shape and publish it).

​
Outcome

A published version of the workflow, with a plan the person has read. When the person agrees, it also has a run that you have followed to its end. The person knows each step’s cost, which steps have no figure, and that the version runs nothing until they start a run.

​
Before you start

  • Know the job in the person’s words: what starts it, what it reads, what it makes and who hears about it.
  • Know which Shape and which collection it uses. Ask if you are not sure.
  • Check what you may do. A project editor, admin or owner changes workflows, and a key needs workflows.write (card rule workflow.10).

​
Steps

  1. Read the steps you can use: penumbra workflows catalog. Read one with penumbra workflows catalog --step <operation>.
  2. Write the workflow file. Give each step only the inputs it needs, and route every outcome the catalog lists for it (card rules workflow.2 and workflow.3).
  3. Check it: penumbra workflows check --file workflow.json. Fix each problem it prints, then check again. Checking is free.
  4. Save it: penumbra workflows create --file workflow.json. Later edits use penumbra workflows update <workflow> --file workflow.json.
  5. Publish it: penumbra workflows publish <workflow>. A draft with problems is refused, and the problems are listed.
  6. Plan it: penumbra workflows plan <workflow>. Planning is free.
  7. Tell the person the cost of a run and the most a month can cost. Say which steps have no figure and why. Say that the version does nothing by itself. Wait for a clear yes before you go on to anything that spends.
  8. Only when the person says yes, ask them to start the run, or start it as them when they have signed in: penumbra workflows run <workflow> --input name=value. Add --watch to follow it. A run needs a signed-in person; a key is refused (card rule workflow.12).
  9. Follow it: penumbra workflows runs get <run> shows the status, the charge and every attempt. Stop it with penumbra workflows runs cancel <run> if the person asks (card rule workflow.14).

​
Check

  • penumbra workflows show <workflow> shows problems: none and the published version.
  • The plan lists every step. Each step with paid in its effects has a figure or a not_estimated basis that you have explained.
  • The digest you give is the digest of the plan you ran last.
  • After a run, penumbra workflows runs get <run> shows a status that is not pending or running, and a charge that you have told the person.

​
If it goes wrong

​
Worth offering

  • A paid step may have no figure because its scope comes from another step. Offer to read the extraction plan for a sample of the Files first (recipe extract-files).
  • Offer to read the plan together, step by step, before the person decides.

​
Report

Say what the workflow does, what starts it, and which version you published. Give the cost of a run and the most a month can cost, as the plan states them. Name each paid step that has no figure. Say that the version runs nothing until a person starts a run. Give the digest of the plan. If a run started, give its id, its status and what it has charged.

​
Keep going

Workflow · Extraction · Shape · Collection · A step can end in a way the workflow does not handle · A step names an operation this project cannot use · A plan gives a different digest than the one the person saw · A run cannot start because the workflow has no published version · Extract entities from Files