Configuration & Deployment

This guide covers workflow module configuration, deployment, and operational considerations.

Module Configuration

Privileges

The workflow module uses the following privileges:

Privilege	Description	Grants Access To
`mod-workflows`	Access Workflows management page	View and manage workflow definitions
`mod-workflows-edit`	Edit workflow metadata	Edit roles, workgroups, enable/disable
`mod-workflow`	Access Workflow Designer	View workflow designs
`mod-workflow-edit`	Edit workflow definitions	Modify workflow structure and logic

Assignment: - Assign mod-workflows to users who need to manage workflows - Assign mod-workflow-edit to workflow designers - Restrict mod-workflows-edit to administrators - Use roles and workgroups for fine-grained access control

Audit Logging

Configure audit logging in application.conf:

ambience.modules.workflow.audit {
  public: true    // Log changes to elxPublic
  private: false  // Log changes to elxPrivate
}

Options: - public: true - Log all changes to elxPublic data (recommended) - private: true - Log all changes to elxPrivate data (use with caution)

Considerations: - Public logging: Safe for compliance, no sensitive data - Private logging: May log sensitive data, ensure audit log is secured - Default: Public logging enabled, private logging disabled - Logs appear in Audit Log module

Best Practices: - Enable public logging for compliance requirements - Enable private logging only if necessary and secure audit logs - Review audit log retention policies - Implement log archival for long-term storage

Database Configuration

Workflows store definitions and instances in MongoDB.

Workflow Definitions: - Stored in system workflow database - Configured at module level - Shared across all workflows

Workflow Instances: - Stored in user-specified database and collection - Configured per workflow definition - Allows separation by workflow type

Configuration per Workflow: - Database: MongoDB database name (e.g., main, workflows) - Collection: Collection name (e.g., leaveRequests, expenseClaims) - Chainset: ETL chainset for this workflow

Best Practices: - Use descriptive collection names - Separate high-volume workflows into different collections - Consider separate databases for different environments - Plan for data growth and archival

Example Structure:

Database: main
  Collections:
    - leaveRequests (Leave Request workflow instances)
    - expenseClaims (Expense Claim workflow instances)
    - issueTracker (Issue Tracker workflow instances)

Database: workflows-archive
  Collections:
    - leaveRequests-archive (Archived instances)
    - expenseClaims-archive (Archived instances)

ETL Chainset Configuration

Each workflow is associated with an ETL chainset.

Chainset Contains: - OnEntry chains for states - OnExit chains for states - OnTransition chains for transitions - Guard chains for conditional logic

Best Practices: - One chainset per workflow (or related workflow group) - Name chainsets descriptively (e.g., leave-request-chains) - Organize chains with prefixes (e.g., LR_NotifyManager, LR_ValidateRequest) - Document chain purposes - Version chainsets with workflows

Deployment

Installing the Workflow Module

The workflow module is part of the Ambience platform.

Installation Steps: 1. Deploy workflow module JAR files 2. Configure module in application.conf 3. Restart Ambience server 4. Verify module appears in module list 5. Assign privileges to users

Verification:

# Check module is loaded
curl http://localhost:8080/api/modules

# Should include:
{
  "modules": [
    ...
    {
      "id": "workflow",
      "name": "Workflows",
      "version": "..."
    }
  ]
}

Database Setup

Ensure MongoDB is configured and accessible.

Requirements: - MongoDB 4.0 or higher - Appropriate connection string in configuration - Database user with read/write permissions - Sufficient storage for workflow instances

Indexes:

Create indexes for optimal performance:

// For workflow instances collection
db.leaveRequests.createIndex({ "workflowId": 1 })
db.leaveRequests.createIndex({ "states.nodeId": 1 })
db.leaveRequests.createIndex({ "elxPublic.employeeId": 1 })
db.leaveRequests.createIndex({ "elxPublic.submittedAt": -1 })

// Compound indexes for common queries
db.leaveRequests.createIndex({ 
  "states.nodeId": 1, 
  "elxPublic.submittedAt": -1 
})

Environment Configuration

Configure for different environments.

Development:

ambience.modules.workflow {
  audit {
    public: true
    private: true  // Enable for debugging
  }
}

Production:

ambience.modules.workflow {
  audit {
    public: true
    private: false  // Disable for security
  }
}

Backup and Restore

Implement backup strategies for workflows.

What to Backup: - Workflow definitions (MongoDB workflow database) - Workflow instances (MongoDB instance collections) - ETL chainsets - Configuration files

Backup Strategies:

1. Export Workflows:

# Export single workflow
# Use Workflow Management UI → Download

# Export all workflows
# Use More Actions → Select All → Download

2. MongoDB Backup:

# Backup workflow definitions
mongodump --db=workflows --collection=definitions --out=/backup

# Backup workflow instances
mongodump --db=main --collection=leaveRequests --out=/backup

3. Automated Backups:

# Daily backup script
#!/bin/bash
DATE=$(date +%Y%m%d)
mongodump --db=workflows --out=/backup/workflows-$DATE
mongodump --db=main --collection=leaveRequests --out=/backup/instances-$DATE

Restore:

# Restore workflow definitions
mongorestore --db=workflows --collection=definitions /backup/workflows/definitions.bson

