Working With Workflows

This chapter focuses on what happens after you have purchased workflows: downloading, compiling (if needed), and running them in your own environment.

It is written for end users and power users, not developers. You will not need to modify code or internal services.

From Purchase to Binary

When you purchase a workflow:

1. A licence is created for your account.
2. You gain the right to compile and run that workflow (according to your subscription tier and licence).
3. You can either:
   • Download an already‑compiled binary (if the platform offers pre‑built binaries for your OS), or
   • Trigger a compilation to produce a fresh binary for your target environment.

Exactly how this appears depends on your deployment (web UI vs TUI vs CLI), but the basic flow is the same: you end up with a single executable file per workflow.

Downloading a Binary

From your Library (once implemented) or web UI:

• Choose the workflow.
• Select the build for your platform (for example, Linux x86‑64, macOS Apple Silicon, Windows 64‑bit).
• Download the binary file (for example, my-workflow-linux, my-workflow.exe).

Keep track of:

• Which environment the binary is for (development, staging, production).
• Which version of the workflow it corresponds to (new releases may contain bug fixes or improvements).

Running a Binary Directly

Once you have a binary:

Linux/macOS

1. Make it executable (if it is not already):

   chmod +x /path/to/your/my-workflow-linux
   

2. Run it:

   /path/to/your/my-workflow-linux
   

3. Provide input if required:

   • Some workflows run with default settings and no input.

   • Others expect JSON input on standard input:

     cat input.json | /path/to/your/my-workflow-linux
     

   • Workflow‑specific documentation will tell you what shape the input JSON should take.

Windows

1. Double‑click the .exe to run it, or run it from PowerShell/cmd:

   .\my-workflow.exe
   

2. If the workflow expects input via standard input, you can use PowerShell:

   Get-Content input.json | .\my-workflow.exe
   

Output

Most compiled workflows write their output as JSON to standard output:

• You can view it directly in the terminal.

• Or pipe it into another tool or save it to a file:

  /path/to/your/my-workflow-linux > output.json
  

Using the Controller (Optional)

For more advanced setups, you can run workflows through the controller instead of invoking binaries directly. This is typically configured by your admin, but it is useful to understand what it means for you.

With a controller:

• Workflows are registered once with the controller.
• You trigger them by:
  • Clicking a button in a UI.
  • Sending an HTTP request to a trigger endpoint.
  • Scheduling them (for example, “run every hour”).

From a user’s point of view:

• You no longer need to remember full binary paths.
• You can see recent runs and basic status in one place (once the UI is wired up).

If your organisation uses a controller, your admin will usually give you:

• A workflow identifier (for example, daily-report-workflow).
• Instructions for triggering it (for example, via a small CLI or an internal web page).

Advanced: Traces and Diagnostics

If you are a power user and want more insight into what your workflows are doing at runtime, compiled binaries can emit trace logs.

Enabling Traces

Before running a workflow:

export N8N_TRACE_PATH=/path/to/trace.jsonl
/path/to/your/my-workflow-linux

This causes the workflow to append structured JSON lines to the specified file as it runs, including:

• Node execution start/finish times.
• Status (success/failure) per node.
• Basic diagnostic messages.

Viewing Traces

You can use the trace-viewer tool (where available) to summarise traces:

trace-viewer /path/to/trace.jsonl

This produces per‑node statistics such as:

• Number of times each node ran.
• Average duration per node.
• How many runs succeeded or failed.

This is especially useful when:

• You want to optimise a workflow that runs many times per day.
• You need to debug occasional failures without editing the workflow itself.

If you are not comfortable with these tools, you can ignore this section; workflows still run fine without traces.

Best Practices for Working With Binaries

To minimise headaches:

• Keep versions organised

  • Name folders by environment and date (for example, workflows/prod/2025-01-15/).
  • Keep a small text README with the workflow name, version, and URL to its marketplace entry.

• Use consistent locations

  • For frequently used binaries, add them to a directory on your PATH so you can run them by name.

• Avoid editing binaries

  • Binaries are compiled artefacts; if you need to change behaviour, update the workflow definition and compile a new binary.

• Work with your admin

  • For scheduled or webhook‑based workflows, coordinate with whoever manages the controller and infrastructure to ensure they are deployed correctly.

By following these practices, you can treat workflows as reliable tools in your toolbox and avoid fragile, one‑off setups.