Integration Cookbook¶
Concrete, copy-paste recipes for integrating AppControl with common enterprise tools.
Prerequisites¶
All recipes assume:
- AppControl backend is running at https://appcontrol.example.com
- You have an API key: ac_your-api-key-here
- The target application is already modeled in AppControl with ID APP_ID
Create an API Key¶
Open Account settings and select Manage Keys, or use the API with an authenticated account. For a single application's lifecycle operations:
jq -n --arg app "$APP_ID" '{name: "control-m-integration", allowed_actions: [("app:" + $app + ":read"), ("app:" + $app + ":start"), ("app:" + $app + ":stop")]}' > key-request.json
curl -X POST https://appcontrol.example.com/api/v1/api-keys \
-H "Authorization: Bearer $JWT_TOKEN" \
-H "Content-Type: application/json" \
--data-binary @key-request.json
Keys are a ceiling on the account's application permissions. They default to read-only with a 30-day expiry when omitted. Restricted keys deny unclassified routes; the recipes below need capabilities matching their actual endpoints. Recovery planning requires plan, diagnosis diagnose, and recovery execution execute, alongside the account's required RBAC. Legacy * keys retain full account permissions and should not be used for analysis-only AI integrations.
Save the returned key — it's shown only once.
1. Control-M Integration¶
Start an Application from a Control-M Job¶
Create a Control-M job that calls the AppControl CLI:
Job Name: START_BILLING_APP
Command: /usr/local/bin/appctl start billing-prod --wait --timeout 300
Run As: appcontrol-svc
Exit Codes: 0=OK, 1=FAIL, 2=TIMEOUT
AppControl CLI exit codes: | Code | Meaning | |------|---------| | 0 | Success | | 1 | Failure | | 2 | Timeout | | 3 | Auth error | | 4 | Not found | | 5 | Permission denied |
Check Application Status Before a Job¶
#!/bin/bash
# pre-condition.sh — use as Control-M pre-condition
STATUS=$(appctl status billing-prod --format short)
if [ "$STATUS" != "RUNNING" ]; then
echo "Application not running, aborting job"
exit 1
fi
exit 0
Stop After a Batch Window¶
Job Name: STOP_BILLING_APP
Command: /usr/local/bin/appctl stop billing-prod --wait --timeout 180
Condition In: END_OF_BATCH_WINDOW
2. AutoSys Integration¶
JIL Definition for AppControl Start¶
insert_job: start_billing_app
job_type: CMD
command: /usr/local/bin/appctl start billing-prod --wait --timeout 300
machine: appcontrol-host
owner: autosys_svc
permission: gx,ge
alarm_if_fail: 1
std_out_file: /var/log/autosys/appcontrol_start.log
std_err_file: /var/log/autosys/appcontrol_start.err
Conditional Start Based on AppControl State¶
#!/bin/bash
# autosys_wrapper.sh
APP_ID="billing-prod"
ACTION="$1"
# Check current state via API
STATE=$(curl -s -H "Authorization: ApiKey $AC_API_KEY" \
"https://appcontrol.example.com/api/v1/orchestration/apps/$APP_ID/status" \
| jq -r '.all_running')
if [ "$ACTION" = "start" ] && [ "$STATE" = "true" ]; then
echo "Already running, skipping"
exit 0
fi
appctl "$ACTION" "$APP_ID" --wait --timeout 300
exit $?
3. Dollar Universe Integration¶
Creating a Dollar Universe Task¶
# DU task script
#!/bin/bash
# u_start_app.sh — Dollar Universe uproc
AC_API_KEY="${AC_API_KEY}"
APP_ID="${U_APP_ID}"
TIMEOUT="${U_TIMEOUT:-300}"
# Start via REST API (Dollar Universe prefers API calls over CLI)
RESPONSE=$(curl -s -w "\n%{http_code}" \
-X POST "https://appcontrol.example.com/api/v1/orchestration/apps/$APP_ID/start" \
-H "Authorization: ApiKey $AC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"dry_run": false}')
HTTP_CODE=$(echo "$RESPONSE" | tail -1)
if [ "$HTTP_CODE" != "200" ]; then
echo "Start failed with HTTP $HTTP_CODE"
exit 1
fi
# Wait for completion
WAIT_RESPONSE=$(curl -s -w "\n%{http_code}" \
"https://appcontrol.example.com/api/v1/orchestration/apps/$APP_ID/wait-running?timeout=$TIMEOUT" \
-H "Authorization: ApiKey $AC_API_KEY")
STATUS=$(echo "$WAIT_RESPONSE" | head -1 | jq -r '.status')
case "$STATUS" in
running) exit 0 ;;
timeout) exit 2 ;;
failed) exit 1 ;;
*) exit 1 ;;
esac
4. XL Release (Digital.ai Release) Integration¶
HTTP Task: Start Application¶
In your XL Release template, add an HTTP Request task:
| Field | Value |
|---|---|
| URL | https://appcontrol.example.com/api/v1/orchestration/apps/${app_id}/start |
| Method | POST |
| Headers | Authorization: ApiKey ${api_key}, Content-Type: application/json |
| Body | {"dry_run": false} |
HTTP Task: Wait for Running¶
Add a second HTTP Request task:
| Field | Value |
|---|---|
| URL | https://appcontrol.example.com/api/v1/orchestration/apps/${app_id}/wait-running?timeout=300 |
| Method | GET |
| Headers | Authorization: ApiKey ${api_key} |
| Expected Status | 200 |
Validate Your XL Release Sequence¶
Before migrating, validate that your XL Release template's restart order matches AppControl's DAG:
curl -X POST "https://appcontrol.example.com/api/v1/apps/$APP_ID/validate-sequence" \
-H "Authorization: ApiKey $AC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sequence": ["redis-cache", "postgres-db", "api-server", "web-frontend"],
"operation": "start"
}'
Response:
{
"valid": true,
"conflicts": [],
"expected_order": [["redis-cache", "postgres-db"], ["api-server"], ["web-frontend"]]
}
If there are conflicts, the response tells you exactly what's wrong:
{
"valid": false,
"conflicts": [
{
"type": "dependency_order_violation",
"dependent": "api-server",
"dependency": "postgres-db",
"message": "'api-server' depends on 'postgres-db' but starts at position 0 while postgres-db is at position 1"
}
]
}
Replace XL Release Restart Templates¶
Before (XL Release manages dependencies):
Phase: Restart Application
Task 1: Start Redis (SSH)
Task 2: Start PostgreSQL (SSH)
Task 3: Wait 30s
Task 4: Start API Server (SSH)
Task 5: Wait 10s
Task 6: Start Web Frontend (SSH)
Task 7: Health check (HTTP)
After (AppControl manages dependencies):
Phase: Restart Application
Task 1: POST /api/v1/orchestration/apps/{id}/start
Task 2: GET /api/v1/orchestration/apps/{id}/wait-running?timeout=300
5. Jenkins Integration¶
Post-Deploy Restart via Jenkinsfile¶
pipeline {
agent any
environment {
AC_API_KEY = credentials('appcontrol-api-key')
AC_URL = 'https://appcontrol.example.com'
APP_ID = 'your-app-id'
}
stages {
stage('Deploy') {
steps {
// Your deployment steps here
sh 'helm upgrade myapp ./helm/myapp'
}
}
stage('Restart via AppControl') {
steps {
sh """
curl -f -X POST ${AC_URL}/api/v1/orchestration/apps/${APP_ID}/start \
-H "Authorization: ApiKey ${AC_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"dry_run": false}'
"""
// Wait for all components to be running
sh """
STATUS=\$(curl -s ${AC_URL}/api/v1/orchestration/apps/${APP_ID}/wait-running?timeout=300 \
-H "Authorization: ApiKey ${AC_API_KEY}" | jq -r '.status')
if [ "\$STATUS" != "running" ]; then
echo "Application failed to start: \$STATUS"
exit 1
fi
"""
}
}
}
}
6. GitLab CI Integration¶
.gitlab-ci.yml¶
restart_application:
stage: post-deploy
image: curlimages/curl:latest
variables:
AC_URL: "https://appcontrol.example.com"
APP_ID: "your-app-id"
script:
- |
# Trigger restart
curl -f -X POST "$AC_URL/api/v1/orchestration/apps/$APP_ID/start" \
-H "Authorization: ApiKey $AC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"dry_run": false}'
# Wait for running
STATUS=$(curl -s "$AC_URL/api/v1/orchestration/apps/$APP_ID/wait-running?timeout=300" \
-H "Authorization: ApiKey $AC_API_KEY" | jq -r '.status')
if [ "$STATUS" != "running" ]; then
echo "Restart failed: $STATUS"
exit 1
fi
echo "Application is running"
only:
- main
7. PagerDuty / Opsgenie Integration¶
Webhook Notification Setup¶
Configure AppControl to send webhooks on FAILED state transitions:
# Subscribe to failure events via API
curl -X POST "https://appcontrol.example.com/api/v1/notification-preferences" \
-H "Authorization: Bearer $JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"event_type": "failure",
"channel": "webhook",
"webhook_url": "https://events.pagerduty.com/v2/enqueue",
"webhook_headers": {
"Content-Type": "application/json"
}
}'
PagerDuty Webhook Payload Transform¶
AppControl webhook payload:
{
"event_type": "state_change",
"component_id": "...",
"component_name": "api-server",
"application_name": "billing-prod",
"from_state": "RUNNING",
"to_state": "FAILED",
"timestamp": "2026-02-24T10:30:00Z"
}
Use a PagerDuty integration or middleware to transform this into PagerDuty's event format.
8. ServiceNow Integration¶
Change Request on Operations¶
Use AppControl's audit trail to feed ServiceNow change records:
# Export audit trail for a time range
curl -s "https://appcontrol.example.com/api/v1/apps/$APP_ID/reports/audit?from=2026-02-23&to=2026-02-24" \
-H "Authorization: ApiKey $AC_API_KEY" \
| jq '.entries[] | {
type: .action,
target: .entity_type,
user: .user_id,
timestamp: .created_at
}'
9. Topology Export for Documentation / CMDB¶
Export DAG as Graphviz¶
# Get DOT format for Graphviz rendering
curl -s "https://appcontrol.example.com/api/v1/apps/$APP_ID/topology?format=dot" \
-H "Authorization: ApiKey $AC_API_KEY" \
| jq -r '.content' > app_topology.dot
# Render to PNG
dot -Tpng app_topology.dot -o app_topology.png
Export as YAML for Config Management¶
curl -s "https://appcontrol.example.com/api/v1/apps/$APP_ID/topology?format=yaml" \
-H "Authorization: ApiKey $AC_API_KEY" \
| jq -r '.content' > app_topology.yaml
Export as JSON for CMDB Ingestion¶
curl -s "https://appcontrol.example.com/api/v1/apps/$APP_ID/topology?format=json" \
-H "Authorization: ApiKey $AC_API_KEY" > app_topology.json
10. Dry Run and Plan Validation¶
Get Execution Plan Before Any Operation¶
# What would a start do?
curl -s "https://appcontrol.example.com/api/v1/apps/$APP_ID/plan?operation=start" \
-H "Authorization: ApiKey $AC_API_KEY" | jq '.plan'
# What would a stop do?
curl -s "https://appcontrol.example.com/api/v1/apps/$APP_ID/plan?operation=stop" \
-H "Authorization: ApiKey $AC_API_KEY" | jq '.plan'
# Plan for a specific component and its dependencies
curl -s "https://appcontrol.example.com/api/v1/apps/$APP_ID/plan?operation=start&scope=$COMPONENT_ID" \
-H "Authorization: ApiKey $AC_API_KEY" | jq '.plan'
Response example:
{
"levels": [
{
"level": 0,
"components": [
{"name": "redis", "current_state": "RUNNING", "predicted_action": "skip"},
{"name": "postgres", "current_state": "STOPPED", "predicted_action": "start"}
]
},
{
"level": 1,
"components": [
{"name": "api-server", "current_state": "STOPPED", "predicted_action": "start"}
]
}
],
"total_actions": 2
}