FAQ and Troubleshooting

This document provides answers to frequently asked questions and solutions to common issues encountered when using Decision Control. Topics are organized by functional area for quick reference.

Frequently Asked Questions

General Questions

What is Decision Control?

Decision Control is an enterprise-grade decision intelligence platform that enables organizations to author, test, deploy, and govern Decision Model and Notation (DMN) models across multiple environments. It provides visual DMN authoring, intelligent testing via natural language prompts, multi-environment management, role-based governance workflows, and comprehensive audit trails. Built on Apache KIE technology with enterprise enhancements, Decision Control manages business logic as versioned, auditable, and governable assets.

What are the different editions of Decision Control?

Decision Control is available in four tiers:

Pioneer: Core DMN authoring and execution for development teams
Innovator: Adds Prompt UI for natural language testing and business analyst collaboration
Horizon: Adds Management UI and governance features for multi-environment deployments
Keystone: Complete feature set with advanced analytics for enterprise-wide decision intelligence

Each edition builds on the previous, with pricing and features aligned to organizational maturity.

How does Decision Control differ from other DMN engines?

Unlike standalone DMN execution engines, Decision Control provides end-to-end lifecycle management including:

Integrated authoring, testing, and management interfaces
Built-in governance workflows with four-eyes principle enforcement
Multi-environment deployment coordination (dev, test, prod)
Natural language testing via Prompt UI
Complete audit trails for regulatory compliance
OAuth2/OIDC authentication with role-based access control

Decision Control is a complete platform, not just an execution engine.

Can Decision Control integrate with my existing systems?

Yes. Decision Control provides RESTful APIs with OpenAPI documentation for seamless integration. Common integration patterns include:

API Integration: REST endpoints for decision execution and model management
Event-Driven: Kafka connectors for asynchronous decision requests
CI/CD: Git-based model storage with automated testing pipelines
SSO: OAuth2/OIDC integration with enterprise identity providers

See Integration and APIs for detailed integration guidance.

Is Decision Control cloud-native?

Yes. Decision Control is designed for Kubernetes deployment with:

Containerized microservices architecture
Horizontal scaling for high availability
Health checks and readiness probes
Prometheus metrics for observability
ConfigMap/Secret integration for configuration
Ingress-based routing with TLS termination

All components run as stateless services with state in managed PostgreSQL databases.

Authentication and Security

How does authentication work?

Decision Control uses Keycloak for OAuth2/OIDC authentication. The authentication flow:

User accesses Decision Control landing page
System redirects to Keycloak login
User provides credentials
Keycloak issues access token, refresh token, and ID token
User’s browser stores tokens in localStorage
All API calls include Authorization: Bearer {token} header
Tokens automatically refresh before expiration

See Integration and APIs - Authentication for implementation details.

What roles are available?

Decision Control and Aletyx Decision Control Tower share the same OIDC role model, with two app roles:

Claim value	Capabilities
`user`	View environments, models, tasks, and the audit trail; submit promotion requests
`tower-approvers`	Everything `user` can do, plus approve / reject / request-changes on promotion tasks

Roles are assigned in your OIDC provider (Microsoft Entra ID or Keycloak) and emitted in the JWT under the configured role claim (default roles). For provider-specific setup, see Aletyx Decision Control Tower Identity & Access Management.

What is the four-eyes principle?

The four-eyes principle keeps a single person from both submitting and approving a promotion. In Aletyx Decision Control Tower, approval is gated by membership in the tower-approvers group: only members can see and act on review tasks, so a submitter who does not also hold that role cannot approve their own request. Treat the integrity of the tower-approvers group as the operational separation-of-duties control.

How long do access tokens last?

By default:

Access tokens: 5 minutes
Refresh tokens: 30 days
ID tokens: 5 minutes

Tokens automatically refresh using the refresh token before expiration. If the refresh token expires, users must log in again.

Model Management

What DMN versions are supported?

Decision Control supports DMN 1.5 specification (which includes backward compatibility with DMN 1.1-1.4). Models created in any supported version can be executed. The Authoring UI generates DMN 1.5 by default.

Can I import existing DMN models?

Yes. Upload existing DMN files (.dmn extension) via:

Authoring UI: Click “Upload Model” and select file
API: POST to /api/management/units/{unitId}/versions/{versionId}/models with multipart/form-data

