Aufmerksamkeit

Mit dieser Schnittstelle sehen Ihre eigenen Werkzeuge, was in Ihrer Flotte Aufmerksamkeit braucht – und bestätigen Meldungen der Module, ohne die Konsole zu öffnen. Sie liefert dieselben Einträge wie die Karte Aufmerksamkeit in der Konsole. Diese Seite ist die Referenz für Integratoren und für alle, die einen KI-Assistenten an den Controller anbinden.

Verwendung durch Dritte

Diese Schnittstelle ist für die Nutzung durch Drittsysteme freigegeben. Erweiterungen erfolgen additiv: neue Felder und neue Werte kommen hinzu, bestehende bleiben.

Sie wollen nur wissen, wie die Karte funktioniert?

Die Bedienung in der Konsole beschreibt Funktionsumfang – Aufmerksamkeit und Meldungen der Module.

Grundlagen

Basis-URL: https://cmp.sf-app.de/api/v1. Betreiben Sie den Controller selbst, setzen Sie Ihren eigenen Host ein.
Authentifizierung: ein Konto des Controllers. Skripte melden sich per HTTP Basic mit E-Mail-Adresse und Passwort eines lokalen Kontos an. Konten, die sich nur über einen Identitätsanbieter (Microsoft, Google, STARFACE) anmelden, haben kein Passwort und eignen sich dafür nicht.
Sichtbarkeit: Sie sehen die Anlagen, auf die Ihr Partnerzugang ein Recht hat – eigene und vertretungsweise betreute. Eine fremde Anlage verhält sich wie eine, die es nicht gibt (404).
Bestätigung je Partnerzugang: Eine Bestätigung gilt für alle Konten Ihres Partnerzugangs. Andere Partner derselben Anlage bestätigen für sich und sehen Ihre Bestätigung nicht.
Rollen: Konten mit der Rolle Betrachter lesen, bestätigen aber nicht (403).
Format: JSON, UTF-8. Zeitpunkte sind Millisekunden seit 1970 (UTC).

Woher die Meldungen kommen

Die Karte kennt zwei Arten von Einträgen:

Art	Entsteht	Verschwindet
Befund (`offline`, `trunks`, `backupFailed`, `backupMissing`, `version`, `modules`)	Der Controller wertet Bestand und Erreichbarkeit aus.	Von selbst, sobald die Ursache behoben ist.
Meldung eines Moduls (Befund `events`)	Ein Fluxpunkt-Modul auf der Anlage sendet ein `AttentionEvent`.	Wenn Ihr Partnerzugang sie bestätigt – bis das Modul sie erneut meldet.

Der Weg einer Meldung:

Ein Modul sendet auf der Anlage ein AttentionEvent.
Das Admin Power Pack legt daraus einen STARFACE-Systemreport an und leitet die Meldung an den Controller weiter – nur wenn ein Partner auf der Anlage freigegeben ist. Je Modul gehen höchstens 5 Meldungen auf einmal und danach eine alle zwei Minuten hinaus.
Der Controller fasst Meldungen mit gleicher Anlage, gleichem Modul und gleichem Betreff zu einem Eintrag zusammen und zählt die Wiederholungen.

Das Objekt „Meldung“

Feld	Typ	Beschreibung
`id`	Integer	Kennung der Meldung. Bleibt für Anlage, Modul und Betreff gleich, auch über Wiederholungen hinweg.
`module`	String	Anzeigename des meldenden Moduls, z. B. `Call Recording`.
`moduleId`	String, optional	Modulkennung (sfmId), falls das Modul sie mitsendet.
`subject`	String	Betreff, höchstens 200 Zeichen.
`description`	String, optional	Beschreibung mit Ursache und nächsten Schritten, höchstens 4000 Zeichen.
`severity`	String	`INFO` (Hinweis), `WARNING` (Warnung), `ERROR` (Fehler) oder `CRITICAL` (kritisch).
`firstAt`	Integer	Erste Meldung, Uhr der Anlage.
`lastAt`	Integer	Letzte Meldung, Uhr der Anlage.
`occurrences`	Integer	Wie oft die Meldung einging.
`suppressed`	Integer	Meldungen, die die Anlage wegen der Drosselung zurückgehalten hat.

