XML-RPC-Befehle

Admin Power Pack meldet die zwölf Wartungsfunktionen des Tabs sowie die beiden Systemaktionen STARFACE-Neustart und STARFACE-Update als native Methoden an der XML-RPC-Schnittstelle der STARFACE an. Damit lösen Drittsysteme — Monitoring, RMM-Werkzeuge, Deployment- und Wartungsskripte — jede dieser Funktionen per HTTP-Aufruf aus, ohne die Moduloberfläche zu öffnen. Die Antwort bestätigt die Annahme des Befehls; die Ausführung läuft asynchron im Hintergrund, den Abschluss meldet je Wartungsaktion ein Ereignis — nur die Systemaktionen RestartStarface und UpdateStarface senden keines. Dieselben Befehle stellt — ab der nächsten Modulversion — auch die HTTP-API bereit; sie authentifiziert über statische API-Tokens statt über ein STARFACE-Benutzerkonto.

Verwendung durch Dritte

Diese Schnittstelle ist für die Nutzung durch Drittsysteme freigegeben. Änderungen und Erweiterungen werden je Version in den Release Notes dokumentiert.

Grundlagen

Typ: XML-RPC über HTTPS (POST, Content-Type: text/xml, UTF-8)
Endpunkt: https://pbx.example.de/xml-rpc — der STARFACE-Webserver (443/TCP)
Methodenname: <Instanzname>.<Befehl> — der Name der Modulkonfiguration ist Teil des Methodennamens. Der Standardname lautet „Admin Power Pack", ein Aufruf heißt also z. B. Admin Power Pack.ProvisionDevices. Wird die Modulkonfiguration umbenannt, ändern sich alle Methodennamen entsprechend; Leerzeichen sind erlaubt, XML-Sonderzeichen im Namen (etwa &) müssen im rohen XML-Body maskiert werden (&).
Authentifizierung: Anmeldung als STARFACE-Benutzer über die URL-Parameter de.vertico.starface.auth (Login-ID und Passwort-Hash) oder de.vertico.starface.jwt (OAuth2-Access-Token) — siehe Anmeldung. Kein HTTP Basic Auth, kein Authorization-Header. Die STARFACE prüft die Anmeldung, bevor der Modul-Handler läuft; das Modul verlangt zusätzlich das Administrationsrecht des angemeldeten Benutzers und lehnt andere Aufrufer ab.
Eingabe: ein einzelnes XML-RPC-struct als erster Parameter. Bei Befehlen ohne Parameter darf das <params>-Element leer sein oder ganz entfallen. Unbekannte struct-Member werden ignoriert; das Feld trigger setzt das Modul serverseitig immer auf API — es lässt sich per Aufruf nicht überschreiben.
Antwort: struct mit dem Mitglied status = "ok" oder "error" (siehe Antwortformat). "ok" bestätigt die Annahme, nicht das Ergebnis.
Lizenz: Die Annahme des Aufrufs erfolgt unabhängig von der Lizenz, die Ausführung ist lizenzgebunden — ohne gültige Modullizenz wird der angenommene Befehl verworfen (Eintrag im Modul-Log, kein Abschlussereignis).
Verfügbar seit: Modulversion 26.6.12; die Systemaktionen RestartStarface und UpdateStarface ab der nächsten Modulversion nach 26.7.28 (siehe Hinweis unter Befehle)

Den fertigen Aufruf zeigt das Modul selbst an: Öffnen Sie im Tab STARFACE Verwaltung das Aktionsmenü einer Funktion und wählen Sie API-Aufruf — der Dialog nennt Endpunkt, Methodennamen und einen kopierbaren Beispiel-Body.

Anmeldung

Die Anmeldedaten werden — wie bei der STARFACE-XML-RPC-Schnittstelle üblich — als URL-Parameter übergeben, nicht als HTTP-Header. Die STARFACE akzeptiert zwei Varianten; sind beide Parameter gesetzt, wertet sie ausschließlich de.vertico.starface.jwt aus.

Variante 1 — Login-ID und Passwort-Hash (de.vertico.starface.auth):

https://pbx.example.de/xml-rpc?de.vertico.starface.auth=<LoginID>:<Secret>

Das Secret wird aus Login-ID und Passwort des Benutzers berechnet (Hexadezimal, Kleinschreibung):

