Skip to content
3

@miragon/rules/worker-topic-naming โ€‹

Reports a worker topic that does not follow the project's naming scheme: the topic of a Camunda 7 or Operaton external task, or the job type of a Camunda 8 task.

Examples โ€‹

Both models show the same external service task. Only its topic differs.

worker-topic-naming/invalid.bpmn

Invalid model: a worker topic off the naming scheme

Valid model: a worker topic on the naming scheme

1 finding
  • serviceTask_reviewOrder Worker topic <review-order> must match <camelCase>

Invalid: the topic review-order is off the default camelCase scheme

Valid: the same task with the topic reviewOrder

The same, as XML. ๐Ÿ‘Ž wrong:

xml
<bpmn:serviceTask id="serviceTask_reviewOrder" camunda:type="external" camunda:topic="review-order" />
<bpmn:serviceTask id="serviceTask_reviewOrder">
  <bpmn:extensionElements>
    <zeebe:taskDefinition type="review-order" />
  </bpmn:extensionElements>
</bpmn:serviceTask>

๐Ÿ‘ right:

xml
<bpmn:serviceTask id="serviceTask_reviewOrder" camunda:type="external" camunda:topic="reviewOrder" />
<bpmn:serviceTask id="serviceTask_reviewOrder">
  <bpmn:extensionElements>
    <zeebe:taskDefinition type="reviewOrder" />
  </bpmn:extensionElements>
</bpmn:serviceTask>

Why โ€‹

A worker topic is a contract between the model and the code. The worker subscribes to exactly this string, so a developer writing the worker has to find it, an operator reading Cockpit or Operate has to recognise it, and nothing fails at deploy time when two teams spell it differently. A scheme such as billing.validateInvoice says which service owns the work and what the work does. Without one the scheme lives in a wiki page nobody checks, and a topic like validate-invoice next to ValidateInvoice leaves the developer guessing which worker picks it up.

Camunda 7 calls this string a topic, Camunda 8 a job type. It is the same contract, so one rule with one scheme covers both, and a team that moves from Camunda 7 to 8 keeps its configuration.

Why this matters for agentic BPMN โ€‹

An agent that adds a service task has to invent a topic. With no stated scheme it copies whatever shape it saw last, and the result deploys cleanly while no worker ever fetches the job.

Typical AI artifact without this rule: billing.validateInvoice, validate-invoice and ValidateInvoiceTopic in one model, each from a different edit.

What this rule guarantees: every worker topic follows one configured scheme, so a tool can generate a topic that passes from the same .bpmnlintrc.

Scope โ€‹

The rule reads the topic where the engine keeps it:

  • Camunda 7 and Operaton: camunda:topic or operaton:topic on an external task (camunda:type="external" or operaton:type="external"). That covers a service, business rule or send task, reported on the task, and the message event definition of a throw or end event, reported on the event.
  • Camunda 8: the type of <zeebe:taskDefinition> in an element's extension elements, reported on that element.

It leaves these alone:

  • A missing topic or job type. That is a deploy error the engine layer reports, not a naming finding.
  • An expression (=โ€ฆ in FEEL, ${โ€ฆ} or #{โ€ฆ} in JUEL). The engine resolves it at runtime, so there is no fixed value to check.
  • A task that is not external, even if it carries a camunda:topic attribute.

The rule reads only camunda:, operaton: and zeebe: attributes, so a diagram without workers never produces a finding.

Configuration โ€‹

Every option is optional. Without any, the rule checks the default scheme: camelCase segments joined by a dot.

OptionDefaultEffect
prefixnoneFixed text every topic starts with, followed by the separator.
separator.Joins the prefix and every segment.
casecamelCaseShape of every segment: camelCase, PascalCase, snake_case, kebab-case or any.
segmentsone or moreExact number of segments after the prefix. Any value but a positive integer is ignored.

An unknown case falls back to PascalCase, the same way element-id-naming does. A dot inside the prefix does not count as a segment: { "prefix": "com.acme.billing", "segments": 1 } accepts com.acme.billing.validateInvoice.

ConfigurationPassesReported
nonevalidateInvoice, billing.validateInvoicevalidate-invoice
{ "prefix": "billing" }billing.validateInvoicevalidateInvoice, billing.ValidateInvoice
{ "segments": 2 }billing.validateInvoice, shipping.validateInvoicevalidateInvoice, billing.invoice.validateInvoice
{ "prefix": "billing", "separator": "/", "case": "kebab-case" }billing/validate-invoicebilling/validateInvoice

Several services โ€‹

One .bpmnlintrc often covers several services, each with its own lead (billing.โ€ฆ, shipping.โ€ฆ). Two ways to check that:

  • { "segments": 2 } in the shared .bpmnlintrc fixes the shape <service>.<name> for every service. It does not know the service names, so a typo such as biling.validateInvoice passes.
  • One .bpmnlintrc per service, each with its own prefix, checks the service name exactly. Run bpmnlint once per service, for example npx bpmnlint --config services/billing/.bpmnlintrc "services/billing/**/*.bpmn".

A tool that creates BPMN reads the same options through the exported naming helpers. It builds the topic from the prefix and a name it was given, never a guessed service, and checks the result:

ts
import { naming } from '@miragon/bpmnlint-plugin-rules';

const scheme = new naming.ValueNamingScheme({ segments: 2 });

scheme.matches('billing.validateInvoice'); // true
scheme.describe(); // '<camelCase>.<camelCase>'

Further reading โ€‹