Offene Meldungen lesen

GET /api/v1/sites

Die Anlagenliste trägt je Anlage zwei Felder für die Aufmerksamkeit:

attention – die Befunde als Liste von Schlüsseln. events steht darin, sobald mindestens eine Meldung für Ihren Partnerzugang offen ist.
attentionEvents – die offenen Meldungen, die schwersten zuerst, innerhalb einer Schwere die jüngsten zuerst.

Alle Anlagen mit offenen Meldungen
curl -s -u "technik@partner.de:••••••" https://cmp.sf-app.de/api/v1/sites \
  | jq '[.[] | select((.attentionEvents // []) | length > 0)
          | {anlage: .displayName, meldungen: [.attentionEvents[] | {id, severity, module, subject}]}]'

Ausschnitt einer Anlage
{
  "id": "1458d78f-6e4c-4cf2-b524-888b0c3caddf",
  "displayName": "Muster GmbH – Zentrale",
  "attention": ["events"],
  "attentionEvents": [
    {
      "id": 4711,
      "module": "Call Recording",
      "moduleId": "de.fluxpunkt.callrecording",
      "subject": "Aufzeichnungsziel nicht erreichbar",
      "description": "Die Freigabe \\\\nas01\\aufnahmen antwortet nicht. Aufnahmen werden lokal zwischengespeichert.",
      "severity": "ERROR",
      "firstAt": 1790863200000,
      "lastAt": 1790920800000,
      "occurrences": 7,
      "suppressed": 0
    }
  ]
}

Die Antwort trägt ein ETag. Fragen Sie regelmäßig ab, senden Sie den Wert als If-None-Match mit: Ohne Änderung antwortet der Controller mit 304 und ohne Inhalt. Neue Meldungen und Bestätigungen ändern das ETag.

Anwendungsbeispiel

Ihr Ticketsystem fragt alle fünf Minuten die Anlagenliste ab. Für jede neue Meldung mit Schwere ERROR oder CRITICAL legt es ein Ticket an, mit Kunde, Modul und Beschreibung. Die Kennung id merkt es sich, damit eine Wiederholung kein zweites Ticket erzeugt.

Meldung bestätigen

POST /api/v1/sites/{siteId}/attention/{attentionId}/acknowledge
Content-Type: application/json

Parameter	Ort	Pflicht	Beschreibung
`siteId`	Pfad	ja	Kennung der Anlage (`id` aus der Anlagenliste).
`attentionId`	Pfad	ja	Kennung der Meldung (`attentionEvents[].id`).
`comment`	Body	nein	Begründung für die Historie, höchstens 1000 Zeichen.

Bestätigen mit Begründung
curl -s -u "technik@partner.de:••••••" -H "Content-Type: application/json" \
  -d '{"comment": "NAS nach Stromausfall neu gestartet"}' \
  https://cmp.sf-app.de/api/v1/sites/1458d78f-6e4c-4cf2-b524-888b0c3caddf/attention/4711/acknowledge

Antwort 200
{
  "attentionId": 4711,
  "siteId": "1458d78f-6e4c-4cf2-b524-888b0c3caddf",
  "alreadyAcknowledged": false,
  "acknowledgedAt": 1790921400000
}

Der Aufruf ist idempotent. Hat Ihr Partnerzugang die Meldung in ihrem aktuellen Stand schon bestätigt, antwortet er mit alreadyAcknowledged: true und schreibt keinen zweiten Eintrag in die Historie. Meldet das Modul das Problem danach erneut, ist die Meldung wieder offen und kann erneut bestätigt werden.

Anwendungsbeispiel

Ein Techniker schließt das Ticket zum Aufzeichnungsziel. Ihr Ticketsystem ruft dabei den Endpunkt mit der Lösung aus dem Ticket als comment auf. Die Meldung verschwindet aus der Konsole, und die Historie der Anlage zeigt, wer sie wann und warum erledigt hat.

Fehler

Fehlerantworten tragen error (Code) und message (deutscher Text).

Status	`error`	Bedeutung
`400`	`invalid_request`	Begründung länger als 1000 Zeichen.
`401`	–	Nicht angemeldet oder falsches Passwort.
`403`	`forbidden`	Das Konto hat die Rolle Betrachter.
`404`	–	Meldung gibt es nicht, gehört zu einer anderen Anlage oder ist für Ihren Partnerzugang nicht sichtbar.

