Executable Processes Models: BPMN in Aletyx Playground

​

Accessing Aletyx Playground

curl -sL https://raw.githubusercontent.com/aletyx-labs/kie-10.0.0-sandbox/refs/heads/main/docker-compose.yaml | docker compose -f - up

curl -sL https://raw.githubusercontent.com/aletyx-labs/kie-10.0.0-sandbox/refs/heads/main/docker-compose.yaml | docker-compose -f - up

curl -sL https://raw.githubusercontent.com/aletyx-labs/kie-10.0.0-sandbox/refs/heads/main/docker-compose.yaml | docker-compose -f - up

​

The Aletyx Playground Interface

​

Exploring the Sample Hiring Process

1

Open the sample

From the welcome screen, click Try Sample under the Process section of the Aletyx Playground Create area to start seeing the basics of a BPMN workflow.

2

Review the model

The hiring process BPMN model will open in the editor.

3

Rename the process

If you click the name Sample on the top of the editor, you can change the name. As a best practice, this typically matches the process identification behind the processID for the BPMN model. For this change, we’ll shift it from Sample to hiring.

4

Preview the properties

The properties of the diagram will be explored in more detail later, but to understand the process ID and name, you can get a preview of the panel here.

​

Understanding the Hiring Process Flow

• Start: The process begins with a “New Hiring” event that initializes the candidate evaluation.
• Decision Gateway: Evaluates if the candidate meets minimum requirements.
• Offer Creation: If qualified, an offer is created with salary and bonus calculations.
• Parallel Interviews: HR and IT interviews proceed in parallel.
• Interview Timeouts: Both interviews have timer events (180-second timeouts).
• Hiring Decision Gateway: Based on approvals from both departments.
• Final Steps: Either sending an offer or application denial.

What each numbered part of the BPMN editor does

Top bar and controls

1. Apply Accelerator — Creates a pre-scaffolded project from standards attached to referenced projects, so you can build from model to deployment efficiently using templates. See the Accelerators Reference.
2. New File button — Create new Workflow (.bpmn), Decision (.dmn), or (.pmml) files within the current project folder, or upload other files from your workstation. Applying an accelerator brings in all the files associated with the workspace.
3. Deploy (Dev Deployment) — Trigger a Dev Deployment to try out a service. It’s not a replacement for a full deployment, but an excellent quick testing tool. See the Dev Deployment Reference.
4. Share — Synchronize your project with a Git provider using your credentials, or download the BPMN/DMN file in XML format to use elsewhere. See Git Configuration.
5. Properties of selected item (pen-and-paper icon, top-right) — Opens the selected node’s properties.

Diagram nodes and connectors

6. Start node (green circle) — The entry point of the process. Can be a generic start (as shown here) or triggered from timers, signals, or events (like a Kafka event). See the Start Events Reference.
7. New Hiring script task — Runs a script; here it initializes process variables. Opening its properties shows things like kcontext.setVariable("hr_approval", false).
8. Gateway — split (diamond with ✕) — A point where the process can branch. Here it’s an exclusive gateway: if the candidate meets the requirements the process moves forward, otherwise the application is denied. See the Gateway Reference.
9. Gateway branch (the conditional label on a flow, e.g. “Candidate doesn’t meet requirements”) — The condition a branch follows, typically in DRL syntax (MVEL or Java). See the Gateway Reference.
10. Create Offer script task — Another script task, here building a base offer from the application details so interviewers can review what would be offered.
11. Human task (e.g. “HR Interview”) — A task delegated to a person to work on. See the Human Task Reference.
12. Boundary timer event (clock attached to a task) — Set on tasks (and other services) to escalate, cancel, or create new pathways. Uses the ISO-8601 time standard. See Intermediate Events and the ISO-8601 Reference.
13. Gateway — join (diamond with ✕) — A point where multiple branches of a process come back together. See the Gateway Reference.
14. End node (red circle) — Where the process concludes when it reaches this point. See the End Events Reference.

Left palette (drag elements onto the canvas)

15. Start nodes — Palette items for the various start nodes: generic, or triggered from timers, signals, or events. See the Start Events Reference.
16. Catching and throwing nodes — Create catching and throwing events: compensation events, messages, signals, etc.
17. End nodes — Palette items for the various end nodes. See the End Events Reference.
18. Activities — Create the activities in the process: User tasks, Business Rules tasks, Script tasks, and Service tasks. See the BPMN Activities Reference.
19. Subprocesses — The various types of subprocesses you can use within a process. See the Subprocesses Reference.
20. Gateways — The different gateways a process can use. See the Gateway Reference.
21. Containers — Group tasks belonging to a user/group by swimlane.
22. Artifacts — Annotations that describe or group your model; they have no executable impact.
23. Custom tasks — Use custom tasks within the editor, typically tied to custom work item handlers.

View Sample DMN Model

​

Key BPMN Components

​

1. Events

• Start Event: Marks the beginning of the process
• End Events: Marks process completion
• Boundary Timer Events: The clock symbols attached to interview tasks that trigger after 180 seconds

​

2. Activities

• Script Tasks: “New Hiring”, “Create Offer”, “Send notification HR Interview avoided”, etc.
• User Tasks: “HR Interview” and “IT Interview” requiring human interaction
• Service Tasks: Automated tasks that execute system services (not in this example)

​

3. Gateways

• Exclusive Gateways (Diamond with X): Decision points like “Candidate meets requirements?”
• Parallel Gateways: Points where the process splits into parallel paths (not explicitly shown but parallel flow exists)
• Inclusive Gateways: Points where some paths are taken based on conditions (not in this example)

​

4. Sequence Flows

• Normal Flow: Standard progression path
• Conditional Flow: Follows specific conditions (e.g., “Candidate doesn’t meet requirements”)
• Default Flow: Followed when no other conditions are met

