ameax per KI einrichten: Konfiguration als Blueprint

Ein neuer Geschäftsbereich soll in ameax abgebildet werden: Reklamationen sollen als eigene Vorgangsart laufen, mit sechs Status und klaren Prozess-Buttons, dazu drei Zusatzfelder am Kunden, eine Handvoll Textvorlagen und eine Kampagne für die Nachfassaktion. Das Konzept steht nach einem Workshop auf zwei Seiten. Danach beginnt die eigentliche Arbeit: Masken öffnen, Status anlegen, Farben wählen, Buttons verknüpfen, Textvorlagen kopieren. Ein bis zwei Tage Klickarbeit, und wer mehrere Standorte oder als Agentur mehrere Kunden betreut, macht sie in jeder Installation noch einmal.

Dabei ist die Einrichtung von ameax zu einem großen Teil über die Schnittstelle erreichbar, und die aufwendigsten Teile lassen sich als ein zusammenhängendes JSON-Dokument beschreiben, als sogenannter Blueprint. Ein Sprachmodell kann aus der Beschreibung in natürlicher Sprache genau so ein Dokument erzeugen. Es wird gegen ein JSON-Schema geprüft, in einer Testumgebung eingespielt, von einem Menschen abgenommen und dann in die produktive Installation übertragen. Aus zwei Tagen Klickarbeit wird eine Stunde Prüfarbeit.

Der Ablauf im Überblick

Die Rollen sind klar verteilt. ameax ist das führende System und liefert das Schema, gegen das geprüft wird. n8n führt die Schritte aus. Das Sprachmodell übersetzt Anforderungen in ein strukturiertes Dokument. Ein Mensch nimmt das Ergebnis in der Testumgebung ab, bevor es produktiv geht.

1. Anforderung formulieren. Jemand beschreibt in normaler Sprache, was gebraucht wird: „Eine Vorgangsart Reklamation mit Eingang, Prüfung, Rückfrage beim Kunden, Lösung, Erledigt und Abgelehnt.“
2. Schema und Bestand laden. n8n holt das JSON-Schema des passenden Blueprints, etwa GET /api/v2/task-schemes/blueprint/schema, und die vorhandene Einrichtung, damit keine Kürzel und Namen doppelt vergeben werden.
3. Blueprint erzeugen. Das Sprachmodell erhält Anforderung, Schema und Bestand und liefert ausschließlich ein Blueprint-JSON zurück.
4. Prüfen. n8n prüft das Dokument gegen das JSON-Schema und mit einigen eigenen Regeln, etwa ob jeder Button auf einen existierenden Status verweist.
5. In der Testumgebung einspielen. Das geprüfte Dokument geht per POST /api/v2/task-schemes/blueprint in eine Installation, die Sie zum Testen nutzen.
6. Abnehmen. Ein Mensch klickt die neue Vorgangsart in der Oberfläche durch, ergänzt, was der Blueprint nicht abdeckt, und gibt frei.
7. Produktiv übertragen. n8n exportiert die abgenommene Fassung aus der Testumgebung mit GET /api/v2/task-schemes/{id}/blueprint und spielt genau dieses Dokument in der produktiven Installation ein.
8. Wiederverwenden. Das exportierte Dokument wird abgelegt und steht für weitere Standorte, Mandanten oder Kunden bereit.

Der wichtigste Schritt ist der siebte: Produktiv eingespielt wird nicht, was das Sprachmodell erzeugt hat, sondern was ein Mensch in der Testumgebung gesehen und abgenommen hat.

Was sich per Schnittstelle einrichten lässt

Nicht jeder Teil der Einrichtung ist gleich gut für diesen Weg geeignet. Die folgende Übersicht zeigt, welche Bereiche über die REST-API v2 erreichbar sind, ob es einen Blueprint gibt und welches Recht der technische Benutzer dafür braucht. Die Rechte sind mit ihrem technischen Namen angegeben, wie sie die Schnittstelle prüft.

Zeitarten haben ebenfalls einen Blueprint unter /time-types/blueprint. Artikel und Rollen lassen sich über die API nur lesen. Den Artikelstamm und die Rollen des Kundenportals pflegen Sie weiterhin in der Oberfläche. Für die übrigen Bereiche gilt: Wo ein Blueprint existiert, ist er der bessere Weg, weil er eine zusammenhängende Einrichtung in einem Dokument beschreibt und Verweise über Namen statt über interne IDs auflöst.