Secret = SHA-512( LoginID + "*" + SHA-512(Passwort) )

Ist für die Benutzeranmeldung der Anlage ein externer Identity-Provider (OAuth) konfiguriert, lehnt die STARFACE diese Variante grundsätzlich ab — verwenden Sie dann Variante 2 oder die HTTP-API.

Variante 2 — OAuth2-Access-Token (de.vertico.starface.jwt):

https://pbx.example.de/xml-rpc?de.vertico.starface.jwt=<AccessToken>

<AccessToken> ist ein gültiges OAuth2-Access-Token (JWT) einer STARFACE-Anmeldung. Access-Tokens sind kurzlebig und ohne interaktiven Anmeldefluss nicht unbeaufsichtigt erneuerbar — für dauerhaft angebundene Drittsysteme ist die HTTP-API mit statischen API-Tokens der passende Weg.

Für die Python-Beispiele dieser Seite wird der folgende Proxy (Variante 1) vorausgesetzt:

import hashlib
import xmlrpc.client

HOST = "pbx.example.de"
LOGIN_ID = "0101"
PASSWORD = "geheim"

pw_hash = hashlib.sha512(PASSWORD.encode("utf-8")).hexdigest()
secret = hashlib.sha512(f"{LOGIN_ID}*{pw_hash}".encode("utf-8")).hexdigest()

proxy = xmlrpc.client.ServerProxy(
    f"https://{HOST}/xml-rpc?de.vertico.starface.auth={LOGIN_ID}:{secret}"
)

Der angemeldete Benutzer benötigt das Administrationsrecht. Fehlgeschlagene Anmeldungen meldet die STARFACE an ihre Sicherheitsüberwachung; wiederholte Fehlversuche können zur IP-Sperre führen.

Antwortformat

Jeder erfolgreich angenommene Befehl antwortet mit demselben struct:

<?xml version="1.0" encoding="UTF-8"?>
<methodResponse>
  <params><param><value><struct>
    <member>
      <name>status</name>
      <value><string>ok</string></value>
    </member>
  </struct></value></param></params>
</methodResponse>

status = "error" liefert das Modul nur, wenn der Befehl intern nicht weitergereicht werden konnte. Fehler auf Protokollebene (Anmeldung, unbekannte Methode, fehlendes Administrationsrecht) beantwortet die STARFACE als XML-RPC-Fault — siehe Fehlerbehandlung.

Datentypen und Zeitstempel

Boolesche Parameter werden als <boolean>1</boolean> bzw. <boolean>0</boolean> übergeben, Ganzzahlen als <int>. Die XML-RPC-Schnittstelle der STARFACE kennt kein 64-Bit-Ganzzahl-Element (<i8>): Unix-Zeitstempel in Millisekunden (Parameter startTime, endTime) überschreiten den <int>-Wertebereich und werden deshalb als <string> übergeben — das Modul wandelt sie beim Verarbeiten in Zahlen um. In Python gilt dasselbe: übergeben Sie Millisekunden-Zeitstempel als Zeichenkette, da xmlrpc.client große int-Werte ablehnt.

Befehle

Befehl	Wirkung	Parameter	Abschlussereignis
`RunAutoCleanup`	Auto-Cleanup ausführen	–	`AutoCleanupExecutedEvent`
`DeleteSystemMessages`	Systemmeldungen löschen	–	`SystemMessagesDeletedEvent`
`DeleteLogs`	Logdateien löschen	`scope`	`LogsDeletedEvent`
`DeleteTemporaryFiles`	Temporäre Dateien löschen	–	`TemporaryFilesDeletedEvent`
`DeleteRecordings`	Gesprächsaufzeichnungen löschen	–	`RecordingsDeletedEvent`
`DeleteFaxes`	Faxe löschen	–	`FaxesDeletedEvent`
`DeleteCallData`	Ruflisteneinträge löschen	`startTime`, `endTime`, `incoming`, `outgoing`, `missed`, `answered`, `filter`, `confirmed`	`CallDataDeletedEvent`
`DeleteFirmware`	Firmware-Dateien löschen	`vendor`	`FirmwareDeletedEvent`
`DeleteBackups`	Sicherungen löschen	`scope`	`BackupsDeletedEvent`
`ReRegisterTrunks`	Leitungen neu anmelden	–	`TrunksReRegisteredEvent`
`HangupAllCalls`	Alle Gespräche beenden	–	`AllCallsHungUpEvent`
`ProvisionDevices`	Endgeräte provisionieren	`type`	`DevicesProvisionedEvent`
`RestartStarface`	STARFACE neu starten — sofort oder geplant	`mode`, `executeAt`	keines
`UpdateStarface`	STARFACE-Update ausführen — sofort oder geplant	`version`, `executeAt`	keines

