In dieser Dokumentation werden die Grundlagen der audioXchange-Plattform und deren technischen Umsetzung beschrieben.

Kurzeinstieg in die Buchungsprozesse der audioXchange-Plattform

Dieses Dokument soll einen kompakten Einstieg in die Buchungsprozesse der audioXchange-Plattform geben. Insbesondere soll hier das Zusammenspiel zwischen der Agentur, bei audioXchange meist als Buyer bezeichnet, und dem Vermarkter, dem Seller, veranschaulicht werden.

Die Informationen hier sind stark komprimiert. Es handelt sich hierbei nicht um eine Referenz-Dokumentation. Detailliertere Informationen finden sich auf der audioXchange-Homepage und im Playground.

Hier geht es darum, ein Grundverständnis für die Arbeitsweise von audioXchange zu schaffen und die Einordnung, an welchen Stellen man bei einer Anbindung an audioXchange selbst tätig werden muss, zu ermöglichen.

Stark vereinfachtes Objektmodell der audioXchange-Plattform:

Hierarchie

Campaign bildet die Werbekampagne einer Agentur ab. Eine Kampagne bezieht sich auf einen Werbetreibenden.

Ein CampaignElement dient der Organisation der Werbekampagne. Hier muss das zu bewerbende Produkt des Werbetreibenden und ein Zeitraum hinterlegt werden. Eine Werbekampagne kann damit nach den Wünschen der Agentur aufgeteilt werden. Es muss mindestens ein CampaignElement geben.

Der Plan wird meist mit einem Planungstool wie audioXpert erstellt.

Für jeden im Plan berücksichtigten Vermarkter gibt es ein PlanElement. Somit ist gewährleistet, dass jeder Vermarkter nur die ihn betreffenden Daten einsehen kann.

Für jedes zu belegende Vermarkterprodukt wird ein RequestStream erstellt.

Ein Request stellt jeweils einen der nachfolgend beschriebenen Buchungsprozesse dar und enthält mindestens einen RequestSpot. Dabei handelt es sich um die zu buchenden Termine in Form von Belegungsplan- oder Streuplanspots.

Der Vermarkter beantwortet den an ihn gerichteten Request mit einer Answer.

Diese enthält dann die zu den RequestSpots korrespondierenden AnswerSpots als Streuplan.

Einführung in die verschiedenen Prozesse

  • [A] Vorarbeiten auf Seiten der Agentur:
    1. Campaign und CampaignElement anlegen
  • [B] Der Planungsprozess auf Seiten der Agentur:
    1. Plan und Planelement anlegen
    2. RequestStream anlegen
    3. Request erstellen
    4. Planung ggf. nochmals bearbeiten
  • [C] Der Einkaufsprozess zwischen Agentur und Vermarkter:
    1. Agentur-Einkäufer bearbeitet Request
    2. Agentur-Einkäufer gibt den Request für den Vermarkter frei
    3. Vermarkter ruft Request ab
    4. Vermarkter erstellt Answer
    5. Vermarkter gibt die Answer für die Agentur frei
    6. Agentur ruft den Request mit der Answer ab
  • [D] Zusätzliche Schritte beim Angebotshandling:
    1. Agentur nimmt die letzte Answer an, hat Änderungswünsche oder verwirft endgültig
    2. Vermarkter reagiert auf die Reaktion der Agentur

Einfacher Buchungsprozess (Bereich C)

