Anlegen und Ändern von Anzeigen und Aufträgen

Anzeigen und Aufträge können angelegt und geändert werden. Änderungen werden dabei bei Anzeigen mit bestimmter Bedingung in PRINT NGEN abgefragt und gespeichert. Zusätzlich werden Buchungsdaten abgefragt und der Produktionsstatus kann zurückgegeben werden.

Funktionalitäten des Anlegens und Änderns von Anzeigen und Aufträgen

Abfrage von Buchungsdaten
Vergleich von Anzeigen
Aktualisierung des Anzeigenmotivs

Inhaltsverzeichnis

Abfrage geänderter Anzeigen

Änderungen an einem Auftrag oder an Anzeigen werden als Event in der Tabelle “dauftrag_changed_event” gespeichert. Zudem werden produktionsrelevante Änderungen an Anzeigen mit der Eigenschaft “DAnzProduktionsArt=api” in der Tabelle “dauftrag_production_event” gespeichert. Jedes Event erhält eine fortlaufende ChangeID und wird zusammen mit der CID (= Cluster ID) des “DAuftrag” gespeichert. Bei den Abfragen werden nur Anzeigen berücksichtigt, die die Bedingung “DAnzeigeZugeladen!=ja” erfüllen.

In der Tabelle “dauftrag_changed_event” werden auch Änderungen an Beilagen und den übergeordneten Aufträgen gespeichert. Zur Unterscheidung von Anzeigen- und Beilagen-Events wird der Auftragstyp (“AN” = Anzeige, “BE” = Beilage) an jedem Event in der Tabelle gespeichert.

Bei der Abfrage geänderter Anzeigen werden nur Events mit Auftragstyp “AN” berücksichtigt.

Aufruf: {{baseURL}}/adapi/v1/ads/events

Parameter

Vorhandene Parameter

eventName: Entscheidet über die Art der Abfrage. Folgende Werte sind möglich:
- changed: Alle Änderungen an Aufträgen und Anzeigen werden berücksichtigt
- production: Nur produktionsrelevante Änderungen an Anzeigen mit “DAnzProduktionsArt=api” werden berücksichtigt
offset: Gibt die letzte “ChangeID” an. Alle nachfolgenden “ChangeIDs” in der Tabelle “dauftrag_production_event” werden beim nächsten Aufruf berücksichtigt. Zurückgegeben wird die im Aufruf höchste berücksichtigte “ChangeID”. Der Wert ist beim ersten Aufruf leer. Bei weiteren Aufrufen wird der Wert des jeweils vorherigen Aufrufs zurückgegeben.
limit: Gibt an, wie viele Datensätze bei jedem Aufruf ausgegeben werden sollen.

Token-Variable unter “Authorization” eintragen:

Reiter “Authorization”

Rückgabewerte

offset: Die im Aufruf höchste berücksichtigte “ChangeID”.
data: Auftrags- und Anzeigen.-Nummern ab dem angegebenen offset. Es werden maximal so viele Datensätze ausgegeben, wie im Limit definiert sind.

Mit den bei “/ads/events” erhaltenen Nummern können die Daten der zugehörigen Elemente abgefragt werden.

Mögliche Ausnahmeregelungen bei Aufträgen

Events bei bestimmten Aufträgen verhindern

Es ist möglich, Ausnahmen zu definieren, bei welchen bestimmte Angaben an Aufträgen nicht zur Speicherung eines Events führen.

Beispiel:

Es ist möglich, es so einzurichten, dass für Aufträge der Verrechnungsarten “NurZurVerrechnung” und “AuftraggeberGutschrift” kein Event gespeichert wird. Anzeigen von Aufträgen dieser Verrechnungsarten werden somit nicht übertragen.

Zu beachten ist dabei, dass erst nach Auswahl dieser Verrechnungsart keine Events mehr erzeugt werden. Wird der Auftrag ohne Angabe der Verrechnungsart angelegt, wird ein Event gespeichert und Änderungen an den Anzeigen von externen Systemen als solche erkannt. Wird nachträglich die Verrechnungsart “NurZurVerrechnung” oder “AuftraggeberGutschrift” gewählt, wird diese Änderung nicht übertragen, da ab diesem Zeitpunkt aufgrund der Ausnahmeregelung keine Events mehr gespeichert werden.

Production-Events bei Statusänderungen

Production-Events werden bei produktionsrelevanten Änderungen an einer Anzeige erzeugt. Einige Statuswechsel an einem Auftrag führen nicht zu produktionsrelevanten Änderungen an Anzeigen. Der Auftrags-Statuswechsel selbst ist jedoch als produktionsrelevant einzuordnen. Zum Beispiel der Wechsel von “AngebotMitMotiv” zu “Buchung”. Diese Statuswechsel erzeugen Production-Events für den Auftrag. Das sind folgende Status-Wechsel:

	Erfassung	PreisPrüfung	Buchung	BuchhaltungPrüfen	Fakturierungsstop	Fakturiert	Storniert	Gestoppt	AngebotMitMotiv	AngebotOhneMotiv

	Erfassung	PreisPrüfung	Buchung	BuchhaltungPrüfen	Fakturierungsstop	Fakturiert	Storniert	Gestoppt	AngebotMitMotiv	AngebotOhneMotiv