The system validates DMN syntax and rejects invalid models with detailed error messages.

How do I version my models?

Decision Control automatically manages versioning for you. When you publish a model, the system automatically increments the version number within the Unit/Version/Models hierarchy. You don’t need to manually specify version numbers. Published versions are immutable. To make changes, simply create and publish a new version, and the system will automatically assign the next version number.

Can I delete a published version?

No. Published versions are immutable to maintain audit trail integrity. If a version should not be used:

Disable the version: Set status to DISABLED (prevents execution but retains for audit)
Document reason: Add note in version changelog
Communicate: Notify users and update documentation

To remove all traces (not recommended), administrators can delete via database, but this breaks audit trails.

What happens if my DMN model has errors?

The system validates DMN models at upload and execution: Upload Validation:

XML syntax errors → 400 Bad Request with error details
Missing required elements → Validation error message
Invalid FEEL expressions → Syntax error with line number

Execution Validation:

Missing inputs → Error message listing missing input names
Type mismatches → Type conversion error
Logic errors → Decision evaluation failure with context

Always test models before publishing to catch validation errors.

Decision Execution

How do I execute a decision?

Execute decisions via REST API:

curl -X POST https://decision-control-prod.../api/runtime/units/{unit}/versions/{version}/execute \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "modelName": "MyModel",
    "decisionName": "MyDecision",
    "context": {
      "Input1": "value1",
      "Input2": 123
    }
  }'

See Integration and APIs - Decision Execution for complete reference.

Audit and Compliance

How do I access audit trails?

The promotion audit trail lives in Aletyx Decision Control Tower’s Audit Trail sidebar entry. From there you can filter by status, date range, or requester; drill into any promotion’s full task history; and export the current view to CSV. Your visibility depends on your role: tower-approvers see every promotion in the tenant; users without that role see only the promotions they themselves submitted. See the Audit Trail how-to for step-by-step walkthroughs.

Can audit records be deleted?

No. The audit trail is reconstructed from Aletyx Decision Control Tower’s workflow engine history together with the persisted promotion-request rows; both are append-only by design. CSV exports include all metadata required for regulatory audits.

Prompt UI and Testing

What is Prompt UI?

Prompt UI allows testing DMN models using natural language queries instead of technical API calls. Business users can test models by describing scenarios conversationally, making testing accessible to non-technical stakeholders. Available in Innovator edition and higher.

How accurate is natural language parsing?

Prompt UI uses language models to extract input values from natural language queries. Accuracy depends on query clarity:

High accuracy (>95%): Clear queries with explicit values (“age 35, income $75000”)
Medium accuracy (80-95%): Conversational queries with some ambiguity
Low accuracy (<80%): Vague queries, missing values, or unclear context

For critical testing, verify extracted inputs before execution.

Troubleshooting

Authentication Issues

Error: “Token expired” (401 Unauthorized)

Symptom: API calls fail with 401 status and message “Token expired”. Cause: Access token has expired (default lifetime: 5 minutes). Solution: Implement automatic token refresh:

async function refreshIfNeeded() {
  const session = JSON.parse(localStorage.getItem('session'));
  const now = Math.floor(Date.now() / 1000);

  if (session.expires_at - now < 30) {
    // Token expires in less than 30 seconds, refresh
    const response = await fetch(
      'https://keycloak.../realms/aletyx/protocol/openid-connect/token',
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body: new URLSearchParams({
          grant_type: 'refresh_token',
          client_id: 'decision-control-ui',
          refresh_token: session.refresh_token
        })
      }
    );
    const tokens = await response.json();
    // Update session with new tokens
  }
}

Error: “Insufficient permissions” (403 Forbidden)

Symptom: User can log in but cannot access certain features or approve requests. Cause: User lacks the required OIDC role for the action. Solution:

Verify user roles: Decode the JWT token to check the role claims:

echo $TOKEN | cut -d. -f2 | base64 -d | jq .realm_access.roles

Check role requirements: For approve / reject / request-changes actions in Aletyx Decision Control Tower, the user must hold tower-approvers. For read-only access, user is enough.
Contact administrator: Request role assignment if the required role is missing from the token.

Error: “Redirect URI mismatch”

