Share code between workflows
Several workflows that talk to the same system tend to carry the same helper file, such as a tracker.py or a pricing calculation. The copies drift, and a fix has to be made in each one.
A shared module is that helper kept once: a named Python package in a feature, versioned, and imported by workflows rather than copied into them. A module has no main file, parameters or runs, so it never appears in a run list. For a job with its own run history, write a workflow; a workflow can run another workflow.
Make one
Section titled “Make one”ronja module — aliased mod — keeps a module’s .py files in a folder on your machine, the same way ronja wf keeps a workflow’s.
ronja module init pricing_helpers --feature <feature ID> # set up this foldercp ../quotes/discounts.py . # move the helper inronja module push # create it, and sync the folderronja module publish # take it live, or ask an admin toThe name you pass to init is the Python package your workflows will import, so it has to be a valid Python identifier — letters, digits and underscores, not starting with a digit — unique among the live modules of its feature, and not the name of something Python or the workflow already provides (json, requests, pandas, tools, …): a name that shadows one is refused. Modules in different features may share a name, but one workflow can’t use two modules with the same name: saving a workflow that would is refused, and so is renaming or restoring a module into a name another module of one of its workflows already has.
The feature ID appears in the feature’s URL in the app. Nothing exists in Ronja until your first push, which prints the module’s id — you need it for the marker below, and ronja module status prints it again any time.
| Command | What it does |
|---|---|
init <name> --feature <id> |
Sets up the folder you are in: the manifest, an __init__.py if there is none, and the local sync record. Creates nothing in Ronja. |
clone <module ID> [directory] |
Copies an existing module down into a new folder. Read-only — it does not open a draft. |
status |
What you changed locally, what the module looks like in Ronja, whether a draft is open and whose it is. |
validate |
Checks the folder on your machine and sends nothing: the file names, including the name rule below, the sizes, the package name, the __init__.py, and the rule that a module carries no markers. |
push |
Syncs the folder into the module’s draft — creating the module itself on a first push. --force overwrites a draft that changed in Ronja since your last sync. A push can also rename the module (below). |
publish |
Publishes the draft. A module in a shared feature that is waiting for its first approval is already with the Admins, and publish says so rather than sending it again. --overwrite-remote commits over a version somebody published while you were working. |
discard |
Throws the draft away; your local files are untouched. In a shared feature a module waiting for its first review is its draft, so discarding it deletes the module — that needs --delete-module. |
Every command takes --json and exits non-zero when it fails.
Renaming a module
Section titled “Renaming a module”A push renames the module to the title in ronja.json only when the module still has the title the folder last saw. The push stops and shows both names if someone renamed the module in Ronja since, or if the folder has no record of the title, as when its ronja.lock.json was never committed after a deploy. Put the current title in ronja.json to keep it, or push with --force to rename it. Commit ronja.lock.json after a deploy that changes the title.
File rules
Section titled “File rules”- Only
.pyfiles are part of a module. Anything else in the folder is skipped, and each command lists what it left out. Data belongs in a table, a file or a Codex. - Names: each
.pyfile needs a name of ASCII letters, digits and underscores, with no folder or file name starting with a digit —my_helpers.py, notmy-helpers.pyorcalc.v2.py. Any other character (a hyphen, or a dot before.py) or a leading digit is refused before anything is written, and the message suggests a name that works. __init__.pymakes the folder importable, so it is always there and can’t be deleted: empty it if you have nothing to put in it.- No file and folder of the same name. Don’t keep a file and a folder of the same name side by side, such as
report.pybesidereport/__init__.py: a run of a workflow that uses the module stops before any code starts and names the two files. Delete one of them, publish the module, and republish each workflow that uses it. Withoutreport/__init__.py,report.pyquietly becomes thereportfolder’s__init__.pyinstead. - Size: a file can be up to 1 MiB, and a module up to 256 files.
One draft, not one per person
Section titled “One draft, not one per person”Unlike a workflow, a module has a single draft. ronja module status names whose draft is open, and only that person or an Admin can push into it; discard names them too, before it asks.
Import it from a workflow
Section titled “Import it from a workflow”In the workflow’s Python, write the marker where the package name would go:
from {{ module('module-abc123') }} import discountsimport {{ module('module-abc123') }} as pricingRonja replaces the marker with the module’s package name when the workflow runs. ronja wf push and ronja wf publish work as usual, and the module’s files never appear in the workflow’s folder. Only a Python workflow can import a module; a JavaScript workflow’s marker is refused.
A module takes what it needs as function arguments. It holds no {{ ref }}, {{ secret }} or other Ronja marker: the workflow resolves those and passes the database handle, the data and the configuration in. A marker in a module file is refused when you save it, naming the file.
A module reads tables the way the workflow does, through tools.query(...): it runs inside the workflow’s run, which can’t open a table’s files. In a workflow Ronja writes as one main function, a module can’t call tools.getVariable either, so the workflow passes those values in as arguments. A module that opens a table’s files directly is refused when you push or publish the workflow that imports it, naming the module and the file: fix the module, publish a new version, then republish the workflow.
An older workflow keeps running with the module version it already uses. Adding a module to it, or moving it to a newer version, changes its code, so ask Ronja to bring it up to date in the same change.
A module cannot import another module. If two modules share code, keep that code in one of them and call it with an argument.
A workflow in a shared feature may import only modules that are themselves in shared features: everyone who reviews or runs that workflow has to be able to read the code it executes.
Publishing a module changes nothing until you republish the workflow
Section titled “Publishing a module changes nothing until you republish the workflow”A workflow runs the module version its author last saved and tested with, and keeps running it. Publishing a new version of a module reaches no live workflow on its own: each one picks it up the next time it is published. So a fix can’t change what last night’s automation does, and a workflow an Admin approved keeps running the code that was approved.
A change to shared code is two steps, and the second one is per workflow:
- Publish the module.
- In each workflow that should take the new version,
ronja wf pushandronja wf publish— republishing is what moves its pin.
ronja module publish tells you how many workflows import the module, so you know how much work step 2 is:
3 workflow(s) pin this module — each picks up the new version when it is next republished. Publishing a module changes nothing for a consumer on its own.Try a change before you publish it
Section titled “Try a change before you publish it”Edit the module folder, ronja module push, then run ronja wf test in a workflow that imports it: a test run of your own draft uses your open module draft rather than the published version, so you can get a workflow and a module working together and publish both at the end. There is no ronja module test — a module has nothing to run on its own.
Publishing the workflow is the point where an unpublished module is caught: a workflow that imports a module nobody has published yet is refused with “publish module … first”. Save and test freely; publish the module before the workflow goes live.
Read a module in the app
Section titled “Read a module in the app”You write a module from the terminal and read it in the app. On the feature’s page a Modules lane sits beside Codexes, one row per module: its title, its Package column — the name workflows import — and when it was last changed. A feature with none tells you to create one from the CLI with ronja module init.
Open a row for the module’s own page. It carries the title, the description, the package name and when it was published, with a Details sidebar alongside and three sections under it:
- Files — every
.pyfile in the module, with its code. - Versions — the published versions, newest first, the newest marked Head.
- Used by — the live workflows that import the module (the first hundred, and a line says so when there are more), each linked, with the version that workflow pins: Latest, a date when it is still on an older version, or Not pinned yet while nobody has published the module.
The workflows in Used by showing a date are the ones step 2 has left to do; each reads Latest once you have republished it.
A workflow you have no access to still counts in Used by. It appears as a restricted row with no name and no link.
Nothing on the page edits anything. Changing a module is the loop above: ronja module clone to get it onto your machine, then ronja module push and ronja module publish.
Shared modules and who may change them
Section titled “Shared modules and who may change them”A new module in a shared feature is a proposal: anyone who can see the feature creates it, and an Admin or a maintainer of the feature approves it before any workflow can import it.
A module proposal is listed in the Inbox on the Shared features page as NEW MODULE, and an edit draft submitted for review as MODULE CHANGE, but neither is decided there; how each is decided is in Propose and review changes. ronja module publish on a proposal says it is already with the Admins rather than deciding it.
Admins hear about modules through the New module proposed, Module change submitted for review and Module proposal decided notifications, which start switched off; an Admin turns them on in the Proposals and Reviews groups of Notification routing, in the sidebar’s Governance group.
Changing a live shared module is for an Admin or a maintainer of its feature, which makes a module stricter than a workflow: anyone who can see a shared workflow can edit it into a draft and submit it, but only an Admin or that maintainer can check out, push to and publish a shared module’s draft. Ask one of them, or keep the helper in your own private feature, where a shared workflow can’t import it.
Where your organization doesn’t allow approving your own work, an Admin’s ronja module publish of their own change submits it for review, and another Admin publishes it.
A module cannot be moved to the trash while a live workflow still imports it. The refusal names the workflows; remove the marker from each one and save before trying again.
Related
Section titled “Related”- Create a workflow — the job a module is imported into.
- Use the Ronja CLI — installing and signing in.
- Work on Ronja from your editor — stacks, and the
ronja wfloop this one mirrors. - Propose and review changes — drafts, proposals and who approves what.
- Versions, drafts, and approvals — the lifecycle every shared resource follows.