Verfügbar ab der nächsten Modulversion

Die Systemaktionen RestartStarface und UpdateStarface sind in den Modulversionen bis einschließlich 26.7.28 noch nicht enthalten und erscheinen mit der nächsten Modulversion. Auf Anlagen ohne diese Version sind die beiden Methodennamen unbekannt (XML-RPC-Fault faultCode 2).

`RunAutoCleanup`

Führt die Auto-Cleanup-Routine aus — identisch zur gleichnamigen Schaltfläche in Bereinigen & Löschen. Der Umfang ist fest: Systemmeldungen der Kategorien Backup, Lizenzierung, E-Mail, Systemzustand, Update und Manuell (Sicherheitsmeldungen bleiben erhalten), alte Logdateien, temporäre Dateien sowie alle Sicherungen außer der jüngsten.

Keine Parameter. Abschlussereignis: AutoCleanupExecutedEvent.

curl
Python

curl -s -X POST \
  -H "Content-Type: text/xml; charset=utf-8" \
  --data-binary @- \
  "https://pbx.example.de/xml-rpc?de.vertico.starface.auth=0101:9c0f1f9a…" <<'XML'
<?xml version="1.0"?>
<methodCall>
  <methodName>Admin Power Pack.RunAutoCleanup</methodName>
  <params/>
</methodCall>
XML

result = getattr(proxy, "Admin Power Pack.RunAutoCleanup")({})
print(result["status"])   # "ok"

Antwort: status = "ok" — vollständiges XML unter Antwortformat.

`DeleteSystemMessages`

Löscht sämtliche Systemmeldungen der STARFACE — anders als der Auto-Cleanup einschließlich der Sicherheitsmeldungen.

Keine Parameter. Abschlussereignis: SystemMessagesDeletedEvent.

curl
Python

curl -s -X POST \
  -H "Content-Type: text/xml; charset=utf-8" \
  --data-binary @- \
  "https://pbx.example.de/xml-rpc?de.vertico.starface.auth=0101:9c0f1f9a…" <<'XML'
<?xml version="1.0"?>
<methodCall>
  <methodName>Admin Power Pack.DeleteSystemMessages</methodName>
  <params/>
</methodCall>
XML

result = getattr(proxy, "Admin Power Pack.DeleteSystemMessages")({})

Antwort: status = "ok".

`DeleteLogs`

Löscht Logdateien der Anlage.

Parameter	Typ	Pflicht	Standard	Beschreibung
`scope`	String	nein	`old`	`old`: rotierte und archivierte Logdateien (u. a. `.log.`, `.gz`, `messages-`, `secure-` in den Logverzeichnissen von System, Tomcat, Asterisk, Openfire und Modulen) sowie Logdateien ohne Zugriff seit mehr als 30 Tagen. `all`: zusätzlich werden die aktiven* Logdateien (`*.log`, `messages`, `secure`) auf 0 Byte gekürzt.

Abschlussereignis: LogsDeletedEvent.

curl
Python

curl -s -X POST \
  -H "Content-Type: text/xml; charset=utf-8" \
  --data-binary @- \
  "https://pbx.example.de/xml-rpc?de.vertico.starface.auth=0101:9c0f1f9a…" <<'XML'
<?xml version="1.0"?>
<methodCall>
  <methodName>Admin Power Pack.DeleteLogs</methodName>
  <params>
    <param>
      <value>
        <struct>
          <member>
            <name>scope</name>
            <value><string>old</string></value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>
XML

result = getattr(proxy, "Admin Power Pack.DeleteLogs")({"scope": "old"})

Antwort: status = "ok".

`DeleteTemporaryFiles`

Leert die temporären Verzeichnisse des Anwendungsservers (/opt/tomcat/temp) und des Systems (/var/tmp).

Keine Parameter. Abschlussereignis: TemporaryFilesDeletedEvent.

curl
Python