Symptom: After Keycloak login, browser shows error “Invalid redirect URI”. Cause: Keycloak client configuration doesn’t include the application’s redirect URI. Solution:

Log in to Keycloak admin console
Navigate to Realm aletyx → Clients → decision-control-ui
Add redirect URI to Redirect URIs field:
- Development: http://localhost:8080/*
- Production: https://landing-page.your-domain.com/*
Save changes

Model Execution Issues

Error: “Model not found” (404 Not Found)

Symptom: Decision execution fails with “Model not found” error. Cause: Model name, unit name, or version is incorrect, or version is not published. Solution:

Verify model exists:

curl https://decision-control-prod.../api/management/units \
  -H "Authorization: Bearer $TOKEN"

Check version status: Ensure version is PUBLISHED, not DRAFT.
Verify exact names: Model names are case-sensitive. Use exact names from API response.
Check environment: Ensure querying correct environment (dev, test, prod).

Error: “Type mismatch: expected number, got string”

Symptom: Execution fails with type conversion error. Cause: Input value type doesn’t match DMN model definition. Solution:

Check DMN model: Verify data types for all inputs (number, string, boolean, date).
Provide correct types in JSON:
- Numbers: {"age": 35} (no quotes)
- Strings: {"name": "John"} (with quotes)
- Booleans: {"approved": true} (no quotes)
- Dates: {"dob": "1990-01-15"} (ISO 8601 string)
Validate JSON: Use JSON validator to ensure correct syntax.

Slow execution performance

Symptom: Decision execution takes longer than expected (>500ms). Cause: Complex models, large decision tables, or insufficient resources. Solution:

Optimize decision tables: Reduce rules, use simpler conditions.
Simplify model structure: Break complex decisions into smaller, focused decisions.

Increase resources: Scale up CPU/memory limits:

resources:
  requests:
    cpu: 4000m
    memory: 4Gi
  limits:
    cpu: 6000m
    memory: 8Gi

Use batch execution: Process multiple inputs together to amortize overhead.

Monitor metrics: Check Prometheus metrics for bottlenecks:

curl https://decision-control-prod.../actuator/metrics/dmn.execution.duration.seconds

Database and Infrastructure Issues

Database connection errors

Symptom: Application logs show “Cannot connect to database” errors. Cause: PostgreSQL service down, incorrect credentials, or network policy blocking access. Solution:

Check PostgreSQL pod status:

kubectl get pods -n prod | grep postgres

Verify database service:

kubectl get svc -n prod | grep postgres

Test connectivity:

kubectl exec -it deployment/decision-control-dev -n dev -- \
  psql -h postgres-dev -U decision_control -d decision_control

Verify credentials: Check Secret contains correct database password:

kubectl get secret postgres-dev-secret -n prod -o jsonpath='{.data.password}' | base64 -d

Check network policies: Ensure pods can reach database service.

Ingress not routing requests

Symptom: Cannot access Decision Control URLs, getting 404 or 503 errors. Cause: Ingress misconfigured, DNS not resolving, or TLS certificate issues. Solution:

Check Ingress status:

kubectl get ingress -n prod
kubectl describe ingress decision-control-dev -n dev

Verify DNS resolution:

nslookup decision-control-dev.example.com

Test TLS certificate:

curl -v https://decision-control-dev.example.com

Check backend service:

kubectl get svc decision-control-dev -n dev

Review ingress controller logs:

kubectl logs -n ingress-nginx deployment/ingress-nginx-controller

Pod crashes or restarts frequently

Symptom: Pods enter CrashLoopBackOff or restart frequently. Cause: Out of memory, application errors, or failing health checks. Solution:

Check pod logs:

kubectl logs -f deployment/decision-control-dev -n dev --previous

Describe pod for events:

kubectl describe pod decision-control-dev-xxxx -n prod

Check resource usage:

kubectl top pod decision-control-dev-xxxx -n prod

Increase resource limits if OOMKilled:
resources: limits: memory: 6Gi
Fix health check endpoints if failing readiness/liveness probes.

Performance Issues

High API latency

Symptom: API requests take longer than expected (>1 second). Cause: Insufficient resources, database query performance, or network issues. Solution:

Check Prometheus metrics:

curl https://decision-control-prod.../actuator/metrics/http.server.requests \
  | jq '.measurements[] | select(.statistic == "MAX")'

