Automation Anywhere Control-Room-API: Warum Sie vor der Integration zuerst die Versionen klären müssen.

Ein Bot-Start ist nicht nur ein Endpunkt

Für einen vollständigen Ablauf benötigen Sie mindestens Authentifizierung, Repository-Zugriff, Deployment und Ausführungssteuerung. Diese Funktionen liegen nicht unter einer gemeinsamen Version. Der aktuelle Authentifizierungsaufruf verwendet v2, das empfohlene Deployment v4 und der Bot Execution Orchestrator v3. Selbst innerhalb des Orchestrators bleibt die Geräteliste auf v2.

Die erste Architekturfrage lautet deshalb nicht: „Welche Control-Room-Version setzen wir ein?“ Sie lautet: „Welche fachliche Funktion gehört zu welcher API und welcher Generation?“ Eine globale Versionsnummer für die gesamte Integration gibt es in dieser Landschaft nicht.

Das ist besonders relevant, wenn dieselbe Anbindung in mehrere Control Rooms übertragen wird. Ein funktionierender Pfad beweist nicht, dass Request-Body, Statusmodell und Berechtigungen in der Zielumgebung identisch verwendet werden können. Die Versionsentscheidung muss pro Fähigkeit dokumentiert werden.

Wie die Automation Anywhere Control Room API wirklich aufgebaut ist

Die 23 APIs erschließen sich leichter über Verantwortungsbereiche als über eine lange Endpunktliste. So wird sichtbar, warum verschiedene Versionen innerhalb eines einzigen Geschäftsablaufs zusammenkommen.

• Ausführung und Orchestrierung: Authentication, Bot Deploy, Bot Execution Orchestrator und API Task Execution decken Anmeldung, Start, synchrone Aufrufe und Laufsteuerung ab.
• Planung und ereignisgesteuerte Verarbeitung: Automation Scheduler, Trigger und Work Load Management steuern Zeitpläne, Ereignisse, Queues und Work Items.
• Repository und Lifecycle: Repository Management, Bot Lifecycle Management, Packages Usage, Policy Management und Migration unterstützen Suche, Transport, Qualitätsprüfung und Migrationsauswertung.
• Plattformverwaltung: Device, Device Pool, User Management, Credential Vault und License verwalten technische Laufzeitvoraussetzungen.
• Transparenz und Auswertung: Audit, BotInsight und ACC Automations liefern Ereignisse, Laufdaten und Kennzahlen.
• Erweiterte Prozess- und KI-Funktionen: Process Composer, Team Management und AI Agent Studio bilden AARI- beziehungsweise Co-Pilot-Prozesse, Teams und Custom-LLM-Connectoren ab.

Diese Gruppen sind fachlich zusammengehörig, aber technisch nicht auf eine Generation standardisiert. v1 bis v4 sind keine saubere Ablösungskette. Eine höhere Versionsnummer bedeutet nur innerhalb des jeweiligen API-Bereichs etwas.

Eine vollständige Übersicht der verfügbaren Module und API-Generationen finden Sie in der offiziellen Dokumentation zu den Automation Anywhere Control Room APIs.

Das Versionsproblem an drei konkreten Beispielen

Deploy v3 und v4: gleicher Zweck, anderer Vertrag

Der Wechsel von Deploy v3 auf v4 ist kein Austausch des Pfadpräfixes. v3 erwartet fileId, v4 dagegen botId. In v3 liegen runAsUserIds und poolIds flach im Body. v4 verlangt genau einen Ausführungsblock: attendedRequest, unattendedRequest oder headlessRequest.

Auch die Gerätewahl ändert ihr Modell. v3 verwendet overrideDefaultDevice als booleschen Wert. v4 ersetzt dies durch deviceUsageType mit drei definierten Werten: Default-Gerät bevorzugen, Pool-Geräte verwenden oder ausschließlich das Default-Gerät nutzen. Wer nur URL und Feldnamen oberflächlich anpasst, erzeugt eine fachlich falsche oder stille Fehlpayload.

Ein minimaler v4-Body für einen unbeaufsichtigten Start zeigt den neuen Vertrag:

{
  "botId": 21,
  "unattendedRequest": {
    "runAsUserIds": [639],
    "poolIds": [2],
    "deviceUsageType": "PREFER_DEFAULT_DEVICE"
  }
}