​

5. Data Objects

• Process Variables: candidate, experience, skills, category, salary
• Input/Output Mappings: Data passed between tasks

​

Working with the BPMN Editor

​

Understanding the Editor Interface

• Left Palette: Contains BPMN elements you can drag onto the modeller
• Modeller: The main editing area where you build your process
• Properties Panel: Right-side panel for configuring selected elements
• Top Menu: Tools for saving, deploying, and validating your model

​

Exploring Element Properties

// Example script from "Create Offer" task
if (experience <= 5) {
    salary = 30000;
    category = "Software Engineer";
} else if (experience <= 10) {
    salary = 40000;
    category = "Senior Software Engineer";
} else {
    salary = 50000;
    category = "Software Architect";
}

bonus = skills.split(",").length * 150;

kcontext.setVariable("category", category);
kcontext.setVariable("salary", salary);
kcontext.setVariable("bonus", bonus);

​

Modifying the Process

​

Adding a New Task

1. From the left palette, drag a “User Task” onto the modeller after “Create Offer”.
2. Connect it to the flow:
   • Click on the sequence flow between “Create Offer” and “HR Interview”.
   • Delete it by pressing Delete/Backspace.
   • Use the arrow tool to connect “Create Offer” to your new task.
   • Connect your new task to “HR Interview”.
3. Configure the task:
   • Name it “Manager Approval”.
   • Set the actor to “manager”.
   • Add data inputs/outputs as needed.

​

Adding a Condition to a Gateway

1. Click on the exclusive gateway after “New Hiring”.
2. In the properties panel, select a sequence flow to edit.
3. Add a condition like: return experience >= 2;

​

Adding a Service Task

1. Drag a “Service Task” from the palette to the modeller.
2. Configure it with:
   • Name: “Background Check”
   • Implementation: Select “Java” implementation type
   • Class name: org.acme.hiring.BackgroundCheckService
   • Method: performCheck

​

Process Variables and Data Flow

• Input Variables:
  • candidate (String): Candidate’s name
  • experience (Integer): Years of experience
  • skills (String): Comma-separated list of skills
• Process Variables:
  • hr_approval (Boolean): HR interview approval
  • it_approval (Boolean): IT interview approval
• Output Variables:
  • category (String): Job category based on experience
  • salary (Integer): Base salary calculation
  • bonus (Integer): Bonus calculation based on skills

​

Data Mapping Example

• HR Interview Task:
  • Inputs:
    • candidate: Candidate name
    • approve: Current approval status (hr_approval)
    • category: Job category
    • baseSalary: Salary amount
    • bonus: Bonus amount
  • Outputs:
    • approve: Updated approval status (hr_approval)
    • category: Potentially modified category
    • baseSalary: Potentially modified salary
    • bonus: Potentially modified bonus

​

Process Execution and Testing

​

Testing Your BPMN Process

1. Click the “Deploy” button in the top-right corner.
2. Select the “Deploy to Dev” option.
3. Once deployed, click “Start Process”.
4. Enter test data:
   • Candidate: “John Doe”
   • Experience: 8
   • Skills: “Java,Spring,Drools”
5. Click “Start” to begin the process instance.
6. Navigate to the “Instances” tab to see the running process.
7. Complete user tasks as they appear in the “Tasks” tab.

​

Monitoring Process Execution

1. In the “Instances” tab, click on a running instance.
2. View the process diagram with the highlighted current state.
3. Examine the “Variables” tab to see current values.
4. Check the “Logs” tab for execution history.

​

Deployment Options

​

Local Deployment

1. Click “Deploy” in the top menu.
2. Select “Deploy to Dev”.
3. Access the runtime at http://localhost:9090/management.

​

Kubernetes Deployment

1. Set up Kubernetes configuration:
   • Click on the Profile icon (👤).
   • Select the “Kubernetes” tab and add your cluster.
2. Deploy to Kubernetes:
   • Click “Deploy” in the top menu.
   • Select your Kubernetes environment.
   • Configure deployment options (replicas, resources).
   • Click “Deploy”.

​

Integrating BPMN with DMN

1. Create a DMN model for determining eligibility:
   • Click “New File” > “Decision”.
   • Name it “CandidateEligibility”.
   • Create a decision table with inputs for experience and skills.
   • Connect it to your BPMN model.
2. Integrate the DMN with your BPMN:
   • Replace the exclusive gateway condition with a business rule task.
   • Configure the task to call your DMN model.
   • Map process variables to DMN inputs/outputs.

​

Java Application Integration

​

Setting Up a Java Project

<!-- Maven dependency for KIE API -->
<dependency>
    <groupId>org.kie</groupId>
    <artifactId>kie-api</artifactId>
    <version>10.0.0</version>
</dependency>

​

Invoking the Process from Java

import org.kie.kogito.process.Process;
import org.kie.kogito.process.ProcessInstance;

@Inject
Process<HiringModel> hiringProcess;

public void startHiringProcess(String candidate, int experience, String skills) {
    HiringModel model = HiringModel.builder()
        .candidate(candidate)
        .experience(experience)
        .skills(skills)
        .build();

    ProcessInstance<HiringModel> instance = hiringProcess.createInstance(model);
    instance.start();
}

​

Next Steps

• Create Custom Service Tasks: Develop Java components for integration.
• Use Process Variables: Define complex data structures.
• Add Error Handling: Implement boundary error events and compensation.
• Create Multi-Instance Tasks: Handle collections of data in parallel.
• Build End-to-End Applications: Combine BPMN with DMN and Java services.

​

Additional Resources

• BPMN 2.0 Specification
• Aletyx Documentation
• KIE Apache Projects
• Drools Documentation
• jBPM Documentation