Bestätigungen in der Historie

GET /api/v1/sites/{siteId}/history

Jede Bestätigung erscheint als Eintrag mit kind = ATTENTION_ACK. Sie sehen nur die Bestätigungen Ihres eigenen Partnerzugangs.

Feld	Beschreibung
`actor`	Name der bestätigenden Person zum Zeitpunkt der Bestätigung.
`channel`	`console` (Konsole oder REST) oder `mcp` (KI-Assistent).
`createdAt`	Zeitpunkt der Bestätigung.
`attention.id`, `attention.module`, `attention.subject`, `attention.severity`	Die bestätigte Meldung.
`attention.comment`	Begründung, sonst `null`.

tool, state, outcome und completedAt sind bei diesen Einträgen null.

Eintrag der Historie
{
  "kind": "ATTENTION_ACK",
  "actor": "Anna Admin",
  "own": true,
  "channel": "console",
  "createdAt": 1790921400000,
  "siteName": "Muster GmbH – Zentrale",
  "attention": {
    "id": 4711,
    "module": "Call Recording",
    "subject": "Aufzeichnungsziel nicht erreichbar",
    "severity": "ERROR",
    "comment": "NAS nach Stromausfall neu gestartet"
  }
}

Für KI-Assistenten (MCP)

Die MCP-Schnittstelle des Controllers bietet dieselben Daten als Werkzeuge an.

Werkzeug	Wirkung	Benötigte Stufe
`fleet_attention`	Alle Anlagen mit Befunden. Offene Meldungen stehen je Anlage unter `events` mit `attentionId`, `module`, `subject`, `description`, `severity`, `firstAt`, `lastAt` und `occurrences`.	Lesen
`fleet_attention_acknowledge`	Bestätigt eine Meldung für Ihren Partnerzugang. Argumente: `attentionId` (Pflicht), `comment` (optional, höchstens 1000 Zeichen).	Lesen + Schreiben, für Konto und Zugangstoken

Antwort von fleet_attention_acknowledge
{
  "outcome": "ok",
  "attentionId": 4711,
  "siteId": "1458d78f-6e4c-4cf2-b524-888b0c3caddf",
  "alreadyAcknowledged": false,
  "acknowledgedAt": 1790921400000
}

Der Assistent ist angewiesen, nur auf ausdrücklichen Wunsch zu bestätigen. In der Historie steht die Bestätigung mit dem Namen des Kontos und dem Weg mcp.

Anwendungsbeispiel

Sie fragen Ihren Assistenten: „Was ist heute in der Flotte offen?“ Er listet zwei Meldungen. Nach Ihrer Prüfung sagen Sie: „Bestätige die PowerDesk-Meldung bei Muster, Schlüssel ist erneuert.“ Der Assistent ruft fleet_attention_acknowledge mit dieser Begründung auf.

Grenzen

Grenze	Wert
Betreff	200 Zeichen, längere werden gekürzt
Beschreibung	4000 Zeichen, längere werden gekürzt
Begründung	1000 Zeichen, längere werden abgelehnt (`400`)
Verschiedene Meldungen je Anlage	200; danach werden nur bestehende fortgeschrieben
Weiterleitung je Modul (Anlage)	5 auf einmal, danach eine alle zwei Minuten

Ist der Kanal zum Controller unterbrochen, hält das Admin Power Pack bis zu 20 Meldungen zurück und sendet sie nach dem Wiederverbinden.

Nächster Schritt

Wie ein eigenes Modul oder die EventBridge eine Meldung auslöst, steht unter Admin Power Pack – Ereignisse.

Grundlagen​

Woher die Meldungen kommen​

Das Objekt „Meldung“​

Offene Meldungen lesen​

Meldung bestätigen​

Fehler​

Bestätigungen in der Historie​

Für KI-Assistenten (MCP)​

Grenzen​

Nächster Schritt​

Grundlagen

Woher die Meldungen kommen

Das Objekt „Meldung“

Offene Meldungen lesen

Meldung bestätigen

Fehler

Bestätigungen in der Historie

Für KI-Assistenten (MCP)

Grenzen

Nächster Schritt