Vorbereitung in ameax

Ein technischer Benutzer mit Verwaltungsrechten

Ein Token hat in ameax keine eigenen Rechte-Scopes, es erbt die Rechte des Benutzers, dem es gehört. Für die Einrichtung per Schnittstelle legen Sie deshalb einen eigenen technischen Benutzer an und geben ihm genau die Verwaltungsrechte aus der Tabelle oben, die der Workflow braucht. Wer nur Vorgangsarten und Textvorlagen einrichten will, braucht kein Recht auf Betreuergruppen. Das Token erzeugen Sie unter /c/apitoken, am besten mit Ablaufdatum und einer IP-Liste, die nur Ihren n8n-Server zulässt — hinterlegt wird es dann als Credential, um n8n an ameax anzubinden. Da Verwaltungsrechte weit reichen, ist ein kurzes Ablaufdatum hier sinnvoller als bei einem Token, das nur Kunden liest.

Eine Installation zum Testen

Für diesen Ablauf brauchen Sie eine zweite Installation, in der eingespielt und ausprobiert werden darf, ohne dass Mitarbeiter oder Kunden davon etwas sehen. Sie bekommt einen eigenen technischen Benutzer und ein eigenes Token. In n8n legen Sie für beide Installationen je eine Zugangsdaten-Konfiguration an, damit ein Workflow nie versehentlich mit dem falschen Token arbeitet.

Die Schnittstelle freischalten

Die REST-API v2 ist über einen Modulschalter aktiviert und im Paket „Plus“ des CRM als „API / offene Schnittstelle“ enthalten. Sie antwortet nur über HTTPS. Ob Ihre Installation die Schnittstelle bereits nutzt, sehen Sie am einfachsten daran, ob GET /api/v2/openapi.json mit Ihrem Token eine Spezifikation liefert.

Auslöser

Die Einrichtung ist keine Daueraufgabe, der Workflow startet deshalb auf Anforderung. In n8n eignet sich dafür ein Formular-Trigger mit einem großen Textfeld für die Anforderung und einer Auswahl, welcher Bereich eingerichtet werden soll. Wer im Team lieber schreibt, als Formulare auszufüllen, nutzt einen Chat-Trigger. Beide Wege enden an derselben Stelle: Der Workflow erzeugt einen Blueprint, prüft ihn und spielt ihn in der Testumgebung ein.

Für die Übertragung auf die produktive Installation empfiehlt sich ein eigener, manuell gestarteter Workflow. Er nimmt die ID der abgenommenen Einrichtung in der Testumgebung entgegen, exportiert sie und spielt sie produktiv ein. So ist der Schritt in die Produktion immer eine bewusste Handlung und kein Nebeneffekt eines anderen Laufs.

Wer mehrere Installationen betreut, ergänzt einen zeitgesteuerten Lauf: Einmal pro Woche exportiert er die Referenz-Einrichtung, vergleicht sie mit den Blueprints der anderen Installationen und meldet Abweichungen. Ob die Abweichung gewollt ist, entscheidet ein Mensch.

Umsetzung Schritt für Schritt

Das durchgehende Beispiel ist eine Vorgangsart für Reklamationen. Die Installation heißt https://ihrefirma.ameax.de, alle IDs sind Beispielwerte. Jede Anfrage trägt das Token im Kopf Authorization: Bearer …, Anfragen mit Inhalt zusätzlich Content-Type: application/json.

Schritt 1: Schema und Bestand laden

Zuerst holt n8n das JSON-Schema des Blueprints. Es beschreibt, welche Felder erlaubt sind, welche Pflicht sind und welche Werte gelten, etwa die zulässigen Statustypen und Zuständigkeitsmodi. Dazu kommt die Liste der vorhandenen Vorgangsarten, denn das Kürzel einer Vorgangsart muss eindeutig sein.

GET https://ihrefirma.ameax.de/api/v2/task-schemes/blueprint/schema
GET https://ihrefirma.ameax.de/api/v2/task-schemes?per_page=100

