Understanding BPMN Choreography Diagrams

One of the most common confusions I see in early modeling sessions is the belief that a choreography diagram must show internal steps. That’s not the point.

When someone says, “I want to show how each team does their part,” they’re describing a process or collaboration diagram. A choreography diagram doesn’t care about internal logic. It only cares about the sequence of messages exchanged.

That’s the core of what is a BPMN choreography diagram: a specification of expected interactions between participants, where each message is a first-class task in the flow.

After two decades of modeling across industries—from insurance to supply chains—I’ve found that choreography diagrams are most powerful when used as formal contracts between systems or organizations. They’re not about how things are done internally. They’re about what must happen, and in what order.

By the end of this chapter, you’ll know when to use a choreography diagram, how to model it clearly, and why it’s the right tool for defining interoperability—especially when you can’t control the internal process of a partner.

What Is a BPMN Choreography Diagram? (The Core Concept)

Let’s start with a simple truth: a choreography diagram models the orchestration of interactions, not the execution of work.

Unlike process diagrams, which show the internal steps of a single participant, or collaboration diagrams, which show message flows between pools, choreography diagrams place all participants on equal footing and focus exclusively on the sequence of messages.

Each message is represented as a choreography task. These tasks are not internal activities. They are the only events that matter in the choreography.

Think of it like a script for a play. You don’t need to know how the actors prepare backstage. You only need to know when they speak, in what order, and to whom.

This is the essence of the BPMN choreography definition: a global view of message exchange sequences between autonomous participants.

Why Choreography Exists in BPMN

BPMN didn’t add choreography just for complexity. It exists because real-world systems often need to interoperate without full visibility into each other’s internals.

Consider a bank integrating with a payment gateway. The bank doesn’t need to know how the gateway validates transactions. It only needs to know: “I send a payment request. Then I receive an acknowledgment. Then I receive a settlement confirmation.”

That sequence—defined by messages—is the choreography.

Choreography diagrams are especially useful when:

• Two organizations are building systems that must interoperate.
• One party is not under your control (e.g., a vendor, a regulator, a third-party service).
• You need a shared understanding of behavior, not implementation details.

Choreography Modeling in BPMN: Key Elements

Choreography diagrams use a small but precise set of elements. Mastering them means understanding that every line and shape is about message flow, not internal logic.

Choreography Tasks: The Building Blocks

Each choreography task represents a message exchange. It’s not a process step. It’s not an activity. It’s a message sent or received.

For example:

• A send task means the participant initiates a message.
• A receive task means the participant waits for a message.

These are not activities like “approve invoice” or “update database.” They are communication events.

Importantly, choreography tasks can be initiated by any participant. There’s no “start” or “end” in the traditional sense. The flow is defined by the sequence of messages.

Participants and Roles

Each participant in a choreography diagram is a role in the interaction. They’re not pools. They’re not lanes. They’re autonomous entities with responsibilities.

Participants can be marked as initiating or non-initiating:

• An initiating participant sends the first message.
• A non-initiating participant waits for the first message.

These roles are crucial for defining the choreography’s starting point and ensuring alignment.

Choreography Sequence Flows

Sequence flows in choreography diagrams connect choreography tasks. They define the order of message exchanges.

Unlike in process diagrams, these flows are not internal control flows. They are the only way to show the order of communication.

Each flow must connect a send task to a receive task, or vice versa. No loops, no diverging paths—unless the choreography explicitly allows them (e.g., for retries).

Choreography Diagrams vs. Process and Collaboration Diagrams

Confusion often arises because all three diagram types show interactions. But their purpose, scope, and structure differ significantly.

Let’s clarify the key differences with a comparison table:

Aspect	BPMN Choreography Diagram	BPMN Process Diagram	BPMN Collaboration Diagram
Focus	Message exchange sequence between participants	Internal workflow of a single participant	Message flows between pools (participants)
Viewpoint	Global, contract-like	Internal, orchestration	Interactions, coordination
Participants	Equal, no hierarchy	One participant (pool)	Multiple pools, roles defined
Internal Detail	Not shown	Shown in full	Partially shown (message flows only)
Use Case	Contract specification, system integration	Automation, documentation, internal process	Cross-functional handoffs, B2B workflows

