DEV Community: Marc Gille-Sepehri

BPMN as config: one vocabulary runs the model, the runtime, and the analytics

Marc Gille-Sepehri — Thu, 23 Apr 2026 05:52:11 +0000

BPMN 2.0 lets you put arbitrary attributes in your own namespace on any element. The established BPM runtimes — Camunda and Flowable — both preserve those attributes through parsing and make them accessible at runtime. That's table stakes for the spec; neither engine violates it.

What differs is how those attributes reach your code. In Camunda, a Java delegate pulls the current BPMN model instance, walks to the element in question, and reads the namespaced attribute through the generic model API — execution.getBpmnModelElementInstance().getAttributeValueNs(ns, name). Flowable's pattern is similar. Both work, both have a decade of production runtime behind them. Over time, though, the path of least resistance steers teams toward each engine's own extension schema — camunda:inputOutput, camunda:properties, flowable:field — because the platform does more lifting when you author in its vocabulary. Gradually the engine's vocabulary starts winning over the business's.

in-concert — the BPMN 2.0 engine I work on — flattens that ergonomic gradient. There is no engine-defined extension schema for service tasks, user tasks, sequence flows, or gateways. What the engine does instead: hand your callback every attribute you authored, as a plain JavaScript bag in the payload.

item.payload.extensions['acme:costCenter']
transition.attrs['acme:condition1']

No model traversal. No namespace-aware API calls. No translation step. Whether you use our bundled tri:* prefix (which the built-in triggers happen to ship with) or your own acme:* is invisible to the engine — the authoring surface is intentionally unbiased, so your vocabulary wins by default.

The rest of this article is what that means in practice — from bpmn.io, through four extension points at runtime, to the analytics payoff.

Step 1 — Author it in the modeler

Pick any BPMN editor. bpmn.io is free and runs in the browser; Camunda Modeler is an Electron app; you can hand-edit XML if you prefer. All three save extension attributes the same way. Here's a fragment of a loan-approval process with four extension points, each carrying acme:* attributes my fictional company authored for its own runtime:

<bpmn:definitions
  xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
  xmlns:acme="http://acme.example.com/schema/bpmn">

  <!-- 1. Trigger: start the process when an application arrives -->
  <bpmn:message id="Msg_Application" name="loan-application"
    acme:connectorType="acme-application-inbox"
    acme:source="customer-portal"
    acme:minAmount="1000" />

  <bpmn:process id="LoanApproval" isExecutable="true">
    <bpmn:startEvent id="Start">
      <bpmn:messageEventDefinition messageRef="Msg_Application" />
    </bpmn:startEvent>

    <!-- 2. Service task: call out to a credit scoring tool -->
    <bpmn:serviceTask id="Task_Score" name="Run credit score"
      acme:toolId="credit-score-v2"
      acme:timeoutSeconds="5"
      acme:retryStrategy="exponential"
      acme:costCenter="risk-ops" />

    <!-- 3. User task: have an underwriter review -->
    <bpmn:userTask id="Task_Review" name="Underwriter review"
      acme:roleId="senior-underwriter"
      acme:formSchema="loan-review-v3"
      acme:slaMinutes="240"
      acme:escalationChannel="slack:#underwriting-escalation" />

    <!-- 4. Transition conditions with authored rule metadata -->
    <bpmn:exclusiveGateway id="Gw_Decide" name="Approve?" default="Flow_Reject" />

    <bpmn:sequenceFlow id="Flow_Approve" sourceRef="Gw_Decide" targetRef="End_Approved"
      name="Approve"
      acme:condition1="score_above_threshold"
      acme:condition2="amount_within_limits"
      acme:explanation="Auto-approve when both the credit score and the loan amount are in band." />

    <bpmn:sequenceFlow id="Flow_Reject" sourceRef="Gw_Decide" targetRef="End_Rejected"
      name="Reject"
      acme:explanation="Everything else routes to manual review." />

    <!-- …endEvents, the other flows… -->
  </bpmn:process>
</bpmn:definitions>

Four extension points, each of which would normally force you to either contort into the engine's vocabulary or split your logic into an external config. Here, each attribute is just part of the BPMN — one file, one change, one commit.

Step 2 — The engine parses everything

Deploy the model. The parser picks up every non-reserved <prefix>:<name> attribute (reserved: bpmn, bpmndi, dc, di, xsi, xml, xmlns) and carries the bags verbatim into the internal graph model:

<bpmn:message> extension attributes → node.messageAttrs
<bpmn:startEvent> extension attributes → node.selfAttrs
<bpmn:serviceTask> / <bpmn:userTask> extension attributes → node.extensions
<bpmn:sequenceFlow> extension attributes → flow.selfAttrs

The engine does not look inside these bags. It doesn't check acme:toolId. It doesn't parse acme:condition1. It doesn't know what escalationChannel means. These are opaque strings that the engine is legally obligated to carry from XML to your handlers, and nothing more.

Step 3 — Your handlers consume them