Entscheidung: Behandeln Sie v3 und v4 als unterschiedliche Datenmodelle. Nutzen Sie keine gemeinsame Payload-Klasse mit lediglich austauschbarem Pfad.

Die Request-Modelle und verfügbaren Operationen können zusätzlich in der offiziellen Bot Deploy API v4 geprüft werden.

WLM: v4 ergänzt v3, ersetzt es aber nicht

Unter /v4/wlm liegen ausschließlich acht Operationen, die in /v3/wlm als deprecated markiert sind. Die übrigen 30 Operationen existieren nur in v3. Dazu gehören wesentliche Funktionen für Models, Queues, Zugriffe, Work Items und WLM-Automationen.

Die Praxisregel ist daher eindeutig: Die acht migrierten Operationen laufen auf v4, der übrige WLM-Umfang bleibt auf v3. Eine pauschale Umstellung des gesamten WLM-Clients auf v4 führt zu fehlenden Funktionen. Ein gemischter Betrieb ist hier kein Übergangsfehler, sondern durch die vorliegenden Spezifikationen vorgegeben.

Einzelne Altversionen bleiben Teil des aktuellen Ablaufs

Der Bot Execution Orchestrator liegt auf v3. Die Operation POST /v2/devices/list blieb jedoch auf v2. Beim Scheduler ist v1 vollständig deprecated, während neue Implementierungen v2 verwenden sollen. In der Policy-API startet die Analyse auf v2, der Download des Reports bleibt auf v1.

Diese Beispiele zeigen ein wiederkehrendes Muster: Versionierung erfolgt pro Operation oder Teil-API, nicht pro Control Room. Ein Integrationsclient braucht deshalb eine gepflegte Capability-Matrix, keine einzelne Konstante wie apiVersion = 4.

Was jede Integration unabhängig vom Use Case braucht

Authentifizierung: genau ein Verfahren pro Request

Ein Request verwendet entweder X-Authorization mit JWT oder Authorization: Bearer mit OAuth-Token. Beides zusammen ist nicht erlaubt. Der Token gilt standardmäßig 20 Minuten, wobei die Laufzeit im Control Room konfigurierbar ist. Ein Refresh erzeugt einen neuen Token und invalidiert den alten.

Bei SSO-Control-Rooms ersetzt apiKey das Passwort für technische Benutzer. apiKey und Passwort dürfen nicht gemeinsam gesendet werden. Für langlebige Abläufe bedeutet das: Token-Erzeugung und Refresh müssen zentral koordiniert werden, damit parallele Prozesse nicht nach einem Refresh mit dem alten Token weiterarbeiten.

Filter: gleiches Muster, unterschiedliche erlaubte Felder

Fast jede Listenoperation verwendet einen POST-Request mit filter, sort und page. Die Filterlogik unterstützt Vergleichsoperatoren von eq bis substring sowie die logischen Knoten and, or und not.

{
  "filter": {
    "operator": "and",
    "operands": [
      { "operator": "eq", "field": "status", "value": "COMPLETED" },
      { "operator": "substring", "field": "name", "value": "invoice" }
    ]
  },
  "sort": [{ "field": "endDateTime", "direction": "desc" }],
  "page": { "offset": 0, "length": 100 }
}

Die Einheitlichkeit endet bei den Feldnamen. Jede API erlaubt nur wenige filterbare Felder. Nicht vorgesehene Felder werden ignoriert oder führen zu einem Fehler. Übernehmen Sie deshalb nicht automatisch einen funktionierenden Filter in eine andere Listenoperation. Prüfen Sie die erlaubten Felder je API in der Spezifikation beziehungsweise im Swagger der eigenen Instanz.

Status: technisch präziser als „läuft“ oder „fertig“

Für belastbares Monitoring müssen Sie Zwischen- und Fehlerzustände getrennt interpretieren. QUEUED bedeutet, dass Benutzer oder Gerät belegt sind. PENDING_EXECUTION zeigt, dass ein Gerät gewählt, die Ausführung aber noch nicht zugestellt wurde. DEPLOY_FAILED steht für ein fehlgeschlagenes Autologin.

