Human Task Framework: Abstraction and Business Workflow Patterns

[igordayen]

Human Task Framework: Abstraction and Business Workflow Patterns

Overview

Purpose

A comprehensive Human Task framework that provides a generic abstraction for human work
within automated workflows, with specialized business patterns for common use cases like
inbox management, approval workflows, and collaborative processes.

Key Concepts

• Human Task: Generic abstraction for any work requiring human intervention
• Business Workflow Patterns: Specialized implementations for common scenarios
• GOAP Integration: Human tasks as first-class actions in goal-oriented planning
• Pattern Composition: Multiple patterns can be combined for complex workflows

---

Human Task Abstraction (Foundation Layer)

Core Human Task Definition

  @HumanTask(
      priority = Priority.NORMAL,           // Task urgency level
      deadline = "PT2H",                          // ISO-8601 duration from creation
      assignedRole = "MANAGER",           // Role-based assignment
      assignedUser = "john.doe",          // Direct user assignment
      candidateGroups = ["TEAM_LEADS"],   // Group-based assignment
      escalationDeadline = "PT4H",        // When to escalate
      escalationTo = "SENIOR_MANAGER"     // Escalation target
  )
  @Action(pre = {"requestReady"}, post = {"requestProcessed"})
  ProcessedResult processRequest(Request request, OperationContext context)

Human Task Properties

Assignment Strategies

// Direct assignment
@humantask(assignedUser = "specific.user")

// Role-based assignment
@humantask(assignedRole = "MANAGER")

// Group-based assignment
@humantask(candidateGroups = ["SUPPORT_AGENTS", "TEAM_LEADS"])

// Parallel assignment (collaborative)
@humantask(
candidateGroups = ["REVIEWERS"],
parallelism = ParallelismType.ALL_MUST_COMPLETE
)

Priority and Timing

enum class Priority {
LOW, MEDIUM, HIGH, URGENT, CRITICAL, NORMAL
}

@humantask(
priority = Priority.URGENT,
deadline = "PT1H", // 1 hour deadline
escalationDeadline = "PT30M", // Escalate after 30 minutes
escalationTo = "SUPERVISOR"
)

Lifecycle Management

  enum class HumanTaskState {
      CREATED,     // Task defined but not ready
      READY,       // Available for assignment
      CLAIMED,     // Reserved by specific user
      INPROGRESS,  // User actively working
      COMPLETED,   // Task finished successfully
      FAILED,      // Task failed or expired
      ESCALATED,   // Escalated to higher authority
      RELEASED     // Unclaimed, back to ready state
  }

---

Business Workflow Patterns (Implementation Layer)

1. Inbox Pattern - Shared Task Pool

Core Concept

Tasks arrive in a shared inbox where multiple users can claim work items, preventing
conflicts through atomic claim operations.

Pattern Implementation

Claim Task from Inbox:
@humantask(candidateGroups = ["SUPPORT_AGENTS"], priority = HIGH, deadline = "PT4H")
@action(pre = {"taskAvailable"}, post = {"taskClaimed"})
ClaimTask claimSupport(
InboxRequest request,
OperationContext context
) : ClaimedRequest

Process Claimed Task:
@humantask(assignedUser = "CLAIMER", priority = HIGH, deadline = "PT2H")
@action(pre = {"taskClaimed", "ownedByCurrentUser"}, post = {"taskProcessed"})
ApprovalTask processRequest(
ClaimedRequest request,
OperationContext context
) : ProcessedRequest

Release Task (Optional):
@humantask(assignedUser = "CLAIMER")
@action(pre = {"taskClaimed", "ownedByCurrentUser"}, post = {"taskAvailable"})
ReleaseTask releaseRequest(
ClaimedRequest request,
OperationContext context
) : ReleasedRequest

Inbox Service Operations

@service
class InboxService {

  // Atomic claim operation - prevents race conditions
  fun claimTask(taskId: String, userId: String): ClaimedTask? {
      return transactionTemplate.execute {
          val task = findAvailableTask(taskId) ?: return@execute null
          if (task.state != TaskState.READY) return@execute null

          updateTaskState(
              taskId = taskId,
              newState = TaskState.CLAIMED,
              claimedBy = userId,
              claimedAt = Instant.now()
          )
      }
  }

  fun releaseTask(taskId: String): ReleasedTask
  fun getAvailableTasks(filter: InboxFilter): List<InboxTask>
  fun getMyTasks(userId: String): List<InboxTask>

}

2. Approval Pattern - Decision Workflows

Direct Approval