# Restore workflow instances
mongorestore --db=main --collection=leaveRequests /backup/main/leaveRequests.bson

Performance Tuning

Query Optimization

Optimize workflow instance queries.

Best Practices: - Use indexes for common queries - Filter by state for “pending” queries - Limit result sets with pagination - Use projection to return only needed fields

Example Optimized Query:

// Good: Uses index, limits fields
db.leaveRequests.find(
  { "states.nodeId": "PendingApproval" },
  { "elxPublic": 1, "states": 1 }
).limit(50)

// Poor: No index, returns all fields
db.leaveRequests.find({})

ETL Chain Performance

Optimize ETL chain execution.

Best Practices: - Keep OnEntry/OnExit chains lightweight - Move heavy processing to async operations - Cache external data - Use batch operations - Avoid synchronous external API calls in chains

Example:

// Poor: Synchronous API call in OnEntry
OnEntry:
  1. Call external API (blocks for 2 seconds)
  2. Process response
  3. Update instance

// Better: Async processing
OnEntry:
  1. Queue async job
  2. Return immediately

Async Job:
  1. Call external API
  2. Send event to workflow when complete

Scaling Considerations

Plan for growth.

Horizontal Scaling: - Ambience server can be scaled horizontally - MongoDB can be sharded for large datasets - Load balance API requests

Vertical Scaling: - Increase server resources for ETL processing - Increase MongoDB resources for large collections

Data Archival: - Archive completed instances regularly - Move old data to separate collections/databases - Implement data retention policies

Monitoring

Health Checks

Monitor workflow system health.

Metrics to Track: - Workflow instance creation rate - Average workflow completion time - Error rate (failed transitions) - Timeout rate - Escalation rate - ETL chain execution time - Database query performance

Example Monitoring Query:

// Count instances by state
db.leaveRequests.aggregate([
  {
    $group: {
      _id: "$states.nodeId",
      count: { $sum: 1 }
    }
  }
])

// Find stuck instances (in same state > 7 days)
db.leaveRequests.find({
  "elxHistory": {
    $elemMatch: {
      "ts": { $lt: new Date(Date.now() - 7*24*60*60*1000) }
    }
  }
})

Alerts

Set up alerts for issues.

Alert Conditions: - High error rate (>5% of transitions fail) - Excessive timeouts (>10% of instances timeout) - Stuck instances (in same state >7 days) - Performance degradation (slow queries) - Database storage approaching limits

Logging

Configure appropriate logging.

Log Levels: - INFO: Normal operations - WARN: Potential issues - ERROR: Failures

What to Log: - Workflow instance creation - State transitions - Guard evaluations - ETL chain execution - Errors and exceptions - Performance metrics

Troubleshooting

Common Deployment Issues

Module Not Loading

Symptoms: Workflow module doesn’t appear

Solutions: 1. Check module JAR is in classpath 2. Verify configuration in application.conf 3. Check server logs for errors 4. Restart Ambience server 5. Verify dependencies are present

Database Connection Issues

Symptoms: Cannot create/load workflows

Solutions: 1. Verify MongoDB is running 2. Check connection string in configuration 3. Verify database user permissions 4. Check network connectivity 5. Review MongoDB logs

Permission Issues

Symptoms: Users cannot access workflows

Solutions: 1. Verify user has required privileges 2. Check role assignments 3. Verify workgroup associations 4. Review workflow access settings 5. Check audit log for access attempts

Performance Issues

Slow Queries

Symptoms: Workflow list loads slowly

Solutions: 1. Add appropriate indexes 2. Reduce result set size 3. Use pagination 4. Optimize query filters 5. Consider database sharding

Slow ETL Chains

Symptoms: State transitions take long time

Solutions: 1. Profile ETL chain execution 2. Identify slow steps 3. Optimize external API calls 4. Use caching 5. Move heavy processing to async

Migration

Migrating Workflows

Strategies for updating workflows with existing instances.

Strategy 1: Create New Workflow 1. Create new workflow with changes 2. Disable old workflow 3. Migrate instances to new workflow 4. Archive old workflow

Strategy 2: In-Place Update 1. Export workflow as backup 2. Modify workflow 3. Test with new instances 4. Monitor existing instances 5. Handle edge cases

Strategy 3: Versioned Workflows 1. Add version field to instances 2. Maintain multiple workflow versions 3. Route to appropriate version based on instance 4. Gradually migrate instances

Data Migration

Migrating workflow instance data.

Process: 1. Export instances from old collection 2. Transform data to new structure 3. Import to new collection 4. Verify data integrity 5. Update workflow configuration 6. Archive old collection

Example ETL Chain for Migration:

1. Source: Old collection
2. Transform: Map old structure to new
3. Validate: Check data integrity
4. Sink: New collection
5. Log: Record migration results

FAQ

How do I change a workflow after instances exist?

Options: 1. Create new workflow version, migrate instances 2. Modify carefully, test thoroughly 3. Use version field to support multiple versions

Best Practice: Test changes in development first.

How do I handle stuck instances?

Solutions: 1. Send manual event to progress workflow 2. Use ETL chain to update instance state 3. Implement timeout handling 4. Add admin override transitions

How do I archive old instances?

Process: 1. Create archive collection 2. Use ETL chain to copy completed instances 3. Delete from active collection 4. Maintain for retention period