NOTE: This is a read-only viewer. It renders exported files for reference and clarity. Orchestration Builder remains the source of truth for what will or won't validate or compile the viewer never edits anything.
Workday Orchestration Builder is a browser-based, low-code drag-and-drop tool on the Workday Developer Site used to create real-time, event-driven workflows and integrations. You get a trigger at the top, steps flowing downward, branches fanning out, loops with their bodies tucked inside, and the whole thing validates and compiles as you go. Then you export the project from your app, open the folder in VS Code, click any .orchestration file, and all of that visual clarity collapses into one line.
Not one object —one line —thousands of characters long, every value wrapped in a _type and _value envelope, and your editor dutifully renders it as an infinite horizontal scroll. You know there is a flow in there. You built it. You just cannot see it from here.
Workday already bridges part of this with Local Disk Sync, which saves your app to a local folder and keeps the builder and disk in step. That gets the files into git. It doesn't help when you're reading a colleague's branch, reviewing a pull request, or working somewhere Chrome isn't open.
The builder is where a flow gets made, and the repo is where it gets reviewed, versioned and shared, and I wanted the second place to be as readable as the first.
So I built a small extension that carries the builder's picture of a flow into the editor. It is called Orchestrate Flow Viewer, it works in VS Code and Cursor, and it renders .orchestration and .suborchestration files as interactive flow diagrams drawn the way the builder draws them.
This post is the what, the why, and enough of the how that you could build something similar yourself.
What it does
Any Workday app can be exported so a developer can see its underlying folder structure. Choose any app that has an orchestration in it, export it, and open it up using this tool (any app with appManifest.json and an orchestration/ directory).
Click a flow file, and you get the same picture the builder would show you, right there in your editor. The Start or trigger step sits at the top and the steps flow downward along a spine.
Branch on Conditions arms fan out side by side, in the same left to right order the builder evaluates them under little white pills and reconverges at a join. When it comes to Loop bodies, they are nested under their loop card behind a chevron you can collapse.
Error handlers are the one place I deliberately depart from the builder. There, local and global handlers open on their own canvas. A static diagram can't click through, so the viewer pulls them inline: the global handler as a detached region below the main flow, and local handlers as a badge on the step that owns them, borrowing the builder's lightning bolt icon.
If you can read a flow in Orchestration Builder, you can read it here, because the visual language is the same on purpose.
Selecting any step opens a details panel loaded with context straight from the builder:
Step Context: Review assignments, expressions, branch conditions, loop iterators, add integration message severity, and store-document settings.
Resource Resolution: Inspect CSV columns resolved directly from the flow's resources alongside suborchestration parameters.
Subflow Navigation: Click Call Subflow cards to instantly jump to target suborchestrations across your workspace without waiting for page loads.
Developer Environment Tools: Enjoy full editor support with pan, zoom, a minimap, live re-rendering on edit, theme matching, and a toggle for pretty-printed raw JSON.
Why a viewer, and why read-only
Orchestration Builder remains the place to create orchestrations—this project doesn't change that. But once you download the source, you're dealing with files. And files belong where developers already work: in repositories, branches, and pull requests ready for review.
As Workday expands its developer platform, it brings an expectation that you can work in standard development environments. You build in Orchestrate, then review, version, and share in VS Code or GitHub just like any other code you ship.
However, the file reads like it was written for the compiler, not for you. The IntelliJ plugin takes the same view, treating the orchestration folder as read-only and pointing you back to Orchestration Builder to edit. The viewer follows that convention.
The goal is intentionally focused: make exported files readable right where they live—nothing more. It isn't a secondary editor or a replacement for the builder. The viewer simply renders what is in the file, which doesn't guarantee the flow will validate or compile.
What the file knows, and what the builder knows
To reconstruct the builder's visual layout from an exported file, I first examined the underlying file structure. Two key characteristics stood out immediately. First, every single value is wrapped inside a type envelope, as shown when pretty-printing a flow:
{
"_type": "CreateValues",
"_value": {
"name": { "_type": "String", "_value": "InputFile" },
"isDisabled": { "_type": "Boolean", "_value": false },
"errorHandler": {
"_type": ["Opt", "ErrorHandler"],
"_value": { "_type": "ErrorHandler", "_value": { "…": "…" } }
}
}
}
Taking errorHandler as an example, it is represented as an ["Opt", "ErrorHandler"] wrapper enclosing another inner wrapper. Optional fields effectively create nested envelopes, where an absent optional evaluates to an envelope wrapping null. Furthermore, certain exporter versions emit un-wrapped bare objects for group bodies, requiring the parser to handle both representation styles seamlessly.
The second, more subtle realization influenced the entire architectural approach: diagram information exists within the Orchestration Builder interface rather than the source file itself. The exported file stores structural data rather than graphical layout—omitting explicit edges, node identifiers, or spatial coordinates. Execution sequence is inferred from array ordering, branching is established through element containment, and loop bodies are structured as nested lists. While this compact format is optimized for platform execution and compilation, re-creating the builder's interactive diagram within VS Code required translating these structural semantics back into a visual node graph.
This led to a multi-stage pipeline architecture designed to make implicit relationships explicit, enforcing a clear separation of concerns at each phase:
.orchestration file (text)
│
▼
src/core/parse.ts unwrap the envelopes → typed FlowModel
│
▼
src/core/graph.ts synthesise nodes and edges → FlowGraph
│
▼
src/core/layout.ts assign x/y/w/h to every node
│
▼
src/webview/… render with React Flow inside VS Code
All components in src/core/ consist of pure TypeScript without any VS Code API dependencies. Consequently, the core pipeline can execute in standalone Vitest suites or standard browser environments. The VS Code extension itself acts as a lightweight wrapper around this core logic—a design boundary that significantly simplified testing and maintenance.
Teach the parser the envelope, once
Before building the parser, I established a clear vocabulary for interpreting the format: eight utility functions in src/core/unwrap.ts designed to handle any output variation from the exporter. The core work is handled by peel:
/**
* Peel wrapper-of-wrapper layers (e.g. Opt<ErrorHandler> whose _value is the
* wrapped ErrorHandler) down to the innermost wrapper. A null Opt stays put,
* so callers see unwrap(peel(v)) === null for absent optionals.
*/
export function peel(v: unknown): unknown {
let cur = v;
while (isWrapped(cur) && isWrapped(cur._value)) {
cur = cur._value;
}
return cur;
}
Building on this foundation are field, str, bool, num, list, and record. Each helper safely evaluates wrapped or bare objects, returning undefined or an empty list for unexpected shapes instead of throwing an error. Routing all property access through these utilities encapsulates envelope parsing entirely. This enforces a core architectural rule across the project: malformed input degrades gracefully rather than crashing the application.
Assume Workday will ship something you have not seen
Workday releases new Orchestrate components regularly. This means the parser will inevitably encounter step types it hasn't seen before—and it will meet them in real user projects, not just in test fixtures. The default case of parseStep gracefully handles these situations using a two-tiered approach:
default: {
// Unseen component types must never break the diagram. If the payload
// carries a body of child steps (loop-like components such as Batch
// Loop / Join Loop), render it as a container so the children survive.
const groupRaw = field(raw, 'group');
const hasGroup = list(field(groupRaw, 'nodes')).length > 0;
const directNodes = list(field(raw, 'nodes'));
if (hasGroup || directNodes.length > 0) {
warnings.push(`Unknown container type "${rawType}" (${id}) — rendered generically.`);
const group = hasGroup
? parseGroup(groupRaw, childPath, warnings)
: { id, name, steps: directNodes.map((n) => parseStep(n, childPath, warnings)) };
return { ...base, kind: 'genericContainer', group, entries: leafEntries(raw, new Set(['group', 'nodes'])) };
}
warnings.push(`Unknown step type "${rawType}" (${id}) — rendered generically.`);
return { ...base, kind: 'generic', entries: leafEntries(raw) };
}
If a component I haven't written a parser for contains child steps, it is parsed as a generic container. This allows any nested steps to be parsed normally and displayed as functional cards. Any other unrecognized structure becomes a generic step, displaying a raw dump of its fields in the details panel for complete visibility. Both paths increment a warning counter in the toolbar. While an unseen component might lack a custom icon, it will never break the visual diagram.
Why I wrote 150 lines instead of using dagre
When it came to the layout stage, using an existing graph library like Dagre or ELK seemed like the obvious choice. However, I decided to build a custom solution instead. General-purpose layout engines tend to produce organic structures that shift dynamically as the graph changes. In contrast, the Orchestration Builder interface relies on a consistent, highly predictable layout: a single vertical spine flanked by neatly aligned branch arms.
Branch order matters too, Orchestrate evaluates Branch on Conditions arms left to right and runs the first that's true, so a layout engine that reorders arms is misreporting execution order. A custom algorithm guarantees this exact structure every time—ensuring identical input always yields identical output.
layoutGraph operates using two recursive tree passes. The first pass measures bottom-up, memoizing each subtree's bounding box so branch arms know their required width before placement. The second pass places elements top-down, centering items along the spine and advancing a y-cursor. Branch arms are centered as rows beneath their root node, and joins are placed at the measured bottom so all paths reconverge seamlessly.
Centralizing node dimensions in a single lookup table makes global visual adjustments simple:
const SIZES: Record<NodeKind, { w: number; h: number }> = {
trigger: { w: 300, h: 118 },
end: { w: 220, h: 64 },
step: { w: 280, h: 84 },
branchRoot: { w: 280, h: 84 },
globalError: { w: 280, h: 84 },
pill: { w: 132, h: 36 },
expander: { w: 26, h: 26 },
join: { w: 10, h: 10 },
};
Deterministic layout also makes the visual structure fully unit-testable. For instance, a key test suite iterates through every node pair across all test fixtures to verify that no elements overlap:
it("has no overlapping nodes", () => {
for (let i = 0; i < graph.nodes.length; i++) {
for (let j = i + 1; j < graph.nodes.length; j++) {
const a = graph.nodes[i];
const b = graph.nodes[j];
expect(overlaps(a, b), `${a.id} overlaps ${b.id}`).toBe(false);
}
}
});
If a measurement pass undercounts a subtree, overlapping cards immediately fail the test with the precise node IDs responsible. This test caught several real layout bugs during development—an advantage made possible solely by deterministic positioning, which third-party layout engines cannot reliably guarantee.
The rest is plumbing
The webview component renders via React Flow. Since the layout phase computes absolute node positions in advance, the webview primarily maps graph nodes directly to locked React Flow elements—ideal for a read-only viewer.
Edges use right-angle elbow connectors rather than bezier curves, categorized by function so horizontal segments route exactly where the Orchestration Builder would place them. Furthermore, because all color styles leverage VS Code's CSS variables, light and dark themes work seamlessly out of the box without requiring custom styling code.
On the extension side, a CustomTextEditorProvider allows VS Code to handle document state, text editing, and file watching natively, leaving the extension focused entirely on rendering. Communication between the host and webview relies on a lightweight, typed protocol. Incoming edits stream in with debouncing so side-by-side editing won't trigger heavy re-layouts on every keystroke. Additionally, a workspace index scans orchestration IDs, enabling Call Suborchestration cards to display target names and open corresponding files on click.
Key Takeaways
If you're building a similar extension or tool, here are three core principles worth applying:
Identify the core problem first: The goal was never just to render raw JSON, but rather to bring Orchestration Builder's visual clarity directly into the editor environment. Defining this goal made designing the processing pipeline straightforward.
Keep core logic decoupled: Avoiding VS Code API dependencies in the core pipeline enabled comprehensive unit testing against exported files, allowed fast diagram iteration in a standalone browser harness, and minimized webview complexity.
Design for future schema changes: Implementing a two-tiered fallback mechanism alongside a warning counter ensures that newly released Workday components render gracefully without breaking the layout achieved in about thirty lines of code.
Start here
Getting started takes only a couple of minutes:
- Install the extension: Orchestrate Flow Viewer on VS Code Marketplace
- Open a downloaded: Select any project folder containing an
appManifest.jsonand anorchestration/directory. - View the flow: Click any flow file and toggle the JSON view once to compare the formatted diagram against raw source data.
The source code is available on GitHub under the MIT license at https://github.com/Ekwuno/workday-orchestrate-viewer . Upcoming roadmap features include breadcrumb navigation for subflow drill-ins and PNG/SVG export options. If you encounter rendering issues with an exported flow, please open an issue in the repo
Orchestration Builder has always understood your flow's visual layout now your editor does too. Head to developer.workday.com and join the Workday Developer Program, where you'll find the guides, the community and everything you need to start building.
