Custom workflow processes
Purpose: Implement Java process steps for workflows, with payload handling and failure semantics.
Who this page is for
| Audience | Why it matters to you |
|---|---|
| Backend engineers | Automation inside content processes |
A process step
@Component(service = WorkflowProcess.class,
property = {"process.label=PHI Premium Validation"})
public class PremiumValidationProcess implements WorkflowProcess {
@Override
public void execute(WorkItem item, WorkflowSession session, MetaDataMap args)
throws WorkflowException {
String path = item.getWorkflowData().getPayload().toString();
// resolve payload with a service-user resolver, validate premium fields
// throw WorkflowException to fail the step (instance shows failure)
}
}The process.label is what workflow model editors pick in the UI. args carries the PROCESS_ARGS configured on the step — parameterise, don't hardcode.
Payload discipline
| Rule | Why |
|---|---|
| Treat payload as a path, verify it exists and is the expected type | Steps run on assets, pages, anything |
| Use a service-user session, not the workflow session's admin-ish powers, for external effects | Least privilege, auditability |
| Keep steps small and composable | Models are easier to reason about as pipelines of small steps |
| Store step outputs in workflow metadata, not on the content, unless the content is the point | Avoids polluting pages with transient state |
Failure & retry semantics
- Throwing WorkflowException marks the step failed; admins can retry from the console — make steps idempotent.
- Long/external work should not block a workflow thread: enqueue a Sling Job and complete, or use the job's callback to advance (advanced pattern — document it if you use it).
- Failed instances pile up silently; monitoring must watch workflow failure counts (monitoring).