Rewst Workflow Best Practices

1. Canvas Layout

• Space actions equally apart on the canvas—a consistent two-dot/two-line grid gap. This isn't cosmetic: consistent spacing makes a workflow faster to read, faster to debug, and easier to extend later.
• When branching for conditionals or loops, offset from the originating action by a consistent amount. Pick a rule and use it everywhere—the goal is that any workflow in your library "looks" the same.
• Use explicit BEGIN and END points to start and end the flow—capitalized so it's clear where the workflow starts and ends when looking at results. Don't let a workflow trail off without a clear end.

2. Naming Conventions

• Always rename actions. A dragged-in action's default name (e.g. auto_task_get_contact) tells you nothing about what it's for in this flow. Rename it to describe the actual outcome—e.g. get_authorized_contacts_for_onboarding, not just get_contacts.
• Never abbreviate. Not in variable names, action names, or code. Abbreviations save a few keystrokes and cost readability every time someone else reads the flow.
• Case conventions:
  • Variables and action names → snake_case
  • Dictionary/JSON keys → camelCase
• Names should be specific enough that looking at the results pane tells you exactly what happened, without opening the action.

3. Jinja and Code Conventions

• Jinja inside actions should always be spread across multiple lines. Never write it as a single dense block—that's what an unsupervised AI tends to do, and it's much harder to read or debug.
• Use comments/notes to explain the parts that aren't obvious from the names—keep them concise, not verbose. Notes clutter a canvas, so use them sparingly; if you find yourself needing a lot of them, that's usually a sign the naming needs work instead.

4. Error Handling

There are several ways to handle errors in a workflow (fail silently and check logs later, fail hard immediately, use dedicated failure/exception branches). The standard approach here is a completion handler pattern, split into core and secondary actions.

Core vs. secondary actions

• Core actions are the actions the workflow exists to perform (e.g. in a password reset: generate password, reset password).
• Secondary actions are supporting actions (e.g. create ticket, update ticket, update user).

Rule: if a core action fails, the whole flow fails, hard. If a secondary action fails, the flow continues—the end user doesn't need to know a secondary action failed.

The pattern

• Every workflow keeps a workflow_log—a list variable initialized at the start of the workflow. Every action's success or failure transition appends an entry to it.
• A core action's failure transition ends the flow immediately (hard fail)—it doesn't route anywhere else.
• A secondary action's failure transition just logs the failure and moves on to the next action.
• Every workflow outputs a standardized workflow_result: one of success, failure, or partial_success.
  • success—everything passed.
  • failure—a core action failed. The whole flow stopped.
  • partial_success—core actions passed, but one or more secondary actions failed.

The completion handler

