Technical migration cookbook

Use each pattern independently. These are implementation decisions and tests, not sequential migration stages or an artifact support matrix.

Choose workflow boundaries

Implementation: Group workflows that share security, scaling and deployment requirements. Split integrations that need independent isolation or capacity.

Verify: Load-test independent workloads together and confirm that shared compute does not violate latency objectives.

See hosting and isolation.

Replace durable orchestrations

Implementation: Use stateful workflows for persisted execution. Rebuild transactions and compensation explicitly rather than assuming a distributed transaction across connectors.

Verify: Interrupt an execution between side effects; recover it and reconcile the external state.

A stateful workflow persists execution state; it does not provide an atomic transaction spanning a database, a broker and an HTTP API. Model committed side effects explicitly and use a compensating action when a later step fails. A compensation operation must itself handle retries and duplicate invocation.

Use Scopes for related actions and runAfter conditions to express failure paths. This action fragment illustrates failure routing, not a complete workflow:

{
  "Process_order": {
    "type": "Scope",
    "actions": {
      "Capture_order_id": {
        "type": "Compose",
        "inputs": "@triggerBody()?['orderId']"
      }
    },
    "runAfter": {}
  },
  "Report_failure": {
    "type": "Scope",
    "actions": {
      "Fail_run": {
        "type": "Terminate",
        "inputs": {
          "runStatus": "Failed",
          "runError": {
            "code": "OrderProcessingFailed",
            "message": "Order processing failed; inspect correlated action telemetry."
          }
        }
      }
    },
    "runAfter": {
      "Process_order": ["Failed", "TimedOut"]
    }
  }
}

In the real flow, validate orderId and send diagnostic metadata to the appropriate monitoring or failure destination before terminating. Terminate alone is not a recovery queue.

Preserve correlation and ordering

Implementation: Carry a stable business ID across messages. Use a broker session or durable state store where conversation correlation or ordered processing requires it.

Verify: Interleave two business conversations, deliver a duplicate and replay a message after a restart.

A workflow run ID is an execution identifier, not a replacement for a business correlation key. Carry an order/conversation ID through broker properties, workflow data and downstream calls.

For session-based brokering, confirm that the selected connector operation supports the required session and settlement behavior. Setting trigger concurrency to one does not create global ordering across multiple workflows, hosts or producers.

Validate message contracts

Implementation: Preserve XML namespaces, required elements and encoding. Validate against the intended schema before transformation or business side effects.

Verify: Reject malformed XML and missing required data; check that a namespace change cannot silently produce an empty result.

Reuse maps deliberately

Implementation: Evaluate generated XSLT and its dependencies rather than renaming a BizTalk map. Select a compatible transform action and deploy the map with its referenced artifacts.

Verify: Compare output XML structurally and exercise custom functoids, script dependencies and culture-sensitive values.

Use the transformation guide and local mapping lab for executable examples.

Decompose pipeline behavior

Implementation: Separate decode, disassemble, validate, transform and send behavior into explicit operations. Preserve envelope, signing and batching semantics.

Verify: Test a multi-document envelope, invalid encoding and partial batch failure without losing individual messages.

Replace adapter operations

Implementation: Compare the exact trigger/action, protocol and delivery semantics. Select built-in or managed connectivity and configure identity, DNS and private access.

Verify: Exercise the target operation from the actual runtime network with its intended identity, not only from a developer machine.

See connections, identity and networking.

Adapt custom .NET logic

Implementation: Separate pure business logic from BizTalk runtime dependencies. Use local functions for suitable workflow-specific code or a separate service for independent lifecycles.

Verify: Run unit tests for the extracted logic and integration tests for serialization, failures and runtime dependencies.

See custom code boundaries and limitations.

Preserve B2B contracts

Implementation: Recreate partner agreements, certificate references and acknowledgments with the selected B2B operations. Keep certificate rotation and partner routing explicit.

Verify: Test signatures, negative acknowledgments, retries, expiry and partner duplicate handling.

Package and configure Standard

Implementation: Version workflows, maps, schemas and connections together. Inject environment configuration separately from source and provision dependencies before activating triggers.

Verify: Deploy the same build to an isolated environment and inspect resolved settings, identities and connection references.

See project layout and configuration.

Trace business outcomes

Implementation: Record business IDs, workflow runs, action failures and downstream acknowledgments without exposing payloads or credentials.

Verify: Diagnose a failed business message end-to-end using telemetry and correlation alone.

Make retries and replay safe

Implementation: Use explicit retry limits, failure paths and durable idempotency for side effects. Quarantine messages that cannot be safely processed.

Verify: Replay the same business ID during a transient outage and confirm that external side effects occur only as intended.

For an action that supports retry configuration, an illustrative policy inside its inputs is:

{
  "retryPolicy": {
    "type": "exponential",
    "count": 3,
    "interval": "PT10S"
  }
}

Check operation-specific limits. Do not retry non-idempotent side effects blindly. Use the same stable business key on retries and persist processing state in a store with atomic conditional writes. A "look up, then insert" sequence without concurrency protection is vulnerable to duplicate processing.

Handle the crash window between committing an external side effect and recording completion. Prefer downstream idempotency support or a transactional outbox/inbox design where appropriate; a completed flag alone does not close that window.

Troubleshooting

Symptom	Inspect first	Technical correction to evaluate
Duplicate business records	Retry history, trigger redelivery and downstream IDs	Atomic deduplication and downstream idempotency
Error path never runs	Action status and runAfter dependencies	Include actual failure/timeout statuses and check skipped-parent behavior
Unrelated conversations mix	Business IDs, session IDs and shared mutable state	Explicit conversation keys and isolated state
Lost messages after "success"	Broker settlement and target acknowledgment	Align acknowledgment with durable completion
Recovery repeats an irreversible action	Source of replay and side-effect commit state	Reconcile before replay; use safe compensation or deduplication

References: error handling and retry configuration, Standard runtime model.