BW5 Does Not Break. That Is Why Nobody Remembers How It Works.

TL;DR — BusinessWorks 5 is still running critical integration at some of the largest companies in the world because it works, and because it keeps working. The challenge was never reliability. It is that an estate of hundreds or thousands of interfaces, built by different people over twenty-plus years, is more than anyone can hold in their head. We put MakeDoc and Claude beside the existing build pipelines so every EAR explains itself, publishes into the TIBCO Developer Hub, and stays current on every build.

BW5 Does Not Break

It is legacy in the sense of the word. It's been carrying production integration traffic at some of the largest enterprises in the world for the better part of two decades, and it is still there because it earned the right to be. Deploy an EAR and it runs. Engines stay up for years. There is no dependency treadmill, no framework that reinvents itself every eighteen months, no quarterly upgrade that breaks three things on the way to fixing one. The interfaces built in 2005 are still moving messages today, and most of them have not needed a human thought since the week they went live.

Anyone who has operated a modern stack at 3am has some envy for a platform whose defining characteristic is that nothing happens.

TIBCO's recent behavior is the strongest endorsement anyone has given it. They have spent the better part of a decade encouraging customers off BW5 and onto BW6 and BWCE. For many, new development went that direction, but existing estates really did not move unless there were major refactors needed. TIBCO eventually stopped pushing this migration. BW5 got long-term support releases, and new plugins kept arriving in the ecosystem around it. A platform that was supposed to be on its way out is still supported and still being extended, even containerized.

But reliability has a side effect that nobody plans for. Software that rarley demands attention rarley receives any. There is no incident to force someone to open it up. No outage that makes a team learn how it works. No failing test that documents an assumption. The people who built it move on, then the people who inherited it move on, and at no point does anything break badly enough to force a proper handover. The code keeps working perfectly while the understanding of it quietly evaporates.

Twenty years later the interfaces are fine. It is the knowledge that has decayed.

Dozens, Then Hundreds, Then Thousands

This would be manageable if it were one interface. It never is.

Estates grow the way estates grow. A handful of integrations in the first year, a few dozen by the end of the next project, a hundred after the first acquisition, and at the large shops several thousand EARs accumulated across twenty-plus years. Built by different teams. Under different naming conventions. Following whatever the standard was that year, or following nothing at all. Some are three activities long. Some are enormous. A meaningful share were written by consultants who left before the project closed.

Every one of them still works.

Collectively, nobody can tell you what they all do. Not because anyone was negligent, but because the math doesn't permit it. If it takes a Senior TIBCO Developer half a day to properly read one non-trivial interface and write down what it does, then eight hundred EARs is roughly two person-years of reading before anyone writes a line of anything. That is why the analysis never happens: not because it is hard, but because it does not fit.

So the estate becomes something you operate rather than something you understand. Questions that ought to be simple get expensive. Is this interface still used? Which of these two nearly identically named things is the live one? If we retire this queue, what stops? What does the transformation actually do to a field we care about?

In most institutions this is how TIBCO ends up being treated: as a black box. It is the layer everything depends on and almost nobody opens. The symptoms are consistent wherever you find it. Things get rebuilt that already exist, because writing a new interface is faster than establishing whether the one you need was deployed in 2011. And other things run for years with no intervention of any kind, which is fine right up until somebody asks a question about them.

The answers exist. They are sitting inside the EARs. They are just distributed across more artifacts than any person can read.

The Last Mile of Generated Documentation

MakeDoc has solved most of this for years. Point it at a single BW5 (or BW6/CE) EAR and it will produce something like eleven thousand pages: every process, every activity, every global variable, every field binding in every mapper, every adapter destination, cross-referenced in both directions. It is complete, it is correct, and when you are already inside a problem it is exactly what you want.

It is not what you want at 9am on your first day.

Generated documentation stops at the boundary of what can be read off the artifact. It can tell you that a process contains thirty-two activities and that one of them is a Mapper with 249 field bindings. It cannot tell you that the interface exists so downstream subscribers can filter price changes by sales organization, that all of the real decision logic lives in the error handlers, or that the transformation quietly drops a handful of fields nobody has thought about since it was written. Those are conclusions. Reaching them means reading the whole thing and thinking about it.

Which is why the front page of a generated documentation site is almost always a table of contents. Nobody is ever onboarded by a table of contents.

That last mile, the step from complete to understood, is the part that used to require the two person-years.

"Good IT decisions come down to context. TIBCO Platform's Developer Hub and Make Doc put the right context in the right hands at the right time — whether the decision is strategic and deliberate or operational and fast, human or AI-driven."

Hugo Peters
Senior Principal Product Manager — Platform Innovation & AI
TIBCO

A Step Next to the Build

The input we need is already sitting in your pipeline. The EAR is the thing that gets built and deployed, it carries its shared libraries, every transformation, and all integration touchpoints with it, and it is what is actually running in production. No source repository archaeology, no developer workstation, nothing installed on anyone's machine.

So the step slots in beside the existing BW5 or BW6 build, and the chain is short:

build the EAR
  → run MakeDoc against it
    → invoke Claude, read-only
      → controlled output into overview.md
        → generate catalog-info.yaml and the mkdocs config
          → push to documentation repo
            → register or update the component in the TIBCO Developer Hub

Nothing in there is exotic. MakeDoc runs headless in a container against the EAR the pipeline just produced. Claude is pointed at the Markdown MakeDoc wrote, its answer lands in a fixed structure as overview.md, and the catalog entry and site config are emitted next to it. The last step hands the whole thing to the Developer Hub, which renders it and keeps it findable.