Im einfachsten Fall gehen wir davon aus, dass die Agentur (Buyer) mindestens einen Termin bei einem Vermarkter (Seller) plant und bestellt. Der Seller nimmt die Bestellung entgegen und bestätigt dem Buyer die Annahme. Der Buyer bestätigt seinerseits, der Seller schließt den Prozess durch seine Kenntnisnahme ab.

  • [C.1] Objekttechnisch bedeutet das, dass der Buyer einen RequestStream für den Seller und dessen SellerProduct (einzukaufendes Vermarkterprodukt, z.B. ‘RMS Superkombi’) angelegt hat. Jeder RequestStream bezieht sich immer auf genau ein SellerProduct. Innerhalb des RequestStreams liegt dann der Request mit den RequestSpots. Über den progressState des Request wird die Verarbeitung gesteuert. Insbesondere wird darüber festgelegt, ob der Buyer oder der Seller den Prozess bearbeiten kann. Der RequestSpot steht für einen oder mehrere zu buchende Termine. Er kann sowohl für einen Belegungsplan-Termin als auch für einen Streuplan-Termin stehen, erkennbar an der gewünschten Anzahl zu buchender Termine in Verbindung mit dem Buchungszeitraum.
  • [C.2] Hat der Einkäufer seine Arbeiten abgeschlossen, wird der progressState des Request auf den Wert BUYER_COMMIT geändert. Damit wird dieser Request für den Seller sichtbar.
  • [C.3] Der Seller sollte periodisch die Plattform nach zu bearbeitenden Requests abfragen. Eine passende GraphQL-Query stellt die audioXchange natürlich zur Verfügung.

Warning Bitte beachten
WICHTIG: Bereits beim Ausführen der Query zum Einlesen des Requests ändert die audioXchange-Plattform automatisch den progressState von BUYER_COMMIT auf SELLER_IN_WORK. Ab diesem Zeitpunkt ist der Request exklusiv im Zugriff des Sellers!

Der Seller wird nun in seinem hauseigenen Dispositionssystem die Anfrage bearbeiten und, damit das Beispiel einfach bleibt, den gewünschten Termin einbuchen.

  • [C.4] Der Request wird mit einer Answer mit dem state CONFIRMED bestätigt, die wiederum einen AnswerSpot enthält, der den konkret gebuchten Termin darstellt. Die Daten des Request können vom Seller, bis auf den progressState, nicht verändert werden.

Warning Bitte beachten
WICHTIG: AnswerSpot und RequestSpot verfügen beide über die Attribute dspKey und sspKey. Es wird dringend empfohlen, im Attribut sspKey des AnswerSpot die interne ID des korrespondierenden gebuchten Termins des Seller-Disposystems zu hinterlegen. Bei später folgenden Requests zur weiteren Bearbeitung des Terminbestands (Umbuchungen, Stornierungen) wird der RequestSpot auf den vom Seller gelieferten sspKey Bezug nehmen und somit eine eindeutige Identifizierung der Termine ermöglichen. Das Attribut dspKey kann die interne ID des Termins im Agentursystem enthalten und sollte, wenn mit dem RequestSpot geliefert, in den AnswerSpots auch wieder rückgeliefert werden.

  • [C.5] Der progressState des Requests wird auf den Wert SELLER_COMMIT gesetzt. Damit signalisiert der Seller, dass er seine Arbeiten abgeschlossen hat und der Buyer bekommt wieder Zugriff.
  • [C.6] Der Buyer kann nun das gelieferte Ergebnis überprüfen (Soll-Ist-Vergleich). Er könnte dabei den progressState des Request auf BUYER_IN_WORK setzen. In diesem Beispiel ist alles wunschgemäß erledigt worden - daher endet dieser Prozess hier.

Angenommen, es wäre nicht alles wunschgemäß gelaufen…?

In diesem Fall würde der Buyer im gleichen RequestStream einen neuen Request erstellen. Er würde dort die nicht passenden Termine umbuchen (s.u.) oder alle Termine stornieren (s.u.) und erneut anfordern. Im letzteren Fall wäre ein Hinweis an den Seller im Kommentarfeld (s.u.) hilfreich, was denn beim nächsten Versuch verbessert werden sollte.

Exkurs zur Übertragung der Spots

Der Prozess sieht vor, dass bei Änderungen am Terminbestand immer alle bisherigen Spots zu einem RequestStream mitgeliefert werden. Man erhält also recht einfach den aktuellen Terminbestand eines RequestStreams, indem man sich die AnswerSpots der letzten Answer betrachtet.

Bei Zubuchungen, Umbuchungen und Stornierungen werden vom Buyer alle bisher vorhandenen Spots als RequestSpots geliefert. Im Attribut action des RequestSpots ist definiert, was mit dem Spot zu tun ist. Beispielsweise steht ADDITIONAL für „Zubuchung“, KEEP für „unverändert beibehalten“ und CANCEL für „stornieren“. Die vollständige Aktionsliste findet man in der Doku im Playground.

