Workbench SDK

The Workbench SDK is how you extend the tool engineers use all day. Custom views, managers, and utilities that live inside Workbench turn repetitive engineering into a click. Software Pile builds them – and builds them so they survive Niagara upgrades.

What the Workbench SDK Enables

  • Custom Workbench views and managers for tasks the stock UI makes slow
  • Engineering utilities: bulk edits, station audits, and validation built into the tool, not run as scripts on the side
  • Wizards that encode your commissioning and QA standards so every job is done the same way
  • Integration between Workbench and your external systems – asset databases, ticketing, documentation

Tooling That Pays for Itself

A Workbench tool that saves each engineer time on every project is one of the highest-return investments an integrator can make. We build them as proper signed modules, documented and versioned for your team – see our broader Workbench tools work.

Tell us what your engineers do repeatedly and on which Niagara versions. We will propose the tool and what it saves.

Decide Where the Tool Should Live

Three places can host the same capability, and picking wrong is the usual reason a tool goes unused.

A Workbench view or plugin suits engineer-facing work: something used while connected to a station, during commissioning or an audit. A station-side component suits anything that must run continuously whether or not an engineer is logged in. An external script hitting oBIX, REST or a BQL export suits reporting and one-off analysis, and has the advantage that nothing needs installing on anyone’s machine.

If the task happens once per project while an engineer has Workbench open, the SDK is the right home. If it needs to happen every night, it is not.

Anything Destructive Needs a Preview Mode

A tool that only reads is recoverable when it turns out to be wrong. A tool that renames points across a station, rewrites tags, or reconfigures histories is a different category of software, and it deserves engineering to match.

Practically that means a dry run producing the full list of intended changes for review, a log written before anything is applied, the ability to run against a copy of the station first, and a clear statement of what cannot be undone. Bulk tools are valuable precisely because they act at scale, which is the same reason a mistake in one is expensive to reverse by hand.

Surviving Version Changes

A tool compiled against one Niagara release may need rebuilding for another, and a tool that only runs on the newest release is of limited use to a team whose fleet spans several. Before building, establish which versions your engineers actually encounter in the field.

That answer shapes the design: pin what you compile against, keep the build reproducible, and test against each version in the fleet before release. Version targeting is settled at scoping time for exactly this reason.

Distributing a Tool Inside a Team

Internal tooling needs the same release hygiene as anything else you install on production machines. Modules get signed, named and versioned. Each release carries a short note saying what changed, because an engineer who finds different behavior from last week with no explanation stops trusting the tool.

Keep a path back to the previous version. Internal software gets deployed with less ceremony than client deliverables, which makes an easy rollback more important, not less.

Tools Worth Building First

Start with read-only audits. Their failure modes are recoverable, they prove the value of the approach quickly, and the output gives you a picture of the fleet that does not depend on anyone’s memory. Reading is not free, though. A bulk audit still puts query and subscription load on a live station, so run it against a copy, or outside the hours when operators are depending on the view.

  • Naming convention audit across a station or a group of stations
  • Points missing units, facets or sensible display names
  • History configuration review: what is collecting, what silently stopped, and what nobody reads
  • Alarm class and route review, including alarms configured to reach nobody
  • Device inventory export with version and offline history
  • Tag coverage check before any analytics or Project Haystack work begins

What Is Actually Inside a Module

A Niagara module is a jar, and its name declares where its contents are allowed to run. A module named siteTools ships as siteTools-rt.jar for code the station executes, siteTools-wb.jar for the Workbench interface, siteTools-ux.jar for the browser side, and siteTools-doc.jar for help. A host installs only the parts it needs, which is why a view-only tool never has to reach a controller.

That split is a design decision, not a packaging detail. Workbench classes dragged into the -rt part pull a desktop interface dependency onto controllers with no display, and station logic parked in -wb cannot run when nobody is logged in. It is worth settling before the first class is written, because moving a class across the line later changes the module's published API and costs a refactor and a new release on every machine that has it.

  • A manifest listing every module this one depends on, each with the minimum version it requires, which is what makes a module refuse to load outright rather than fail halfway through
  • Type registrations mapping a name such as siteTools:AuditReport to a class, so a station can create and load that component by name without knowing anything else about it
  • Agent registrations, which attach a view to a component type rather than to a menu. An agent declared on baja:Component appears on everything in the tree, which is rarely what was intended
  • The compiled parts themselves, one per host type, plus the help files that put the tool's own documentation inside Workbench where the tool is

Once a Type Ships, Its Slots Are Data

The first time a station saves a component your module defines, the property names in your source become names in that station's database. From then on the class is not only code, it is the schema for saved data on every station holding an instance. Removing a frozen property in a later version migrates nothing and takes the stored value with it, and renaming one is the same operation seen from a different angle.

The failure that follows is quiet rather than loud. If the module is missing or too old when the station loads, its components come back unresolved: they keep their place in the tree and their stored data, but nothing runs until the right module is present, and a save performed while they are unresolved is where data actually gets lost. The diagnostic is the station log at startup, which names the type it could not resolve.

  • Add rather than remove. A new frozen property takes its default on existing instances; a deleted one takes its stored value with it
  • Keep the type name and the module name stable. The type is stored as module:TypeName, so renaming either orphans every instance already in the field
  • Downgrades are the harder direction. A station whose module is older than the file it is loading has no definition for slots added since, so a rollback has to be tested against data saved by the newer version, not only against the older station it came from
  • Test an upgrade by loading a backup of a real station made with the previous version. An empty station never exercises the migration at all

Every Read Crosses the Network

A Workbench tool does not run inside the station. It runs on the engineer's machine and reaches the station over Fox, so each property read, each write and each action invocation is a round trip. The same loop over ten thousand points feels instant against a station on the same laptop and takes minutes against a controller at the far end of a VPN, with nothing in the code changed.