@humantask(assignedRole = "MANAGER", priority = HIGH, deadline = "PT6H")
@action(pre = {"requestSubmitted"}, post = {"requestDecided"})
ApprovalTask approveRequest(
ApprovalRequest request,
OperationContext context
) : ApprovalDecision {
// Present request details to manager
// Capture approval/rejection with reasoning
// Return decision with metadata
}

Approval with Escalation

@humantask(
assignedRole = "MANAGER",
priority = HIGH,
deadline = "PT4H",
escalationDeadline = "PT2H",
escalationTo = "SENIOR_MANAGER"
)
@action(pre = {"highValueRequestSubmitted"}, post = {"requestDecided"})
ApprovalEscalatedTask approveHighValueRequest(
HighValueRequest request,
OperationContext context
) : ApprovalDecision

3. Collaborative Pattern - Parallel Human Workflows

Group Review (All Must Complete)

@humantask(
candidateGroups = ["TECHNICAL_REVIEWERS", "BUSINESS_REVIEWERS", "SECURITY_REVIEWERS"],
parallelism = ParallelismType.ALL_MUST_COMPLETE,
priority = MEDIUM,
deadline = "P3D"
)
@action(pre = {"documentReady"}, post = {"allReviewsComplete"})
GroupReviewTask reviewDocument(
Document document,
OperationContext context
) : CombinedReviewResult {
// Creates parallel review tasks for each group
// Technical review (assigned to TECHNICAL_REVIEWERS)
// Business review (assigned to BUSINESS_REVIEWERS)
// Security review (assigned to SECURITY_REVIEWERS)
// Waits for all reviews to complete
// Merges results into CombinedReviewResult
}

Consensus-Based Approval

@humantask(
candidateGroups = ["SENIOR_MANAGERS"],
parallelism = ParallelismType.MAJORITY_CONSENSUS,
minApprovers = 3,
priority = HIGH,
deadline = "PT12H"
)
@action(pre = {"proposalSubmitted"}, post = {"proposalDecided"})
GroupApprovalTask approveProposal(
Proposal proposal,
OperationContext context
) : ConsensusDecision {
// Multiple managers review simultaneously
// Decision requires majority agreement
// Returns consensus with vote breakdown
}

Collaborative Parallelism Types

enum class ParallelismType {
ALL_MUST_COMPLETE, // Every participant must finish
MAJORITY_CONSENSUS, // >50% must agree on decision
FIRST_WINS, // First completion determines outcome
QUORUM_BASED, // Minimum number must complete
WEIGHTED_VOTING // Participants have different vote weights
}

---

Pattern Composition and Workflows

Complex Workflow: Inbox + Approval + Collaboration

// 1. INBOX: Claim approval from shared pool
@humantask(candidateGroups = ["MANAGERS"], priority = HIGH, deadline = "PT6H")
@action(pre = {"approvalRequestAvailable"}, post = {"approvalRequestClaimed"})
ClaimApprovalTask claimApproval(
InboxApprovalRequest request,
OperationContext context
) : ClaimedApprovalRequest

// 2. APPROVAL: Manager reviews claimed request
@humantask(assignedUser = "CLAIMER", priority = HIGH, deadline = "PT4H")
@action(pre = {"approvalRequestClaimed", "ownedByCurrentUser"}, post = {"managerDecision"})
ApprovalTask processApproval(
ClaimedApprovalRequest request,
OperationContext context
) : ManagerDecision

// 3. COLLABORATIVE: If escalated, requires group approval
@humantask(
candidateGroups = ["SENIOR_MANAGERS", "DIRECTORS"],
parallelism = ParallelismType.MAJORITY_CONSENSUS,
minApprovers = 2,
priority = URGENT,
deadline = "PT24H"
)
@action(pre = {"managerDecision", "escalated"}, post = {"finalDecision"})
GroupApprovalTask processGroupApproval(
EscalatedApproval approval,
OperationContext context
) : FinalApprovalDecision

// 4. AUTOMATED: Process final decision
@action(pre = {"finalDecision"}, post = {"requestProcessed"})
ProcessedRequest processDecision(
FinalApprovalDecision decision,
OperationContext context
) : ProcessedRequest

GOAP Integration - Human Tasks as Actions Extensions

// Result: Automatic workflow construction based on conditions
// submitRequest → claimFromInbox → processApproval → [escalate if needed] → finalProcessing

---

Naming Conventions

Task Naming Pattern: [Pattern][Purpose]Task

Generic Pattern-Based Naming

Inbox Pattern Tasks:
ClaimTask // Generic claim from inbox
ClaimApprovalTask // Claim approval-type tasks
ClaimReviewTask // Claim review-type tasks
ClaimSupportTask // Claim support-type tasks

Approval Pattern Tasks:
ApprovalTask // Standard approval decision
ApprovalEscalatedTask // Escalated approval
ApprovalUrgentTask // Urgent approval