Erfassung		-	X	-	-	-	X	X	X	-
PreisPrüfung	X		X	-	-	-	X	-	X	-
Buchung	X	-		-	-	-	X	X	X	-
BuchhaltungPrüfen	X	-	X		-	-	X	X	X	-
Fakturierungsstop	-	-	-	-		-	X	-	-	-
Fakturiert	-	-	-	-	-		X	-	-	-
Storniert	X	-	X	-	-	-		-	X	-
Gestoppt	X	-	X	-	-	-	X		X	-
AngebotMitMotiv	X	-	X	-	-	-	X	X		-
AngebotOhneMotiv	X	-	X	-	-	-	X	-	X

Buchungsdaten

Abfrage Auftragsdaten

get {{baseURL}}/adapi/v1/orders/{{Auftragsnummer}}

Abfrage Anzeigendaten

get {{baseURL}}/adapi/v1/ads/{{Anzeigennummer}}

Beim Abrufen von Anzeigen wird einschränkend mit der Bedingung “DAnzeigeZugeladen!=ja” gesucht. Nur mit dieser Zusatzbedingung ist die Suche eindeutig, denn durch die Funktion “AnzeigenZuladen” kann es mehrere Anzeigen mit derselben Anzeigennummer geben.

Rückmeldung Produktionsstatus

put {{baseURL}}/adapi/v1/ads/{{Anzeigennummer}}

Unmittelbar nach dem Abholen der Anzeigendaten über die API liefert die technische Anzeigenproduktion den beim Abrufen zuletzt erhaltenen Timestamp (production_timestamp) im Feld “production_status_timestamp” als Quittierung sowie den Produktionsstatus (“production_status”) und eine optionale textuelle Info (“production_info”) zurück.

Beispiel:

{
"production_status": "Gestaltet",
"production_status_timestamp": "2022-06-07T07:35:00+01:00",
"production_note": "Wie gewünscht dezente Farben verwendet."
}

Prüfungen

Motivprüfung

Bei jedem put oder post einer Anzeige wird in der Abbildung “AdAPISettings” die dem Eintrag “MotivPrüfen” zugeordnete Suchbedingung durchlaufen, die feststellt, ob die Anzeigenprüfung durchzuführen ist. (Rückgabewert 2). Ist die Bedingung erfüllt, wird die in Rückgabewert 1 angegebene komplexe Aktion ausgeführt. In dieser komplexen Aktion ist das ActiveX#AnzeigenImport aufzurufen, damit der Anzeigenvergleich ausgeführt oder das Motiv verworfen und die Anzeige in den Status “Geplant” zurückgesetzt wird.

Suchbedingung kann sein: Produktionsstatus=Fertig & Status=(Fertig,Fehler). In der Suchbedingung werden nur Eigenschaften der Anzeige ausgewertet (unabhängig vom Auftrag). So ist ausgeschlossen, dass eine Änderung am Auftrag eine Prüfung der Motive mit Rückmeldung in Richtung Anzeigenproduktion erfordert.

Prüfung Timestamp

Bei jedem put oder post einer Anzeige wird in der Abbildung “AdAPISettings” die dem Eintrag “TimestampPrüfen” zugeordnete Suchbedingung durchlaufen, die feststellt, ob die Prüfung des Timestamps durchzuführen ist. Ist die Suchbedingung erfüllt, wird geprüft, ob der übergebene Timestamp dem zuletzt gespeicherten Event in der Tabelle “dauftrag_production_event” entspricht.

Andernfalls ist davon auszugehen, dass nicht mit dem aktuellen Stand der Daten gearbeitet wurde und die Anzeige sollte noch einmal aktualisiert übergeben werden.

Rückmeldungen

Falls mindestens eine Prüfung zum Fehler führt, gibt es im Response Body des post- oder put-Requests die "validations"-Property, bei der nur die Properties enthalten sind, bei denen ein Fehler auftrat. Der Inhalt der Property ist jeweils eine entsprechende Fehlermeldung.

Beispiel:

{
"validations": {
"colors": "verschieden",
"width": "zu schmal",
"height": "zu hoch",
"production_timestamp": "The production_status_timestamp does not correspond to the current version of the ad."
}
}

Motivdaten

Anzeigenmotiv abrufen

Aufrufe:

get {{baseURL}}/adapi/v1/ads/images/10009404-1/HighRes

get {{baseURL}}/adapi/v1/ads/images/10009104-1/Thumbnail

Anzeigenmotiv aktualisieren

Aufruf:

put {{baseURL}}/adapi/v1/ads/images/10009404-1?filename=Test1.pdf

Motivaktualisierungen werden immer nur an Anzeigen ausgeführt, die die Bedingung “DAnzeigeZugeladen!=ja” erfüllen. Gibt es zugeladene Anzeigen mit derselben Anzeigennummer, so sind diese im Rahmen des Anzeigenvergleichs im Workflow zu aktualisieren.