curl -s -X POST \
  -H "Content-Type: text/xml; charset=utf-8" \
  --data-binary @- \
  "https://pbx.example.de/xml-rpc?de.vertico.starface.auth=0101:9c0f1f9a…" <<'XML'
<?xml version="1.0"?>
<methodCall>
  <methodName>Admin Power Pack.DeleteTemporaryFiles</methodName>
  <params/>
</methodCall>
XML

result = getattr(proxy, "Admin Power Pack.DeleteTemporaryFiles")({})

Antwort: status = "ok".

`DeleteRecordings`

Löscht alle Gesprächsaufzeichnungen (WAV-Dateien im Aufzeichnungsverzeichnis) einschließlich der zugehörigen Datenbankverweise — die Aufzeichnungs-Anhänge verschwinden damit auch aus den Ruflisten.

Keine Parameter. Abschlussereignis: RecordingsDeletedEvent.

curl
Python

curl -s -X POST \
  -H "Content-Type: text/xml; charset=utf-8" \
  --data-binary @- \
  "https://pbx.example.de/xml-rpc?de.vertico.starface.auth=0101:9c0f1f9a…" <<'XML'
<?xml version="1.0"?>
<methodCall>
  <methodName>Admin Power Pack.DeleteRecordings</methodName>
  <params/>
</methodCall>
XML

result = getattr(proxy, "Admin Power Pack.DeleteRecordings")({})

Antwort: status = "ok".

`DeleteFaxes`

Löscht alle gespeicherten Faxe (PDF-Dateien im Faxverzeichnis) einschließlich der zugehörigen Datenbankverweise.

Keine Parameter. Abschlussereignis: FaxesDeletedEvent.

curl
Python

curl -s -X POST \
  -H "Content-Type: text/xml; charset=utf-8" \
  --data-binary @- \
  "https://pbx.example.de/xml-rpc?de.vertico.starface.auth=0101:9c0f1f9a…" <<'XML'
<?xml version="1.0"?>
<methodCall>
  <methodName>Admin Power Pack.DeleteFaxes</methodName>
  <params/>
</methodCall>
XML

result = getattr(proxy, "Admin Power Pack.DeleteFaxes")({})

Antwort: status = "ok".

`DeleteCallData`

Löscht Ruflisteneinträge (cdrsummary und cdrdata) — unwiderruflich. Der Befehl wird nur ausgeführt, wenn confirmed = true gesetzt ist; andernfalls wird er still verworfen.

Parameter	Typ	Pflicht	Standard	Beschreibung
`startTime`	Zeitstempel (ms), als String übergeben	nein	`0`	Untere Grenze auf den Gesprächsbeginn (`starttime`), einschließlich. `0` = keine Untergrenze.
`endTime`	Zeitstempel (ms), als String übergeben	nein	`0`	Obere Grenze auf den Gesprächsbeginn, einschließlich. `0` = keine Obergrenze.
`incoming`	Boolean	nein	`true`	Eingehende Anrufe einbeziehen.
`outgoing`	Boolean	nein	`true`	Ausgehende Anrufe einbeziehen.
`missed`	Boolean	nein	`true`	Nicht angenommene Anrufe einbeziehen.
`answered`	Boolean	nein	`true`	Angenommene Anrufe einbeziehen.
`filter`	String	nein	–	Einschränkung auf Rufnummern-/Namensfelder, z. B. für DSGVO-Löschersuchen. Ohne Platzhalter: Teilzeichenkette; `?`/`` als Platzhalter; `/…/` umschließt einen regulären Ausdruck (Groß-/Kleinschreibung wird ignoriert). Durchsucht werden Anrufer-/Angerufenen-Name und -Nummern, gewählte Nummer, annehmender Benutzer, Leitungsname und Rückrufnummer. Gelöscht werden stets vollständige Anrufe* (alle Zeilen derselben `callid`).
`confirmed`	Boolean	ja	`false`	Muss `true` sein — die Löschung ist unwiderruflich.

Die Flag-Paare wirken nur einschränkend, wenn genau eines der beiden Flags gesetzt ist (z. B. nur incoming); sind beide gesetzt oder beide nicht gesetzt, gilt keine Einschränkung. Ohne jede Einschränkung (kein Zeitraum, kein Filter, beide Paare vollständig) werden alle Ruflisteneinträge entfernt und die ID-Sequenzen zurückgesetzt. Vorhandene KI-Transkripte betroffener Anrufe werden mitgelöscht.