At runtime, each extension point has a callback your handler registers for at engine init. When execution reaches that point, the engine fires the callback with a payload that includes the raw attribute bag. Your handler — written in TypeScript, in your project — reads whatever attributes it authored and does whatever it wants.

Event trigger

acme-application-inbox is a custom trigger plugin your team wrote. It's a StartTrigger implementation, roughly 100 lines. When the engine sees the message start event at deploy time, it iterates registered triggers and the plugin claims it based on acme:connectorType:

class AcmeApplicationInboxTrigger implements StartTrigger {
  readonly triggerType = 'acme-application-inbox';

  claimFromBpmn(event) {
    if (event.messageAttrs?.['acme:connectorType'] !== 'acme-application-inbox') return null;
    return {
      config: {
        source: event.messageAttrs['acme:source'],
        minAmount: Number(event.messageAttrs['acme:minAmount'] ?? 0),
      },
    };
  }

  async fire(invocation) {
    const newApplications = await acmeInbox.poll(invocation.definition.config.source);
    return {
      starts: newApplications
        .filter((a) => a.amount >= invocation.definition.config.minAmount)
        .map((a) => ({ dedupKey: a.id, payload: { application: a } })),
      nextCursor: invocation.cursor,
    };
  }
}

The engine doesn't know acme-application-inbox exists until you register it. The attributes that parameterize it (source, minAmount) live on the BPMN — operators can change them in bpmn.io without touching code.

Service task tool invocation

When execution reaches Task_Score, the engine fires onServiceCall with a payload that includes the task's extensions bag:

onServiceCall: async (item) => {
  const ext = item.payload.extensions;
  const toolId = ext?.['acme:toolId'];
  const timeoutSeconds = Number(ext?.['acme:timeoutSeconds'] ?? 30);
  const retryStrategy = ext?.['acme:retryStrategy'] ?? 'none';

  const result = await acmeToolRuntime.invoke(toolId, {
    timeoutMs: timeoutSeconds * 1000,
    retryStrategy,
    input: await readInstanceState(item.instanceId),
  });

  await client.completeExternalTask(item.instanceId, item.payload.workItemId, { result });
}

The engine knows nothing about tool invocation. Your tool runtime — in whatever shape it takes, MCP, a gRPC service, a Python subprocess, Anthropic's tool-use API — consumes the attributes and does the work.

User task / communication

Same mechanism, different handler. When the process reaches Task_Review, onWorkItem fires:

onWorkItem: async (item) => {
  const ext = item.payload.extensions;
  const form = ext?.['acme:formSchema'];
  const slaMinutes = Number(ext?.['acme:slaMinutes'] ?? 1440);
  const escalation = ext?.['acme:escalationChannel'];

  await worklist.create({
    instanceId: item.instanceId,
    workItemId: item.payload.workItemId,
    formSchema: form,
    dueAt: new Date(Date.now() + slaMinutes * 60_000),
    escalateTo: escalation,
  });
}

The worklist UI renders acme:formSchema="loan-review-v3" however it wants. The escalation job wakes up at the SLA deadline and pings slack:#underwriting-escalation. Both services read the same BPMN attributes — no shadow config file.

Transition conditions

When execution reaches Gw_Decide, onDecision fires with a transitions[] array. Each transition carries its source flow's attrs bag:

onDecision: async (item) => {
  const { instanceId, transitions } = item.payload;
  const state = await readInstanceState(instanceId);

  const match = transitions.find((t) => {
    if (!t.attrs) return t.isDefault;
    const rule1 = t.attrs['acme:condition1'];
    const rule2 = t.attrs['acme:condition2'];
    return evaluateRule(rule1, state) && evaluateRule(rule2, state);
  });

  await client.submitDecision(instanceId, item.payload.decisionId, {
    selectedFlowIds: [match!.flowId],
  });
}

The engine never attempted to evaluate score_above_threshold. It just handed you the string. Your rule engine (or LLM, or embedded DSL) does the actual work. The rule names are authored in bpmn.io by whoever models the process.

Step 4 — Analytics: the same attributes, for free

Here's the part that earns its keep in production.

Every attribute you author on the BPMN — acme:costCenter, acme:customerTier, acme:experimentId, acme:dataClassification, acme:regulatoryRegime — lands in your system in the same shape the analytics layer already expects, because you chose the shape. There's no intermediate translation.

A few concrete implications:

Cost allocation. Your finance team already allocates spend by costCenter. Put acme:costCenter="risk-ops" on every service task that calls a paid API, and your process telemetry joins to your chargeback reports without anyone writing a mapping.
Customer-tier SLA reports. acme:customerTier on a user task, and your SLA dashboard filters by tier natively.
A/B experimentation. acme:experimentId on the flow your experiment toggles; your experiments platform already aggregates by that id.
Compliance audits. acme:dataClassification="PII" on the tasks that read personal data; GDPR audit queries filter on that flag directly, and the same flag is visible to reviewers opening the BPMN in bpmn.io.
ML training data. Every onDecision event emits a row with flowId, transitions[].attrs, and the state the handler saw. Your ML team gets a ready-made training set for the rule engine because the labels were authored in the model.