This table captures the heart of the BPMN choreography vs process diagram distinction: one is about behavior, the other about execution.

Choreography modeling in BPMN is not about replacing process diagrams. It’s about adding a layer of clarity for external interactions.

Real-World Examples of Choreography Modeling

Let’s walk through a real example from a logistics company integrating with a customs authority.

Scenario: Import Clearance Process

The goal: Define the sequence of messages between the logistics provider and the customs system.

Participants:

• Logistics Provider (initiating)
• Customs Authority (non-initiating)

Choreography flow:

1. Logistics Provider sends import declaration.
2. Customs Authority receives and validates.
3. Customs Authority sends validation result.
4. If approved, Logistics Provider sends payment confirmation.
5. Customs Authority sends clearance notice.

This choreography defines the contract. The logistics company doesn’t need to know how the customs system processes the declaration. It only needs to know what messages to send and when.

Now, contrast this with a collaboration diagram. That would show the logistics company’s internal steps (e.g., “generate declaration,” “verify documents”) and how they connect to the customs system via message flows.

But the choreography is the agreement. It’s what both parties can sign off on.

Another Example: Insurance Claim Handling

Two insurers are integrating to handle joint claims. They don’t want to expose internal underwriting rules.

Choreography:

1. Insurer A sends claim notification.
2. Insurer B receives and checks eligibility.
3. Insurer B sends eligibility response.
4. If eligible, Insurer A sends claim details.
5. Insurer B sends payment request.
6. Insurer A sends payment confirmation.

This choreography is a contract. It’s the only thing both parties need to agree on to integrate.

Best Practices for Modeling Choreography Diagrams

Here’s what I’ve learned from dozens of successful implementations:

1. Start with the message sequence. Don’t model internal steps. Ask: “What messages must be exchanged, and in what order?”
2. Use clear, unambiguous message names. Avoid vague terms like “notify” or “send data.” Use specific names like “send claim validation result” or “request payment confirmation.”
3. Define initiating participants clearly. The first message must be initiated by one party. This sets the choreography’s starting point.
4. Use choreography tasks consistently. Every message exchange should be a choreography task. No exceptions.
5. Keep it minimal. If you find yourself adding internal logic, you’re not building a choreography. You’re building a collaboration or process diagram.

One mistake I’ve seen repeatedly: trying to show internal steps inside a choreography diagram. It’s not wrong to do so—but it defeats the purpose. The moment you add internal logic, you’re no longer modeling a contract. You’re modeling a process.

Stick to the rule: if it’s not a message, it doesn’t belong in the choreography.

Frequently Asked Questions

What is a BPMN choreography diagram?

A BPMN choreography diagram is a model of message exchange sequences between autonomous participants. It defines the expected behavior of interactions without revealing internal process details. Each message is a choreography task, and the flow is defined by sequence of exchanges.

How is a BPMN choreography diagram different from a process diagram?

A process diagram shows the internal steps of a single participant. A choreography diagram shows the sequence of messages between multiple participants, regardless of internal logic. The choreography focuses on what is exchanged, not how it’s processed.

When should I use choreography modeling in BPMN?

Use choreography modeling when you need to define a contract between systems or organizations, especially when you cannot control or see the internal processes of a partner. It’s ideal for integration, API contracts, and cross-organizational workflows.

Can a choreography diagram be executable?

Not directly. Choreography diagrams are descriptive, not executable. They define behavior, not implementation. However, the message sequence can be used to generate executable process models or integration logic in a workflow engine.

Is a choreography diagram the same as a collaboration diagram?

No. A collaboration diagram shows message flows between pools, but it still includes internal process steps. A choreography diagram shows only message exchanges, with no internal logic. Collaboration diagrams are about coordination; choreography diagrams are about contracts.

How do I link a choreography diagram to a process diagram?

Use shared participant names and message interfaces. In tools like Visual Paradigm, you can link a choreography task to a corresponding message flow in a process diagram. This maintains consistency and enables traceability between the contract and implementation.