Glossary

User-facing terms:

• Workflow: A sort of document/project: contains all steps and renders as a whole.
  • How users access them:
    • Owner can view and edit secrets
    • Editor can edit steps (that don't require secrets), including uploading files. (Deleting a step that contains a secret can be undone, but the secret will be lost.)
    • Viewer can view all steps and tables
    • Report Viewer can view only the results of all steps that appear in the report. (The default report contains all chart steps.)
  • How users share them:
    • Private workflow: a workflow with an easy-to-guess URL that only collaborators can access.
    • Secret workflow: a workflow with a hard-to-guess URL that anybody (logged in or not) can read.
    • Public workflow: a workflow with an easy-to-guess URL that anybody (logged in or not) can read. (If this workflow was previously a secret workflow, the old secret link will redirect to the public link.)
  • How users find them:
    • Community workflow: a workflow that Workbench staff flagged to appear in every user's "Community workflows" list. Should be public.
    • Collaborator: a workflow owner gave this user permission; this user can now see the workflow in the "Shared with me" page. (A Report Viewer is a collaborator who can't access most workflow data.)
  • How they behave:
    • Normal workflow: editors and owners can edit the workflow (at the same time); viewers see the changes in real time.
    • Lesson workflow: the first access to a lesson URL creates a session-linked (or if the user is logged in, user-linked) temporary workflow. The workflow has an ID (for network requests), but that ID isn't reflected in the UX. If the user isn't logged in, the workflow will disappear when the session expires or is deleted. The user can't share the workflow. The user can duplicate a lesson workflow to create a normal workflow.
• Step: Unit of computation. Its input is a Table and its output is a Table. It holds a module, parameters and secrets.
• Module: Function used in a Step. (It's a big block of Python code.) Each module accepts a certain set of parameters.
• Params: Parameters to a module, stored on a Step. (We store them as JSON.)
• Secrets: Special parameters that are as restrictive as possible while fulfilling the module's purpose. The workflow owner can set secrets (but usually can't read them). Other workflow viewers can see minimal identifying information ("logged in as foo@bar.com"). The module can see enough information to make API calls on behalf of the user -- in the case of OAuth2, the module sees client ID (for the module), client secret (for the module), and recent user access token (but not refresh token).
• Tab: A visual helper for organizing steps.
• Table: The data before and after each step.
• Report: Sequence of blocks
• Block: One element of a report. A block can be a Chart Block, Table Block or Text Block.

Developer-facing terms:

• Delta: Database row containing a valid command -- one that can be applied that will change the workflow. Users create (and apply) Deltas using API methods. Everything the user can "undo" is stored in a Delta.
• Command: A Delta's underlying logic. (Each Delta refers to a Command -- for instance, "Add Step".) Commands are used to validate and create a Delta, and to apply its "forward" (do) and "backward" (undo) logic.
• Update: Package sent by the server that modifies all clients' Workflow state.
• Mutation: Client-side optimistic update. The server ignores mutations (except to pass mutation IDs). The client stores "pending mutations" to derive optimistic Workflow state. For instance, when deleting a Step, the client stores a pending "delete step" mutation in its state (with a mutation ID); then it uses the server's API to create a "delete step" delta row in the database; then it waits for the server's "delete step" Update to arrive; then it applies the Update and deletes its local "delete step" mutation.