Der EDI-X Im- und Exporter ermöglicht es, Dateien im Standard EDI-X 1.3 in die Main-API einzulesen.

Benutzung

Der Importer ist unter https://int-edix-converter.audioxchange.de zu erreichen und bietet die Möglichkeit, Anfragen und Antworten in Form von EDI-X-Dateien zu importieren. Dies kann wahlweise über eine REST-API oder eine GraphQL-API erfolgen.

POST-Endpunkt /import

Über den Endpunkt /import der REST-API kann eine Anfrage in Form einer EDI-X-Datei importiert werden.

Request

Keine Parameter. Die EDI-X-Datei wird über das Feld file im Request Body hochgeladen.

Responses

{
  "message": "string",
  "issues": [
    {
      "location": "string",
      "errorMessage": "string"
    }
  ]
}

Als Rückgabe gibt es eine Nachricht und gegebenenfalls eine Liste von Fehlern, die beim Einlesen der Datei oder beim Import-Prozess aufgetreten sind. Siehe dazu: EDI-X-Importer Fehlermeldungen

POST-Endpunkt /import/answer

Über den Endpunkt /import/answer der REST-API kann eine Antwort in Form einer EDI-X-Datei importiert werden.

Request

Es gibt den optionalen Parameter planElementId für das zugehörige PlanElement. Wird die Id weggelassen, wird das PlanElement über die Informationen in der EDI-X-Datei gesucht.

Die EDI-X-Datei wird über das Feld file im Request Body hochgeladen.

Responses

{
  "message": "string",
  "issues": [
    {
      "location": "string",
      "errorMessage": "string"
    }
  ]
}

Als Rückgabe gibt es eine Nachricht und gegebenenfalls eine Liste von Fehler, die beim Einlesen der Datei oder beim Import-Prozess aufgetreten sind. Siehe dazu: EDI-X-Importer Fehlermeldungen

GraphQL-Endpunkt /graphql

Über den Endpunkt /graphql der GraphQL-API können Anfragen und Antworten in Form von EDI-X-Dateien importiert werden.

Import der Anfrage eines Buyers

query { 
  edixMutationForSeller {
    importFromBuyer(file: Upload!): [ID]
  }
}

Import der Antwort eines Sellers

query {
  edixMutationForBuyer {
    importFromSeller(file: Upload!, planElementId: ID): [ID]
  }
}

Beispiel

Eine Anfrage an den GraphQL-Endpunkt ist ein Multipart-POST-Request. Für eine Anfrage an den Importer-Endpunkt benötigen wir folgende Felder:

operations: {"query":"mutation ImportFromBuyer($file:Upload!) { edixConverterForSeller { importFromBuyer(file: $file)}}","variables":{"file":null}}
map: {"0": ["variables.file"]}
0: [Datei]

Prozess: Import der Anfrage

Im Folgenden wird der Prozessablauf für den Import eines EDI-X-Dokuments durch eine Agentur beschrieben. Der Prozess entspricht der Buyer-Seite des allgemeinen Workflows. Eine EDI-X-Datei entspricht dabei einer Menge von Requests, die zu einem PlanElement gehören.

Prozessablauf

  1. Es wird untersucht, ob die zugehörigen Organisationen bereits im audioXchange-System vorhanden sind. Buyer und Seller müssen vorhanden sein, Advertiser und AdvertiserProduct können während des Prozesses angelegt werden.
  2. Die AAP-Elemente von Campaign bis RequestStream, die zu der Anfrage gehören, werden entweder herausgesucht oder neu angelegt.
  3. Je nach Status des RequestStream (siehe auch Status-Transitionen) wird ein neuer Request angelegt oder ein Update auf dem letzten Request ausgeführt.

Einzelne Elemente

Buyer

Der Buyer wird im EDI-X-Format als Agency bezeichnet. Er muss im audioXchange-System bereits vorhanden sein, da er im Import-Prozess nicht angelegt werden kann.

Der Importer sucht den Buyer anhand des Namens und der Adresse im audioXchange-System. Ist er nicht vorhanden, kann die Datei nicht importiert werden.

Advertiser

Der Advertiser wird im EDI-X-Format als Customer bezeichnet.

Der Importer sucht den Advertiser anhand seines Namens und seiner Adresse im audioXchange-System. Wenn er nicht vorhanden ist, wird er mit createAdvertiser angelegt.