Das Schema kommt unter data zurück und bringt ein vollständiges Beispiel mit. Genau dieses Beispiel ist für das Sprachmodell wertvoll: Es zeigt nicht nur die Regeln, sondern auch, wie ein gutes Dokument aussieht.

Schritt 2: Das Sprachmodell erzeugt den Blueprint

Der Prompt ist streng. Das Modell soll nicht beraten und nicht erklären, sondern ein Dokument liefern, das gegen das Schema besteht. Alles Weitere, etwa Rückfragen zu unklaren Anforderungen, gehört in ein eigenes Feld der Ausgabe und nicht in den Blueprint.

ROLLE
Du erzeugst Konfigurationsdokumente für ameax. Du antwortest ausschließlich mit JSON.

EINGABE
- anforderung: Beschreibung in natürlicher Sprache
- schema: JSON-Schema "ameax Task Scheme Blueprint"
- vergebene_kuerzel: Liste der bereits verwendeten Kürzel (abbrev)

REGELN
1. Halte dich exakt an das Schema. Verwende keine Felder, die dort nicht stehen.
2. abbrev: höchstens 3 Zeichen, Großbuchstaben, nicht in vergebene_kuerzel.
3. Genau ein Status hat "is_default": true.
4. state_type: waiting = offen, progress = in Arbeit, upcoming = geplant,
   onhold = Rückmeldung erforderlich, finished = abgeschlossen.
5. target_state und trigger_states verweisen nur auf Titel aus "states".
6. Status, die einen Grund brauchen (Ablehnung, Rückfrage), bekommen
   Buttons mit "comment_mode": "force".
7. Ist eine Anforderung unklar, triff keine Annahme im Blueprint,
   sondern nenne sie unter "rueckfragen".

AUSGABE
{"blueprint": { ... }, "rueckfragen": ["..."]}

Schritt 3: Das Ergebnis am Beispiel Reklamation

So sieht ein Blueprint aus, der die Anforderung aus dem Einstieg umsetzt. Die Feldnamen entsprechen dem Schema der Schnittstelle:

{
  "meta": {
    "document_type": "ameax_task_scheme_blueprint",
    "schema_version": "1.0"
  },
  "scheme": {
    "name": "Reklamation",
    "abbrev": "REK",
    "color": "#C0392B",
    "active": true,
    "ticket_activate": false
  },
  "states": [
    {"title": "Eingegangen", "state_type": "waiting", "is_default": true, "color": "#95A5A6", "sort": 10},
    {"title": "In Prüfung", "state_type": "progress", "color": "#3498DB", "sort": 20},
    {"title": "Rückfrage beim Kunden", "state_type": "onhold", "color": "#F39C12", "sort": 30},
    {"title": "Lösung veranlasst", "state_type": "progress", "color": "#8E44AD", "sort": 40},
    {"title": "Erledigt", "state_type": "finished", "color": "#27AE60", "sort": 50},
    {"title": "Abgelehnt", "state_type": "finished", "color": "#7F8C8D", "sort": 60}
  ],
  "proceedings": [
    {"name": "Prüfung übernehmen", "trigger_states": ["Eingegangen"],
     "target_state": "In Prüfung", "assignee_mode": "self", "sort": 10},
    {"name": "Rückfrage stellen", "trigger_states": ["In Prüfung"],
     "target_state": "Rückfrage beim Kunden", "comment_mode": "force", "sort": 20},
    {"name": "Antwort liegt vor", "trigger_states": ["Rückfrage beim Kunden"],
     "target_state": "In Prüfung", "comment_mode": "optional", "sort": 30},
    {"name": "Reklamation anerkennen", "trigger_states": ["In Prüfung"],
     "target_state": "Lösung veranlasst", "comment_mode": "force",
     "main_customer_required": true, "sort": 40},
    {"name": "Reklamation ablehnen", "trigger_states": ["In Prüfung"],
     "target_state": "Abgelehnt", "comment_mode": "force", "sort": 50},
    {"name": "Abschließen", "trigger_states": ["Lösung veranlasst"],
     "target_state": "Erledigt", "comment_mode": "optional", "sort": 60},
    {"name": "Eskalieren", "trigger_states": ["Eingegangen", "In Prüfung"],
     "prio_mode": "set", "prio": "critical", "assignee_mode": "agent", "sort": 70}
  ]
}