Claude gets read, grep, and glob. No write, no shell, no network. It can look at what MakeDoc produced for this EAR and existing MakeDoc outputs for the rest of the estate stored next to it. It has no other way to obtain a fact. Anything in the output either came from the EAR or did not come from anywhere.

It runs per EAR, so estate size stops mattering. Half a day of careful reading per interface was the constraint that made estate-wide analysis impossible. A few minutes of compute per interface is not a constraint at all. Eight hundred EARs is a build queue.

Three Questions

The output is not a summary. It is a fixed structure, and it has to answer three questions before it is any use to a human being:

What is this, what does it do, and what does it talk to.

Everything else exists to serve those. Here is the top of a real generated introduction for one BW5 interface, with the customer's identifiers removed:

Direction SAP ECC to EMS, inbound IDOC to outbound canonical publication
Consumes Adapter message from an inbound EMS queue
Produces Canonical pricing document on an EMS topic

What it does. SAP publishes a pricing conditions IDOC. The SAP adapter turns it into an adapter message on an EMS queue. BusinessWorks picks it off that queue, renames the IDOC segments and fields into the canonical pricing schema, extracts three values to attach as JMS message properties, and publishes the result to an EMS topic.

The three properties are the point of the design. Subscribers put a JMS selector on sales organization, price list type or material type rather than receiving every price condition change.

This is one of the simplest interfaces in the estate. There is no enrichment, no lookup, no database access, no filesystem use on the runtime path, no conditional routing and no aggregation. All of the real decision logic is in error handling.


Direction	SAP ECC to EMS, inbound IDOC to outbound canonical publication
Consumes	Adapter message from an inbound EMS queue
Produces	Canonical pricing document on an EMS topic

Six sections follow, in a fixed order: how it flows, eight numbered steps from the inbound message to the acknowledgment; what it integrates with, every external endpoint and its transport in one table; the transformation, its shape and anything it silently drops; error handling, a matrix of each failure against what it does to the source message; worth knowing, the things that will confuse the next person; and open questions, the short list only the customer can answer.

The generated overview as it is served: TechDocs inside the TIBCO Developer Hub, with the full MakeDoc tree one click away in the sidebar.

That is roughly two screens. You can read it before a handover call, or before deciding whether an interface moves, merges or gets switched off.

Where It Lands

The output does not go into a SharePoint folder. It publishes into the TIBCO Developer Hub, which is where your teams are heading anyway.

The same step that generates the documentation also emits a catalog entry, so each legacy EAR registers as a first-class Developer Hub component:

# catalog-info.yaml (one per EAR, generated alongside the docs)
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: ord-pub-sap-listprice
  title: ORD-PUB-SAP-ListPrice
  description: SAP ECC to EMS, inbound IDOC to outbound canonical publication
  annotations:
    backstage.io/techdocs-ref: dir:.
  tags: [bw5, ear, makedoc, assessment]
spec:
  type: bw5-ear
  lifecycle: production
  owner: integration-team

A twenty-year-old BW5 EAR as a first-class Developer Hub component, with an owner, a lifecycle and its documentation attached.

The consequences are the point of the exercise. Interfaces built before Backstage existed become searchable next to the new work, in the same catalog, with the same ownership model and the same tags. Someone planning a migration wave filters the catalog rather than opening a spreadsheet. TechDocs renders the generated site, so the two-screen overview and the eleven thousand pages beneath it live at the same address.

Filtering the catalog by tag turns "which interfaces are still on BW5?" from a spreadsheet exercise into a query.

You end up with one front door for the estate you are running today and the platform you are running it on tomorrow.

What Reading All of It Turns Up

Writing an accurate description means reading the whole interface, and reading the whole interface surfaces things nobody went looking for. On one of the simplest interfaces in the estate:

Seven fields and one entire segment were silently dropped by the transformation, all of them long material number and extended length variants. If the source system ever switches those on, the published document quietly loses the data.
Several canonical element names had nothing to do with their sources. A customer number mapped into an element named for a material version. Harmless at runtime, common in integration, possibly misleading to anyone building against the feed.
Nothing in the scanned estate subscribed to the topic this interface publishes to. Either the consumer sits outside the assessed scope, or it does not exist. A reasonable assumption for an AI without knowledge of EMS Bridges. MakeDoc documents EMS too, just not yet in this repo.

None of these are exotic findings. Each one is reachable by a competent engineer with enough time, and time is precisely what an eight-hundred-EAR estate does not give you. Each one is also a decision waiting for somebody, about an interface that until now nobody could describe.

Regenerated, Not Maintained

Hand-written interface documentation has a predictable life. It is accurate on the day it is written, approximately right for a release or two, and quietly wrong forever after. The gap between the document and the deployment stays invisible until somebody trusts it during an incident, or during a migration.

Running as a build step removes the maintenance question rather than answering it. The overview is not a document that has to be kept in sync with the EAR. It is derived from the EAR, from the exact artifact the pipeline just produced, every time the pipeline runs. A change to an error handler shows up in the failure table on the next build, because there is nowhere else for it to come from.

BW5 gets to keep doing what it has always been good at, which is running without drama. It just stops being a black box while it does it.

MakeDoc supplies the ground truth. Claude supplies the understanding. The Developer Hub supplies the front door. The pipeline supplies the discipline.

MakeDoc is ours, and there is more about what it covers on the MakeDoc for TIBCO page.

If you are running a BW5 estate that has quietly grown past what anyone can explain, whether you are heading for the TIBCO Platform or simply want to know what you have, that understanding is far more reachable than it used to be. Get in touch about MakeDoc licensing, or about partnering with us to put Claude beside your own build pipelines. We would be glad to talk about either.