None of this requires a separate "process metadata" service or a parallel tagging system. The BPMN is the config, and the config is whatever vocabulary your business already speaks.

Why this matters

Camunda and Flowable are mature, battle-tested engines with enormous BPMN coverage and deep Java integration. in-concert doesn't try to compete on that surface area. What it does optimize for is a narrower, increasingly relevant shape: your process model should carry your business vocabulary, and that vocabulary should reach your runtime handlers without an API call.

The concrete payoff of transparent extension attributes:

One source of truth. Your process logic, tool wiring, form schemas, escalation rules, cost centers, compliance flags — all in the BPMN, all authored in a modeler, all versioned alongside the graph. Not 40% in BPMN and 60% in handler code and YAML.
Vocabulary parity across systems. acme:customerTier in the BPMN is the same customerTier your analytics warehouse already uses. No translation layer between the model and reporting.
Editor independence. Every BPMN editor that round-trips extension attributes (bpmn.io, Camunda Modeler, Signavio, hand-edited XML) works — nothing in-concert-specific needs to be installed.
LLM-friendly. When your conditions are prompts, your tool calls are MCP-style invocations, and your routing decisions are LLM-evaluated — all of which in-concert supports natively — keeping every attribute in a plain JSON bag at handler time is the right shape for the AI/agentic workloads the engine is positioned for.

The engine's job is to carry BPMN semantics — sequencing, tokens, gateways, events — and get out of the way of the attributes. What happens at each task, at each trigger, at each gateway is yours to author in the model and yours to implement in code. The bridge between the two is the attribute bag.

Try it

in-concert is open-source (modified MIT with attribution) and on npm as @the-real-insight/in-concert. The trigger-plugin guide is at docs/sdk/custom-triggers.md; the decision-callback reference with the transition.attrs walkthrough is in docs/sdk/usage.md.

If you've been splitting process logic across BPMN and config files because your engine wouldn't carry your attributes, swap engines or swap strategies — but don't keep doing it. The model should win.

Generalized BPMN triggers: watch files, inboxes, or let an LLM decide when to start

Marc Gille-Sepehri — Tue, 21 Apr 2026 18:09:52 +0000

BPMN processes traditionally start via API calls. But real events happen in the world — files appear, mailboxes fill, thresholds cross. A generalized trigger mechanism makes 'how my process starts' part of the BPMN itself, not glue code around it.

Most process engines ask you to tell them when to start. "Dear engine, please spin up a new instance of this workflow now." That's fine when the event originates in your code — a user clicks a button, a webhook fires, a batch job runs. It's backwards when the event originates in the world.

Someone drops a PDF into a SharePoint folder. An email arrives. A weather sensor reports conditions that might matter. A stock price might have moved far enough to care. In each of these cases, the process engine should be the one paying attention — and starting instances on your behalf — rather than forcing you to write a separate watcher service that calls startInstance() once it notices.

That's what generalized start triggers give you. In in-concert — the BPMN 2.0 engine I work on — every way a process can start is an instance of the same plugin interface. Timers, Microsoft 365 mailboxes, SharePoint folders, and (new in the latest release) AI-listener agents are all first-party triggers. The engine handles polling, exactly-once instance creation, crash recovery, pause/resume, and credentials. You write BPMN.

Let me walk through two of the more interesting cases from a user's perspective — file-monitoring and AI-driven evaluation — and wrap up with a note on the abstraction underneath.

The concept in one paragraph

A trigger is a named thing (timer, graph-mailbox, sharepoint-folder, ai-listener, or one you write) that can produce start requests. A BPMN author references a trigger by putting tri:connectorType="..." on a <bpmn:message> element together with a handful of trigger-specific attributes. At deploy time the engine persists a trigger schedule — a row that remembers what to watch, how often, whether it's paused, and any credentials. A generic scheduler polls active schedules, calls the matching plugin, and creates process instances for whatever the plugin returns. From your side, that's it. No code writing polling loops, no cron jobs, no webhook receivers to deploy and monitor.

Four properties fall out of this design:

Declared in BPMN. Adding or changing an event source doesn't touch your application code.
Exactly-once. Every generated start carries a dedup key, enforced by a unique index. Crashes, retries, and overlapping polls collapse to a single process instance.
Pausable and resumable. Turn a trigger off for maintenance; turn it back on when you're ready. No redeploy.
Credentials per schedule. Different mailboxes, different tenants, different API keys — stored on the schedule row, not hard-coded.

Watching a folder: the SharePoint trigger

Scenario. Your ops team drops order PDFs into /Incoming/Orders on a SharePoint site. Every file should kick off your existing order-processing workflow. The file's metadata (name, size, path, webUrl) becomes the initial variables for the process instance.

Before generalized triggers, some team built and operated one of: a webhook receiver with Azure AD plumbing, a cron job with a "last-seen" state file, a Microsoft Graph change-notification subscription with a public HTTPS endpoint, or — most commonly — a human who checks the folder once a morning. Somebody wrote it, somebody keeps it running, and somebody handles the part where the SharePoint delta token silently expires after 30 days of quiet.