Einige Entscheidungen darin sind typisch für eine gute Einrichtung. Die Buttons „Rückfrage stellen“ und „Reklamation ablehnen“ erzwingen einen Kommentar, weil später niemand mehr weiß, warum abgelehnt wurde, wenn es nicht im Moment der Entscheidung festgehalten wird. „Prüfung übernehmen“ setzt den Ausführenden als Zuständigen. „Eskalieren“ setzt die Priorität auf kritisch und weist den Vorgang dem Kundenbetreuer zu. Bei kritischer Priorität verschickt ameax die Benachrichtigung an die Beteiligten sofort statt gebündelt. „Reklamation anerkennen“ steht nur zur Verfügung, wenn der Vorgang einem Kunden zugeordnet ist.

Die Statustypen sind mehr als eine Beschriftung. ameax kennt fünf Arten, und an ihnen hängen Auswertungen und Verhalten, etwa die Wiedereröffnung eines abgeschlossenen Tickets, wenn der Kunde noch einmal schreibt:

Schritt 4: Prüfen, bevor etwas eingespielt wird

Die erste Prüfung ist das JSON-Schema selbst. Ein Code-Knoten in n8n prüft das Dokument mit einer JSON-Schema-Bibliothek, sofern Ihre n8n-Installation externe Module zulässt, sonst übernimmt das ein kleiner Prüfdienst. Die zweite Prüfung betrifft Zusammenhänge, die ein Schema nicht ausdrücken kann:

// n8n Code-Knoten: inhaltliche Prüfung des Blueprints (vereinfacht)
const bp = $json.blueprint;
const fehler = [];
const titel = (bp.states || []).map(s => s.title.toLowerCase());
const defaults = (bp.states || []).filter(s => s.is_default).length;
if (defaults !== 1) fehler.push(`Genau ein Standardstatus erwartet, gefunden: ${defaults}`);
if ($('Vorhandene Kürzel').all().some(k => k.json.abbrev === bp.scheme.abbrev))
  fehler.push(`Kürzel ${bp.scheme.abbrev} ist bereits vergeben`);
for (const p of bp.proceedings || []) {
  if (p.target_state && !titel.includes(p.target_state.toLowerCase()))
    fehler.push(`${p.name}: Zielstatus fehlt`);
  for (const t of p.trigger_states || [])
    if (!titel.includes(t.toLowerCase())) fehler.push(`${p.name}: Auslösestatus ${t} fehlt`);
}
return { json: { ...$json, fehler } };

Diese Prüfung ist wichtig, weil die Schnittstelle Verweise auf unbekannte Status nicht als Fehler zurückweist, sondern den Verweis beim Einspielen einfach weglässt. Ein Button ohne Zielstatus fällt erst auf, wenn ihn jemand drückt. Findet der Code-Knoten Fehler, geht das Dokument mit der Fehlerliste zurück an das Sprachmodell, höchstens zwei- oder dreimal. Danach übernimmt ein Mensch.

Schritt 5: In der Testumgebung einspielen

Das geprüfte Dokument geht unverändert an die Testumgebung. Die Schnittstelle nimmt den Blueprint direkt oder eingepackt unter dem Schlüssel blueprint an:

POST https://test.ihrefirma.ameax.de/api/v2/task-schemes/blueprint
Authorization: Bearer <token-test>
Content-Type: application/json

{ "blueprint": { "meta": { ... }, "scheme": { ... }, "states": [ ... ], "proceedings": [ ... ] } }

Bei Erfolg antwortet ameax mit 201, liefert die angelegte Einrichtung als Blueprint zurück und nennt unter meta.scheme_id die neue ID. Ist das Kürzel bereits vergeben, kommt eine Validierungsmeldung mit dem Feld abbrev und dem Code duplicate, im Format application/problem+json. Diese Meldung kann n8n direkt an das Sprachmodell zurückgeben.

Schritt 6: Abnahme und Ergänzung in der Oberfläche

