Workflows in the CLI

xmatix workflows copies the definitions behind the workflow designer between a tenant and your workspace, one JSON file per workflow, so that a workflow can be reviewed in a pull request and pushed back as one unit. Workflows are usually built in Setup → Process Studio → Workflows. The CLI is how you put them in git, compare versions, and push a reviewed change. Snapshots, migrations and xmatix watch use the same commands for their workflows step.

xmatix workflows list
xmatix workflows pull                          # → xmatix/automation/workflows/<name>.json
xmatix workflows pull <name-or-definition-id>
xmatix workflows push <file.json>              # publish state taken from the file
xmatix workflows push <file.json> --publish    # make the pushed version live
xmatix workflows push <file.json> --no-publish # save it as a draft
xmatix workflows push <file.json> --new        # always create a new workflow

Overview

There are three commands:

workflows list prints a table with the columns Name, Definition Id, Version, Published and Description, sorted by name. Each row describes the workflow's latest version. If the tenant has none, you see "(no workflows)".
workflows pull writes each workflow to xmatix/automation/workflows/<name>.json, with its complete activity tree. It overwrites files that already exist and never deletes a file.
workflows push reads one file and either updates the workflow with the file's definition id or creates a new workflow.

There is no command to delete, publish without pushing, unpublish, or look at runs. Do those in Setup → Process Studio → Workflows.

When to use it

To keep a tenant's workflows in source control and see in a diff which condition, step or literal changed.
To make the same mechanical edit to many workflows (an entity name, a template reference, a message) in an editor, then push them.
To deploy a reviewed change and decide in the pipeline whether it goes live straight away or waits for someone to publish it.

Build and test new workflows in the designer. It shows each step's settings in a form, catches structural mistakes as you work, and its View runs action is how you check that a workflow did what you expected.

How xMatix handles it

Pull writes the server's own view of the workflow. Each file holds the workflow exactly as the server returns it: its definition id, name, description, latest version number, whether that version is published, the full activity tree (root) and its server-managed settings (customProperties). The file is named after the workflow. A workflow with no name is named after its definition id, and characters your operating system doesn't allow in file names become _.

Push matches by definition id. Push first asks the server for the workflow with the file's definitionId:

If the server returns it, push updates that workflow. Every update saves a new version, one higher than the latest, even if the file hasn't changed.
If the file has no definition id, or the server doesn't return the workflow, or you pass --new, push creates a new workflow. The server gives it a new definition id and version 1.

Push doesn't write the new definition id back into your file. Pushing the same file again therefore creates another copy. After a create, run xmatix workflows pull and commit the file, so later pushes update the workflow you created.

Push treats any failure of that first request as "not found", not only a missing workflow. A temporary server error at that moment also makes push create a copy.

Push sends only part of the file. It sends name, description, root and the publish decision. It ignores version and customProperties:

On an update, a missing name or description keeps the server's value. The workflow's Sequence and Show in the customer menu settings are kept.
On a create, Sequence is blank, so the workflow runs in the shared workflow slot, and Show in the customer menu is on. Set them again in the product if the original workflow used them.

The publish decision. --no-publish wins over --publish. With neither flag, push uses the file's isPublished value, both when it updates and when it creates. A file pulled from a published workflow is therefore pushed as published and goes live at once, even into another tenant.

What the decision means at run time is the designer's rule: only the published version registers triggers. When you push a draft over a published workflow, the new version is saved as a draft and the previously published version keeps running until someone publishes the draft. Note that workflows list and the Version and Published values in a pulled file describe the latest version. They can show "no" while an older published version is still running.

The server checks what you push. The activity tree is read the same way as when the designer saves. A tree the server can't accept is refused, and push prints the server's errors. If a step was saved at a time when its activity type was unavailable, the server restores the real step when it reads or saves the workflow, so a pull followed by a push repairs it.

Each tenant sees only its own workflows. The server marks every workflow it saves with the tenant it belongs to, and it lists, reads and updates only the current tenant's workflows. A definition id from another tenant doesn't resolve, so pushing that file creates a new workflow.

Prerequisites

A signed-in workspace (see Authentication). pull must run inside the workspace, and so must list and push, because they read the workspace's configuration to find the tenant.
Any custom entities, fields and templates that a workflow uses must already exist on the target tenant. Push the metadata first.

Procedure

Step 1 — Find the workflow

Run xmatix workflows list. Note the Name and Definition Id of the workflow you want, its Version, and whether it is Published. Names are matched exactly in the next step, so copy the name as shown, including case.

Step 2 — Pull it