Here's what replaces all of that in the BPMN:

<bpmn:message id="Msg_NewOrder" name="incoming-orders"
  tri:connectorType="sharepoint-folder"
  tri:siteUrl="https://contoso.sharepoint.com/sites/Operations"
  tri:driveName="Documents"
  tri:folderPath="/Incoming/Orders"
  tri:fileNamePattern="*.pdf"
  tri:pollIntervalSeconds="60"
  tri:initialPolicy="skip-existing" />

<bpmn:startEvent id="Start" name="Order arrived">
  <bpmn:messageEventDefinition messageRef="Msg_NewOrder" />
</bpmn:startEvent>

Deploy the process, set your Azure AD app credentials against the generated schedule, and resume it:

const [schedule] = await client.listTriggerSchedules({ triggerType: 'sharepoint-folder' });
await client.setTriggerCredentials(schedule._id, { tenantId, clientId, clientSecret });
await client.resumeTriggerSchedule(schedule._id);

Done. From now on:

Every matching file that arrives in the folder starts a process instance with the file's metadata as variables.
initialPolicy="skip-existing" means the engine doesn't flood you with a thousand instances for files that were already there when you deployed. The first poll silently records the current state; only new arrivals fire.
Duplicates from retries, crashes, or overlapping polls collapse to one instance per (itemId, eTag).
If the delta token expires, the trigger transparently resets and keeps going.
Need to pause for maintenance? client.pauseTriggerSchedule(id). Resume when ready.

The process designer never sees a polling loop or a state file. The person reviewing the BPMN sees one <bpmn:message> element with a handful of attributes that say exactly what's being watched and how.

Letting an LLM decide: the AI-listener trigger

This one is newer — and harder to do any other way.

Scenario. You run an escalation workflow that wakes up the duty officer when severe weather threatens an outdoor event. "Severe" has a definition that evolved over the years: some combination of precipitation, wind, lightning risk, and whether the event is happening on a field, in a stadium, or on a lake. Your current threshold rules are pages long and still miss edge cases.

You'd love to write: "Given the current observation, should we wake the duty officer?" And have something qualified answer that question.

An ai-listener trigger does precisely that. It polls an MCP-style tool endpoint (any HTTP endpoint that returns JSON), passes the result to an LLM together with a prompt authored in the BPMN itself, and starts a process instance when the LLM answers "yes".

<bpmn:message id="Msg_SevereWeather" name="severe-weather-detected"
  tri:connectorType="ai-listener"
  tri:toolEndpoint="https://weather.example.com/tools/call"
  tri:tool="get_weather"
  tri:llmEndpoint="https://llm.example.com/evaluate"
  tri:prompt="Given this observation for the upcoming regatta at Lake Zurich, should we wake the duty officer? Consider wind above 30 km/h, lightning within 50 km, and heavy rain forecast for the event window. Answer strictly yes or no."
  tri:pollIntervalSeconds="300" />

<bpmn:startEvent id="Start" name="Severe weather">
  <bpmn:messageEventDefinition messageRef="Msg_SevereWeather" />
</bpmn:startEvent>

Every five minutes the engine:

Calls the weather tool endpoint to fetch current observations.
Feeds them to the LLM endpoint together with the prompt.
Parses the response for a strict yes/no.
On yes, starts the escalation process. On no or ambiguous output, does nothing.

The escalation process itself is unchanged BPMN — service tasks, user tasks, gateways, the lot. What changed is that it no longer needs an external watchdog service, a threshold spreadsheet, or a person staring at a dashboard.

The business rule lives in the prompt

This is the part that feels genuinely new. Your "when to escalate" policy is right there in the BPMN, in English, next to the process that implements it. Want to tighten the rule? Edit the prompt. Want to add "ignore conditions during the lunch break"? Edit the prompt. Want a different operator to take a different view? They edit their copy of the prompt.

You get domain experts who can't write TypeScript writing the actual rules of the business.

Exactly-once across many polls

The interesting subtlety: if the weather has been bad for an hour, you don't want twelve escalation instances (one per five-minute poll). You want one.

The trigger's dedup key comes from one of two places:

From the LLM itself — the response can include a correlationId that names the ongoing event. "lake-zurich-storm-2026-04-21" stays the same across many polls; all those "yes" answers collapse to one process instance.
From the tool output — if the LLM doesn't supply a correlation id, the plugin hashes the tool result. Identical observations → same hash → same instance.

Either way: retries, crashes, overlapping polls, and routine "yes, still yes" cycles all produce one instance per event, not one per observation. Your handlers don't have to worry about whether they're already running for this storm.

Bring your own LLM

The default flow is plain HTTP — any MCP-compatible tool server, any LLM with a POST { prompt, context } → { answer } endpoint. That keeps the plugin dependency-free and works with whatever inference stack you're already running.