AdvertiserProduct

Das AdvertiserProduct wird im EDI-X-Format als Product bezeichnet.

Der Importer sucht das AdvertiserProduct anhand seines Namens und der zugehörigen Advertiser-Id. Wenn es nicht vorhanden ist, wird es mit createAdvertiserProduct angelegt.

Seller

Der Seller wird im EDI-X-Format als Publisher bezeichnet. Er muss im audioXchange-System bereits vorhanden sein, da er im Import-Prozess nicht angelegt werden kann

Der Seller wird anhand seiner TDB-Nummer identifiziert.

Campaign

Es wird geprüft, ob es bereits eine Campaign mit dem passenden Namen zum Buyer und Advertiser gibt. Ist dies der Fall, wird diese Campaign verwendet. Ansonsten wird eine neue Kampagne mit createCampaign angelegt.

CampaignElement

Das CampaignElement existiert im EDI-X-Format nicht.

Falls der im EDI-X-Dokument angegebene Plan im audioXchange-System vorhanden ist, wird das übergeordnete CampaignElement verwendet. Ansonsten wird mit createCampaignElement ein neues angelegt, dessen Name sich aus dem zugehörigen Plan und einem Timestamp zusammensetzt.

Plan

Der Plan wird anhand seines Namens im audioXchange-System gesucht. Er ist einem CampaignElement zugeordnet. Wenn der Plan nicht existiert, wird mit createPlan ein neuer angelegt.

PlanElement

Das PlanElement existiert im EDI-X-Format nicht. In einem Plan gibt es für jeden Seller ein PlanElement. Wenn es für den Plan aus dem EDI-X-Dokument schon ein PlanElement für den benutzten Publisher gibt, wird dieses verwendet. Ansonsten wird mit createPlanElement ein neues angelegt.

SellerProduct

Zu jedem Audio-Element in der EDI-X-Datei gibt es ein SellerProduct. Dieses wird anhand der EDI-Nummer identifiziert.

RequestStream

Ein RequestStream repräsentiert sämtliche Anfragen und Antworten zu einem SellerProduct in einem PlanElement.

Zu jedem Audio-Element in der EDI-X-Datei wird entweder ein bestehender RequestStream gesucht oder es wird ein neuer Stream mit createRequestStream angelegt.

Request

Beim Import wird für jeden RequestStream je nach RequestProgressState ein neuer Request erstellt oder ein Update auf dem letzten Request ausgeführt (siehe auch Status-Transitionen).

Ein Request enthält die Informationen zu den Spots aus der EDI-X-Datei.

Prozess: Import der Antwort

Im Folgenden wird der Prozessablauf für den Import einer Antwort in Form eines EDI-X-Dokuments durch den Vermarkter beschrieben. Der Prozess entspricht der Seller-Seite des allgemeinen Workflows. Eine EDI-X-Datei entspricht dabei einer Menge von Answers, die zu einem PlanElement gehören.

Prozessablauf

  1. Wenn keine planElementId mitgegeben wird, wird aus allen PlanElementen des Sellers das ausgewählt, das zu den in der EDI-X-Datei angegebenen Campaign, Plan und Buyer gehört. Sollte das nicht eindeutig bestimmbar sein, gibt es eine Fehlermeldung. Siehe dazu: EDI-X-Importer Fehlermeldungen

Status Aktueller Status
BUYER_COMMIT oder SELLER_IN_WORK

  1. Es wird untersucht, ob alle RequestStreams, auf die geantwortet werden soll, im RequestProgressState BUYER_COMMIT oder SELLER_IN_WORK stehen. Nur dann können die Antworten geschrieben werden
  2. Die Antworten werden geschrieben und der ProgressState wird auf SELLER_COMMIT gesetzt.

Status Aktueller Status
SELLER_COMMIT

Einzelne Elemente

AnswerSpots

Falls im zugrunde liegenden Audio-Objekt eine OrderNo angegeben wurde, wird hierfür ein neues Order-Objekt angelgt. Dies geschieht automatisch. Das Order-Objekt hat die Pflichtfelder name und sspOrderNo, welche automatisch mit dem Wert der OrderNo aus der importierten EDI-X-Datei gefüllt werden.