This issue is a high level plan to sort out confusion over names and ids in Projects & Workflows right across the kit repo.

It contains a summary of the standard I want to enforce across the repo, and also a longer explanation to show my reasoning and working out.

It might be helpful to also develop a list of what we need to do to align with the plan - it's not always obvious where work is needed. Documentation, APIs, types and variable names all need to align to this language.

Summary

A local project is any workflow or step which is only executed locally and is not linked to an in-app project.

An app project is any workflow or step which is linked to to an app project on some domain. A Workspace may contain app projects on many domains. A Sandbox is always an app project.

I am imposing the following basic rules:

• A NAME is always a human readable label, with spaces and emojis and stuff. Names aren't really needed in local projects, and are usually cloned from the app. They might be used in logging/reporting, if present
• An ID is always a single-word, slugified, web-safe identifier. It is the primary way that internal structures link to each other. An id may be generated from a NAME. An id is NEVER a UUID.
• A UUID is always a UUID. The point is that a UUID is a not an id, an a UUID is always explicitly named
• An ALIAS is a local-only shorthand for something. It's used exclusively by the CLI as a reference in user commands.

I hope this sounds obvious and intuitive. But when in the weeds of this repo, when working with different data structures, it can be confusing whether you want o use the id or name or uuid or what.

Project

• id: a slugified, single-word identifier for the project. For app projects, this is derived from the project name.
• name: A human readable label for the project. Not used by the CLI - its just decorative metadata.
• alias: alias for the project. Particularly useful for sandboxes and forks. Ie, instead of doing openfn checkout msf-lime-mosul-staging, users can do openfn checkout staging. In a project file name, like main@openfn.org, the alias is the bit before the @. In sandboxes the alias defaults to the sandbox name, in OG projects it defaults to main.

Workflow

• id: a slugified, single-word identifier for the workflow. For app projects, this is derived from the workflow name. the id is used when expanding a project do disk, ie, files are written to ./projects/<workflow-id>/<workflow-id>.json. CLI will also be able to support openfn execute sync-patients to execute a workflow by its id from within a Workspace (ie, no need to pass the full path to the workflow.json!)
• name: A human readable label for the Workflow. Not used by the CLI - its just decorative metadata.
• alias: alias for the workflow. Not sure how useful this is yet, but you should be able to set a local alias on a workflow do make it easier to execute. Aliases are never auto-generated or synced with lightning.

Reasoning

I've sketched out the uses of id, name and alias across the CLI and lightning. I think it comes out really cleanly

excalidraw source