Skip to content
Skills Library
Programming · Building & coding

create-delegate

/create-delegate

Create, update or test a JavaDelegate or an execution/task listener for a BPMN element on Fluxnova (Camunda 7 fork), wired as a Spring @Component and invoked by expression (#{beanName}), together with its unit test and the process test of its path. Use when the user asks to create a delegate, wire a service task to code, add a JavaDelegate or listener, or test an existing delegate. A delegate extends BaseDelegate, calls exactly one inbound port, and reads process variables through the typed ProcessApi.

Licence
MIT
Last repository change
07.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
6
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 07.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • SKILL.md zawiera komentarze HTML (6). Nie widać ich w podglądzie Markdown, a model je czyta.

What it does and when to use it

Create, update or test a JavaDelegate or an execution/task listener for a BPMN element on Fluxnova (Camunda 7 fork), wired as a Spring @Component and invoked by expression (#{beanName}), together with its unit test and the process test of its path. Use when the user asks to create a delegate, wire a service task to code, add a JavaDelegate or listener, or test an existing delegate. A delegate extends BaseDelegate, calls exactly one inbound port, and reads process variables through the typed ProcessApi.

Arguments

/create-delegate [element-id or task name] [DelegateClassName]
Original author description

Create, update or test a JavaDelegate or an execution/task listener for a BPMN element on Fluxnova (Camunda 7 fork), wired as a Spring @Component and invoked by expression (#{beanName}), together with its unit test and the process test of its path. Use when the user asks to create a delegate, wire a service task to code, add a JavaDelegate or listener, or test an existing delegate. A delegate extends BaseDelegate, calls exactly one inbound port, and reads process variables through the typed ProcessApi.

How it works

  1. Production pattern
  2. Test it twice
  3. Instructions
Original SKILL.md headings · 177 lines, 953 words
SKILL.md preview
---
name: create-delegate
argument-hint: "[element-id or task name] [DelegateClassName]"
description: "Create, update or test a JavaDelegate or an execution/task listener for a BPMN element on Fluxnova (Camunda 7 fork), wired as a Spring @Component and invoked by expression (#{beanName}), together with its unit test and the process test of its path. Use when the user asks to create a delegate, wire a service task to code, add a JavaDelegate or listener, or test an existing delegate. A delegate extends BaseDelegate, calls exactly one inbound port, and reads process variables through the typed ProcessApi."
allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Skill
---

# Skill: create-delegate

One `@Component` per piece of work in `adapter/inbound/fluxnova/` (package `io.miragon.blueprint`
under `service/app/src/main/`), plus its tests; one bean may serve several elements
(`sendCancellationConfirmationDelegate`). Fluxnova runs **embedded**; service tasks call
**JavaDelegates by expression**, not external task workers. The architecture rules are in
`AGENTS.md` (Architecture); this skill does not repeat them.

## Production pattern

Copy the shape of the existing classes instead of inventing one:

| Case | Reference |
|---|---|
| a delegate that calls a port and nothing else | `SendContractDelegate` |
| reads a variable, writes one back, maps a domain exception to a `BpmnError` | `OrderBikeDelegate` |
| a task listener | `ClarifyAlternativeTaskListener` |
| an execution listener | `BikeOrderAuditListener` |

- A delegate extends `BaseDelegate` and overrides `executeTask`; a listener implements
  `TaskListener` / `ExecutionListener` directly.
- The BPMN references the bean by expression, `#{beanName}` (class name with a lowercase first
  letter): `camunda:delegateExpression` on a service task or message event, `delegateExpression` inside
  `camunda:taskListener` / `camunda:executionListener`. The model test
  `ServiceTaskDelegateExpressionRule` only requires service tasks to use an expression; a wrong bean
  name surfaces in the process test.
- Suffix `Delegate`, `Worker` or `Listener`; at most one inbound port (the architecture tests fail
  above one). A delegate calls exactly one; a listener may call none.
- The application id comes from the business key (`execution.processBusinessKey`), every other
  variable through `<Process>ProcessApi.FlowNodes.<Node>.Variables`, never a raw string. Process
  variables stay minimal: ids, plus what a gateway or the DMN reads.
- A domain exception becomes `BpmnError(Errors.<X>.code, …)` where the model has a boundary event for
  it. The `@Transactional` service behind the delegate declares that exception in `noRollbackFor`
  (see `OrderBikeService`), or the job transaction rolls back and the error path never runs.

## Test it twice

**1. A unit test** in the test tree's `adapter/inbound/fluxnova/<Name>Test`, one test per outcome:
the happy path (the exact port call with the id from the business key, every variable written
back), each `BpmnError` the delegate throws (the code from the generated `Errors`, never a string
literal), and for a listener the effect it has. No Spring, no engine; verify the port call and that
nothing else was called; call `execute`, not `executeTask`, so `BaseDelegate` runs as in the engine.
Same style as the service tests (`OrderBikeServiceTest`): `underTest`, given/when/then comments.

No delegate test exists yet, so here is a sketch written against `OrderBikeDelegate`
(imports left out; `FlowNodes` comes from `BikeLeasingProcessProcessApi`):

<!-- variant:kotlin-gradle -->
```kotlin
class OrderBikeDelegateTest {

    private val useCase = mockk<OrderBikeUseCase>()
    private val execution = mockk<DelegateExecution>()
    private val underTest = OrderBikeDelegate(useCase)

    private val applicationId = ApplicationId.new()
    private val bikeId = BikeId("BIKE-900")

    @BeforeEach
    fun givenTheApplicationAndItsBike() {
        every { execution.processBusinessKey } returns applicationId.value.toString()
        every { execution.getVariable(FlowNodes.ServiceTaskOrderBike.Variables.BIKE_ID.value) } returns bikeId.value
        every { execution.currentActivityId } returns FlowNodes.ServiceTaskOrderBike.ELEMENT_ID
    }

    @Test
    fun `orders the bike of the application and keeps the order id`() {

        // given: the dealer accepts the order
        every { useCase.orderBike(applicationId, bikeId) } returns OrderId("ORDER-900")
        every { execution.setVariable(FlowNodes.ServiceTaskOrderBike.Variables.ORDER_ID.value, "ORDER-900") } just Runs

        // when: the engine executes the delegate
        underTest.execute(execution)

        // then: the order is placed for the application and its id lands in the process
        verify { useCase.orderBike(applicationId, bikeId) }
        verify { execution.setVariable(FlowNodes.ServiceTaskOrderBike.Variables.ORDER_ID.value, "ORDER-900") }
        confirmVerified(useCase)
    }

    @Test
    fun `turns an unavailable bike into the bikeUnavailable BPMN error`() {

        // given: the dealer cannot deliver the bike
        every { useCase.orderBike(applicationId, bikeId) } throws BikeUnavailableException(bikeId)

        // when / then: the delegate throws the BPMN error the boundary event catches
        assertThatThrownBy { underTest.execute(execution) }
            .isInstanceOf(BpmnError::class.java)
            .extracting("errorCode")
            .isEqualTo(Errors.BIKE_UNAVAILABLE.code)
        verify { useCase.orderBike(applicationId, bikeId) }
        confirmVerified(useCase)
    }
}
```

`BaseDelegate` logs `execution.currentActivityId` on every exception: stub it, or the strict mock
throws a `MockKException` that hides the `BpmnError`.
<!-- /variant:kotlin-gradle -->

<!-- variant:java-maven -->
```java
class OrderBikeDelegateTest {

    private final OrderBikeUseCase useCase = mock(OrderBikeUseCase.class);
    private final DelegateExecution execution = mock(DelegateExecution.class);
    private final OrderBikeDelegate underTest = new OrderBikeDelegate(useCase);

    private final ApplicationId applicationId = ApplicationId.newId();
    private final BikeId bikeId = new BikeId("BIKE-900");

    @BeforeEach
    void givenTheApplicationAndItsBike() {
        when(execution.getProcessBusinessKey()).thenReturn(applicationId.value().toString());
        when(execution.getVariable(FlowNodes.ServiceTaskOrderBike.Variables.BIKE_ID.getValue())).thenReturn(bikeId.value());
    }

    @Test
    void ordersTheBikeOfTheApplicationAndKeepsTheOrderId() throws Exception {

        // given: the dealer accepts the order
        when(useCase.orderBike(applicationId, bikeId)).thenReturn(new OrderId("ORDER-900"));

        // when: the engine executes the delegate
        underTest.execute(execution);

        // then: the order is placed for the application and its id lands in the process
        verify(useCase).orderBike(applicationId, bikeId);
        verify(execution).setVariable(FlowNodes.ServiceTaskOrderBike.Variables.ORDER_ID.getValue(), "ORDER-900");
        verifyNoMoreInteractions(useCase);
    }

    @Test
    void turnsAnUnavailableBikeIntoTheBikeUnavailableBpmnError() {

        // given: the dealer cannot deliver the bike
        when(useCase.orderBike(applicationId, bikeId)).thenThrow(new BikeUnavailableException(bikeId));

        // when / then: the delegate throws the BPMN error the boundary event catches
        assertThatThrownBy(() -> underTest.execute(execution))
                .isInstanceOf(BpmnError.class)
                .extracting("errorCode")
                .isEqualTo(Errors.BIKE_UNAVAILABLE.getCode());
        verify(useCase).orderBike(applicationId, bikeId);
        verifyNoMoreInteractions(useCase);
    }
}
```

Mockito's `mock()` is lenient; the strictness comes from `verifyNoMoreInteractions`.
<!-- /variant:java-maven -->

**2. A process test** for the path through the engine in the test tree's `adapter/process/` (see
`BikeLeasingProcessTest`): it walks the path the element sits on and verifies the port call there.
The unit test proves the mapping, the process test proves the wiring (bean name, variables, boundary
events). Delegates are outside the mutation gate, which covers the domain only, so the
unit test is the only isolated check of the mapping.

## Instructions

1. **Load** the model in `service/app/src/main/resources/bpmn/` and the generated
   `BikeLeasingProcessProcessApi` (or `CancelBikeOrderProcessApi`). The BPMN is the source of truth for
   the element, its `delegateExpression`, its variables and its boundary events.
2. **Identify the element** from `$ARGUMENTS`, else list the service tasks and listeners and ask.
3. **Find the inbound port** in `application/port/inbound/` (`*UseCase`/`*Query`). If it is missing,
   create port and service first, or run skill `automate-process` when the model changes too.
4. **Write the unit test first**, then the delegate; for an existing class add only what is missing.
5. **Add or extend the process test** for the path.
6. **Run** both (`AGENTS.md` → Verify After Each Task): the unit test by name, then the
   `io.miragon.blueprint.adapter.process` tests.
<!-- variant:blueprint -->
7. **Both variants:** the same delegate and the same tests in `kotlin-gradle/` and `java-maven/`.
<!-- /variant:blueprint -->

Versions

RepositoryScoreLicence
This page · Miragon/process-engine-blueprints100MIT
Miragon/process-engine-blueprints100MIT
Miragon/process-engine-blueprints100MIT
Miragon/process-engine-blueprints90MIT

Database snapshot: 13.11.2026 · package version 17b296d7a8e4 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100create-worker
    Implements one BPMN service task as a job worker, JavaDelegate or external-task handler that calls one use case, with names from the generated Process API. Use when a service task or job type needs code that handles it.
  • 100automate-process
    Change an executable Fluxnova BPMN model of this repo (bike-leasing.bpmn, cancel-bike-order.bpmn) and wire its glue code across the hexagon: edit the model with bpmn-cli, regenerate the typed process API, add ports, services, delegates and process-adapter methods, cover the new…
  • 100test-worker
    Writes the unit test for one job worker, JavaDelegate or external-task handler, covering inputs, outputs, BPMN errors and retries. Use when testing a worker or after create-worker.
  • 90camunda-job-workers
    Use this skill when writing the code behind an automated step of a BPMN process — a Java, Spring Boot, or TypeScript handler bound to a service task that completes the job, fails it, or throws a BPMN error — even if job workers aren't mentioned. Implements Camunda 8 job workers.…
  • 100camunda-bpmn
    Use this skill whenever work that spans several steps, people, or systems must run reliably — approvals, hand-offs, escalations, deadlines, retries, or compensation — even if Camunda or BPMN isn't mentioned. Load it before recommending an approach or tool for running such work.…
  • 100automate-process
    Change an executable CIB seven BPMN model of this repo (bike-leasing.bpmn, cancel-bike-order.bpmn) and wire its glue code across the hexagon and up to the browser: edit the model with bpmn-cli, regenerate the typed process API, add ports, services, delegates and process-adapter…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.