If you'd rather call the Anthropic or OpenAI SDK directly (for retries, structured output, prompt caching), inject a function and skip HTTP entirely:

const plugin = getDefaultTriggerRegistry().get('ai-listener') as AIListenerTrigger;

plugin.setEvaluate(async (prompt, context) => {
  const completion = await anthropic.messages.create({
    model: 'claude-opus-4-7',
    max_tokens: 20,
    system: 'Answer strictly with yes or no. No other words.',
    messages: [{ role: 'user', content: `${prompt}\n\nData: ${JSON.stringify(context)}` }],
  });
  const text = (completion.content[0] as { text: string }).text;
  return parseEvaluation({ answer: text });
});

With that, tri:llmEndpoint becomes optional metadata and the plugin calls your function for every evaluation. Same idea for setCallTool if you'd rather use an MCP client SDK for the tool half.

One interface, any source

The real win isn't any one trigger. It's that how your process starts becomes part of the BPMN, not a separate service.

Underneath, every trigger — timer, mailbox, SharePoint, AI-listener — implements the same five-method interface:

type StartTrigger = {
  readonly triggerType: string;
  readonly defaultInitialPolicy: 'fire-existing' | 'skip-existing';
  validate(def): void;
  nextSchedule(def, lastFiredAt, cursor): TriggerSchedule;
  fire(invocation): Promise<TriggerResult>;
};

An S3 bucket watcher, an SQS queue poller, a webhook receiver, a filesystem watcher — any of these is about 100 lines of code against that interface, registered once at engine init. The engine handles scheduling, exactly-once, crash recovery, pause/resume, and credentials on your behalf.

The effect on your codebase is that the boundary between the world and your processes becomes a BPMN concern rather than a glue-code concern. New event source? Swap one attribute on one message element. Remove it again? Swap it off. The process graph stays the graph; the triggers are plug-ins around it.

Try it

The engine is open-source (modified MIT with attribution) and on npm as @the-real-insight/in-concert. Source, docs, and more triggers at github.com/The-Real-Insight/in-concert.

If you write a trigger for something interesting — an IoT feed, a database change stream, a message bus — I'd love to hear about it. The interface is deliberately small; the space of useful triggers is not.

Self-Starting Processes: Timer Events, Mailbox Polling, and Why Your Agentic Workflows Should Launch Themselves

Marc Gille-Sepehri — Thu, 16 Apr 2026 21:55:48 +0000

Follow-up to Why We Keep Process Data Outside the Engine

In the first article, we made the case for keeping process data outside the engine. The instanceId is the only binding key. Your code handles the intelligence. The engine handles the orchestration.

But there was a gap in that story. Someone still had to start the process.

A REST call. A button click. A cron job in a separate service calling startInstance(). The engine could orchestrate anything — once a human or an external trigger told it to begin. The process itself had no agency over its own lifecycle.

That changes now.

Processes That Start Themselves

in-concert now supports timer start events and message start events — standard BPMN elements that let a process definition declare when and why it should launch, without any external trigger.

A timer start event says: run this process every hour. Or every weekday at 8:30. Or on the last Friday of every month. Or three times at 10-minute intervals, then stop.

A message start event says: run this process when an email arrives in this mailbox.

Deploy the BPMN. The engine takes it from there. No Lambda functions. No external scheduler. No webhook plumbing. The process definition is self-sufficient.

Timer Start Events — Every Flavour of "When"

Put a timer on a start event and the engine creates a persistent schedule. A background worker fires it, starts an instance, advances the schedule, and goes back to sleep. If the server restarts, the schedule is in MongoDB — nothing is lost.

<bpmn:startEvent id="TimerStart" name="Daily compliance check">
  <bpmn:timerEventDefinition>
    <bpmn:timeCycle>R/P1D</bpmn:timeCycle>
  </bpmn:timerEventDefinition>
</bpmn:startEvent>

That is a process that runs once a day, forever, until you pause it. The engine supports five expression formats:

Format	Example	What it does
ISO 8601 repeating interval	`R/PT1H`, `R3/PT10M`	Every hour (unbounded), or 3 times at 10-min intervals
ISO 8601 duration	`PT30M`	Once, 30 minutes after deploy
ISO 8601 date-time	`2026-12-25T00:00:00Z`	Once, at that exact moment
Cron (5-field)	`30 8 * * 1-5`	Weekdays at 8:30
RRULE (RFC 5545)	`FREQ=MONTHLY;BYDAY=FR;BYSETPOS=-1`	Last Friday of every month

RRULE is the format behind Outlook and Google Calendar recurrence. Any pattern you can set in a calendar invitation, you can use to schedule a process. FREQ, INTERVAL, BYDAY, BYMONTHDAY, BYMONTH, BYSETPOS, COUNT, UNTIL — all supported. Zero external dependencies.

<bpmn:startEvent id="TimerStart" name="Last Friday of every month">
  <bpmn:timerEventDefinition>
    <bpmn:timeCycle>DTSTART:20260130T090000Z
