Skip to content

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
}