Abschlussereignis: CallDataDeletedEvent — es meldet die Anzahl der gelöschten Zeilen.

Anwendungsbeispiel

Ein Betroffener verlangt nach Art. 17 DSGVO die Löschung seiner Daten. Ihr Skript ruft DeleteCallData mit filter = +4972112345678 und confirmed = true auf — alle Anrufe mit dieser Rufnummer verschwinden vollständig aus den Ruflisten, inklusive Detailzeilen und Transkript-Verweisen. Das CallDataDeletedEvent liefert die gelöschte Anzahl für den Löschnachweis.

curl
Python

curl -s -X POST \
  -H "Content-Type: text/xml; charset=utf-8" \
  --data-binary @- \
  "https://pbx.example.de/xml-rpc?de.vertico.starface.auth=0101:9c0f1f9a…" <<'XML'
<?xml version="1.0"?>
<methodCall>
  <methodName>Admin Power Pack.DeleteCallData</methodName>
  <params>
    <param>
      <value>
        <struct>
          <member>
            <name>startTime</name>
            <value><string>0</string></value>
          </member>
          <member>
            <name>endTime</name>
            <value><string>1767225600000</string></value>
          </member>
          <member>
            <name>incoming</name>
            <value><boolean>1</boolean></value>
          </member>
          <member>
            <name>outgoing</name>
            <value><boolean>1</boolean></value>
          </member>
          <member>
            <name>missed</name>
            <value><boolean>1</boolean></value>
          </member>
          <member>
            <name>answered</name>
            <value><boolean>1</boolean></value>
          </member>
          <member>
            <name>filter</name>
            <value><string></string></value>
          </member>
          <member>
            <name>confirmed</name>
            <value><boolean>1</boolean></value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>
XML

Das Beispiel löscht alle Einträge mit Gesprächsbeginn bis einschließlich 1. Januar 2026, 00:00 Uhr UTC (endTime = 1767225600000).

result = getattr(proxy, "Admin Power Pack.DeleteCallData")({
    "startTime": "0",                 # Millisekunden als String übergeben
    "endTime": "1767225600000",       # bis 01.01.2026 00:00 UTC
    "incoming": True,
    "outgoing": True,
    "missed": True,
    "answered": True,
    "filter": "",
    "confirmed": True,
})
print(result["status"])   # "ok"

Antwort: status = "ok" — die Anzahl der gelöschten Einträge meldet das Abschlussereignis, nicht die XML-RPC-Antwort.

`DeleteFirmware`

Löscht heruntergeladene Telefon-Firmware-Dateien aus dem Provisionierungsspeicher (/var/firmware).

Parameter	Typ	Pflicht	Standard	Beschreibung
`vendor`	String	nein	`all`	`all` \| `snom` \| `yealink` \| `gigaset` \| `other`. `other` umfasst die Verzeichnisse weiterer Hersteller (Fanvil, Panasonic, Grandstream, Sirrix).

Abschlussereignis: FirmwareDeletedEvent.

curl
Python

curl -s -X POST \
  -H "Content-Type: text/xml; charset=utf-8" \
  --data-binary @- \
  "https://pbx.example.de/xml-rpc?de.vertico.starface.auth=0101:9c0f1f9a…" <<'XML'
<?xml version="1.0"?>
<methodCall>
  <methodName>Admin Power Pack.DeleteFirmware</methodName>
  <params>
    <param>
      <value>
        <struct>
          <member>
            <name>vendor</name>
            <value><string>snom</string></value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>
XML

result = getattr(proxy, "Admin Power Pack.DeleteFirmware")({"vendor": "snom"})

Antwort: status = "ok".

`DeleteBackups`

Löscht Sicherungsdateien (*.sar) aus dem Backup-Verzeichnis der Anlage.

Parameter	Typ	Pflicht	Standard	Beschreibung
`scope`	String	nein	`allExceptLast`	`allExceptLast`: behält Sicherungen, auf die innerhalb der letzten 24 Stunden zugegriffen wurde — in der Praxis bleibt die jüngste Sicherung erhalten. `all`: löscht sämtliche Sicherungen.

Abschlussereignis: BackupsDeletedEvent.

curl
Python