RRULE:FREQ=MONTHLY;BYDAY=FR;BYSETPOS=-1</bpmn:timeCycle>
  </bpmn:timerEventDefinition>
</bpmn:startEvent>

Pause and resume any schedule at runtime via the SDK or REST API. The schedule is a first-class object — queryable, manageable, observable.

const schedules = await client.listTimerSchedules({ definitionId });
await client.pauseTimerSchedule(schedules[0]._id);
// ... later
await client.resumeTimerSchedule(schedules[0]._id);

Why This Matters for Agentic Workflows

Agentic systems are not request-response. They are continuous. A compliance monitoring agent should check every morning whether anything changed overnight. A portfolio rebalancing agent should evaluate positions on a schedule. A reporting agent should assemble and distribute summaries at the end of every week.

These are not one-off tasks triggered by a user. They are standing processes with their own heartbeat. Timer start events give them that heartbeat — expressed in standard BPMN, persisted in the engine, surviving restarts and deployments.

Message Start Events — Email as a Process Trigger

Timer events handle "when." Message events handle "what happened."

A message start event with the graph-mailbox connector tells the engine: poll this Microsoft 365 mailbox, and when an unread email arrives, start a process instance.

<bpmn:message id="Msg_Inbox" name="inbox-poll"
  tri:connectorType="graph-mailbox"
  tri:mailbox="support@your-company.com" />

<bpmn:startEvent id="Start" name="Email received">
  <bpmn:messageEventDefinition messageRef="Msg_Inbox" />
</bpmn:startEvent>

Two tri: extension attributes on the <bpmn:message> element identify the connector type and the mailbox. The Graph API credentials are configured once as engine settings — environment variables or SDK init() — and never appear in the BPMN.

Deploy the process. The engine polls. An email arrives. A process instance is created.

The onMailReceived Callback

Here is where the "data outside the engine" principle from the first article meets the real world.

The engine creates the process instance — so you have an instanceId — but does not advance a single token until your callback returns. Your code receives the full email: subject, sender, body, and attachment metadata. You store it in your domain. You decide whether to proceed.

client.init({
  connectors: {
    'graph-mailbox': {
      tenantId: process.env.GRAPH_TENANT_ID,
      clientId: process.env.GRAPH_CLIENT_ID,
      clientSecret: process.env.GRAPH_CLIENT_SECRET,
    },
  },

  onMailReceived: async ({ mailbox, email, instanceId, getAttachmentContent }) => {
    // Store the email in your domain, bound to the process instance
    await myStore.saveEmail(instanceId, {
      subject: email.subject,
      from: email.from.address,
      body: email.body.content,
      receivedAt: email.receivedDateTime,
    });

    // Download attachments on demand — metadata is already there, content is lazy
    for (const att of email.attachments) {
      const buffer = await getAttachmentContent(att.id);
      await myStorage.upload(instanceId, att.name, buffer, att.contentType);
    }

    // Return { skip: true } to terminate the instance without running
    if (isSpam(email)) return { skip: true };
  },

  onServiceCall: async ({ instanceId, payload }) => {
    // Your agentic logic — LLM calls, tool invocations, etc.
  },
});

Attachments are not pre-loaded into memory. The callback receives metadata — name, content type, size — and a getAttachmentContent() function that downloads a single attachment on demand. A 40 MB zip does not sit in your Node process unless you explicitly ask for it.

The { skip: true } return value terminates the instance. Spam filter, sender allowlist, duplicate detection — your code, your rules. The engine created the instance so you have an instanceId to correlate against. If you skip, it is cleanly terminated. If you proceed, the process runs.

Why This Matters for Agentic Workflows

Email is the entry point for most business processes in the real world. Customer requests, supplier invoices, regulatory notifications, internal approvals — they arrive as emails with attachments, and someone has to triage them, extract data, route them, and act.

This is exactly what agentic workflows do. The BPMN process models the routing. The LLM handles the triage and extraction. The human task is the escalation point when the AI is uncertain. And now the trigger — the email itself — is part of the process definition.

No middleware. No separate polling service. No Azure Function glue. The BPMN file declares the mailbox. The engine polls it. Your onMailReceived callback stores the data. The process runs.

A support email arrives → the agent extracts the intent → checks the knowledge base → drafts a response → routes to a human reviewer if confidence is low → sends the reply. All modelled in BPMN. All starting from an email. All running without anyone clicking "start."

The Architecture — Same Pattern, Different Triggers

Both timer and message start events follow the same internal pattern we use for the continuation worker:

Deploy creates a persistent schedule document in MongoDB
Worker loop polls for due schedules, claims with an optimistic lease
Fire calls startInstance() — same as if you called it yourself via the API
Advance updates the schedule (next fire time, or mark as exhausted)

Multi-instance safe. Survives restarts. No in-memory state. The schedule is a MongoDB document with an index — the same infrastructure the engine already uses for continuations and outbox delivery.

Come Build With Us

Timer and message start events are available now in @the-real-insight/in-concert on npm. The full documentation — RRULE expressions, cron, Graph mailbox setup, onMailReceived callback reference — is in the SDK usage guide.

