Integrationen¶
Expecto kommuniziert mit externen Plattformen in zwei Richtungen:
- Context — bevor eine Lieferung verarbeitet wird, liest Expecto Referenzdaten aus einem externen System und legt sie in den Session-Kontext: die Salden des Vormonats aus einem Data Warehouse, eine Fondsnummer aus einer Stammdaten-API, einen Wechselkurs aus einer Reporting-Datenbank. Geschäftsregeln und Transformer nutzen diese Werte wie jeden anderen Kontext.
- Outbound — erreicht eine Session einen Meilenstein (Prüfungen bestanden, eine Stufe fehlgeschlagen, das Paket exportiert), schreibt Expecto einen Datensatz in eine externe Plattform: einen Status-Datensatz in Salesforce, eine Zeile in einer Betriebstabelle.
Beide Richtungen bestehen aus denselben drei Bausteinen.
Die Bausteine¶
| Baustein | Lebt auf | Enthält |
|---|---|---|
| Connection | Organisation (Settings → Connections) | Wie ein externes System erreicht wird: Typ, URL oder DSN, Zugangsdaten, anbieterspezifische Konfiguration. Zugangsdaten werden verschlüsselt gespeichert und nie wieder angezeigt. |
| Context Source | Projekt (Project → Context) | Eine Abfrage gegen eine Connection mit {{ … }}-Platzhaltern sowie die Kontexttabelle oder der Skalar, den sie erzeugt. |
| Outbound Binding | Projekt (Project → Context → Outbound Bindings) | Welche Session-Ereignisse an welche Connection gehen und wie die Nutzlast geformt wird. |
Der Typ einer Connection bestimmt, was sie kann. Jeder Typ wird von einem Adapter implementiert, der seine Fähigkeiten deklariert:
| Plattform | Typ | Fähigkeiten | Seite |
|---|---|---|---|
| Salesforce | salesforce |
outbound | Salesforce |
| BuiltAPI | builtapi |
context | BuiltAPI |
| PostgreSQL | postgres |
context | PostgreSQL |
Eine Context Source muss auf eine context-fähige Connection verweisen, ein
Outbound Binding auf eine outbound-fähige; alles andere wird beim Speichern
mit einer klaren Meldung abgelehnt. Der aktuelle Katalog mit Fähigkeiten und
Formularfeldern kommt von GET /api/integration-connections/types (bzw. dem
MCP-Tool list_connection_types), sodass Clients ihn nie hart kodieren.
Wer darf was¶
| Aktion | Benötigt |
|---|---|
| Connections anlegen, bearbeiten, testen, löschen; Context Sources und Outbound Bindings bearbeiten | Die Berechtigung integrations:manage — enthalten in den Rollen owner und admin |
| Outbound Bindings und ihr Zustellungsprotokoll unter Settings → Webhooks sehen | webhooks:manage (ebenfalls owner/admin) |
Connections¶
Öffnen Sie Settings → Connections. Jede Zeile zeigt den Typ, das
Fähigkeits-Badge (context / outbound), ob die Connection aktiv ist und ob
Zugangsdaten hinterlegt sind.
Add Connection öffnet ein Formular, dessen Felder aus dem Typkatalog stammen — zuerst den Typ wählen, dann passt sich das Formular an: My-Domain-URL plus Consumer Key / Secret für Salesforce, Basis-URL plus Service-Token und Workspace-ID für BuiltAPI, DSN plus Passwort für PostgreSQL.
Zugangsdaten sind write-only
Was Sie als Geheimnis eingeben, wird verschlüsselt gespeichert und von
keiner Leseoperation zurückgegeben — die API liefert nur
has_credentials: true. Zum Rotieren geben Sie unter Edit ein neues
Geheimnis ein; zum Löschen nutzen Sie clear_credentials. Geheimnisse
erscheinen nie in Logs, Zustellungsdatensätzen oder Fehlermeldungen.
Test führt den günstigsten authentifizierten Aufruf aus, den die Plattform
erlaubt, ohne auf der Gegenseite etwas zu ändern: eine Token-Anfrage bei
Salesforce, eine Einzeilen-Listenabfrage bei BuiltAPI, SELECT 1 in einer
Read-only-Transaktion bei PostgreSQL. Das Ergebnis ist eines von:
error_kind |
Bedeutung |
|---|---|
| (ok) | System erreicht und authentifiziert. |
connection_error |
Nicht erreichbar, Timeout oder 5xx-Antwort. |
auth_error |
Die Zugangsdaten wurden abgelehnt. |
query_error |
Die Connection-Konfiguration ist unvollständig (z. B. fehlende BuiltAPI-workspace_id). |
Sie können auch eine noch nicht gespeicherte Nutzlast testen — derselbe Button
Test connection im Anlage-Dialog oder
POST /api/integration-connections/test mit type, base_url, config und
credentials.
Netzwerkregeln¶
HTTP-basierte Connections müssen https:// verwenden und auf einen öffentlichen
Host zeigen: Die URL wird beim Speichern aufgelöst und abgelehnt, wenn sie in
einen privaten, Loopback- oder Link-local-Bereich fällt oder user:password@
enthält. Ein PostgreSQL-DSN trägt Benutzer, Host, Port, Datenbank und
sslmode; das Passwort gehört in das Zugangsdaten-Feld, nie in den DSN.
Deaktivieren und Löschen¶
- Inaktive Connections behalten ihre Zugangsdaten, aber jeder
Kontext-Fetch und jede Outbound-Zustellung, die auf sie verweist, schlägt
sofort fehl (
connection_inactive). So pausieren Sie eine Integration, ohne die Konfiguration zu verlieren. - Delete wird verweigert, solange Context Sources oder Outbound Bindings eines Projekts die Connection noch referenzieren — entfernen Sie zuerst diese Verweise.
Nicht Teil des Organisations-Exports
Export/Import der Organisation umfasst die Konfigurationsschicht (Entities, Projekte, Contracts, Kataloge, Provider), aber nicht Integration Connections, Context Sources oder Outbound Bindings — Geheimnisse dürfen nie in einem Paket reisen. Legen Sie sie nach einem Import von Hand oder per API neu an.
Wo die Projektseite lebt¶
Context Sources und Outbound Bindings werden pro Projekt auf dessen
Context-Seite konfiguriert. Context Sources sind auf den Plattformseiten
beschrieben (BuiltAPI, PostgreSQL), Outbound
Bindings auf der Seite Salesforce. Beide nutzen dieselbe
{{ … }}-Platzhaltersprache — siehe
Platzhalter & Zustellungsreferenz.
API- und MCP-Oberfläche¶
| Zweck | REST (/api) |
MCP-Tool |
|---|---|---|
| Typkatalog | GET /integration-connections/types |
list_connection_types |
| Connections CRUD | POST/GET/PATCH/DELETE /integration-connections[/{id}] |
create_/list_/update_/delete_integration_connection |
| Connection testen | POST /integration-connections/test |
test_integration_connection |
| Context Source probelaufen | POST /integration-connections/test-source |
test_context_source |
| Context Sources eines Projekts | GET/PUT /projects/{id}/context-sources |
get_/set_project_context_sources |
| Kontext-Fetch erneut ausführen | POST /sessions/{id}/context/fetch |
fetch_session_context |
| Outbound Bindings eines Projekts | GET/PUT /projects/{id}/outbound-bindings |
get_/set_project_outbound_bindings |
| Alle Bindings der Organisation (read-only) | GET /outbound-bindings |
— |
| Zustellungshistorie und Replay | GET /webhook-deliveries?connection_id=…, POST /webhook-deliveries/{id}/replay |
list_webhook_deliveries, replay_webhook_delivery |
Die vollständigen Request- und Response-Formen stehen in der OpenAPI-Referenz und im MCP-Tool-Katalog.