curl -s -X POST \
  -H "Content-Type: text/xml; charset=utf-8" \
  --data-binary @- \
  "https://pbx.example.de/xml-rpc?de.vertico.starface.auth=0101:9c0f1f9a…" <<'XML'
<?xml version="1.0"?>
<methodCall>
  <methodName>Admin Power Pack.DeleteBackups</methodName>
  <params>
    <param>
      <value>
        <struct>
          <member>
            <name>scope</name>
            <value><string>allExceptLast</string></value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>
XML

result = getattr(proxy, "Admin Power Pack.DeleteBackups")({"scope": "allExceptLast"})

Antwort: status = "ok".

`ReRegisterTrunks`

Lädt die SIP-Konfiguration der Telefonanlage neu (sip reload) — alle Amtsleitungen melden sich daraufhin neu beim Provider an. Hilfreich nach Netzstörungen oder hängenden Registrierungen.

Keine Parameter. Abschlussereignis: TrunksReRegisteredEvent.

curl
Python

curl -s -X POST \
  -H "Content-Type: text/xml; charset=utf-8" \
  --data-binary @- \
  "https://pbx.example.de/xml-rpc?de.vertico.starface.auth=0101:9c0f1f9a…" <<'XML'
<?xml version="1.0"?>
<methodCall>
  <methodName>Admin Power Pack.ReRegisterTrunks</methodName>
  <params/>
</methodCall>
XML

result = getattr(proxy, "Admin Power Pack.ReRegisterTrunks")({})

Antwort: status = "ok".

`HangupAllCalls`

Beendet alle aktiven Rufkanäle der Anlage — auch laufende Gespräche werden getrennt. Gedacht für Wartungsfenster, etwa unmittelbar vor einem Neustart oder Update.

Keine Parameter. Abschlussereignis: AllCallsHungUpEvent.

curl
Python

curl -s -X POST \
  -H "Content-Type: text/xml; charset=utf-8" \
  --data-binary @- \
  "https://pbx.example.de/xml-rpc?de.vertico.starface.auth=0101:9c0f1f9a…" <<'XML'
<?xml version="1.0"?>
<methodCall>
  <methodName>Admin Power Pack.HangupAllCalls</methodName>
  <params/>
</methodCall>
XML

result = getattr(proxy, "Admin Power Pack.HangupAllCalls")({})

Antwort: status = "ok".

`ProvisionDevices`

Stößt die Provisionierung der Tischtelefone an: Die Anlage sendet ein SIP-NOTIFY des gewählten Typs an alle registrierten SIP-Endgeräte. Für die Werksreset-Typen ergänzt das Modul vorübergehend die nötigen Ereignisdefinitionen in der Asterisk-Konfiguration und entfernt sie nach dem Versand wieder.

Parameter	Typ	Pflicht	Standard	Beschreibung
`type`	String	ja	–	`check-sync` (Synchronisation ohne Neustart) \| `check-sync-reboot` (Synchronisation mit Neustart) \| `reboot-snom` (Neustart snom) \| `factory-reset-snom` (Werkseinstellungen snom) \| `factory-reset-yealink` (Werkseinstellungen Yealink). Fehlt `type`, wird der Befehl still verworfen.

Abschlussereignis: DevicesProvisionedEvent.

curl
Python

curl -s -X POST \
  -H "Content-Type: text/xml; charset=utf-8" \
  --data-binary @- \
  "https://pbx.example.de/xml-rpc?de.vertico.starface.auth=0101:9c0f1f9a…" <<'XML'
<?xml version="1.0"?>
<methodCall>
  <methodName>Admin Power Pack.ProvisionDevices</methodName>
  <params>
    <param>
      <value>
        <struct>
          <member>
            <name>type</name>
            <value><string>check-sync-reboot</string></value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>
XML

result = getattr(proxy, "Admin Power Pack.ProvisionDevices")({"type": "check-sync-reboot"})

Antwort: status = "ok".

`RestartStarface`

Startet die STARFACE neu — sofort oder einmalig zu einem geplanten Zeitpunkt; identisch zur Funktion Zeitgesteuerter Neustart in der Karte Setup & Recovery. Vor dem Neustart meldet das Modul alle Weboberflächen-Sitzungen ab und sichert die Leitungs- und Portkonfiguration; nach einer Karenzzeit von 3 Sekunden löst es den Neustart aus.