Collaborative Pattern Tasks:
GroupReviewTask // Collaborative document review
GroupApprovalTask // Collaborative approval decision
GroupValidationTask // Collaborative validation process

Release Pattern Tasks:
ReleaseTask // Generic release back to inbox
ReleaseApprovalTask // Release approval back to inbox

Workflow Progression Example

// Clear naming shows workflow progression
ClaimApprovalTask → // Claim approval from inbox
ApprovalTask → // Process the claimed approval
GroupReviewTask → // Escalate to collaborative review (if needed)
ApprovalTask → // Final approval after group review

Key Principle: Task names focus on the PATTERN (Claim, Approval, Group) rather than business
domain. The specific business context comes from the data types passed to the task, not the
task name itself.

---

Implementation Architecture

Spring MVC Integration

Human tasks leverage existing Spring MVC infrastructure :

@controller
@RequestMapping("/tasks")
class HumanTaskController(
private val inboxService: InboxService,
private val humanTaskService: HumanTaskService
) {

  @GetMapping("/inbox")
  fun showInbox(model: Model, authentication: Authentication): String {
      model.addAttribute("availableTasks", inboxService.getAvailableTasks())
      model.addAttribute("myTasks", inboxService.getMyTasks(authentication.name))
      return "tasks/inbox"
  }

  @PostMapping("/{taskId}/claim")
  fun claimTask(@PathVariable taskId: String, authentication: Authentication): String {
      inboxService.claimTask(taskId, authentication.name)
      return "redirect:/tasks/inbox"
  }

  @GetMapping("/{taskId}/process")
  fun processTask(@PathVariable taskId: String, model: Model): String {
      val task = humanTaskService.getTask(taskId)
      model.addAttribute("task", task)
      return "tasks/process/${task.type}"
  }

}

GOAP Conditions for Human Tasks

@condition
fun taskOwnedByCurrentUser(task: ClaimedTask, context: OperationContext): Boolean {
val currentUser = context.user()?.id
return task.claimedBy == currentUser
}

@condition
fun taskAvailable(task: InboxTask): Boolean {
return task.state == TaskState.READY
}

@condition
fun taskDeadlineNotExpired(task: HumanTask): Boolean {
return task.deadline?.isAfter(Instant.now()) ?: true
}

---

Key Benefits

1. Unified Abstraction

• Single Framework: All human work modeled consistently
• GOAP Integration: Human tasks work like automated actions
• Composable Patterns: Mix and match patterns for complex workflows

2. Business Pattern Library

• Proven Patterns: Inbox, Approval, Collaborative workflows
• Reusable Components: Standard solutions for common scenarios
• Clear Semantics: Naming conventions communicate intent

3. Scalable Architecture

• Multi-User Support: Atomic operations prevent conflicts
• Parallel Processing: Collaborative tasks enable concurrent human work
• Spring Integration: Leverages existing MVC infrastructure

4. Production Ready

• Race Condition Prevention: Database-level consistency
• Deadline Management: Automatic escalation and timeout handling
• Audit Trail: Complete task lifecycle tracking

This framework provides a solid foundation for human-AI collaboration while maintaining the
flexibility to support diverse business workflow requirements through composable patterns
and generic task abstractions.

Example of using LLM:

@Action(description = "AI-powered escalation decision")
  EscalationDecision determineEscalation(
      StuckTask task,
      OperationContext context
  ) : EscalationPlan {

      return context.ai()
          .withAutoLlm()
          .createObject("""
              Analyze this stuck task and determine escalation strategy:
              
              Task: ${task.summary}
              Stuck Reason: ${task.stuckReason}
              Time Elapsed: ${task.timeElapsed}
              Previous Attempts: ${task.attemptHistory}
              Available Escalation Paths: ${getEscalationOptions(task)}
              
              Determine:
              1. Should this be escalated? (YES/NO with reasoning)
              2. To whom? (specific role/person)
              3. Urgency level for escalation
              4. Additional context needed
              5. Recommended resolution approach
          """.trimIndent(), EscalationPlan::class.java)
  }

[johnsonr]

Interesting idea to elevate human tasks to be like actions, where they can be planned just like any other action.

Currently an action needs to ask for human input explicitly via WaitFor or the like. But modeling a human task as a first class citizen may be more elegant.

Please review in light of existing OutputChannel and also WaitFor behaviour (used in examples StarNewsFinder). Also note the form submission mechanism. It would be good to ensure that all HITL behaviour is type safe and supports multi channel.

[igordayen]

Thanks Rod for quick feedback very much. Idea came from Redhat JBPM 2.0 , quite popular and powerful business workflow system, used in Financial industry for modeling complex approval workflows. will review WaitFor as suggested.