Run xmatix workflows pull for every workflow, or xmatix workflows pull <name-or-definition-id> for one. Each file written is listed with a ✓, then "Wrote N workflow file(s) under xmatix/automation/workflows." If nothing matches, you see "No workflows matched.", nothing is written, and the command still exits with code 0.

Pull never removes files. If a workflow was deleted or renamed in the product, its old file stays in your workspace until you delete it. Commit right after pulling so that the next diff shows only real changes.

Step 3 — Edit the file

Change name, description or the activity tree in root. Keep definitionId as it is unless you mean to create a new workflow. Decide on isPublished now if you'll push without a flag: true makes the push live, false saves a draft. Changes to version or customProperties have no effect, because push ignores them.

The activity tree is the designer's own format. Mechanical edits (a literal, an entity name, a message text) are safe to make by hand. For structural changes such as adding a branch or a step, use the designer, then pull again.

Step 4 — Push the file

Run xmatix workflows push xmatix/automation/workflows/<name>.json. Add --no-publish to save a draft for someone to publish in the product, or --publish to make it live now. The CLI prints one of:

"Updating workflow <name>…" then "✓ Updated (version N, published=true|false)."
"Creating workflow <name>…" then "✓ Created definitionId=<id>, version=1, published=true|false."

If the push created a workflow, run xmatix workflows pull <name> and commit the file, so that the file carries the new definition id.

Step 5 — Check the result

Open Setup → Process Studio → Workflows and confirm the workflow shows the version you expect, with the Draft or Published status you intended. If you pushed a draft, publish it there when it has been approved. Then cause the trigger with a test record and check the run under View runs (see Workflows). Pull the workflow again and commit it: the file now has the new version number.

File fields

Field	What it means	Notes
`definitionId`	The workflow's id. It stays the same across versions	Push matches on it. Missing, unknown or from another tenant: push creates a new workflow
`name`	The workflow's name, as shown in the list	Used as the file name. A missing value keeps the server's name on update
`description`	The workflow's description	A missing value keeps the server's description on update. Use `""` to clear it
`version`	The latest version number when the file was pulled	Ignored by push. Every update saves version + 1
`isPublished`	Whether the latest version was published when pulled	Decides the publish state of a push with no `--publish` or `--no-publish` flag
`root`	The full activity tree: the trigger and every step	Required. A file without a `root` object is refused before anything is sent
`customProperties`	Server-managed settings: the tenant marker, Sequence if set, and Show in the customer menu if it is off	Ignored by push. Set these in the product

Business rules

Push never deletes a workflow, and pull never deletes a file.
Every update creates a new version, even when nothing changed. Snapshot import and migrate apply push every file, so each run adds a version to every workflow in the workspace.
--no-publish beats --publish. Without either flag, the file's isPublished decides, on create as well as on update.
A pushed draft doesn't change what runs. The previously published version keeps running until the draft is published.
A created workflow gets a new definition id that isn't written back to the file. Pull it before pushing again.
On create, Sequence and Show in the customer menu go back to their defaults. On update they are kept.
Pull matches a name or definition id exactly, case included. Two workflows with the same name are written to the same file, so only one of them ends up on disk.

Example

An operations team keeps its workflows in git. The workflow NotifyOpsOnLargeOrder emails the operations team when an order is created, and the team wants to change the email's subject. Publishing in production is done by a lead in the product.

The developer runs xmatix workflows pull NotifyOpsOnLargeOrder. The CLI writes xmatix/automation/workflows/NotifyOpsOnLargeOrder.json. The file shows "version": 4 and "isPublished": true.
They change the subject text in the email step inside root. A colleague approves the one-line diff.
They run xmatix workflows push xmatix/automation/workflows/NotifyOpsOnLargeOrder.json --no-publish. The CLI prints "Updating workflow NotifyOpsOnLargeOrder…" and "✓ Updated (version 5, published=false)." Version 4 keeps sending the old subject.
The lead opens the workflow in Setup → Process Studio → Workflows, checks the change and publishes it. The list shows version 5 as Published.
A test order sends the email with the new subject, and View runs shows a finished run with no incidents on version 5.
The developer runs xmatix workflows pull NotifyOpsOnLargeOrder again. The diff shows "version": 5 and "isPublished": true, and they commit it.

Training

Practice exercise

In a sandbox tenant, create a small test workflow in the designer and leave it as a draft. Pull it with xmatix workflows pull <name>, change its description, and push it with --no-publish. Then push the same file again with --new.

Expected result: the first push prints "✓ Updated (version 2, published=false)." The second prints "✓ Created definitionId=…, version=1, published=false." Setup → Process Studio → Workflows now shows two workflows with the same name, and your file still has the first one's definition id. Run xmatix workflows pull <name> and notice that only one file is written for the two. Delete the copy in the product when you're done.