Jetzt ist ein Mensch dran. Er öffnet die neue Vorgangsart in der Testumgebung, legt einen Testvorgang an und drückt jeden Button einmal. Dabei ergänzt er, was der Blueprint bewusst nicht beschreibt. Der Blueprint enthält Status und Prozess-Buttons mit auslösenden Status, Zielstatus, Kommentarpflicht, Zuständigkeit und Priorität. Prozess-Buttons in ameax können aber mehr, etwa eine Nachricht an den Kunden senden, einen Beleg erstellen, eine Wiedervorlage oder einen Folge-Vorgang anlegen. Solche Aktionen richten Sie nach dem Einspielen in der Oberfläche ein, ebenso die Freigabe für das Kundenportal.

Einige Einstellungen der Vorgangsart selbst lassen sich auch ohne Oberfläche setzen: Die Ticket-Einstellungen, etwa der Textbaustein für die automatische Antwort auf eingehende Mails (ticket_textmodul_id), sind Felder der Ressource /task-schemes und lassen sich per PATCH /api/v2/task-schemes/{id} setzen, sobald der Textbaustein existiert.

Schritt 7: In die produktive Installation übertragen

Nach der Abnahme exportiert n8n die Vorgangsart aus der Testumgebung. Das Ergebnis enthält alle Ergänzungen, die im Blueprint-Format darstellbar sind, und einen Vermerk, wann und von wem exportiert wurde:

GET https://test.ihrefirma.ameax.de/api/v2/task-schemes/42/blueprint

POST https://ihrefirma.ameax.de/api/v2/task-schemes/blueprint
Authorization: Bearer <token-produktiv>
Content-Type: application/json

{ "blueprint": { ...Ergebnis des Exports... } }

Soll eine bestehende Vorgangsart geändert werden, geht der Blueprint an POST /api/v2/task-schemes/{id}/blueprint. ameax gleicht Status und Buttons dabei über ihren Namen ab, ohne auf Groß- und Kleinschreibung zu achten. Vorhandene Einträge mit gleichem Namen werden aktualisiert, neue angelegt. Mit ?delete_omitted_states=true werden Status entfernt, die im Blueprint fehlen, aber nur, wenn kein Vorgang sie verwendet. ?delete_omitted_proceedings=true entfernt fehlende Buttons. Einzelne Status legen Sie alternativ über POST /api/v2/task-schemes/{id}/states an oder löschen sie über DELETE /api/v2/task-schemes/{id}/states/{state_id}. Einen eigenen Endpunkt zum Ändern eines einzelnen Status gibt es nicht. Farbe, Typ oder Reihenfolge ändern Sie, indem Sie den Blueprint mit demselben Statusnamen erneut einspielen.

Was bei den anderen Bausteinen anders ist

Eine Reklamations-Einrichtung besteht selten nur aus einer Vorgangsart. Die Schritte 1 bis 7 sind am Beispiel einer Vorgangsart durchgespielt; für die übrigen Bausteine gilt derselbe Weg. Unterschiedlich ist vor allem eines: ob es für den Bereich einen Blueprint gibt oder ob einzelne Einträge angelegt werden.

Zusatzfelder

Zusatzfelder legen Sie einzeln unter /fields/{modtoken} an, wobei modtoken das Modul bezeichnet, etwa customer. Welche Module es gibt, nennt GET /api/v2/fields, einschließlich der Objektmodule Ihrer Installation. Welche Feldtypen ein Modul erlaubt, nennt GET /api/v2/fields/customer/types. Diese Abfrage gehört in den Prompt, denn die zulässigen Typen unterscheiden sich je Modul. Ein Unterschriftsfeld ist nicht überall erlaubt, und Formularfelder kennen deutlich weniger Typen als der Kunde.

POST https://test.ihrefirma.ameax.de/api/v2/fields/customer
Content-Type: application/json

{
  "label": "Letzte Reklamation am",
  "type": "date",
  "description": "Wird beim Anerkennen einer Reklamation gepflegt",
  "required": false
}

Pflicht sind label und type. Daneben nimmt die Schnittstelle unter anderem field (den technischen Namen), explainer, options, preset, purposeId für Auswahlfelder aus einer Werteliste sowie isFormula und formula für berechnete Felder an. Nach dem Anlegen erscheint das Feld in der OpenAPI-Spezifikation Ihrer Installation mit Bezeichnung und Feldnamen und ist damit für jeden weiteren Workflow sofort nutzbar.