Ports are worth knowing because two different conversations are involved. Fox is 1911 in the clear and 4911 for foxs, and hardened stations normally have the plain port closed, so a tool proven against a lab station with legacy Fox enabled can simply fail to connect in production and report nothing more useful than a connection error. Module installation is not Fox at all. It goes to the platform daemon on 3011, or 5011 with TLS, which is why a tool can talk to a station perfectly well and still fail to install on it.

  • Batch instead of walking. One BQL or NEQL query returning the points and columns you need is a single request; fetching them one at a time is thousands, and the difference only becomes visible over a slow link
  • Subscribe before trusting a value. A proxy point nothing has subscribed can hand back a stale or null out, which an audit then reports as a fault in the point rather than a gap in the tool
  • Assume the connection drops. A run measured in thousands of round trips has to be resumable, because restarting a half-finished bulk operation is worse than continuing one
  • Show progress and mean the cancel. Without both, an engineer who believes Workbench has hung will kill it, and a bulk write killed halfway is the state that is hardest to reason about afterward

Who Opens the Tool Decides How It Is Built

The Workbench part of a module is a Java desktop interface. The browser part is separate JavaScript written against the -ux layer, and the two share no code. A capability that has to appear both in Workbench and in a browser is two implementations of one idea, which belongs in scoping rather than in the discovery made after the Workbench version is finished.

So the first question is not what the tool does but who opens it. If the people who need it are engineers with Workbench in front of them, a Workbench view is where it goes. If they are operators, facility staff, or a client who will never install Workbench, the same capability has to surface as a Px view or a -ux widget, and getting the data is then only half the job.

  • Long work on the UI thread freezes Workbench outright: the window stops repainting and looks crashed. Anything that queries a station has to run off the UI thread and report back to it
  • A view registered as an agent on a component type opens by right-clicking that component, which puts the tool where the data already is. A tool attached to no type needs a deliberate launch point, and one with neither gets forgotten
  • A Workbench-only tool reaches exactly the people who already run Workbench, so a request from a wider audience is a signal that the SDK is not the whole answer

When Not to Build a Module at All

Workbench already does a good deal of this with no code. Manager views edit many rows at once. The ORD bar takes BQL and NEQL queries directly. Program objects run Java inside the station with no module build. Templates and palette branches reproduce a configured set of components on the next job. Each is faster to reach for than a module, and each has a limit.

The line is repetition and record, not difficulty. Something done once, by one person, on one station is cheaper done by hand each time than built, signed, distributed and kept working. Something several engineers repeat, where the output has to be comparable across stations and reviewable months later, is what justifies the build.

  • Multi-select in a manager view sets the same property across every selected row and is the fastest fix for a whole column of wrong facets; it leaves no record of what was changed or by whom
  • A BQL or NEQL query typed into the ORD bar runs against the connected station immediately and returns a table you can sort and export; the query lives only with the person who typed it, and it answers questions rather than changing anything
  • A Program object holds Java the station compiles and runs with no module build, signing or install step, where the station license includes the program feature; it lives in one station's database, so ten stations means ten copies to keep in step
  • A saved template or palette branch reproduces configured components on the next job; it stamps out new work and cannot inspect or correct what is already there

Frequently Asked Questions

What is the Workbench SDK, and what is it not?

It is the Java API and build tooling for producing modules that Niagara loads: new component types, new views, new manager columns, new agents, all participating in the same object model as the stock ones. It is not a scripting layer. The output is a compiled and signed jar installed on a host, not a file you drop in a folder and run. It also grants no access the framework does not already have, since a module works through the same object model and the same permission model as everything else in the station.

What has to be in place before a module can be built and installed?

A Niagara developer installation of the release being targeted, because a module is compiled against that release's own jars, and a code signing certificate the receiving platforms will accept. A self-signed certificate is workable during development provided it is added to the trust store on the machines that will run the tool; a module signed by an authority the platform does not trust will prompt or refuse at install, depending on how that platform is configured. From your side, an audit or validation tool has to be told what correct looks like, which means the naming, tagging or commissioning standard has to be written down rather than living in a few people's heads. Somebody also has to be named as the person who approves a release.

How does the module actually reach a machine or a station?

For a Workbench-only tool the jar goes into the modules directory of the engineer's Niagara installation and is picked up the next time Workbench starts. Anything with a station-side part is transferred through the platform's Software Manager and takes effect on station restart, which on a live site is a planned outage rather than a background operation. The two paths are independent, so an engineer can be running a newer version on a laptop while a station still holds the older one. That mismatch is the first thing to check when a tool starts behaving differently against one station than another.

Whose permissions does the tool run with?

The logged-in user's. A Workbench tool acts through the engineer's own Fox session, so the station's categories and role permissions decide every read, write and action invocation it makes. This matters most in testing: a tool developed under a super user account and then run by an engineer with narrower rights returns quietly incomplete results, and a partial result caused by permissions often looks like a bug in the tool.

Can one tool work across several stations at once?

Yes, but each station is a separate connection with its own credentials, and the tool has to treat them that way. A fleet-wide audit is the same audit run many times with the results merged, so it has to keep going when a station is offline, refuses the login, or runs a Niagara version the tool was not built for, and every row it produces has to say which station it came from. A tool that stops at the first failure is not usable across a fleet, however well it works against a single station.

Is there a record of what the tool changed?

If the station runs the audit history service, property writes and action invocations arriving over Fox are recorded against the user account that made them, and a tool acting as the logged-in engineer appears there exactly like a manual edit. Confirm the service is actually enabled before relying on it, because it is not switched on everywhere. It also records what changed rather than why or as part of which run, so it identifies the account and the value but not the operation the values belonged to.