Übernahme der Motivhöhe als gebuchte Höhe der Anzeige

Beim Motivupdate wird die Abbildung “Änderungen#DAnzeige#AdAPIMotiv” aufgerufen. Hier können Eigenschaften der zu aktualisierenden Anzeige geändert werden.

Mit der Zeile

="DAnzGroesseFest=nein" {"DAnzeigeHoeheGebucht=$(BildHoehe)", "DAnzHoeheGebWert=$(BildHoehe)"}

wird erreicht, dass bei Anzeigen, deren Höhe nicht fixiert ist, die Höhe des angelieferten Motivs als neue gebuchte Anzeige zur Höhe übernommen wird. Somit passen bei einer darauffolgenden Motivprüfung Motiv und Buchungsdaten zusammen.

Bildausschnitt und Bildbeschnitt

Beim Motivupdate werden Bildausschnitt und Bildbeschnitt gemäß Endformatrahmen und Beschnittrahmen der PDF-Datei ermittelt, sofern im Benutzerkontext des NWAs in der Gruppe “Bilder” “BeschnittSetzen=ja" eingestellt ist.

Farbplan

Bei Update eines Motivs wird der Farbplan der Anzeige entsprechend dem überstellten PDF angepasst.

Anzeigenvergleich

Bei Übertragung des Anzeigenmotivs wird die Abbildung “AdAPISettings” aufgerufen. Dort können folgende Parameter definiert werden:

MaxUploadFileSize: Maximal zulässige Größe einer hochzuladenden Datei, Standard ist "104857600".
AktionNachMotivUpdate: Komplexe Aktion, die im Anschluss an die Motivübertragung aufgerufen werden soll. Dies ist die komplexe Aktion “AdAPI_Motiv_Prüfen”.

In der komplexen Aktion “AdAPI_Motiv_Prüfen” findet der Anzeigenvergleich statt. Es werden Größen und Farben überprüft. Passt das überstellte Motiv zu den Buchungsdaten der Anzeige, erhält die Anzeige den im Variablenkontext festgelegten “OK”-Status. Andernfalls erhält die Anzeige den Status “Fehler” und in “DAnzeigeFehlerInfo” werden die Fehler vermerkt. Zusätzlich wird in der komplexen Aktion nach Anzeigen mit derselben Anzeigennummer und “DAnzeigeZugeladen=ja” gesucht und es werden die Bilddaten sowie der Status der Original-Anzeigen zu den zugeladenen Anzeigen übernommen. Damit wird sichergestellt, dass Motivupdates bei allen Anzeigen mit der angegebenen Anzeigennummer ausgeführt werden.

Aufträge

Ändern von Aufträgen: put orders

Falls der Auftrag in einem Status gespeichert werden soll, der nicht mindestens gebucht ist (FestdefinierteWerte "DAuftrag", "Status", "AtLeastBooked")
wird geprüft, ob dies “OK” ist: Es darf keine Leistung verrechnet sein, auch beim Hauptauftrag darf keine Leistung verrechnet sein. Außerdem darf keine Anzeige einen Anstrich haben.

Wird versucht, einen Auftrag, der sich z. B. im Status “fakturiert” befindet (mit fakturierten Leistungen), über die Schnittstelle in den Status Erfassung zurückzustufen, erscheint eine Fehlermeldung:

{
    "error": "Order status 'Erfassung' is not allowed: At least one benefit is already invoiced."
}

In der Abbildung “BuchungLoeschen” wird definiert, in welchen Statusstufen eines Auftrags die zugehörigen Anzeigen ohne Buchungen gespeichert werden (z. B. Status “Erfassung”). Wird ein Auftrag in eine dieser Statusstufen gestuft, werden die Buchungen an den Anzeigen gelöscht. Die Erscheinungsweise ist weiterhin gespeichert, sodass beim erneuten Stufen in einen planungsrelevanten Auftragsstatus die Buchungen an den Anzeigen wiederhergestellt werden können.

Aktualisieren von Abschlüssen

Beim Hinzufügen/Entfernen von Abschüssen zu einem Auftrag muss der Abschluss aktuell gehalten werden, d. h. der Erfüllungsgrad wird neu berechnet.

Bei put und post einer Anzeige oder eines Auftrags wird möglicherweise die Preisberechnung durchgeführt, wodurch auch Abschlüsse ausgecheckt und verändert werden. Möglicherweise werden auch Abschlüsse vom Auftrag entfernt.

Um die korrekte Aktualisierung von Abschlüssen zu gewährleisten, müssen am Anfang des Prozesses mögliche Elemente gemerkt werden, die evtl. während der Verarbeitung des Requests ausgecheckt werden. Zusätzlich müssen auch Elemente gemerkt werden, die während der Verarbeitung des Requests neu in die Referenzen geschrieben wurden. Am Ende werden alle gemerkten Elemente eingecheckt, sofern das noch nicht der Fall ist und Abschlüsse neu berechnet.

PRINT NGEN und CREATE Knowledge Base