BEP Execution

A BEP defined in dotBEP is not a static document. Once the workflows are in place, the BEP can be put into active use: the team creates instances of those workflows to track real work in progress, log every decision and transition, and maintain a full audit trail of how the project was actually carried out. This is what the dotBEP execution engine makes possible.

The execution engine

The execution engine is the part of dotBEP that brings workflows to life. It manages the lifecycle of workflow instances: creating them, advancing them through their steps as events occur, and recording every transition along the way.

A workflow instance is a single run of a workflow tied to a specific asset or deliverable on the project. For example, if your BEP defines a coordination workflow, every clash detection cycle on every model becomes an independent instance of that workflow. Each instance has its own current state, its own history of transitions, and its own log of who did what and when. This is what gives the team traceability: not just what the process should be, but what actually happened.

The runtime

Each BEP in dotBEP has its own runtime. The runtime is the executable layer of the BEP: the code that gives life to the behaviors defined in the workflows. Without the runtime, a workflow is a diagram. With it, the workflow can send notifications, run automatic checks, respond to signals from external software, and chain actions together without human intervention.

This is the clearest expression of what separates BEP as a document from BEP as a software. The runtime is what makes that transition concrete.

Events, effects, and automations

When you define a workflow in dotBEP, you can attach three types of behaviors to it. Each one serves a different purpose in the execution of the process.

Events

Events are signals that move a workflow instance from one step to the next. They represent something that happened: a file was submitted for review, a model was approved, a clash was resolved. When an event is emitted, the engine checks which transition it triggers from the current step and advances the instance accordingly.

Events can carry data with them. A submission event might include a comment from the person submitting. An approval event might include the reviewer’s name. That data becomes part of the instance’s context and can be used by subsequent steps.

Effects

Effects are actions that run automatically when a transition occurs. When the engine advances a workflow instance from one step to the next, any effects attached to that transition fire immediately after. A common use is notifications: when a step is completed, the relevant team members are informed automatically. But effects can do anything: update an external system, create a record, trigger an action in another tool.

Effects are defined in the BEP and implemented in the runtime. The BEP declares what effects exist and which transitions trigger them. The runtime contains the actual code that carries them out.

Automations

Automations are workflow steps that execute without human intervention. Where a regular step requires a person to take an action and emit an event to continue, an automation runs on its own: it performs its logic and immediately emits the event that moves the process forward.

A typical use is automatic validation: when a model file is submitted, an automation checks whether it meets certain criteria and routes the instance to the approval step or back to the author depending on the result. No one needs to trigger this manually. The engine reaches the automation node and the step executes on its own.

Writing the runtime

The runtime is code, and it lives separately from the BEP schema. It does not need to be written to author a BEP. If your project only uses dotBEP for governance and coordination planning, the runtime is not required.

But if your team wants to use the execution engine, the runtime needs to be implemented. You have two options.

Write it yourself. If your team has a developer, the runtime is a TypeScript class that extends the dotBEP base runtime. You implement each effect and automation as a handler function. The dotBEP SDK provides the types and tooling to do this with full type safety. The source code and documentation are available in the dotBEP GitHub repository.

Let your AI assistant write it. You can ask your AI directly to implement the runtime based on a description of what you want each effect or automation to do. If you want to go further, there are AI agents specialized in writing code, such as Claude Code, GitHub Copilot, or Cursor, whose expertise is precisely in generating, reviewing, and refining code. Either way, you describe the behavior in plain language and the assistant generates the corresponding code:

In the coordination workflow, add an effect to the approval step that sends an email notification to the responsible team when the step is completed.

Add an automation to the model submission step that checks whether the file is in IFC format and routes the instance to the review step if it is, or back to the submission step if it is not.

The assistant will write the runtime code, explain what each part does, and make adjustments based on your feedback. You do not need to understand the code to validate that it does what you need.