Textvorlagen

Textvorlagen gehören in Kategorien. Zuerst legt der Workflow die Kategorie an, dann die Vorlagen. Das Feld modules der Kategorie bestimmt, wo sie verfügbar ist, etwa für Nachrichten:

POST https://test.ihrefirma.ameax.de/api/v2/text-module-categories
Content-Type: application/json

{"name": "Reklamation", "modules": "message"}

POST https://test.ihrefirma.ameax.de/api/v2/text-modules
Content-Type: application/json

{
  "category_id": 14,
  "name": "Reklamation Eingangsbestätigung",
  "subject": "Ihre Reklamation ist bei uns eingegangen",
  "message": "#anrede.sehrgeehrte#\n\nvielen Dank für Ihre Nachricht. Wir prüfen Ihre Reklamation und melden uns innerhalb von zwei Werktagen.",
  "is_html": false,
  "language": "de"
}

Zwei Dinge sind bei Textvorlagen zu beachten. Erstens gibt es kein PATCH, geändert wird mit PUT. Der Workflow liest die Vorlage also zuerst, ändert das Nötige und schickt sie vollständig zurück. Zweitens sollte das Sprachmodell nur Platzhalter verwenden, die in Ihren vorhandenen Vorlagen bereits vorkommen. Der Workflow holt dazu einige bestehende Vorlagen mit GET /api/v2/text-modules und gibt sie dem Modell als Muster mit. Wer Vorlagen lieber in der Oberfläche entwirft, nimmt den Textbaustein-Generator des KI-Assistenzsystems: Er fängt erfundene oder verlorene Platzhalter ab.

Kampagnen mit Status

Für eine Nachfassaktion nach anerkannten Reklamationen eignet sich eine Kampagne. Ihr Blueprint beschreibt die Kampagne und ihre Status, einschließlich Fortschritt, Endstatus und Wirkung für die Auswertung:

POST https://test.ihrefirma.ameax.de/api/v2/projects/blueprint
Content-Type: application/json

{
  "meta": {"document_type": "ameax_project_blueprint"},
  "project": {"name": "Nachfassen nach Reklamation", "active": true},
  "types": [
    {"name": "Offen", "progress": 0, "is_default": true, "effect": "neutral"},
    {"name": "Angerufen", "progress": 50, "effect": "neutral"},
    {"name": "Zufrieden", "progress": 100, "is_final": true, "effect": "positive", "color": "#27AE60"},
    {"name": "Unzufrieden", "progress": 100, "is_final": true, "effect": "negative",
     "color": "#E74C3C", "reason_mode": "optional"}
  ]
}

Das Schema dazu liefert GET /api/v2/projects/blueprint/schema, den Export einer bestehenden Kampagne GET /api/v2/projects/{id}/blueprint.

Objektarten mit Feldern und Wertelisten

Wer Reklamationen auf ein konkretes Gerät beziehen will, braucht eine Objektart, etwa „Maschine“. Ihr Blueprint ist der umfangreichste: Er beschreibt die Objektart, ihre Status, die Beziehungen zum Kunden mit eigenen Status, die Felder am Objekt und an der Kunde-Objekt-Beziehung und die Wertelisten, auf die Auswahlfelder verweisen:

POST https://test.ihrefirma.ameax.de/api/v2/object-types/blueprint
Content-Type: application/json

{
  "meta": {"document_type": "ameax_object_type_blueprint"},
  "object_type": {"name": "Maschine", "mode": "multi", "use_object_title": true},
  "states": [
    {"name": "In Betrieb", "is_active": true, "is_default": true},
    {"name": "Außer Betrieb", "is_active": false}
  ],
  "object_fields": [
    {"field": "o_seriennummer", "label": "Seriennummer", "type": "text50", "required": true, "sort_order": 10},
    {"field": "o_baujahr", "label": "Baujahr", "type": "integer", "sort_order": 20},
    {"field": "o_baureihe", "label": "Baureihe", "type": "dropdown", "sort_order": 30,
     "purpose_token": "maschine_baureihe"}
  ],
  "value_lists": [
    {"token": "maschine_baureihe", "name": "Baureihe",
     "properties": [{"name": "Serie A", "sort": 10}, {"name": "Serie B", "sort": 20}]}
  ]
}