Der Seller antwortet auf jede Aktion immer mit einer Answer inklusive aller bisher vorhandenen Spots als AnswerSpots.

In einem Request können verschiedene Aktionen für die Termine enthalten sein. Es ist also erlaubt, mit einem Request Zubuchungen, Stornierungen und Terminänderungen anzufordern.

Anfordern und Annehmen eines Angebots (Bereiche C und D)

Das Vorgehen ist mit dem bereits beschriebenen einfachen Buchungsprozess über weite Strecken nahezu identisch. Der Buyer muss im Angebotsfall im Request das Attribut createOfferOnly auf den Wert TRUE setzen.

Der Seller wiederum wird in seiner Answer das Attribut state auf den Wert IS_OFFER setzen, um die Answer als Angebot zu kennzeichnen. In offerValidUntil ist angegeben, bis wann das Angebot gültig sein wird. In offerHandlingAfterValidity teilt der Seller mit, was mit den angebotenen Terminen nach Ablauf der Gültigkeit des Angebots passieren wird.

Der Ablauf entspricht den im einfachen Buchungsprozess unter [C.1] bis [C.6] beschriebenen Schritten - allerdings ist der Prozess mit [C.6] noch nicht beendet. So geht es weiter:

  • [D.1] In unserem einfachen Beispiel nimmt der Buyer das Angebot des Sellers an. Wenn noch nicht geschehen, setzt er zunächst den progressState auf BUYER_IN_WORK. Dann packt er die vom Seller gelieferte Answer in das Attribut acceptingOfferFromAnswer und setzt progressState auf BUYER_COMMIT. Anmerkung: Es gibt noch die Attribute rejectingOfferFromAnswer und requestingAlternativeToAnswer, und der geneigte Leser sollte jetzt schon eine ungefähre Ahnung entwickelt haben, wozu diese dienen.
  • [D.2] Der Seller liest den Request ein. Der progressState wird automatisch auf SELLER_IN_WORK geändert. Der Seller hat nun in seinem Disposystem etwas Arbeit vor sich. Im Fall der Annahme des Angebots müssen aus den Reservierungen „echte“ Auftragstermine erstellt werden. Zum Abschluss des Prozesses gibt es vom Seller dann wieder eine Answer mit dem kompletten Satz an AnswerSpots. Der progressState wird auf SELLER_COMMIT gesetzt.

Einfacher Stornoprozess (Bereiche C und D)

In diesem Fall storniert der Buyer einen der Termine, die im Beispiel „Einfacher Buchungsprozess“ disponiert wurden. Der Seller wird den Stornowunsch akzeptieren. Der Buyer schaut sich das Ergebnis an und der Seller schließt den Prozess ab.

  • [C.1] Der Buyer erstellt im bereits bestehenden RequestStream einen neuen Request. Dem Request werden alle bestehenden Termine als RequestSpots mitgegeben. Der zu stornierende RequestSpot erhält als action den Wert CANCEL, alle übrigen RequestSpots erhalten als action den Wert KEEP.
  • [C.2] Der Buyer setzt den progressState des Request auf den Wert BUYER_COMMIT. Damit wird dieser Request für den Seller sichtbar.
  • [C.3] Der Seller fragt periodisch die Plattform nach zu bearbeitenden Requests ab. Beim Einlesen des Requests ändert audioXchange den progressState des Request automatisch auf SELLER_IN_WORK. Der Seller wird nun in seinem hauseigenen Dispositionssystem die Anfrage bearbeiten und den gewünschten Termin stornieren.
  • [C.4] Der Request wird mit einer Answer mit dem state CONFIRMED bestätigt. Diese enthält alle jetzt noch vorhandenen Termine als AnswerSpots. Der gerade stornierte Termin ist in der Liste der AnswerSpots jetzt nicht mehr enthalten. Sollten durch diese Aktion alle Termine storniert worden sein, so ist die Answer „leer“, enthält also keine AnswerSpots mehr.
  • [C.5] Der progressState des Requests wird auf den Wert SELLER_COMMIT gesetzt. Damit signalisiert der Seller, dass er seine Arbeiten abgeschlossen hat und der Buyer bekommt wieder Zugriff.
  • [C.6] Der Buyer kann nun das gelieferte Ergebnis überprüfen (Soll-Ist-Vergleich). Er könnte dabei den progressState des Request auf BUYER_IN_WORK setzen. In diesem Beispiel ist alles wunschgemäß erledigt worden - daher endet dieser Prozess hier.