Review database query performance: Enable slow query logging in PostgreSQL.

Increase replicas for horizontal scaling:

kubectl scale deployment decision-control-prod --replicas=3 -n prod

Add connection pooling: Verify HikariCP configuration.
Enable caching: Implement Redis cache for frequently accessed data.

High memory usage

Symptom: Pods consuming excessive memory, approaching limits. Cause: Memory leaks, large compiled models, or insufficient garbage collection. Solution:

Monitor JVM metrics:

curl https://decision-control-prod.../actuator/metrics/jvm.memory.used

Trigger garbage collection: Call actuator endpoint (if enabled).

Increase heap size:

env:
  - name: JAVA_OPTS
    value: "-Xmx3g -Xms2g"

Profile for memory leaks: Use Java profiling tools.

Restart pods as temporary mitigation:

kubectl rollout restart deployment/decision-control-prod -n prod

Getting Additional Help

Documentation Resources

Overview: Platform introduction and capabilities
Architecture: System design and component interactions
Deployment: Deployment and configuration
Decision Control Tower: Multi-environment governance, approvals, and audit trail
Integration and APIs: API reference and integration patterns
Usage Scenarios: Step-by-step tutorials

Support Channels

Enterprise Support:

Email: support@aletyx.com
SLA: based on your Aletyx Licensed Tier

Professional Services:

Implementation consulting
Custom workflow development
Performance tuning and optimization
Training and enablement

Diagnostic Information to Provide

When requesting support, include:

Version information: Decision Control version and edition
Environment: Kubernetes version, namespace, resource allocation
Error details: Complete error message and stack trace
Steps to reproduce: Detailed reproduction steps
Logs: Relevant pod logs (anonymize sensitive data)
Configuration: Relevant ConfigMaps and Secrets (redact passwords)
Network diagram: Architecture and network policies (if relevant)

Useful Diagnostic Commands

Collect diagnostic information:

# Get pod status and events
kubectl get pods -n prod
kubectl describe pod decision-control-dev-xxxx -n prod

# Collect logs
kubectl logs deployment/decision-control-dev -n dev --tail=500 > decision-control.log
kubectl logs deployment/decision-control-tower -n tower-prod --tail=500 > tower.log

# Export resource configurations
kubectl get deployment decision-control-dev -n dev -o yaml > deployment.yaml
kubectl get configmap -n prod -o yaml > configmaps.yaml

# Check resource usage
kubectl top pods -n prod
kubectl top nodes

# Verify networking
kubectl exec -it deployment/decision-control-dev -n dev -- nslookup postgres-dev
kubectl exec -it deployment/decision-control-tower -n tower-prod -- curl -I https://decision-control-test...

Next Steps

Overview: Understand Decision Control capabilities
Deployment: Deploy Decision Control
Usage Scenarios: Learn through step-by-step tutorials

​Frequently Asked Questions

​General Questions

​What is Decision Control?

​What are the different editions of Decision Control?

​How does Decision Control differ from other DMN engines?

​Can Decision Control integrate with my existing systems?

​Is Decision Control cloud-native?

​Authentication and Security

​How does authentication work?

​What roles are available?

​What is the four-eyes principle?

​How long do access tokens last?

​Model Management

​What DMN versions are supported?

​Can I import existing DMN models?

​How do I version my models?

​Can I delete a published version?

​What happens if my DMN model has errors?

​Decision Execution

​How do I execute a decision?

​Audit and Compliance

​How do I access audit trails?

​Can audit records be deleted?

​Prompt UI and Testing

​What is Prompt UI?

​How accurate is natural language parsing?

​Troubleshooting

​Authentication Issues

​Error: “Token expired” (401 Unauthorized)

​Error: “Insufficient permissions” (403 Forbidden)

​Error: “Redirect URI mismatch”

​Model Execution Issues

​Error: “Model not found” (404 Not Found)

​Error: “Type mismatch: expected number, got string”

​Slow execution performance

​Database and Infrastructure Issues

​Database connection errors

​Ingress not routing requests

​Pod crashes or restarts frequently

​Performance Issues

​High API latency

​High memory usage

​Getting Additional Help

​Documentation Resources

​Support Channels

​Diagnostic Information to Provide

​Useful Diagnostic Commands

​Next Steps