How to migrate a TIBCO BusinessWorks integration with code and AI
TLDR
Map the BusinessWorks process and shared connections, then verify order versions, redelivery, and service application state before switching consumers.
Migrate a TIBCO ActiveMatrix BusinessWorks integration by tracing the process starter, activities, bindings, and shared resources. Start with one order-status integration. Rebuild the worker and check receiver state for duplicates, older events, and timeouts before redirecting the message source.
When should you replay a TIBCO order after losing the response?
A BusinessWorks JMS event redelivers after an HTTP timeout. Check the producer event ID, payload digest, shipment version and receiver receipt to separate a duplicate or stale event from a newer unapplied update.
Recovery. Reuse a confirmed receipt for the exact event, quarantine a conflicting duplicate and retain the agreed disposition for stale versions. Send an eligible newer version with the same operation key on retry, and hold possible remote acceptance when receipt lookup and reliable idempotency are unavailable.
Cutover check. Compare BusinessWorks acknowledgment and fault outcomes with the successor ledger and fulfillment state. S-13 must end at version 3 DELIVERED with one receiver operation, one exact duplicate and one stale event; an E3 digest conflict must cause no additional request.
Replace a JMS-to-HTTP BusinessWorks process with a durable worker
The sample inputs and expected results in this walkthrough are synthetic.
Use one BusinessWorks 6 application that accepts shipment status events from a queue and calls a fulfillment HTTP service. Preserve the old destination's order or shipment version rules. Run shadow traffic through a copied or replayable stream and a test receiver. A second consumer on the original queue can divert messages from the incumbent.
Pin the deployed version and convert each activity
Use the BusinessWorks 6.11 administrative client to download the deployed archive by its archive name. Substitute the approved domain, folder and archive. Obtain the active AppSpace/AppNode property overrides separately, including endpoint references and secret names. This operation downloads an archive. Treat its profiles and packaged configuration as sensitive. TIBCO archive download
bwadmin download -d "$BW_DOMAIN" -s "$EXPORT_DIRECTORY" -a "$DEPLOYED_EAR"
| BusinessWorks evidence | Replacement adapter contract |
|---|---|
| JMS starter, shared connection, selector and acknowledgment settings | Capture producer_id,event_id,correlation_id,shipment_id,source_version,status_code,payload_digest with provider delivery metadata. Use stable producer event identity across retries. Preserve selector predicates and validate XSD or equivalent before applying. |
| Input mapper, XPath expressions and subprocesses | Create a versioned status map, such as IT → IN_TRANSIT and DLV → DELIVERED. Preserve required or optional field behavior and explicitly quarantine unknown statuses. |
| Process checkpoint and Confirm | Commit accepted envelope, or a durable rejection for an invalid envelope, before acknowledging when the agreed queue contract allows it. A recovered process and a redelivery can both appear. Deduplicate them by the same durable key. |
| HTTP activity, fault transition and receiver response | Send one stable operation ID and the same shipment version on every attempt. Store the request digest, receiver ID or status lookup, state and last observed response. Categorize business rejection, known temporary failure and ambiguous outcome separately. |
Review the incumbent's checkpoint and Confirm placement along with the broker's delivery behavior. A successful HTTP response may still describe an accepted request awaiting processing. Use the receipt or read-back required by the legacy contract to define final delivery. TIBCO checkpoints and Confirm · TIBCO HTTP activity faults
Implement the message lifecycle and reconciliation job
- Insert an inbox row unique on producer and event ID. Save a payload digest to detect conflicting reuse. Compare and set shipment version when promoting a valid event. Within the same transaction record the state transition and enqueue the receiver operation. Decide which version gaps the existing contract tolerates.
- Claim one queued operation per shipment when the destination requires ordered writes. Record the send attempt before calling the receiver. Retry a known transient failure with the same key. For a possible acceptance followed by a timeout, query by operation ID. If that lookup is unavailable, require reliable receiver idempotency or hold for reconciliation.
- Run a separate scheduled reconciler over old pending and ambiguous rows. Emit oldest queue age, blocked entity count and unconfirmed operation count. Keep the reconciler's identity scoped to read evidence and update local receipt state. Send uncertain writes to an approved operator queue.
Verify recovery when the receiver writes but the process loses the reply
Initialize shipment S-13 at version 2 and status IN_TRANSIT. Deliver event E3 with version 3 and DLV, replay E3, then deliver version 1. Simulate the HTTP receiver recording fulfillment:E3 before the caller loses the response. Expect one applied version, one stale event, one duplicate delivery, one confirmed receiver operation and final status DELIVERED. Run a conflicting duplicate with E3 and a different payload digest and confirm it goes to quarantine with no extra downstream request. Observe whether the legacy broker or workflow treats the conflict differently and obtain owner approval for any intended change.
At cutover, freeze incoming routing or coordinate one active consumer. Drain old deliveries or account for every retained or recoverable BusinessWorks instance. Record broker state and all destination receipts at that boundary. Reopen the legacy route only when it will skip confirmed replacement writes and correctly resume unresolved operations.
Gather the process and deployment context
Record the BusinessWorks version before collecting artifacts. For a 6.x application, keep the Business Studio source, application and shared modules, deployed application archive, and configuration profile. Include the process definition, schemas, message bindings, subprocesses, and shared JDBC, HTTP, or JMS resource names. TIBCO documents the application archive as a deployment unit and explains shared resources. BusinessWorks application archives · BusinessWorks shared resources
Trace starter conditions, fault handlers, transaction boundaries, and where acknowledgement happens relative to downstream writes. Check whether retry belongs to the broker, the process, or both. Record the order correlation key and whether updates must be strictly sequenced or may use the newest accepted version. Capture a normal message, a redelivery, and a receiver failure with sensitive fields removed.
Replace the status worker
- Bind an intake worker to the approved message source and validate the input schema. Preserve the event ID and order version. Use a ledger to record accepted, held, delivered, and ambiguous events.
- Implement the status translation and field defaults as deterministic code with fixture tests. Serialize state changes by order when the receiver needs ordering. Use the destination's idempotency feature or lookup contract where available.
- Check the destination result by receipt or read-back before marking the event complete. If a timeout follows a possible write, leave the event ambiguous until reconciliation shows the actual state. Choose acknowledgement timing with the broker owner and test redelivery.
Implementation runbook
Export BusinessWorks 6 design and runtime profiles separately
Start from the Business Studio workspace for the exact deployed revision, plus the original deployment EAR. For BusinessWorks 6.10 the bwdesign shell can export a selected application project's EAR. Use its matching release. Do not apply the BusinessWorks 6 procedure to BW 5 Designer projects.
bwdesign -data /secure/bw-workspace
export -ear shipping.status.application -path /secure/export
Inspect processes, shared modules, partner bindings, subprocesses, XSD/WSDL, XSLT/XPath, shared JMS/HTTP/JDBC resources and matching profiles. Compare the archive's profiles with active AppSpace/AppNode overrides. Record secrets by reference. For a JMS flow inventory selectors, ack mode, redelivery, queue/topic, transaction groups, checkpoint placement, correlation ID and fault path. BusinessWorks checkpoint and Confirm activity may allow a recovered instance and a resent message to exist at the same time. Capture current recovery, duplicate-key expiry and acknowledgment behavior from configuration and traces. A local transaction group across different connection resources does not imply a single resource transaction. TIBCO bwdesign export · TIBCO runtime property export · TIBCO checkpoints and Confirm · TIBCO local transactions
Shipment-status variant with durable messages
Validate the incoming envelope and commit a durable inbox row keyed by producer/message ID before acknowledging the message if its contract permits. Process the business state from that row. Serialize updates per shipment or use compare-and-set on version. Persist the applied status and outbox in one transaction. Save the correlation and event identifiers. A dispatcher uses a stable operation ID for downstream requests, queries a destination receipt if it loses a response, and routes unrecognized mappings to an operator. Define the exact status precedence from the current process. A late older status cannot overwrite the new status unless explicitly designed to do so. Add a scheduled reconciler for pending or unacknowledged rows and stale queue depth.
Concrete fixture. Shipment S-13 is in transit at source version 2. A delivered event version 3 arrives twice and version 1 arrives late. Simulate crash after committing inbox but before ACK and redeliver version 3. Expect two newly ingested source-event IDs, one logical delivered transition and one destination receipt. Audit the older event as stale. Also simulate destination accept followed by network timeout and confirm the reconciliation path can discover the existing receipt. Switch using a pause/drain plan with one active consuming owner per source partition and documented disposition for recovered BusinessWorks instances.
Run the acceptance logic locally
Run this self-contained fixture with Python 3. It uses synthetic inputs and no vendor connection. For migration signoff, repeat the same checks against a sandbox on your selected replacement.
status, inbox, receipts = {"S-13": (2, "in transit")}, {}, {}
def handle(event, shipment, version, state):
payload = (shipment, version, state)
if event in inbox:
if inbox[event] != payload:
raise ValueError("Event ID has conflicting payloads")
return "duplicate"
inbox[event] = payload
current_version, current_state = status[shipment]
if version < current_version:
return "stale"
if version == current_version:
if state != current_state:
raise ValueError("Conflicting state at the current version")
return "unchanged"
status[shipment] = (version, state)
receipts[event] = f"receipt-{event}"
return "applied"
assert handle("e3", "S-13", 3, "delivered") == "applied"
assert handle("e3", "S-13", 3, "delivered") == "duplicate"
assert handle("e1", "S-13", 1, "ordered") == "stale"
assert status["S-13"] == (3, "delivered")
assert len(inbox) == 2 and receipts == {"e3": "receipt-e3"}
Prove version and replay behavior
For order BW17, send status Packed at version 4 and Shipped at version 5. Under a newest-version-wins fixture, replay version 4 and confirm the service app remains Shipped with exactly two applied updates. Simulate a successful receiver write followed by a network timeout. Expect one completed update after reconciliation and no extra write. Also test an unknown status code and verify it goes to a rejected state without updating the service app.
Prompts you can copy
Read the redacted BusinessWorks process, schema, and profile keys. Identify the starter, resources, correlation IDs, retry owners, acknowledgements, and fault handlers. Flag any delivery guarantee that needs a runtime test.
Draft a local worker and fake service API for the BW17 version fixture. Test broker redelivery, an older event after a newer one, and a timeout after the fake API applies a write.
Run reconciliation and cut over
Keep the message-driven path for timely status changes and schedule a separate job to reconcile ambiguous events and report queue age. Bound retries and alert on stuck or rejected events. Compare the old process and replacement against a shadow receiver. Switch at an agreed broker boundary after accounting for in-flight messages. Enable one active writer to the service app and retain the old process configuration and ledger for rollback.
Need help with the migration?
Explore TIBCO BusinessWorks migration services or browse all DIY migration guides.