Das Auswahlfeld verweist über purpose_token auf die Werteliste, nicht über eine ID. Beim Einspielen sucht ameax die Werteliste zuerst über das Token, dann über den Namen, und legt sie an, wenn es sie noch nicht gibt. Deshalb funktioniert derselbe Blueprint in jeder Installation, auch wenn die internen IDs dort ganz andere sind. Eigenständige Wertelisten haben zusätzlich einen eigenen Blueprint unter /purposes/blueprint.

Betreuergruppen und PLZ-Gebiete

Beim Aufbau einer neuen Vertriebsstruktur legt der Workflow Betreuergruppen als Baum an und ordnet ihnen PLZ-Gebiete zu. Im Modus topdown deckt ein PLZ-Präfix alle Postleitzahlen ab, die damit beginnen, im Modus fromtill gilt ein Bereich:

POST https://test.ihrefirma.ameax.de/api/v2/agents
Content-Type: application/json

{"name": "Region Süd", "parent_id": 0, "color": "#2E86C1"}

POST https://test.ihrefirma.ameax.de/api/v2/agent-territories
Content-Type: application/json

{"agent_id": 3, "country_code": "DE", "mode": "topdown", "postal_code": "8"}

Ob neue Kunden automatisch nach PLZ zugeordnet werden, hängt an einer Einstellung der Installation. Welche Gruppe welchen Bereich bekommt, pflegen Sie im Gebietsmanagement.

Einrichtung auf weitere Installationen übertragen

Richtig stark wird der Ansatz, wenn es mehr als eine Installation gibt: eine Unternehmensgruppe mit mehreren Gesellschaften, ein Franchise-System oder eine Agentur, die ameax für ihre Kunden einrichtet. Hier ist jede Einrichtung, die einmal durchdacht und abgenommen wurde, ein wiederverwendbarer Baustein.

Der Schlüssel dafür ist, dass Blueprints nicht mit internen IDs arbeiten. Prozess-Buttons verweisen auf Status über deren Titel, Auswahlfelder auf Wertelisten über deren Token. Der Export aus Installation A lässt sich deshalb ohne Umrechnung in Installation B einspielen. Anders ist es bei den einzeln angelegten Bausteinen: Eine Textvorlage verweist mit category_id auf eine Kategorie, deren ID in jeder Installation eine andere ist. Der Workflow sucht die Kategorie in der Zielinstallation deshalb über ihren Namen und setzt die dortige ID ein.

In der Praxis bewährt sich eine einfache Ordnung:

• Eine Referenz-Installation hält die abgenommene Standard-Einrichtung. Änderungen daran laufen immer über die Testumgebung.
• Exportierte Blueprints werden versioniert abgelegt, etwa in einem Git-Repository oder einem Dokumentenspeicher. Jeder Export trägt Zeitpunkt und exportierenden Benutzer, und ein Vergleich zweier Stände zeigt genau, was sich geändert hat.
• Je Zielinstallation ein eigener technischer Benutzer und ein eigenes Token. Ein Token, das in allen Installationen gilt, gibt es nicht, und das ist gut so.
• Abweichungen sind erlaubt, aber sichtbar. Braucht ein Mandant einen zusätzlichen Status, bekommt er ihn. Der wöchentliche Vergleichslauf meldet die Abweichung, und ein Mensch entscheidet, ob sie in die Referenz übernommen wird.

Für Agenturen verändert das die Arbeit spürbar. Statt jede Einrichtung neu zu klicken, entsteht ein Baukasten aus geprüften Blueprints: eine Vorgangsart für Reklamationen, eine für Serviceaufträge, eine Kampagne für Messen, eine Objektart für Anlagen. Das Sprachmodell passt einen Baustein an die Besonderheiten des Kunden an, und die Prüfung gegen das Schema stellt sicher, dass das Ergebnis einspielbar ist.

Was in ameax sichtbar wird

Eine per Schnittstelle eingespielte Einrichtung ist von einer von Hand angelegten nicht zu unterscheiden. Sie erscheint an denselben Stellen und verhält sich genauso.