A completion handler (Rewst's newer terminology: inbound/outbound workflows) is a standalone workflow that fires when another workflow completes, reading its workflow_result and workflow_log. Attach it to every workflow you need feedback from. It's responsible for:

• On success—nothing extra, or a routine success notification.
• On failure (core action failed, customer-facing flow)—the end user gets an email saying it didn't go through, and to try again or contact support.
• On partial_success—the end user gets an email saying it succeeded (because it did, from their point of view), while the responsible engineer gets an email listing which secondary actions failed, from the workflow_log.

5. Naming Workflows and Forms

Workflows and forms share a naming convention:

[Bracketed Tag] Friendly Workflow Name

• The bracketed tag names the service, product, or project—e.g. [Office 365], [Halo], [AutoTask]. Option generator workflows get -OG appended inside the brackets, e.g. [AutoTask-OG]. Project-type tags work too—e.g. [Interactive Report], [Internal Cloud Project], [Service Desk Workflows].
• The name itself is friendly, capitalized, whitespace-separated, and says exactly what the flow does—e.g. Get Authorized Contacts for User Onboarding.

6. Tagging

Tag everything—every workflow, every form. It's the only practical way to keep track of what's where in Rewst.

• Tag every relevant service (Office 365, AutoTask, Trend, etc.)
• Tag every relevant project.
• Give every workflow exactly one of three status tags: development, production, or testing—so it's obvious at a glance what's safe to touch.
• Give reusable component workflows an additional reusable component tag. Since a reusable workflow naturally picks up the project tag of every parent that calls it, the combination of multiple project tags + the reusable component tag makes reuse visible at a glance.
• Consider a backup tag (generic or project-specific) for old, disabled versions of a workflow you're keeping around for reference (see Versioning, below).

7. Modular Workflow Design

• A parent workflow's job is to organize: it calls sub-workflows and coordinates the result. A sub-workflow (or reusable component) should do exactly one thing well.
• If you catch yourself wanting to extend a sub-workflow to do a second, different thing (e.g. turning "create ticket" into "create or update ticket"), that's the signal to stop and split it into two workflows instead.
• Small steps (e.g. generate password, reset password) can reasonably stay as plain actions inside a parent if they're truly standalone and not reused elsewhere. They earn their own sub-workflow once there's a reason to abstract detail away (e.g. hiding a messy API call) or once they're reused across more than one parent workflow.
• Treat reusable components like functions:
  • They take input variables—every workflow defines the inputs it needs to run.
  • They abstract complexity away from the caller (e.g. a generic API-call action configured entirely through input variables).
  • They generally don't need their own logging or complex error branching—the parent workflow is responsible for logging and handling the sub-workflow's result.
• Why this matters more with AI-assisted building: specify modularity in your prompts, and an AI building your workflows will build modularly too. The payoff compounds—after enough modular workflows exist, most of the components a new workflow needs already exist, so building it is mostly assembly. Without modularity, every new workflow costs as much as the first one did.

8. Form Field Conventions

• Field names should exactly match what they hold, in snake_case—e.g. a field holding a company ID is company_id.
• Option generators (dropdowns): these default to outputting a value and a label key (surfaced in the form as id and label by default). You can rename these keys to anything, as long as the option generator's output and the form's value/label fields stay in sync.
• Passing more than two pieces of information through an option generator: normally you're limited to a value and a label. To carry more (e.g. a licenses dropdown that needs license name, count, and guide together), nest the extra data as JSON inside the value field, convert it to a JSON string within the option generator, and reference it in the form using "from JSON string" wherever it's read.
• Avoid overcomplicating forms or workflows with fields or logic for functionality that isn't built yet. Build exactly what's needed now—planning ahead in the structure is fine, building ahead in the logic just adds confusion.
• Strip out any debug fields or leftover test values before calling a form finished.

9. Documentation

Documentation happens at two levels:

1. The workflow itself, self-documenting through its action and variable names—this is the primary layer, and should carry most of the weight.
2. An external written document per workflow, stored wherever the client already keeps their knowledge base (SharePoint, IT Glue, or otherwise). This should cover:
   • Overview—what the workflow does and why it exists.
   • Inputs—the variables it requires.
   • Outputs—what it returns (including workflow_result / workflow_log).
   • Technical notes—how it can be extended, without exhaustively listing every action.
   • Tags and dependencies—its tags, and which reusable sub-workflows it calls.
   • Flow diagram—only where it earns its place. A simple flow (password reset) doesn't need one. A flow with real structure to reference (user onboarding) does.

Inline canvas notes stay minimal—use them only where the self-documenting names genuinely aren't enough.

10. Testing

• Maintain a dedicated test organization in Rewst: test users linked to a test site in the PSA and a test site in the RMM, plus a test Office 365 tenant with licenses. The goal is to fully simulate a real client site.
• This matters because workflows can behave differently against a real client environment than against your own instance—permissions and licensing don't always match. Testing only on your own tenant risks missing real issues.
• What "fully tested" means varies by workflow—a password reset is simple to validate; a workflow that analyzes a lot of data needs more thought.
• Promotion from testing to production: fully test against the relevant requirements and edge cases, then get sign-off—from yourself, if that's your call to make, or from whoever it needs to go to.

11. Versioning and Change Management

• Rewst has built-in version history as you save. Save constantly so work is never lost. Add notes to a version specifically when it represents a major change—minor saves don't need them.
• For major revisions to a live production workflow:
  1. Clone the live workflow.
  2. Move the clone back into dev, and make and test all your changes there.
  3. On a planned cutover date, disable the old workflow's triggers and switch over to the new version.
  4. Keep the old, disabled version around as a reference/backup—it costs nothing to leave it there. Tag it accordingly (see Tagging).

12. Connections, Credentials, and API Usage

• Rewst has no built-in naming convention for integration configurations—they default to a generic name. If you're setting up more than one configuration (e.g. per client), name it deliberately.
• Be careful with API calls—Rewst won't warn you when something's inefficient or risky. Whoever's making API calls should be confident doing so, or get help.
• Keep API calls tight: only return the data you actually need.
• Capture API responses in their own set variable action rather than reading and manipulating the data straight off the API call itself—give the response its own named variable, then reference and work with that variable elsewhere in the workflow, for the same clarity reasons as everywhere else in this document.

13. Crates

Crates are Rewst's prebuilt, auto-updating automation packages—useful for a fast start.

The gotcha: if you use a sub-workflow from a crate inside your own custom parent workflow and don't unsync it, a crate update can silently propagate all the way through—even into your custom workflow—and change its behavior without warning. Unsyncing only the sub-workflow isn't enough; you have to unsync the entire chain from the parent workflow down to that sub-workflow.

Recommended practice: if you want to use or extend a crate workflow, clone it into a fully independent copy instead of relying on unsyncing. Then it's genuinely yours, with zero risk of an upstream update changing it under you.

14. Building Workflows with AI (RoboRewsty / Claude)

• Never ask an AI to build a whole workflow or form in one shot. Break the work into manageable pieces and build each independently.
• Use an AI tool to help write the prompt describing exactly what a piece should do, then feed that prompt to RoboRewsty. Option generators and sub-workflows each get their own separate prompt.
• Use a fresh chat window per workflow or form you're building. Once it's built, switch to a separate new window for troubleshooting it.
  • Why: a big context window makes RoboRewsty behave oddly and hallucinate more. Keep prompts and answers concise, and be explicit about the desired outcome.
• All of the above (naming, modularity, error handling, tagging) applies whether you build by hand or with AI—if anything, it matters more with AI, since an unguided AI will happily build monolithic, single-block, unlabeled workflows unless told otherwise.

This document is a living reference—new sections get added as new best practices are worked out.