Flowable user task assignment and candidate groups: when a task goes to one person or a pool
A BPMN process has reached a human step, and someone must own the work before the process can move on. In Flowable, a user task can be given to one assignee who owns it outright, or published to candidate users and candidate groups so that anyone qualified can claim it. Use a direct assignee when the work belongs to a known person, such as a manager approving their own team's leave. Use candidates when the work belongs to a role or queue, such as any member of a credit review group, and a person must claim the task before completing it. Both options are stored in the engine as identity links on the task, which the Flowable engine (an Apache 2.0 licensed Java engine with Java and REST APIs) exposes through its APIs.
The engine stores these links but does not know who your people are. Users, groups and their memberships come from your identity source, such as LDAP, Active Directory, Keycloak or a database table, and the engine only checks them against the identity service you wire in. The Flowable docs describe replacing the default identity management by overriding IdmIdentityServiceImpl or implementing the IdmIdentityService interface, with an LDAP implementation provided as a reference. Confirm with your architects which system is the source of truth for group membership, how group changes reach the engine, and what happens to open tasks when a person leaves a group. Those answers decide whether candidate groups stay accurate for the life of a long-running case.
Before modeling, list every human step and label it as one owner, one pool, or a pool that a named person must claim. Then confirm the identifiers your model will use, such as user IDs and group IDs, match what the identity source returns, because a mismatch fails silently and leaves tasks with no visible owner. Decide who may reassign a task, who may add candidates, and whether an assignee can hand work back to the pool. These rules sit in your application and in the authorization checks you build around the engine, so write them down with the process owner before the first model is deployed.
Which assignment option fits which task
This table compares the six ways a Flowable user task can be routed to people, from a fixed assignee to a custom identity link type. Read each row against your process: the right option depends on how many people should see the task, how often ownership changes, and how much your auditors need to reconstruct who acted on it. The main takeaway is that broader routing gives flexibility at the cost of inbox clarity and reassignment effort.
| Option | When it fits | What it needs from the identity source | Main trade-off |
|---|---|---|---|
| Direct assignee | One known person owns the work for its whole life, such as a manager approving their own team's request | A stable user ID that exists in the identity service when the task is created | Only one person sees the task, so absence or departure stalls it until someone reassigns it |
| Candidate users | A small, named pool of people is allowed to claim the task, such as two reviewers in a specific branch | Stable user IDs for each candidate, resolved at task creation or by expression | Membership is fixed in the model or variables, so changes to the pool need data updates or a listener |
| Candidate groups | Any member of a role or team may claim the work, such as a payments operations group | Group IDs that the identity service returns for each user, consistent across deployments | Inbox visibility depends on group membership being accurate, and claimed work must be tracked for audit |
| Expression-based assignment | Assignee or candidates depend on process data, such as a cost center owner looked up from a variable | Variables or a lookup service the expression can call, with values that are validated before use | Logic lives in expressions that are harder to review and test than static model settings |
| Task listener assignment | Routing needs a lookup, a rule that is too complex for an expression, or a decision made at task creation | Java code with access to the identity service, plus error handling for missing or inactive users | Routing logic sits in code outside the diagram, so changes need a release and tests |
| Custom identity link types | You need a relationship beyond owner and candidate, such as reviewer, approver of record or data steward | A defined link type name agreed with the application and reporting teams, plus queries that read those links | Your application must enforce what each link means, because the engine stores the link without judging it |
Choosing between static, expression and listener-driven assignment
Use a fixed assignee or candidate group when the people responsible for a step do not change with the case. A finance approval that always goes to a named controller group, or a legal review that always goes to the legal queue, is a good fit. The assignment is stored in the BPMN model, so anyone reading the diagram can see who acts at each step. Testing is simple because the expected owner is the same for every instance of the process.
- Model-visible ownership: The assignee or candidate group appears on the user task, so reviewers see the rule without reading Java.
- Easy unit tests: Assert that the task's identity links match the expected group after the task is created.
- Stable identifiers: Group names become part of the model, so they must match the identity source your organization actually uses.
- Limited flexibility: Any change in who owns the step requires a new process deployment, which affects the versioning of running instances.
- Risk of hard-coded roles: Role names copied into many models become hard to rename when the identity directory changes.
Before relying on this approach, confirm with the business owner that the group will not change for the life of the process, and confirm the group name with the team that administers identity.
Use expressions when the owner depends on data in the process, such as a region, an amount threshold or the manager of the requester. The expression reads process variables or calls a bean that performs a lookup, typically against an HR system or directory. This keeps the BPMN model general while the rule for each instance comes from its data. The lookup logic should live in a named Spring or Java service that the engine calls, not inline in the model, so it can be tested without running a process.
- Variable-driven rules: Expressions such as an assignee read from a variable let one model serve many cases.
- Lookup services as the single source: Put directory or HR calls behind one service so every process uses the same rule.
- Test both inputs and outputs: Cover each variable value, missing values and lookup failures, with the expected owner for each.
- Failure handling: Decide what happens when a lookup returns no owner, such as routing to a fallback group or raising an error.
- Operational dependency: An external lookup adds a runtime dependency, so timeouts and availability of the source system affect task creation.
Confirm how Flowable behaves when an expression resolves to null in your version by testing it, and document the fallback rule with the process owner.
Use task listeners when the owner depends on logic that is awkward to express in a model, such as weighted queues, workload balancing or rules that combine several sources. A listener fires when the task is created and can set the assignee, add candidates or change identity links before the task appears to users. This is the most flexible option and also the easiest to hide, because the rule lives in code that the diagram does not show.
- Full control at creation: The listener can read the task, the execution and all variables before choosing an owner.
- Hidden behavior: Document the listener class and its rule in the model documentation so the diagram is not misleading.
- Dedicated unit tests: Test the listener in isolation with a mocked task and verify the identity links it produces.
- Concurrency and ordering: Confirm that other listeners or defaults do not overwrite the owner set at creation.
- Audit trail: Make sure the chosen owner and the reason are recorded in variables or logs, so auditors can reconstruct the decision.
Before choosing this approach, ask the engineering team to show how the listener is tested and where its configuration is deployed across environments.
Setting up user task assignment in a Flowable project
This sequence moves a Flowable project from an agreed identity model to user tasks that route correctly to people and groups, with a check at each stage. The result is a tested assignment design that your team can maintain as identity sources and organizational structures change.
Agree the identity source and group model
Before any BPMN work, the architecture owner and the identity team decide where users and groups come from (a directory such as LDAP, an identity provider, or a database table), which group names will be used as candidate groups, and whether role-based or organization-unit-based groups drive routing. Record the group names, their owners and how membership changes are handled. This step is done when the team can list every candidate group a process will reference and name the system of record for each one. Confirm with your identity team how group membership is synchronized into the environment Flowable will read from.
Connect the identity service
Flowable manages users and groups through its identity management service. Your developers either override IdmIdentityServiceImpl or implement the IdmIdentityService interface, using the LDAP identity service implementation that Flowable provides as a reference starting point. The developer wires the implementation into the engine configuration and points it at your directory or table. Check this step by using the service directly in a test: look up a known user, confirm that user's group memberships, and confirm that an unknown identifier returns nothing rather than an error. Review the Flowable configuration and advanced documentation for the exact extension points in the version you run.
Model tasks with assignee or candidate settings
In the BPMN model, the process designer chooses per user task whether one person owns the work (assignee) or a set of eligible users or groups may claim it (candidate users and candidate groups). Use assignee when the work is fixed to one person at start, and candidate settings when a pool of people should pick it up. Name each candidate group exactly as the identity service returns it. The output is a deployed process definition in which every user task has a deliberate assignment setting. Check this by deploying the model to a test engine and querying the task list for two users, one inside and one outside the candidate group.
Add listeners for dynamic assignment
When eligibility depends on data from the running process, such as a region, a limit or a case owner, add task listeners on the create event that set the assignee, candidate users or candidate groups from process variables or from a service call. Keep the listener logic small and move lookups into a Java service that you can unit test. The step is complete when a process run with different input variables produces different assignments, and the listener writes the chosen values to the task so that they appear in later queries. Confirm that the listener does not depend on information that will not exist at task creation time.
Configure due dates on user tasks
Set due dates on user tasks where the process has a service expectation, using the due date setting for the task in the model or a listener that computes it from variables. Due dates are a property of the task, so they can be read through the task query API and used for reminders or escalations, which are handled by timer events in a separate design. Check the result by completing one task, leaving another open, and confirming that each task carries the due date your rule produces. Document which time zone and calendar rules your team expects, since these affect what the due date means for users.
Verify assignment with tests and task queries
Write automated tests that deploy the process, start instances with representative variables, and query tasks as different users. Cover the assignee path, each candidate group, users who should see nothing, and the listener output. Add a claim and unclaim scenario to confirm that a candidate who claims a task removes it from other candidates' queries. The step is complete when the test suite passes against the same identity service configuration that production will use, and when a query for each role returns the expected task set. Keep these tests in the pipeline so that changes to groups or models are caught before deployment.
Setting due dates on user tasks without losing control of escalation
A due date on a Flowable user task is informational by default. Setting one records when the work is expected to finish, which helps task lists and reporting, but the engine does not act on it by itself. Nothing happens when the date passes unless a timer event in the process model is wired to that task. Decide before modeling whether a due date is only a label for people or the trigger for a reminder, a reassignment or an escalation, because those two uses require different models and different testing.
Escalation behavior belongs to the timer events and deadlines topic, which covers boundary timers, interrupting versus non-interrupting timers and ISO 8601 durations. Keep the due date on the task as the business commitment and let a boundary timer on the same user task carry the consequence. Avoid computing the due date in one place and the escalation in another, since two sources of truth drift apart when a rule changes. A task listener that sets the due date on create is a reasonable pattern, but the listener and the timer definition should read the same duration variable so one edit changes both.
Timers run on the async executor, which fires jobs from a thread pool and coordinates several nodes through lock owners and lock expiration times in the database. In a clustered deployment, a timer that is due can fire on any node, so check that every node shares the same database and job configuration, and test a timer fire on a multi-node setup before production. Confirm how your Flowable version exposes and handles due dates on user tasks against the Flowable documentation for that release, and run a short test that completes a task after its due date to confirm which behavior your model produces.
Security risks in task assignment and identity links
Task assignment decides who sees a Flowable user task, who can claim it and who can finish it. The engine stores assignees, candidate users and candidate groups as data, but it does not decide whether a given caller should be allowed to act on them. The five risks below connect the assignment model to the authorization, identity and audit controls your application and identity provider must supply.
Tasks visible to the wrong people
A candidate group or expression that is broader than intended exposes a task to users who should never see the case. Review every candidate group name and every expression that builds a list of candidates, and confirm that your task query API filters by the identity the caller presents, not by a value the client sends. Test with a user from each adjacent department. Confirm whether your task list endpoints apply any filter beyond what the engine returns.
Stale group membership after role changes
Candidate groups are resolved from the identity service when a task is created or queried, and a person who changes roles can keep access to tasks in groups they left. Confirm how your identity service synchronizes group membership, how often, and whether removals propagate as quickly as additions. Document who owns the group mapping, and test a role change against open tasks before go-live.
Expression injection through process variables
Assignee and candidate expressions that read process variables let anyone who can set those variables influence who receives a task. If a variable comes from a form, an API call or an external message, it is untrusted input. Restrict which variables feed assignment expressions, validate values against an allowed list, and avoid expressions that evaluate free text. Review how the same variables are set by external callers.
Unchecked claim and complete calls
The engine does not verify that the caller is allowed to claim, delegate or complete a task. Those checks belong to your application layer, including the REST application, custom services and any worker that calls the Java API. Map each claim, complete and reassign operation to a permission, enforce it before calling the engine, and test with a user who is not a candidate to confirm the call is refused.
Gaps in reassignment audit history
Reassignments change who is accountable for a decision, so the history of each change matters. Confirm that your history level records assignee changes and identity links, and decide who may reassign tasks and whether a reason must be captured. Check that the stored record includes the acting user, the previous and new assignee, and the time. Retention of this history should match your records policy.
Questions teams ask before assigning user tasks
How much effort does the identity integration take?
The effort depends mainly on how many identity sources you have, how cleanly users and groups map to the roles your process needs, and whether group membership changes in the directory itself or in a separate system. Flowable's docs say identity management can be replaced by implementing the IdmIdentityService interface or overriding IdmIdentityServiceImpl, and an LDAP identity service is provided as a reference. A single directory with stable groups is a small, bounded piece of work. Several directories, nested groups, or groups maintained by hand in spreadsheets add design and testing time. Ask any partner to split the quote into discovery, the identity service build, and test cases for each assignment rule.
Can our internal team do this without a partner?
Yes, if your team has Java developers who already know Flowable's task model and access to your directory. The identity service is a documented extension point, so the build is ordinary application code. Teams usually struggle in three places: agreeing on what a candidate group means across departments, testing assignment rules against realistic data, and keeping reassignment logic consistent across processes. A partner is most useful for the design review and for the first process that sets the pattern. Ask whether the partner will leave you with documented rules and tests your own engineers can extend.
What does the work need from our directory team?
Your directory team needs to confirm which attributes identify a person, how groups are named and nested, and who is allowed to change group membership. They also need to provide a test account set and a read-only service account for the engine to query users and groups. If you use LDAP, they should confirm the search bases, group object classes, and how disabled accounts are represented. Ask for a written list of these items before the design review starts, so the review does not stop on questions about your directory.
How long does a design review depend on the number of processes?
The review length is driven mostly by how many distinct assignment patterns your processes use, not by the raw number of process models. Ten processes that all assign to the same role group need one pattern review. Five processes with dynamic assignment, delegation rules and escalation to managers need a separate review for each pattern. Ask the reviewer to group your processes by assignment pattern and to list the decisions each pattern requires from your business owners. Then ask for the review scope and deliverables in writing before work starts.
Can candidate groups come from LDAP?
Yes, Flowable's identity model can be backed by LDAP through the reference LDAP identity service, so candidate groups can map to directory groups. Confirm with your directory team which group object type you use, whether group membership is stored on the group or the user, and how nested groups should be expanded. Then have the engineers test a group with both direct and nested members, and a user removed from a group mid-task, to see what the engine shows. Check the Flowable identity documentation for the version you run before relying on any specific behavior.
How is reassignment audited?
Reassignment is audited through Flowable's history and your own logging, so you should decide up front which events must be kept and for how long. The engine records identity links and task changes in history when history is enabled, but the retention and detail you need depend on your configuration. Add a task listener that writes who changed the assignee, when, and why, into your audit store. Test the record by reassigning a task, claiming it, and delegating it, then confirm each step appears where your auditors will look. Confirm the exact history levels with your Flowable version's configuration docs.
What changes when moving between Flowable major versions?
Major versions change the platform baseline, which affects the identity integration code. Flowable 7.0.0 moved to Java 17, Spring Boot 3 and Jakarta EE. Flowable 8.0.0 moved to Spring Framework 7 and Spring Boot 4, dropped support for Spring Boot 3, made Jackson 3 the default JSON library with a Jackson 2 compatibility layer, and removed JUnit 3 and 4 support. Your custom identity service and listeners need to be rebuilt against the new baseline and retested. Read the release notes for the version you are moving to before estimating the upgrade.
What Flowable version changes mean for identity integration
If your task assignment depends on a custom identity service, a custom task listener or a Spring-based user lookup, the first check is the runtime baseline those classes run on. Flowable 7.0.0 moved the engines to Java 17, Spring Boot 3 and Jakarta EE, and Flowable 8.0.0 moved to Spring Framework 7 and Spring Boot 4, with Jackson 3 as the default JSON library and no backward compatibility for Spring Boot 3. Any identity code that imports javax packages, relies on Spring Boot 3 auto-configuration, or serializes candidate data with Jackson 2 types needs review before you change versions.
The identity integration points deserve the same scrutiny. The Flowable docs describe replacing identity management by overriding IdmIdentityServiceImpl or implementing the IdmIdentityService interface, with an LDAP implementation provided as a reference. Confirm against the release notes for your target version that the interface methods and the reference LDAP code still match what you have built, and that your task listeners and assignment expressions still resolve the beans they call. Test dynamic assignment on a staging copy with real group data, because a silent change in how a group list is returned will route tasks to the wrong queue without raising an error.
Treat the version decision and the identity review as one piece of work. Ask your Flowable partner or internal team to list every custom class that touches users, groups or identity links, and map each one to the baseline it depends on. The step-by-step upgrade sequence, including the Spring and Jackson changes, is covered in the Flowable upgrades material, which you should read alongside the 8.0.0 release notes before scheduling the change.
What DeployOpen needs from your team to scope this work
This sequence turns your current human task handling into a written assignment model that the Flowable engine can enforce. Each input builds on the previous one, and the result is a scope document that both teams sign before build work starts.
Share the process inventory with human tasks
Your process owners and lead engineers list every BPMN process that contains a user task, with the business purpose, the trigger, and the approximate volume of tasks each process creates. DeployOpen reviews the list against the BPMN models or diagrams you provide and marks which user tasks need a named assignee, which need candidate users or groups, and which are claimed from a queue. The step closes when every human task is on one agreed inventory with an owner for each process.
Document the identity source and group model
Your identity team describes where users and groups live, such as an LDAP directory, an identity provider, or a database table, and how group membership changes over time, including joiners, leavers and role changes. DeployOpen maps each group to the candidate groups used in the inventory and notes any group that is nested, dynamic, or maintained outside your directory. The step closes with a group model that names the source of truth for every group a task can reference.
Define custom identity link types
Your process and business owners state whether any task needs roles beyond assignee and candidate, for example a reviewer, approver or escalation owner that must be recorded on the task. DeployOpen decides with your team whether these become custom identity link types or are better modeled as variables, and checks how the reporting and task queries will read them. The step closes with a short list of link types, each with a meaning and the processes that use it.
Set audit and reassignment rules
Your compliance and operations leads write down who may reassign a task, who may claim it, what happens when an assignee leaves, and which reassignments must be recorded with a reason. They also state which assignment events must be kept for audit and for how long, and who can view them. DeployOpen converts these rules into the listener and authorization design that the build will implement, and flags any rule the engine does not enforce on its own. The step closes with a signed rules table that the build team can test against.
Specify due date and escalation expectations
Your process owners state which tasks have a due date, how that date is set (fixed, relative to a start event, or calculated from a variable), and who is notified when a task is overdue. DeployOpen notes which of these depend on timer events and which depend on your own notification channels, so the scope covers both. The step closes with a due date table for each task in scope.
Provide test users and a test identity environment
Your team supplies test accounts and test groups in a non-production identity source that match the roles in the inventory, including users who should be allowed to act and users who should be refused. DeployOpen uses them to write assignment tests that check each candidate rule, each reassignment permission and each due date. The step closes when the test identities can log in or be resolved by the engine in the test environment, and the test matrix is agreed.
Agree the fixed scope in writing
DeployOpen turns the inventory, group model, link types, rules, due date table and test matrix into a written scope with deliverables, responsibilities and a timeline. Most engagements are fixed-scope, so the scope and the quote are agreed in writing before any build work starts. Your team confirms who signs for the business, security and the platform. The step closes with a signed scope document that names every task, group and rule in the build.
How DeployOpen scopes, builds and supports Flowable task assignment
DeployOpen plans, implements and supports Flowable user task assignment inside your own infrastructure, starting from the people, groups and approval rules your process must honor. Engagements are fixed-scope, with the assignment model agreed in writing before any model or code changes begin.
How we scope
- Inventory every user task and record whether each needs one assignee, a candidate user list or a candidate group.
- Document the identity source of users and groups, and who owns the mapping from identity records to Flowable group names.
- Agree in writing which assignment extensions, custom identity link types and due date rules are in the fixed scope.
How we build
- Model assignment in BPMN and implement dynamic assignment in task listeners, with logic reviewed against your written rules.
- Test claim, delegate, unclaim and reassignment paths with unit tests and scripted scenarios covering each candidate group.
- Connect the identity service to your directory through the Flowable identity extension points, with access checks left to your application where the engine does not perform them.
How we hand over
- Deliver the assignment matrix, listener code, configuration and test evidence as documentation your team can maintain.
- Walk your engineers through how to add a candidate group, change a due date rule and verify task visibility after deployment.
- Record open questions, such as group membership sync timing, so your team can decide them before go-live.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer, scoped separately from the fixed-scope build.
- Retainer work can cover reviewing assignment changes when the Flowable version or identity source changes.
- Confirm the supported Flowable version and upgrade path with your team before scheduling retainer work, since version changes can affect listeners and identity services.