Parameter	Typ	Pflicht	Standard	Beschreibung
`mode`	String	nein	`service`	`service`: nur die STARFACE-Dienste neu starten. `server`: den kompletten Server (Betriebssystem) neu starten. Andere Werte werden still verworfen (Log-Eintrag).
`executeAt`	String	nein	–	Geplanter Zeitpunkt als ISO-8601-Datum/-Zeit ohne Zeitzone (`JJJJ-MM-TTThh:mm`, z. B. `2026-08-12T22:00`), interpretiert in der Zeitzone der Anlage. Leer, ungültig oder in der Vergangenheit: sofortige Ausführung. In der Zukunft: einmalige geplante Ausführung.

Eine geplante Ausführung wird gespeichert und überdauert Modul-Neustarts; ein erneuter Aufruf ersetzt die bestehende Planung. Die Moduloberfläche zeigt die anstehende Aktion an und kann sie abbrechen. Kein Abschlussereignis: Der Neustart beendet die STARFACE-Dienste — überwachen Sie stattdessen die Erreichbarkeit der Anlage.

curl
Python

curl -s -X POST \
  -H "Content-Type: text/xml; charset=utf-8" \
  --data-binary @- \
  "https://pbx.example.de/xml-rpc?de.vertico.starface.auth=0101:9c0f1f9a…" <<'XML'
<?xml version="1.0"?>
<methodCall>
  <methodName>Admin Power Pack.RestartStarface</methodName>
  <params>
    <param>
      <value>
        <struct>
          <member>
            <name>mode</name>
            <value><string>service</string></value>
          </member>
          <member>
            <name>executeAt</name>
            <value><string>2026-08-12T22:00</string></value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>
XML

Das Beispiel plant einen Neustart der STARFACE-Dienste für den 12. August 2026, 22:00 Uhr Anlagenzeit; ohne executeAt erfolgt der Neustart sofort.

result = getattr(proxy, "Admin Power Pack.RestartStarface")({
    "mode": "service",
    "executeAt": "2026-08-12T22:00",   # weglassen für sofortigen Neustart
})
print(result["status"])   # "ok"

Antwort: status = "ok" — bestätigt die Annahme; ob sofort ausgeführt oder geplant wurde, lässt sich der Antwort nicht entnehmen.

`UpdateStarface`

Stößt ein STARFACE-Update an — sofort oder einmalig zu einem geplanten Zeitpunkt; identisch zur Funktion Zeitgesteuerte Updates in der Karte Setup & Recovery. Vor dem Update werden alle Sitzungen abgemeldet und die STARFACE-Dienste heruntergefahren, anschließend läuft der Update-Prozess der Anlage.

Parameter	Typ	Pflicht	Standard	Beschreibung
`version`	String	nein	`latest`	Zielversion — muss exakt einer von der STARFACE angebotenen Update-Version entsprechen (z. B. `10.0.1.6`). `latest` (Groß-/Kleinschreibung beliebig) oder leer: die neueste angebotene Version; sind Beta-Updates in der Anlage aktiviert, zählen Beta-Versionen mit. Nicht verfügbare Zielversionen werden still verworfen (Log-Eintrag).
`executeAt`	String	nein	–	Geplanter Zeitpunkt — Format und Verhalten wie bei `RestartStarface`.

Planung, Ersetzung und Abbruch verhalten sich wie bei RestartStarface. Kein Abschlussereignis: Das Update fährt die STARFACE-Dienste herunter — prüfen Sie nach dem Wartungsfenster die Versionsnummer der Anlage.

Anwendungsbeispiel

Rollout über viele Anlagen: Ihr Deployment-Skript ruft auf jeder Anlage UpdateStarface mit version = latest und einem executeAt im nächtlichen Wartungsfenster auf. Jede Anlage aktualisiert sich zum geplanten Zeitpunkt selbst — das Skript muss nachts nicht laufen, und die Planung übersteht auch einen zwischenzeitlichen Modul-Neustart.

curl
Python

curl -s -X POST \
  -H "Content-Type: text/xml; charset=utf-8" \
  --data-binary @- \
  "https://pbx.example.de/xml-rpc?de.vertico.starface.auth=0101:9c0f1f9a…" <<'XML'
