Skip to main content

Process Measures

Measures are key performance indicators (KPIs) and data points that are calculated dynamically during process execution. They enable powerful reporting, analytics, and process monitoring capabilities by extracting and transforming business data from your process variables.

Overview​

Process measures serve as the bridge between your workflow execution data and business intelligence. They allow you to:

  • Track KPIs in real-time during process execution
  • Generate reports with meaningful business metrics
  • Monitor performance across process instances
  • Analyze trends and patterns in your workflows
  • Create dashboards with calculated business values

How Measures Work​

Calculation Timing​

Measures are calculated automatically at key points during process execution:

  • Process Start: Initial calculation with starting variables
  • Before User Tasks: Updated with current process state
  • Task Completion: Recalculated after task completion
  • Process Events: Updated during timer events, service calls, etc.
  • Process End: Final calculation for completed instances

Data Storage​

  • Measures are stored in the process instance database
  • Values are indexed for fast report queries
  • Historical data is preserved for trend analysis
  • Both current and historical values are available for reporting

Measure Configuration​

Basic Properties​

Each measure consists of three essential components:

1. Label​

  • Purpose: The name/identifier for the measure
  • Usage: Used as column names in reports and dashboards
  • Example: TotalCost, ProcessingTime, CustomerSatisfaction
  • Best Practice: Use descriptive, consistent naming conventions

2. Type​

Defines how the measure value should be processed and stored:

  • String: Text values, categories, status descriptions
    • Example: "Approved", "High Priority", "Finance Department"
  • Number: Numeric calculations, counts, monetary values
    • Example: 1250.50, 45, 0.95
  • Boolean: True/false flags, yes/no indicators
    • Example: true, false
  • Date: Timestamps, deadlines, milestones
    • Example: new Date(), "2024-12-31"
  • Any: Complex objects, arrays, or mixed data types
    • Example: {status: "active", items: [1,2,3]}

3. Field (JavaScript Expression)​

The JavaScript expression that calculates the measure value using process variables.

Field Expression Syntax​

Variable Interpolation​

Use double curly braces to access process variables:

// Simple variable access
{{ customerName }}

// Object property access
{{ order.totalAmount }}

// Array access
{{ items[0].price }}

// Nested object access
{{ customer.address.city }}

Complex Calculations​

Mathematical Operations​

// Total calculation
{{ orderAmount}} +{{shippingCost}}+{{ taxAmount }}

// Percentage calculation
({{completedTasks}} / {{totalTasks}}) * 100

// Average calculation
{{ totalRevenue}} / {{numberOfOrders }}

String Operations​

// String concatenation
{{ firstName}} + ' ' + {{lastName }}

// Conditional string
{{ status}} == 'approved' ? 'APPROVED' : 'PENDING'

// String formatting
'Order #' + {{ orderNumber }}+ ' - ' + {{ customerName }}

Date Calculations​

// Process duration in days
(new Date() - new Date(processStartDate)) / (1000 * 60 * 60 * 24)

// Due date calculation
new Date(Date.now() + (7 * 24 * 60 * 60 * 1000))

// Age calculation
new Date().getFullYear() - new Date(birthDate).getFullYear()

Conditional Logic​

// Simple condition
{{ amount }} > 1000 ? 'High Value' : 'Standard' 

// Multiple conditions
{{ priority }} == 'urgent' ? 'URGENT' : priority == 'high' ? 'HIGH' : 'NORMAL' 

// Boolean logic
{{ isApproved}} && {{  isComplete }}? 'FINALIZED' : 'IN_PROGRESS'

Array Operations​

// Array length
{{ items.length }}

// Array sum (for Type: "any")
{{ items.reduce((sum, item) => sum + item.price, 0) }}

// Array filtering (for Type: "any")
{{ items.filter(item => item.status === 'active').length }}

System Default Measures​

SoftyFlow automatically provides several system measures for every process:

