How to Run Compliance Tests¶

CalcBridge provides multiple ways to execute compliance tests: through the web interface, via REST API, or on automated schedules. This guide covers all three approaches with step-by-step instructions.

Running Tests via UI¶

Step 1: Navigate to Your Workbook¶

Log in to CalcBridge at https://app.calcbridge.io
Click Workbooks in the left navigation
Select the workbook you want to test

Select a workbook from your library

Step 2: Open the Compliance Tab¶

Click the Compliance tab in the workbook detail view
You will see your configured test suites and recent test history

The Compliance tab shows test suites and history

Step 3: Select a Test Suite¶

Choose a test suite from the dropdown:
Standard CLO - Default comprehensive tests
Quick Check - Essential tests only
Custom suites - Your deal-specific configurations
Review the tests that will be executed:

Category	Tests	Description
Concentration	8	Obligor and industry limits
Rating	4	CCC bucket, WARF
Coverage	6	OC and IC ratios
Quality	3	WAS, WAL
Diversity	3	Moody's diversity score

Step 4: Run the Tests¶

Click the Run Tests button
A progress indicator shows test execution status
Results appear within seconds (typically < 30s)

Test Execution Time

Test execution time depends on portfolio size:

Small portfolios (< 100 loans): < 5 seconds
Medium portfolios (100-500 loans): 5-15 seconds
Large portfolios (500+ loans): 15-30 seconds

Step 5: Review Results¶

The results dashboard displays:

Summary cards - Pass/Fail/Warning counts
Test details - Individual test results with values and cushions
Trend chart - Historical compliance status
Action items - Recommended next steps

Compliance test results dashboard

Running Tests via API¶

Basic Test Execution¶

Run compliance tests programmatically using the REST API:

# Run compliance tests on a workbook
curl -X POST https://api.calcbridge.io/api/v1/compliance/run \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
    "test_suite": "standard_clo"
  }'

Response:

{
  "job_id": "job_7f8a9b0c1d2e3f4a",
  "status": "completed",
  "execution_time_ms": 2847,
  "results": {
    "total_tests": 24,
    "passed": 21,
    "warnings": 2,
    "failed": 1,
    "pass_rate": 87.5,
    "tests": [
      {
        "test_name": "Single Obligor Limit",
        "test_category": "concentration",
        "current_value": "8.23",
        "threshold_value": "10.00",
        "cushion": "1.77",
        "status": "pass",
        "description": "ACME Corp: 8.23% of portfolio (limit: 10%)"
      },
      {
        "test_name": "CCC Bucket",
        "test_category": "rating",
        "current_value": "7.12",
        "threshold_value": "7.50",
        "cushion": "0.38",
        "status": "warning",
        "description": "CCC/Caa exposure: 7.12% (limit: 7.5%)"
      }
    ]
  },
  "metadata": {
    "workbook_name": "CLO 2024-1",
    "snapshot_date": "2024-01-15T10:30:00Z",
    "portfolio_par": 500000000,
    "loan_count": 245
  }
}

Specifying Test Categories¶

Run only specific test categories:

curl -X POST https://api.calcbridge.io/api/v1/compliance/run \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
    "categories": ["concentration", "coverage"],
    "include_details": true
  }'

Using Custom Thresholds¶

Override default thresholds for a specific test run:

curl -X POST https://api.calcbridge.io/api/v1/compliance/run \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
    "threshold_overrides": {
      "single_obligor_limit_pct": 8.0,
      "ccc_bucket_limit_pct": 5.0,
      "minimum_oc_ratio": 125.0
    }
  }'

Async Execution for Large Portfolios¶

For large portfolios, use asynchronous execution:

# Start async test run
curl -X POST https://api.calcbridge.io/api/v1/compliance/run/async \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
    "test_suite": "standard_clo",
    "webhook_url": "https://your-app.com/webhooks/compliance"
  }'

Response:

{
  "job_id": "job_async_abc123",
  "status": "queued",
  "estimated_completion_seconds": 45,
  "status_url": "/api/v1/compliance/jobs/job_async_abc123"
}

Check job status:

curl -X GET https://api.calcbridge.io/api/v1/compliance/jobs/job_async_abc123 \
  -H "Authorization: Bearer $TOKEN"

Scheduling Automated Test Runs¶

Creating a Schedule¶

Automate compliance tests to run at regular intervals:

curl -X POST https://api.calcbridge.io/api/v1/compliance/schedules \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Compliance Check",
    "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
    "test_suite": "standard_clo",
    "schedule": "0 6 * * *",
    "timezone": "America/New_York",
    "enabled": true,
    "notification_settings": {
      "on_failure": true,
      "on_warning": true,
      "on_success": false,
      "channels": ["email", "slack"]
    }
  }'

Common Schedule Patterns¶

Pattern	Cron Expression	Description
Daily at 6 AM	`0 6 * * *`	Before market open
Twice daily	`0 6,18 * * *`	Morning and evening
Weekdays only	`0 6 * * 1-5`	Business days
Monthly	`0 6 1 * *`	First of month
End of month	`0 6 L * *`	Last day of month

Schedule Timing Best Practices

Before market open - Run tests at 6 AM to catch issues before trading
After data updates - Schedule tests 30 minutes after your data feed updates
Before reporting deadlines - Add extra runs before trustee report dates
Multiple time zones - Consider running at times convenient for your team