If you are building agentic workflows and want your processes to have their own lifecycle — starting on a schedule, reacting to emails, running continuously without external triggers — this is the engine layer for that.

Star the repo. Try it on a real process. Open an issue if something does not work the way you expect. The BPMN subset is growing, and the patterns we are building — timer-driven agents, email-triggered workflows, LLM-routed decisions — are where #agenticbpm gets practical.

We are The Real Insight GmbH, and we believe BPMN is the orchestration backbone for the agentic era. Processes should not wait to be told when to start. They should know.

→ github.com/The-Real-Insight/in-concert
→ npmjs.com/package/@the-real-insight/in-concert
→ the-real-insight.com

Powered by The Real Insight GmbH BPMN Engine — the-real-insight.com

Why We Keep Process Data Outside the Engine — and Why It Changes Everything for Agentic BPM

Marc Gille-Sepehri — Sat, 11 Apr 2026 11:19:37 +0000

There is a design decision at the heart of in-concert that surprises people when they first encounter it: the engine knows nothing about your data.

No domain objects stored inside the engine. No variable interpolation in BPMN expressions. No built-in scripting that reaches into your database. When a process instance is running, the engine holds exactly one thing that belongs to you: an instanceId. Everything else — documents, application state, business context, AI responses — lives in your systems, bound to that id.

This is not an oversight. It is the central architectural choice, and it shapes everything else about how in-concert works. And this is the beginning of #agenticbpm.

The Problem with Data-Coupled Engines

Traditional BPM engines — Camunda, Flowable, Activiti — manage process variables alongside process state. You deploy a BPMN, you pass in variables, and the engine stores them, interpolates them into conditions, and threads them through the execution. It is convenient at first. Then reality arrives.

Your process needs to evaluate a condition against data that lives in your ERP. Or the "variable" is actually a 40-page document. Or the service task needs to call an LLM with context assembled from five different sources. Or your security model requires that PII never leaves your own database.

Suddenly the engine is not a neutral orchestrator. It has become a data store you did not ask for, a security boundary you have to manage, and an integration point that does not understand the shape of your actual domain.

We built in-concert after running into exactly these problems. The solution was radical simplicity: the engine does not store your data, period.

The Three Touch Points — and Why They Are All Fuzzy

In any BPMN process, there are three places where execution intersects with the outside world. In a traditional engine, these are handled by scripting, expression languages, and built-in connectors. In in-concert, they are handled by your code — deliberately, explicitly, and with full access to everything you know.

1. Service Tasks

A service task means "call something external and continue." In a classic engine, you write a connector or a script that runs inside the engine's JVM or Node.js process. The engine manages the call, handles the result, and stores output variables.

In in-concert, the engine calls your handler and waits:

client.init({
  onServiceCall: async ({ instanceId, payload }) => {
    // Full control. Assemble context from anywhere.
    const context = await myDataStore.getContextFor(instanceId);
    const result = await myLLM.invoke(payload.extensions?.toolId, context);
    await client.completeExternalTask(instanceId, payload.workItemId, { result });
  },
});

The handler receives the instanceId and whatever metadata you put on the BPMN node (tri:toolId, tri:toolType, custom extensions). It completes when it is done — whether that is 50ms or 50 minutes later, whether via a direct response, a message queue reply, or a webhook. The engine waits. It does not care how long.

But "call an LLM" understates what the handler can actually do. Consider what happens in a real agentic workflow:

The LLM as context mapper. Your process node carries a tri:toolId that identifies an MCP tool — say, search-crm or generate-proposal. The tool has a defined input schema. Your application data has its own shape. The LLM's job here is not to answer a question — it is to map your domain objects into the tool's input format, invoke the tool, and map the structured output back into whatever your process needs next.

onServiceCall: async ({ instanceId, payload }) => {
  const toolId = payload.extensions?.toolId;       // e.g. "search-crm"
  const tool = mcpClient.getTool(toolId);           // get tool + schema
  const context = await myDataStore.getContextFor(instanceId);

  // LLM maps context → tool input schema
  const toolInput = await llm.mapToToolInput(tool.inputSchema, context);

  // Invoke the MCP tool
  const toolOutput = await mcpClient.invoke(toolId, toolInput);

  // LLM maps tool output → domain result
  const result = await llm.mapFromToolOutput(tool.outputSchema, toolOutput, context);

  await client.completeExternalTask(instanceId, payload.workItemId, { result });
},

