Workflow Audit

Workflow Audit provides execution history tracking for workflows, allowing you to monitor workflow runs, view execution logs, and troubleshoot failed executions.

Enabling Audit

To enable audit logging for a workflow, set enableAudit: true in the workflow definition:

workflow:
  workflowId: "2e28201d-704e-40b1-8568-7a87d198e255"
  name: "Send Order Confirmation Email"
  enableAudit: true  # Enable audit logging
  logLevel: "Debug"  # Optional: Set log level for detailed logs

Workflow Attributes for Audit

Attribute	Type	Default	Description
enableAudit	boolean	false	Enable audit logging for the workflow
logLevel	string	None	Logging level: None, Debug, Info, Warning, Error

Storage Architecture

Workflow execution data is stored in two locations:

1. Database (PostgreSQL)

Execution metadata is stored in the WorkflowExecutionLogs table for fast queries:

Field	Type	Description
ExecutionId	UUID	Unique identifier for the execution
WorkflowId	UUID	Reference to the workflow
OrganizationId	int	Organization that owns the workflow
UserId	string	User who triggered the execution
ExecutedAt	DateTime	When the execution started
ExecutionStatus	enum	Success or Failed
DurationMs	long	Execution duration in milliseconds

2. S3 Storage

Detailed execution logs are stored in S3:

logs/workflows/orgs/{organizationId}/{workflowId}/{timestamp}-{executionId}-{userId}{-failed}.txt
logs/workflows/orgs/{organizationId}/{workflowId}/{timestamp}-{executionId}-{userId}{-failed}.json

File Types:

Extension	Content
.txt	Raw execution logs (Serilog output)
.json	Structured metadata (inputs, outputs, exceptions, timing)

Accessing Execution History

GraphQL API

Get Single Execution

query {
  workflowExecution(organizationId: 1, executionId: "guid-here") {
    executionId
    workflowId
    executedAt
    executionStatus
    durationMs
    txtLogUrl      # Pre-signed URL for .txt log file
    jsonLogUrl     # Pre-signed URL for .json log file
    user {
      fullName
      email
    }
  }
}

List Executions with Pagination

query {
  workflowExecutions(
    organizationId: 1
    filter: "workflowId:guid-here AND executionStatus:Failed"  # Optional: Lucene filter
    search: "user@example.com"        # Optional: Free-text search
    orderBy: "-executedAt"            # Optional: Sort order (default: most recent first)
  ) {
    items {
      executionId
      executedAt
      executionStatus
      durationMs
      txtLogUrl
      jsonLogUrl
      user {
        fullName
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
    }
  }
}

note

The workflowId is no longer a dedicated argument. Pass it as a Lucene filter clause: filter: "workflowId:guid-here". This follows the standard grid filter pattern used across all list queries.

Filter Examples

Filter	Description
workflowId:guid-here	Show executions for a specific workflow
executionStatus:Failed	Show only failed executions
executionStatus:Success	Show only successful executions
userId:user@example.com	Filter by user
workflowId:guid-here AND executionStatus:Failed	Combine multiple conditions

Search

The search parameter performs free-text matching across userId, executionId, and workflowId. It matches partial substrings (case-insensitive for userId):

query {
  workflowExecutions(organizationId: 1, search: "user@example.com") {
    items {
      executionId
      executedAt
      executionStatus
    }
  }
}

Use search for quick lookups when you have a partial value. Use filter when you need precise, field-scoped conditions.

Sort Options

Order By	Description
-executedAt	Most recent first (default)
executedAt	Oldest first
-durationMs	Longest duration first
durationMs	Shortest duration first

Pre-signed URLs

Log file URLs are generated on-demand as pre-signed S3 URLs with time-limited access. These URLs are only generated when you request the txtLogUrl or jsonLogUrl fields in your GraphQL query.

Security Features:

• URLs expire after a configured time period
• Each URL is unique per request
• Access is controlled by organization permissions

JSON Log Structure

The .json log file contains structured execution data:

{
  "executionId": "guid",
  "organizationId": 1,
  "workflowId": "guid",
  "workflowName": "Send Order Confirmation Email",
  "inputs": {
    "orderId": 12345,
    "emailAddress": "customer@example.com"
  },
  "outputs": {
    "response": "Email sent successfully",
    "statusCode": 200
  },
  "exception": null,
  "isSuccess": true,
  "startExecutionTime": "2025-01-18T10:00:00Z",
  "endExecutionTime": "2025-01-18T10:00:05Z",
  "userId": "user@example.com"
}

Disabling Audit Logging

Per-Workflow

Set enableAudit: false in the workflow definition:

workflow:
  name: "High-Volume Workflow"
  enableAudit: false  # Disable audit for this workflow

Environment-Wide

Set the environment variable to disable all audit logging:

DISABLE_AUDIT_LOGGING=true

This is useful for local development or testing environments.

Best Practices

1. Enable audit for critical workflows - Always enable audit for workflows that process important business data.

2. Use appropriate log levels - Use Debug for development/troubleshooting, Info or Warning for production.

3. Monitor failed executions - Regularly review failed executions using the executionStatus:Failed filter.

4. Clean up old logs - Implement S3 lifecycle policies to archive or delete old execution logs.

5. Protect sensitive data - Be aware that inputs and outputs are logged. Avoid logging sensitive data like passwords or API keys.

Example: Complete Workflow with Audit

workflow:
  workflowId: "2e28201d-704e-40b1-8568-7a87d198e255"
  name: "Process Order"
  description: "Process incoming orders"
  isActive: true
  enableAudit: true
  logLevel: "Info"
  executionMode: "Async"

triggers:
  - type: "Entity"
    entityName: "Order"
    eventType: "Added"
    position: "After"

inputs:
  - name: "orderId"
    type: "Order"

outputs:
  - name: "result"
    mapping: "processOrder.result"

activities:
  - name: "processOrder"
    steps:
      - task: "Order/Process@1"
        name: "process"
        inputs:
          orderId: "{{ orderId }}"
        outputs:
          - name: "result"

With audit enabled, each execution of this workflow will:

1. Create a record in the WorkflowExecutionLogs database table
2. Upload detailed logs to S3 (.txt and .json files)
3. Be queryable via GraphQL API