Building Workflows (Steps)

Steps are the pieces of an analysis inside a project. A file-upload step brings data in, a derivation step turns it into results, a download step pulls in remote files, and any step can be shared across projects. Your work stays connected without duplication. Step configuration and dependencies live in your repository as ordinary versioned files, while the project controls where and how each step is presented.

The current project's active templates determine which step types are available. A project may follow an admin-defined preset or select a custom template list; every step created from those templates remains an independently versioned definition. See Managing Projects for details.

If you administer the instance, continue with the User Repository Setup, the Type Reference, and the notes on project presets.

Step types

Pointy ships three kinds of step. Each starts from a template, but what you see and what happens at run time depend on the kind.

File upload steps

File-upload steps represent data supplied directly through the UI, with accepted extensions determined by the template rather than by a site-wide rule. The sample repository uses them for inputs such as library CSV files and sequencing reads, but an administrator can define the same boundary for any file-oriented input.

Where file-upload steps bring data in, derivation steps turn data into results.

Derivation steps

A derivation step is a runnable Nix build whose template determines both the form presented to the user and the computation eventually submitted. Depending on that template, the form can contain:

• plain text fields
• command-style argument fields
• multi-line text areas
• syntax-highlighted code editors
• enum dropdowns
• references to other steps
• repeatable lists of strings, step references, or structured records
• autocomplete-backed string lists inside structured records, for values such as package names

Step references resolve to the selected upstream step's output during the build.

Download steps

A download step fetches a remote file over HTTP or HTTPS and stores its content hash for reproducible builds. The web form contains a single URL field; on save the backend prefetches the file through the Nix store and records the resulting hash alongside the URL. The stored step configuration then holds a trusted args.downloaded attribute set:

args.downloaded = {
  url = "https://example.com/data.csv";
  hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
};

Because the hash is captured at save time, evaluation resolves downloaded as a fixed-output pkgs.fetchurl derivation. Nix reuses the prefetched store object when available; if the object must be fetched on another builder, Nix accepts it only when its content matches the recorded hash.

Download steps follow the same Run / Stop / output-browsing lifecycle as derivation steps. Editing a download step re-prefetches only when the URL changed; if the URL is unchanged, the existing hash is reused.

The URL field validates that the value is an HTTP or HTTPS URL with a nonempty host and no whitespace. The backend never echoes the raw URL in error messages.

Creating steps

Every step in a project starts as a definition in the repository. Pointy keeps the act of adding a step intentionally explicit. Use the + button in a step table header to add a step of that type. Because projects can share step definitions, adding a row has two deliberately different meanings:

• Create new: create a brand-new step definition
• Add from other project: assign an already-existing step to the current project

Configuring step arguments

When you create or edit a derivation step, Pointy renders a form from the step type definition.

Depending on the template, you may need to:

• fill in text, command, or code arguments
• choose enum values from dropdowns
• choose upstream steps from selectors
• add multiple values to list fields
• add rows to structured record lists when a template groups several related fields together; record fields can include autocomplete-backed string lists whose suggestions update as you type while still allowing free-text values

Step-reference selectors choose from steps that are already assigned to the current project. If you want to reference a step that currently lives in another project, first add that step to the current project with Add from other project. Existing saved references that no longer belong to the project are kept visible with a not in project label so you can fix them deliberately.

Templates may attach informational Markdown notices to particular fields. Pointy loads them when you open the edit or inspect form; they provide context without blocking save, evaluation, or execution. Template authors can define them through passthru.meta.pointy.notices.

Editing, inspecting, and cloning

All steps can be edited. The Edit button opens the same form shown in Configuring step arguments.

Once a step is shareable, share links point to the revision they were generated at. Further editing creates a new revision. Step rows show a relative last modified timestamp when Pointy can read the corresponding steps/<id>.nix Git history; hover it for the exact timestamp.

To see the parameters in read-only mode, use the Inspect Parameters button.

If you want to branch from a shareable step instead of changing it in place, use Clone to create a new editable copy with the same configuration. The Clone action sits next to the row's remove/delete action so copying and removing a step are available in the same action cluster.

When the source step has repository-backed files under srcFiles/<step-id>/, cloning also copies that directory to the new step id. The clone therefore starts with the same files but owns an independent copy that can be edited without changing the source step.

Change highlighting while editing

When you edit a step, Pointy highlights any field with a yellow border whose value currently differs from the saved step definition. This is a live editing aid: it shows what you have changed in the current form before you click Save.

Notes on steps

Each step has a free-form Note field for your own commentary: explanations, caveats, links, anything that helps you or a collaborator make sense of the step later. Notes live on the step definition, so they travel with the step across every project it is assigned to.

Reusing a step across projects

A single step can be assigned to several projects without being duplicated. Its definition, execution state, and outputs are shared everywhere it appears, whereas visibility and sort order belong to each project independently.

Adding an existing step to another project links the same computation and results into a second context. Removing it from the current project merely unassigns that link. The underlying step is not deleted, and its use elsewhere is undisturbed.

Inactive-template warnings

When a project's active preset or custom template list no longer includes a template used by an assigned step, Pointy does not discard that step. The project view shows a collapsible warning listing those orphaned steps by id, type, and name. Re-enable the template, unassign the step from the project, or leave the warning collapsed if the project intentionally no longer uses that template.

Organizing steps inside a project

You control how steps appear through three independent per-project settings.

Reordering

You can reorder steps within each step-type table via drag and drop. The saved order is kept across reloads.

Hiding

You can hide a step without deleting it. Hidden state is also stored per project, so a step can be hidden in one project and visible in another.

Search

The page-header search box is a global step search. Selecting a result jumps to that step, even if it belongs to another project. It does not filter the currently displayed table.

For running steps, uploading files, browsing outputs, and share links, continue with Execution and Data Management.