Managing Schedules¶

List all schedules:

curl -X GET https://api.calcbridge.io/api/v1/compliance/schedules \
  -H "Authorization: Bearer $TOKEN"

Update a schedule:

curl -X PATCH https://api.calcbridge.io/api/v1/compliance/schedules/sched_123 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

Delete a schedule:

curl -X DELETE https://api.calcbridge.io/api/v1/compliance/schedules/sched_123 \
  -H "Authorization: Bearer $TOKEN"

Batch Testing Multiple Workbooks¶

Running Tests on Multiple Deals¶

Execute compliance tests across your entire portfolio:

curl -X POST https://api.calcbridge.io/api/v1/compliance/batch \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workbook_ids": [
      "550e8400-e29b-41d4-a716-446655440000",
      "660f9511-f30c-52e5-b827-557766551111",
      "770a0622-a41d-63f6-c938-668877662222"
    ],
    "test_suite": "standard_clo",
    "parallel": true
  }'

Response:

{
  "batch_id": "batch_xyz789",
  "status": "completed",
  "total_workbooks": 3,
  "results": [
    {
      "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
      "workbook_name": "CLO 2024-1",
      "status": "completed",
      "passed": 22,
      "warnings": 1,
      "failed": 1
    },
    {
      "workbook_id": "660f9511-f30c-52e5-b827-557766551111",
      "workbook_name": "CLO 2024-2",
      "status": "completed",
      "passed": 24,
      "warnings": 0,
      "failed": 0
    },
    {
      "workbook_id": "770a0622-a41d-63f6-c938-668877662222",
      "workbook_name": "CLO 2023-4",
      "status": "completed",
      "passed": 20,
      "warnings": 3,
      "failed": 1
    }
  ],
  "summary": {
    "total_tests": 72,
    "total_passed": 66,
    "total_warnings": 4,
    "total_failed": 2,
    "overall_pass_rate": 91.7
  }
}

Portfolio-Wide Summary¶

Get a high-level compliance summary across all workbooks:

curl -X GET https://api.calcbridge.io/api/v1/compliance/summary \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "as_of": "2024-01-15T10:30:00Z",
  "total_workbooks": 12,
  "workbooks_passing": 9,
  "workbooks_with_warnings": 2,
  "workbooks_failing": 1,
  "tests_by_category": {
    "concentration": {"passed": 92, "warnings": 4, "failed": 0},
    "rating": {"passed": 44, "warnings": 2, "failed": 2},
    "coverage": {"passed": 70, "warnings": 2, "failed": 0},
    "quality": {"passed": 35, "warnings": 1, "failed": 0},
    "diversity": {"passed": 36, "warnings": 0, "failed": 0}
  },
  "critical_issues": [
    {
      "workbook_name": "CLO 2023-4",
      "test_name": "CCC Bucket",
      "current_value": "8.2%",
      "threshold": "7.5%",
      "breach_amount": "0.7%"
    }
  ]
}

Integration Examples¶

Python SDK¶

from calcbridge import CalcBridgeClient

client = CalcBridgeClient(api_key="your_api_key")

# Run compliance tests
results = client.compliance.run(
    workbook_id="550e8400-e29b-41d4-a716-446655440000",
    test_suite="standard_clo"
)

# Check results
if results.failed > 0:
    print(f"ALERT: {results.failed} compliance failures!")
    for test in results.tests:
        if test.status == "fail":
            print(f"  - {test.test_name}: {test.current_value} vs {test.threshold_value}")

JavaScript/Node.js¶

const CalcBridge = require('@calcbridge/sdk');

const client = new CalcBridge({ apiKey: process.env.CALCBRIDGE_API_KEY });

async function runComplianceTests(workbookId) {
  const results = await client.compliance.run({
    workbookId: workbookId,
    testSuite: 'standard_clo'
  });

  console.log(`Pass rate: ${results.passRate}%`);

  results.tests
    .filter(test => test.status === 'fail')
    .forEach(test => {
      console.log(`FAIL: ${test.testName} - ${test.description}`);
    });

  return results;
}

Webhook Integration¶

Configure webhooks to receive test results automatically:

curl -X POST https://api.calcbridge.io/api/v1/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Compliance Results Webhook",
    "url": "https://your-app.com/webhooks/compliance",
    "events": ["compliance.completed", "compliance.failed"],
    "secret": "your_webhook_secret"
  }'

Webhook payload example:

{
  "event": "compliance.completed",
  "timestamp": "2024-01-15T10:30:45Z",
  "data": {
    "job_id": "job_abc123",
    "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
    "workbook_name": "CLO 2024-1",
    "passed": 22,
    "warnings": 1,
    "failed": 1,
    "pass_rate": 91.7
  }
}

Troubleshooting¶

Common Issues

Tests not running:

Verify the workbook has valid portfolio data
Check that required columns are present (par_value, ratings, etc.)
Ensure the workbook is not locked by another process

Unexpected results:

Review the data snapshot used for testing
Check threshold configurations match your expectations
Verify rating mappings are correct for your data format

Timeout errors:

Use async execution for large portfolios (500+ loans)
Check for circular references in the workbook
Contact support if issues persist

Next: Interpreting Results & Cushion Analysis