<?xml version="1.0"?>
<methodCall>
  <methodName>Admin Power Pack.UpdateStarface</methodName>
  <params>
    <param>
      <value>
        <struct>
          <member>
            <name>version</name>
            <value><string>latest</string></value>
          </member>
          <member>
            <name>executeAt</name>
            <value><string>2026-08-12T22:00</string></value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>
XML

result = getattr(proxy, "Admin Power Pack.UpdateStarface")({
    "version": "latest",
    "executeAt": "2026-08-12T22:00",   # weglassen für sofortiges Update
})

Antwort: status = "ok".

Fehlerbehandlung

Protokollfehler beantwortet die STARFACE als XML-RPC-Fault (faultCode/faultString), fachliche Sonderfälle verwirft das Modul bewusst still:

Situation	Verhalten
Anmeldung fehlt oder ist ungültig	XML-RPC-Fault `faultCode` 5 (bzw. 4 bei einem Fehler in der Anmeldeprüfung); der Modul-Handler wird nicht ausgeführt. Der Fehlversuch wird der STARFACE-Sicherheitsüberwachung gemeldet.
Benutzer ohne Administrationsrecht	XML-RPC-Fault `faultCode` 1 („The remote procedure threw an exception during execution."). Der Befehl wird nicht angenommen.
Unbekannter Methodenname (Modulkonfiguration inaktiv, Instanzname falsch oder umbenannt)	XML-RPC-Fault `faultCode` 2 („No processor found for the identifier …").
Befehl kann intern nicht weitergereicht werden	Antwort `status` = `"error"`; Details im Modul-Log.
Keine gültige Modullizenz	Antwort `status` = `"ok"`, die Ausführung wird jedoch verworfen — kein Abschlussereignis, Hinweis im Modul-Log.
`DeleteCallData` ohne `confirmed` = `true`	Antwort `status` = `"ok"`, keine Ausführung, kein Abschlussereignis.
`ProvisionDevices` ohne `type`	Antwort `status` = `"ok"`, keine Ausführung, kein Abschlussereignis.
`RestartStarface` mit ungültigem `mode`	Antwort `status` = `"ok"`, kein Neustart (Log-Eintrag).
`UpdateStarface` mit nicht verfügbarer Zielversion oder ohne verfügbares Update	Antwort `status` = `"ok"`, kein Update (Log-Eintrag).

Wer die Ausführung der Wartungsaktionen überwachen will, abonniert die Abschlussereignisse — z. B. über EventBridge als Webhook oder E-Mail. Die Systemaktionen RestartStarface und UpdateStarface senden kein Abschlussereignis.

Versionierung & Kompatibilität

Die vierzehn Methodennamen (Suffixe), ihre Parameter und das Antwortformat sind stabile Verträge; Erweiterungen erfolgen additiv (neue Befehle, neue optionale Parameter). Die zwölf Wartungsbefehle sind seit Modulversion 26.6.12 verfügbar, die Systemaktionen RestartStarface und UpdateStarface ab der nächsten Modulversion nach 26.7.28; Änderungen dokumentieren die Release Notes der jeweiligen Modulversion. Der vollständige Methodenname hängt vom Namen der Modulkonfiguration ab — für per API angesprochene Anlagen empfiehlt sich, den Standardnamen „Admin Power Pack" beizubehalten.

Grundlagen​

Anmeldung​

Antwortformat​

Datentypen und Zeitstempel​

Befehle​

RunAutoCleanup​

DeleteSystemMessages​

DeleteLogs​

DeleteTemporaryFiles​

DeleteRecordings​

DeleteFaxes​

DeleteCallData​

DeleteFirmware​

DeleteBackups​

ReRegisterTrunks​

HangupAllCalls​

ProvisionDevices​

RestartStarface​

UpdateStarface​

Fehlerbehandlung​

Versionierung & Kompatibilität​

Grundlagen

Anmeldung

Antwortformat

Datentypen und Zeitstempel

Befehle

`RunAutoCleanup`

`DeleteSystemMessages`

`DeleteLogs`

`DeleteTemporaryFiles`

`DeleteRecordings`

`DeleteFaxes`

`DeleteCallData`

`DeleteFirmware`

`DeleteBackups`

`ReRegisterTrunks`

`HangupAllCalls`

`ProvisionDevices`

`RestartStarface`

`UpdateStarface`

Fehlerbehandlung

Versionierung & Kompatibilität