Process Tracking Measures​

  • SF_last_activity_name: Name of the last executed activity
  • SF_involved_users: Array of all users who participated in the process
  • SF_involved_validators: Array of users who validated tasks
  • SF_involved_roles: Array of roles that were assigned tasks
  • SF_observer: Array of observer roles
  • SF_priority: Current process priority level
  • SF_description: Process description text

Instance Metadata (Available in Reports)​

  • SF_status: Process instance status (running, completed, error)
  • SF_name: Process instance name
  • SF_createdAt: Process start timestamp
  • SF_updatedAt: Last update timestamp
  • SF_createdBy: Process initiator information

Using Measures in Reports​

Report Column Configuration​

Measures become available as columns in your reports. When configuring report columns:

  1. Custom Measures: All process measures appear as selectable columns
  2. System Measures: Built-in measures are automatically available
  3. Data Types: Column types match the measure type configuration
  4. Filtering: Measures can be used for report filtering and sorting

Best Practices​

Measure Design​

  1. Meaningful Names: Use descriptive labels that business users understand
  2. Consistent Naming: Follow naming conventions across all processes
  3. Appropriate Types: Choose the correct data type for each measure
  4. Performance Considerations: Avoid overly complex calculations

Expression Writing​

  1. Error Handling: Use conditional logic to handle null/undefined values
  2. Type Safety: Ensure calculations match the expected data type
  3. Readability: Keep expressions clear and well-documented
  4. Testing: Test expressions with various data scenarios

Report Integration​

  1. Column Selection: Include relevant measures for your analysis needs
  2. Filtering Strategy: Use measures for effective data filtering
  3. Aggregation Planning: Consider how measures will be grouped and summarized
  4. Performance Optimization: Be mindful of query complexity with many measures

Troubleshooting​

Common Issues​

Expression Errors​

  • Symptom: Measure shows empty value
  • Cause: JavaScript expression error or undefined variable
  • Solution: Check variable names and add null checks
// Problem: Variable might be undefined
{{ customer.name }}

// Solution: Add null checking
{{ customer ? customer.name : 'Unknown' }}

Type Mismatches​

  • Symptom: Unexpected values in reports
  • Cause: Expression returns different type than configured
  • Solution: Ensure expression result matches measure type
// Problem: String returned for Number type
{{ status === 'active' ? 'Yes' : 'No' }}

// Solution: Return numeric value
{{ status === 'active' ? 1 : 0 }}

Performance Issues​

  • Symptom: Slow report generation
  • Cause: Complex measure calculations
  • Solution: Simplify expressions or pre-calculate values

Debugging Tips​

  1. Test Variables: Verify process variables contain expected data
  2. Simplify Expressions: Start with simple expressions and add complexity gradually
  3. Check Types: Ensure measure types match expression outputs
  4. Monitor Performance: Watch for calculation time in process logs

Integration Examples​

E-commerce Order Processing​

// Measures for order processing workflow
{
  label: "OrderValue",
  type: "number", 
  field: "{{ items.reduce((sum, item) => sum + item.price * item.quantity, 0) }}"
},
{
  label: "ProcessingStatus",
  type: "string",
  field: "{{ isPaid && isShipped ? 'Complete' : isPaid ? 'Shipped' : 'Pending' }}"
},
{
  label: "CustomerTier",
  type: "string", 
  field: "{{ orderValue > 1000 ? 'Premium' : orderValue > 500 ? 'Gold' : 'Standard' }}"
}

HR Approval Workflow​

// Measures for HR approval process
{
  label: "ApprovalTime",
  type: "number",
  field: "{{ approvalDate ? (approvalDate - submissionDate) / (1000 * 60 * 60) : null }}"
},
{
  label: "RequestCategory", 
  type: "string",
  field: "{{ requestType === 'vacation' ? 'Time Off' : requestType === 'expense' ? 'Financial' : 'Other' }}"
},
{
  label: "IsUrgent",
  type: "boolean",
  field: "{{ priority === 'urgent' || daysUntilDeadline < 3 }}"
}

Process measures are powerful tools that transform your workflow data into actionable business intelligence. By properly configuring and utilizing measures, you can create comprehensive reporting solutions that provide deep insights into your business processes and their performance.