• Im Aufgabenmanagement: die neue Vorgangsart mit Farbe, Kürzel, eigenem Nummernkreis, ihren Status und den Prozess-Buttons, die nur in den passenden Status erscheinen.
• In den Einstellungen: Zusatzfelder am Kunden oder an anderen Objekten, Textvorlagen in ihrer Kategorie, Kampagnen mit ihren Status, Objektarten mit Feldern und Wertelisten, Betreuergruppen mit ihren PLZ-Gebieten. Alles lässt sich dort wie gewohnt nachbearbeiten.
• In der Arbeit des Teams: Die Status-Historie jedes Vorgangs, die Kommentare an Statuswechseln mit Kommentarpflicht und die Kampagnenstatus am Kunden entstehen ab dem ersten Tag, weil die Einrichtung vollständig ist.
• In der OpenAPI-Spezifikation: neue Zusatzfelder mit Bezeichnung und Feldnamen, sodass weitere Workflows wie die automatisierte Datenqualität oder die Ticket-Einordnung sie sofort nutzen können.

Best Practices und Stolperstellen

• Das Schema ist die Wahrheit, nicht das Modell. Jedes Dokument wird vor dem Einspielen gegen das JSON-Schema aus …/blueprint/schema geprüft. Holen Sie das Schema bei jedem Lauf frisch aus der Installation, gegen die Sie einspielen, dann prüfen Sie immer gegen deren Stand.
• Nie direkt in die Produktion. Was das Sprachmodell erzeugt, geht in die Testumgebung. In die Produktion geht nur der Export der abgenommenen Fassung. So ist sichergestellt, dass produktiv genau das ankommt, was jemand gesehen hat.
• Namen sind Schlüssel. Beim Aktualisieren gleicht ameax Status und Buttons über ihren Namen ab. Wer einen Status im Blueprint umbenennt, bekommt einen neuen Status zusätzlich zum alten. Umbenennungen deshalb bewusst vornehmen und den alten Status danach gezielt entfernen.
• Löschen ist vorsichtig gebaut. delete_omitted_states entfernt nur Status, die kein Vorgang verwendet. Ein Status, an dem noch Vorgänge hängen, bleibt stehen. Prüfen Sie nach einem Lauf mit Löschoption, ob das Ergebnis Ihren Erwartungen entspricht.
• Kürzel früh festlegen. Das Kürzel einer Vorgangsart hat höchstens drei Zeichen, muss eindeutig sein und steckt in der Vorgangsnummer. Lassen Sie es das Sprachmodell vorschlagen, aber gegen die Liste der vorhandenen Kürzel prüfen.
• Verwaltungsrechte eng halten. Der technische Benutzer für die Einrichtung braucht weitreichende Rechte, aber nur in den Bereichen, die er einrichtet. Ein kurzes Ablaufdatum und eine IP-Liste für das Token begrenzen das Risiko zusätzlich.
• Die Grenzen des Blueprints kennen. Aktionen von Prozess-Buttons jenseits von Status, Zuständigkeit, Priorität und Kommentarpflicht, die Freigabe für das Kundenportal, Artikel und Rollen richten Sie in der Oberfläche ein. Planen Sie diesen Teil in der Abnahme ein, statt ihn zu vergessen.
• Rückfragen ernst nehmen. Ein Sprachmodell, das bei einer unklaren Anforderung rät, erzeugt eine plausible, aber falsche Einrichtung. Das Feld rueckfragen im Ausgabeformat gibt ihm einen Ort für Zweifel, und der Workflow stoppt, wenn es nicht leer ist.

Fazit

Die Einrichtung eines Systems ist Wissensarbeit, die in Klickarbeit steckenbleibt. ameax macht einen großen Teil dieser Einrichtung über die Schnittstelle zugänglich, und die umfangreichen Bereiche lassen sich als Blueprint mit eigenem JSON-Schema beschreiben. Damit wird das Sprachmodell zum Werkzeug, das Anforderungen in ein prüfbares Dokument übersetzt, n8n zum Taktgeber für Prüfung, Test und Übertragung und der Mensch zur Abnahme, die über die Produktion entscheidet. Wer mehrere Installationen betreut, gewinnt am meisten: Eine einmal abgenommene Einrichtung wird exportiert, versioniert und überall dort eingespielt, wo sie gebraucht wird.