UNKNOWN bedeutet einen Verbindungsverlust zum Gerät und ist nicht automatisch ein fachlicher Bot-Fehler. Diese Unterscheidung entscheidet darüber, ob Ihr Ticketsystem einen Prozessfehler meldet, die Infrastruktur eskaliert oder zunächst weiter beobachtet.

Statt permanent zu pollen, kann das Deployment callbackInfo enthalten. Der Zielserver muss POST akzeptieren und vom Control Room aus erreichbar sein. Ist diese Erreichbarkeit nicht gegeben, bleibt Polling über den Orchestrator erforderlich.

Wo die Spezifikationen selbst nicht tragen

Drei Widersprüche müssen als Fehler oder Inkonsistenzen der Spezifikation behandelt werden, nicht als nachgewiesene Produktfehler:

• Deploy v4: Die Required-Liste nennt deployInput, obwohl dieses Feld im Schema nicht existiert. Gemeint ist einer der drei Ausführungsblöcke.
• Scheduler changeOwner: Die Required-Liste verlangt taskId, während das Schema nur taskType kennt.
• WLM-Status: Die Beschreibung mappt Completed und Failed auf COMPLETED und FAILED. Das WorkItem-Schema verwendet dagegen SUCCESSFUL und UNSUCCESSFUL.

Für den WLM-Status empfiehlt die Referenz, beide Varianten gegen die eigene Instanz zu testen. Darüber hinaus enthalten die 32 Spezifikationen keine Angaben zu Rate Limits, zum Verhalten bei HTTP 429 oder zu konkreten Abkündigungsterminen. Diese Punkte sind nicht dokumentiert. Eine Integrationsarchitektur darf dafür weder Zahlen noch Jahresangaben annehmen.

Automation Anywhere Control Room in der Praxis: Vom Deployment bis zum Abbruch

Ein belastbarer End-to-End-Ablauf trennt die Verantwortlichkeiten und speichert die IDs, die den Übergang zwischen den APIs ermöglichen:

1. Authentifizieren: Token über v2 erzeugen. Bei SSO für den technischen Benutzer apiKey statt Passwort verwenden.
2. Bot auflösen: Die Bot-ID über Repository Management v2 ermitteln. Der Variablenname im botInput muss exakt zur Bot-Variablen passen, einschließlich Groß- und Kleinschreibung.
3. Laufzeit prüfen: Run-as-User und Gerätebezug kontrollieren. Der Wert „Picked at run time“ zusammen mit deviceId: -1 zeigt ein fehlendes Default-Gerät.
4. Deployment starten: v4 mit botId und genau einem Ausführungsblock aufrufen. Die Gerätewahl über deviceUsageType ausdrücklich festlegen.
5. Status zuordnen: Die zurückgegebene deploymentId für Callback oder Statusabfrage verwenden. Terminale Zustände sind COMPLETED, RUN_FAILED, RUN_ABORTED, RUN_TIMED_OUT und DEPLOY_FAILED.
6. Abbruch steuern: Falls erforderlich, die Ausführung über POST /v3/activity/manage stoppen. Pro Request ist nur eine Aktion zulässig: stoppen, pausieren oder fortsetzen.

Wichtig ist die Trennung zwischen Deployment-ID und Execution-ID. Das Deployment liefert zunächst die Deployment-ID. Für Detailabfrage und Steuerung arbeitet der Orchestrator mit der Ausführung. Die Integration muss diese Zuordnung nachvollziehbar speichern, statt nur den letzten Statusstring abzulegen.

Fazit: Erst die Versionsfrage beantworten, dann integrieren

Die Automation Anywhere Control-Room-API ist keine einzelne API. Sie besteht aus 23 fachlich getrennten APIs, deren gültige Operationen über v1 bis v4 verteilt sind. Deploy v4 ersetzt nicht das Datenmodell von v3, WLM v4 deckt nur acht Operationen ab und einzelne produktive Funktionen bleiben bewusst auf älteren Pfaden.

Klären Sie vor der ersten Zeile Integrationscode für jede benötigte Fähigkeit: Welche API, welche Operation, welche Version und welches Request-Schema gelten? Dokumentieren Sie diese Entscheidung als Capability-Matrix und testen Sie Payloads, Filterfelder sowie Statusübergänge gegen die Zielinstanz. Genau diese Lesart verhindert, dass eine scheinbar kleine Portierung zur stillen Fehlfunktion wird.