Quick reference

workflows list, workflows pull and workflows push are the only workflow commands. Delete, publish and unpublish in the product.
Files live at xmatix/automation/workflows/<name>.json.
Push matches by definitionId. No match, or --new, creates a new workflow.
After a create, pull again, or the next push creates another copy.
--no-publish beats --publish. With neither, the file's isPublished decides.
A pushed draft doesn't stop the published version from running.
Every push of an existing workflow adds a version, changed or not.
Sequence and Show in the customer menu survive an update but not a create.

Permissions

The CLI acts with the account that signed in with xmatix login, inside that account's tenant. A push can publish a workflow, and a published workflow runs for every matching record. Give CLI access to a tenant only to people who are allowed to change its automation, and use --no-publish in pipelines where publishing should remain a decision someone makes in the product.

Configuration

The CLI has no workflow-specific settings. Everything it reads comes from the workspace configuration (see Workspace layout):

Tenant and API: the workspace's API address and version decide which tenant you pull from and push to. Check them before you push.
Settings the file doesn't carry: Sequence and Show in the customer menu are set in Setup → Process Studio → Workflows, with the Edit JSON action on the workflow's row. Sequence places the workflow on the entity's Execution Plan. Show in the customer menu applies only to workflows that start with "When a customer messages".
xmatix watch pushes a workflow file each time you save it, unless you pass --no-workflows. It passes no flags, so the file's isPublished decides: saving a file marked true makes your edit live. A file with a definition id the tenant doesn't know creates a new workflow on every save. Set isPublished to false while you work, or turn the workflows group off.

Common problems

My pushed workflow doesn't run

The pushed version is a draft. Either you pushed with --no-publish, or the file had "isPublished": false. Open the workflow in Setup → Process Studio → Workflows and publish it, or push again with --publish. If it is published, check the trigger as described in Workflows.

A change went live before anyone approved it

The file had "isPublished": true and was pushed without --no-publish, by hand, by xmatix watch, or by a snapshot import or migrate apply. Unpublish it in the product, or publish the previous behaviour again. In future, set isPublished to false in reviewed files, or push with --no-publish.

Each push creates another copy of the workflow

The file's definition id doesn't exist on the tenant, so every push creates a new workflow and the file keeps the old id. Delete the extra copies in the product, then run xmatix workflows pull <name> and commit the file. If several copies share a name, pull by definition id instead.

"File missing 'root' activity object."

The file has no root, or root isn't a JSON object. Nothing was sent. Pull the workflow again, or restore root from git.

"Push failed: PUT workflows/… returned 400" or "POST workflows returned 400"

The server refused the activity tree. The message includes the server's errors. Undo the structural change, make it in the designer instead, then pull again. A 404 on an update means the workflow was deleted between the check and the save. Push again to create it.

"File not found: <path>"

The path is wrong. Paths are resolved from your current folder. Run the command from the workspace root with the path as shown by pull.

"No workflows matched."

No workflow has exactly that name or definition id. Names are case-sensitive. Run xmatix workflows list and copy the name. The command exits with code 0, so a script won't notice the miss.

The push created the workflow instead of updating it, and a created workflow starts with a blank Sequence and Show in the customer menu on. Set them again with Edit JSON in the product.

Common questions

Can I edit the activity tree by hand?

Yes, for mechanical changes: renaming an entity reference across many workflows, changing a literal, or correcting a message. The tree is the designer's own save format, and the server reads it in the same way as a designer save, so a tree it can't accept is refused with its errors. For structural work such as new steps or branches, the designer is the better editor and the file is the better diff. Make the change in the designer, then pull the workflow and commit it.

How do I copy a workflow to another tenant?

Push the metadata it depends on first. Then copy the file into a workspace signed in to the target tenant and push it. The definition id doesn't exist there, so push creates the workflow, with or without --new. Decide the publish state explicitly: a file pulled from a published workflow goes live at once unless you add --no-publish. After the push, pull the workflow in the target workspace and commit it, and set Sequence and Show in the customer menu again if the original used them.

Why does the version go up every time I push?

Every update saves a new version, whether or not the file changed, so the previous version stays in the history. Snapshot import and migrate apply push every workflow file, so each run adds a version to all of them. That is harmless for what runs, but it makes the version number a poor signal of real change. Use the git history of the file for that.

How do I unpublish or delete a workflow from the CLI?

You can't. The CLI has no unpublish or delete command, and push never deletes. Use Setup → Process Studio → Workflows: unpublish stops new triggers while running instances finish, and delete removes the workflow. Then delete its file from your workspace in the same commit, so that the next import doesn't create it again.