This pattern — LLM as the mapping and reasoning layer around structured tool calls — is where BPMN and agentic AI (i.e. #agenticbpm) meet most naturally. The process definition models the flow and the intent. The BPMN node identifies which tool to use. The LLM handles the fuzzy work of bridging between your data model and the tool's contract. And because all of this happens in your code, you can swap models, adjust prompts, and iterate on the mapping logic without touching the process definition at all.

The handler is also where long-running integration lives. Publish a job to a queue, return immediately, and complete the task when the consumer acknowledges. Poll an external system until it is ready. Wait for a webhook. None of this requires anything special from the engine — it simply waits until your handler calls completeExternalTask.

2. Transition Conditions — the XOR Gateway

This is where the fuzziness gets interesting. In a BPMN XOR gateway, one of several outgoing flows is selected based on a condition. In a traditional engine, you write an expression: ${amount > 1000}, or a FEEL expression, or a Groovy script. The engine evaluates it against stored variables.

But what if the condition is not a clean boolean expression? What if it is "does this application look fraudulent?" or "is this document complete enough to proceed?" or "based on the conversation so far, which department should handle this?"

These are not expressions. They are judgements — and judgements require context, and often require an LLM.

In in-concert, gateway decisions are routed to your handler:

client.init({
  onDecision: async ({ instanceId, payload }) => {
    // payload.transitions is the list of outgoing flows with names and conditions
    // You evaluate — using your data, your rules, your LLM
    const context = await myDataStore.getContextFor(instanceId);
    const selected = await myRouter.evaluate(payload.transitions, context);
    await client.submitDecision(instanceId, payload.decisionId, {
      selectedFlowIds: [selected.flowId],
    });
  },
});

The engine gives you the transition options. You choose. The evaluation logic — however simple or sophisticated — belongs to you. You can use a simple if/else. You can call an LLM with the full application context. You can run a rules engine. The engine does not prescribe how you decide; it only records that you did.

3. Human Tasks — the Worklist

User interaction is the most obviously fuzzy of the three. A human task is not deterministic. The user brings judgement, context, domain knowledge, and occasionally the wrong answer. The task might be "review this contract," "approve this expense," or "assess whether this customer qualifies."

In in-concert, human tasks are projected to a queryable worklist. Your UI queries it, filtered by role, by claimed status, by instance. The user sees the task, opens your application where the full document and context live, makes a decision, and your code calls completeUserTask() with the result.

The engine never renders a form. It never stores the contract. It never knows what the user saw. It only knows that a human task at a given node in a given process instance was completed with a given result — and it advances accordingly.

This lets you build any interaction model: cherry-picking worklists, supervisor assignment, AI-assisted pre-screening before human review. The engine is the backbone, not the bottleneck.

What This Unlocks for Agentic BPM

Here is the part that we find genuinely exciting.

AI agents need orchestration. A single LLM call is not a workflow — it is a function. Useful, but limited. Real agentic systems involve sequences of steps, parallel branches, human checkpoints, error handling, retries, long-running waits. They need state across time. They need the ability to hand off between AI and human. They need audit trails.

BPMN is a remarkably good fit for this. It has been modelling complex, long-running processes for decades. It handles parallelism, subprocesses, boundary events, timers, and message correlation out of the box. And it is visual — a BPMN diagram is something a business analyst and a developer can read together.

in-concert brings BPMN to agentic systems with a clean separation: the engine handles the orchestration; your code handles the intelligence.

Service tasks become LLM invocations. Gateway decisions become LLM evaluations against your domain context. Human tasks become the checkpoints where a person reviews or overrides what the AI decided. And because all data and logic live outside the engine, you can iterate on your prompts, your models, and your routing logic without touching the process definition.

The instanceId is the thread that holds it together. Every LLM call, every database query, every human task can be correlated to a specific process instance. You know exactly where in the process you are, what decisions were made, and what the audit trail looks like — because in-concert records all of that.

Try It

in-concert is open source, MIT-licensed (with attribution), and published on npm:

npm install @the-real-insight/in-concert

The SDK works in two modes. For microservice deployments, run the engine as a standalone service and connect via REST and WebSocket. For embedded or test use, run it directly in-process against MongoDB — same API, no server needed.

import { BpmnEngineClient } from '@the-real-insight/in-concert/sdk';

// REST mode
const client = new BpmnEngineClient({ mode: 'rest', baseUrl: 'http://localhost:3000' });

// Local / embedded mode
const client = new BpmnEngineClient({ mode: 'local', db });

The full quick start, API reference, and BPMN conformance matrix are in the GitHub repository. The README documents every SDK method with accurate type signatures pulled directly from the package.

Come Build With Us

in-concert is early. The BPMN subset is intentionally focused — we implement what production workflows actually need, and we fail loudly on anything we do not support yet. There is meaningful work to be done on the conformance surface, the developer experience, and the agentic integration patterns.

If this resonates with you — if you have built on BPM engines and felt the friction of data-coupled orchestration, or if you are thinking about how to bring structure to agentic AI workflows — we would love to have you involved.

Star the repo. Try it on a real process. Open an issue. Submit a PR. The contribution guide is in docs/contributing.md and there are good first issue labels for anyone who wants to start small.

We are The Real Insight GmbH, and we are building the engine layer for #agenticbpm. This is just the beginning.

→ github.com/The-Real-Insight/in-concert
→ npmjs.com/package/@the-real-insight/in-concert
→ the-real-insight.com

Powered by The Real Insight GmbH BPMN Engine — the-real-insight.com