Einfacher Umbuchungsprozess (Bereiche C und D)

In diesem Fall ändert der Buyer einen der Termine, die im Beispiel „Einfacher Buchungsprozess“ disponiert wurden. Was geändert wurde, ist für das Beispiel egal. Der Seller wird die Umbuchung akzeptieren. Der Buyer schaut sich das Ergebnis an und der Seller schließt den Prozess ab.

  • [C.1] Der Buyer erstellt im bereits bestehenden RequestStream einen neuen Request. Dem Request werden alle bestehenden Termine als RequestSpots mitgegeben. Der umzubuchende RequestSpot erhält die gewünschten Änderungen und als action den Wert CHANGE_DETAILS, alle übrigen RequestSpots erhalten als action den Wert KEEP.
  • [C.2] Der Buyer setzt den progressState des Request auf den Wert BUYER_COMMIT. Damit wird dieser Request für den Seller sichtbar.
  • [C.3] Der Seller fragt periodisch die Plattform nach zu bearbeitenden Requests ab. Beim Einlesen des Requests ändert audioXchange den progressState des Request automatisch auf SELLER_IN_WORK. Der Seller wird nun in seinem hauseigenen Dispositionssystem die Anfrage bearbeiten und die gewünschte Änderung vornehmen. Wie diese Änderung umgesetzt wird, bleibt dem Disposystem des Sellers überlassen. Es wäre also möglich, dass der Seller den bestehenden Termin verändert oder aber den bestehenden Termin storniert und durch einen neu gebuchten Termin ersetzt. Als Buyer könnte man nur an einem möglicherweise geänderten sspKey erkennen, welche Variante zum Einsatz kam.
  • [C.4] Der Request wird mit einer Answer mit dem state CONFIRMED bestätigt. Diese enthält alle vorhandenen Termine als AnswerSpots.
  • [C.5] Der progressState des Requests wird auf den Wert SELLER_COMMIT gesetzt. Damit signalisiert der Seller, dass er seine Arbeiten abgeschlossen hat und der Buyer bekommt wieder Zugriff.
  • [C.6] Der Buyer kann nun das gelieferte Ergebnis überprüfen (Soll-Ist-Vergleich). Er könnte dabei den progressState des Request auf BUYER_IN_WORK setzen. In diesem Beispiel ist alles wunschgemäß erledigt worden - daher endet dieser Prozess hier.

Was tun, wenn’s klemmt?

Es gibt an vielen audioXchange-Objekten das Attribut comment, insbesondere auch an den Objekten Answer, AnswerSpot, Request und RequestSpot. So kann an passender Stelle immer ein Hinweis für „die andere Seite“ hinterlassen werden und Abweichungen vom Kundenwunsch können erklärt werden.

Bei gravierenden Abweichungen zur Anforderung sollte der state in der Answer auf den Wert IS_ALTERNATIVE_OFFER gesetzt werden. Damit wird die Answer eindeutig als Alternative zur ursprünglichen Bestellung gekennzeichnet und als Angebot betrachtet, welches der Buyer dann explizit annehmen muss.

Wenn sich ein Request überhaupt nicht sinnvoll umsetzen lässt, wird mit einer Answer mit dem state REJECTED geantwortet. Gründe für eine Ablehnung könnten zum Beispiel sein, dass die Stornofrist bereits abgelaufen wäre oder für eine Zubuchung keine Kapazität mehr verfügbar sei. Einige Standard-Ablehnungsgründe können über reason geliefert werden.