PEIQ Knowledge Base
[0-17] INBOUND Schnittstelle zu Living-Docs API | Artikel mit Bilder
Transportverfahren | Übertragung per Restful API (https) |
|---|---|
Objekt | Artikel im JSON und Bilder als strukturiertes Objekt im JSON, Artikel-ID als eindeutiges Merkmal (document ID) |
Trigger | Zeitlich gesteuerter Poll durch PRINT NGEN (Pull alle 15 Sekunden, sofern vorhergehender Pull durchgeführt), Artikel-ID = eindeutiges Merkmal |
Typische Drittsysteme | Livingdocs |
Funktionalitäten der Living-Docs API
Die Schnittstelle dient zum Import von Artikeln und Bildern aus einem Web-CMS/Editor nach PRINT NGEN
Die Artikel sind dann in einem Eingangskorb in PRINT NGEN verfügbar
PRINT NGEN pullt in regelmäßigen Abständen die Living-Docs API, gemäß https://docs.livingdocs.io/reference/public-api/publications/publication-events/ & https://docs.livingdocs.io/reference/document/content/ (Version Mai 2020)
In der Basis-Version werden folgende Werte importiert und sofern Artikel-Templates diese unterstützen, entsprechend gemappt
Inhaltsverzeichnis
Austauschformat und Übertragung der Daten
Artikelname der Livingdocs-Artikel in PRINT NGEN
Artikelname des Hauptartikels (DTextName): “livingdocs-{Livingdocs-Document-ID}”
z. B.: “livingdocs-123456”Artikelname des Infoboxartikels (DTextName): “livingdocs-{Livingdocs-Document-ID}-infobox({Nummer bei mehr als einem Infobox-Artikel})”
z. B.: “livingdocs-123456-infobox” oder bei mehreren Infoboxen im Hauptartikel “livingdocs-123456-infobox1”
Folgende Metadaten der Livingdocs Artikel-Daten können in PRINT NGEN dargestellt werden:
Dokument-Id
Objekt/Ausgabe
Ressort
Ressortindex
Erscheinungstag
Formatname
Folgende Inhaltsdaten der Livingdocs Artikel-Daten können in PRINT NGEN dargestellt werden:
Titel
Dachzeile (optional)
Unterzeile (optional)
Vorspann (optional)
Absätze
Zwischenüberschriften (optional)
Autor:in (optional)
Autor:innenkürzel (optional)
Ort (optional)
Zitat (optional)
Zitatautor:in (optional)
Frage (optional)
Antwort (optional)
Zuordnungen der Bilder (optional)
Listen (optional)
Infoboxen mit/ohne Bilder (laufen in PRINT NGEN als eigenständige Artikel ein) (optional)
Folgende Metadaten der Livingdocs Bilder-Daten können in PRINT NGEN dargestellt werden:
Pixeldaten
Dateiname
Bildunterschrift (optional)
Quelle (optional)
Bildursprung (optional)
Ursprüngliche Bild-ID (optional)
Workflow
Durch entsprechend automatisierte Workflows können Artikel, die in Livingdocs publiziert werden, automatisiert in der PRINT NGEN Datenbank gespeichert werden. Diese Workflows greifen je Objekt.
Wird ein Artikel in Livingdocs für mehrere Ausgaben publiziert, so wird für jede übertragene Ausgabe in PRINT NGEN ein eigener Artikel erstellt.
Bereits in PRINT NGEN erstellte Livingdocs-Artikel werden nicht im klassischen Sinne aktualisiert. Wird jedoch ein Livingdocs-Artikel im ersten Schritt mit der Ausgabe A publiziert (d. h. hier wird in PRINT NGEN ein Artikel zur Ausgabe A erstellt), anschließend in Livingdocs nachbearbeitet, die Ausgabe B hinzugefügt und erneut publiziert, wird in PRINT NGEN ein zweiter Artikel zur Ausgabe B mit den aktuellen Artikelinhalten aus Livingdocs erstellt. Der Artikel A wird beim zweiten Publizieren nicht aktualisiert, sondern bleibt in PRINT NGEN mit dem Stand vom ersten Publizieren bestehen.
Das Gleiche gilt auch, wenn die Ausgabe in Livingdocs geändert wird. D. h. wird ein Livingdocs-Artikel mit der Ausgabe A publiziert, anschließend die Ausgabe in Livingdocs zur Ausgabe B geändert und erneut publiziert, bleibt der Artikel in PRINT NGEN zur Ausgabe A wie bisher bestehen. Beim zweiten Publizieren wird in PRINT NGEN ein Artikel zur Ausgabe B erstellt.
Das Erstellen und Publizieren eines Livingdocs-Artikels ist in nachfolgenden Videos beispielhaft skizziert (die gezeigten Metadaten beschränken sich im Video überwiegend auf die Pflichtfelder):
Das manuelle Absetzen der Suche nach Livingdocs-Artikeln ist in folgendem Video skizziert:
Inzwischen ist ein Livingdocs-Button in der Default-Werkzeugleiste vorhanden, über den die Livingdocs-Artikel für zukünftige Erscheinungstage gefunden werden können.
Beispiel 1
Der manuelle Workflow zum Platzieren von nach PRINT NGEN importierten Livingdocs-Artikeln wird in folgendem Video gezeigt:
Beispiel 2
Der manuelle Workflow zum Platzieren von nach PRINT NGEN importierten Livingdocs-Artikeln wird in folgendem Video gezeigt:
Standard-Logik Artikel-Vorlagen
Die Standard-Logik zu den Artikel-Vorlagen, in denen die Livingdocs-Artikel einlaufen, ist in folgendem Video skizziert:
Standard-Logik Autor:innen-Übernahme
Die Standard-Logik zur Übernahme der Autorin bzw. des Autors von Livingdocs in den nach PRINT NGEN importierten Artikel wird in folgendem Video gezeigt:
Mitwirkungspflichten
Die Mitwirkungspflichten für diese Schnittstelle befinden sich hier: https://peiq.atlassian.net/wiki/spaces/PPSD/pages/903381109
Beispieldaten
PublicationEvent-JSON
Über den Endpunkt GET api/v1/publicationEvents/… ruft PRINT NGEN im Workflow alle 15 Sekunden die “PublicationEvents” eines Channels ab. Der Parameter “channel” muss nicht mitgegeben werden. Stattdessen wird ein Token mitgegeben, in dem der Channel bereits konfiguriert ist.
Das Token wird im HTTP Header als Standard "Authorization: Bearer …” mitgegeben.
Dem “PublicationEvents” gibt PRINT NGEN den “after”-Parameter zur Selektion der Events anhand der Event-“id” mit. Dieser Wert ist am Anfang “0” (oder ein eingerichteter Standard) und wird in PRINT NGEN anhand der maximalen “id” in der Antwort gemerkt, um beim nächsten Call wieder danach aufzusetzen, z. B.:
GET api/v1/publicationEvents?after=[event.id]
Das JSON, das an PRINT NGEN zurück geliefert wird, enthält folgende Felder:
Metadaten:
Feld | Inhalt | Option |
"id" | ID des PublicationEvent | erforderlich |
"createdAt" | Erstellungszeitpunkt | - |
"projectId" | ID des Projektes | - |
"channelId" | ID des Channels | - |
"documentId" | ID des Artikels (erforderlich zum Abrufen des Artikel-JSON, vgl. 3.2) | erforderlich |
"documentType" | “article” bei Artikeln | - |
"contentType" | “print” bei Printartikeln | erforderlich |
"eventType" | “publish” bei Printartikeln die zur Veröffentlichung in Print übertragen werden | - |
"publicationId" | ID der Publikation | - |
Als Ergebnis erhält PRINT NGEN ein Array von Events, z. B.:
[
{
"id": 910,
"createdAt": "2016-12-27T09:19:00.928Z",
"projectId": 30,
"channelId": 53,
"documentId": 44,
"documentType": “article",
"contentType": "print",
"eventType": "publish",
"publicationId": 1066
},
{
...
}
]Artikel-JSON
Die DocumentIDs, die PRINT NGEN bei der Abfrage der Events erhalten hat, werden verwendet, um die Artikel abzufragen, z. B.:
GET v1/print/document?documentId=44
Das JSON, das an PRINT NGEN zurück geliefert wird, enthält folgende Felder:
Metadaten:
Feld | Inhalt | Option |
"projectId" | ID des Projektes | - |
"channelId" | ID des Kanals | - |
"documentId" | ID des Artikels | erforderlich |
"contentType" | “print” bei Printartikeln | - |
"documentType" | “article” bei Artikeln | - |
"design": { "name" } | Name des Designs | - |
"design": { "version" } | Versionsnummer des Designs | - |
"metadata": { "title" } | Titel (siehe “Titel des Artikels” unten) | optional |
"metadata": { "publish-date" oder: "publicationDate" } | Erscheinungstag im Format “2020-03-31”. Ein Erscheinungstag für alle übertragenen Ausgaben. | erforderlich, wenn der ET für alle Ausgaben gelten soll |
"metadata": { "publications" oder: "publication": [{ "date" }] | Erscheinungstag im Format “2020-03-31”. Ein unterschiedlicher Erscheinungstag je übertragener Ausgabe (Alternative zu einem Erscheinungstag für alle übertragenen Ausgaben) | erforderlich, wenn je Ausgabe ein unterschiedlicher ET gelten soll |
"metadata": { "publications" oder: "publication": [{ "object" }] | Objekt der Publikation | optional |
"metadata": { "publications" oder: "publication": [{ "name" }] | Name der Publikation | - |
"metadata": { "publications" oder: "publication": [{ "value" }] | Ausgabe der Publikation | erforderlich |
"metadata": { "publications" oder: "publication": [{ "category" }] | Ressort der Publikation | erforderlich |
"metadata": { "publications" oder: "publication": [{ "pageIndex" }] | Ressortindex der Publikation | optional |
"metadata": { "publications" oder: "publication": [{ "printContentType" }] | Formatname (z. B. Aufmacher, Standard) | optional |
"metadata": { "publications" oder: "publication": [{"collective"}] | Kollektiv/Sonderthema der Publikation (Achtung: Der Wert darf nicht die Sonderzeichen *?<>&,%"'! enthalten!) | optional |
"metadata": { "print- categories-xxx" } | Print-Kategorie | - |
"metadata": { "expire-date" } | Endzeitpunkt im Format 2020-04-02T14:10:00.000Z | - |
Inhalt:
Die Inhalte aller "content"-Components werden als (X)HTML erwartet.
Feld | Inhalt | Option |
"id" | ID des Elements im Artikel | - |
"component" | Element des Artikels, z. B.:
| - |
"content": { component: "image", “content”: { “image”: { "originalUrl" }}} | URL des Original-Bildes | erforderlich |
"content": { component: "image", “content”: { “image”: { "url" }}} | URL des platzierten Bildes | optional |
"content": { component: "image", “content”: { “image”: { "width" }}} | Breite des Bildes | - |
"content": { component: "image", “content”: { “image”: { "height" }}} | Höhe des Bildes | - |
"content": { component: "image", “content”: { “image”: { "mimeTyp" }}} | image/jpeg | - |
"content": { component: "image", “content”: { “image”: { "imageService" }}} | imgix | - |
"content": { component: "image", “content”: { “image”: { "origins": { "name" }}}} | Ursprung/Quelle des Bildes z. B. hugo | optional |
"content": { component: "image", “content”: { “image”: { "origins": { "identifier" }}}} | Bild-ID |
|
"content": { component: "image", “content”: { “image”: { "crop": { "x" }}}} | X-Koordinate des Ausschnitts von links oben | - |
"content": { component: "image", “content”: { “image”: { "crop": { "y" }}}} | Y-Koordinate des Ausschnitts von links oben | - |
"content": { component: "image", “content”: { “image”: { "crop": { "width" }}}} | Breite des Ausschnitts | optional |
"content": { component: "image", “content”: { “image”: { "crop": { "height" }}}} | Höhe des Ausschnitts | optional |
"content": { component: "image", “content”: { “image”: { "crop": { "name" }}}} | Bezeichnung des Ausschnitts z. B. 16:9 | optional |
"content": { component: "image", “content”: { “image”: { "caption" }}} | Bildunterschrift | optional |
"content": { component: "image", “content”: { “image”: { "source" }}} | Bildquelle | optional |
"content": { component: "head" oder: "header", content: { "catchline" }} | Dachzeile des Artikels | optional |
"content": { component: "head" oder: "header", content: { "title" }} | Titel des Artikels | erforderlich |
"content": { component: "head" oder: "header", content: { "lead" }} | Unterzeile des Artikels | optional |
"content": { component: "head" oder: "header", content: { "author" }} | Autor:in des Artikels | optional |
"content": { component: "head" oder: "header", content: { "authorShortnames" }} | Autor:innenkürzel | optional |
"content": { component: "head" oder: "header", content: { "city" }} | Ort des Artikels | optional |
"content": { component: "lead-p", content: { "text" }} | Vorspann des Artikels | optional |
"position" | z. B. fixed | - |
"content": { component: "p", content: { "text" }} | Absatz eines Artikels | optional |
"content": { component: “subtitle”, “content“: { “title“ }} | Zwischentitel im Artikel | optional |
"content": { component: “list”, “containers”: { “list” }} | Liste im Artikel | optional |
"content": { component: “list” , “containers”: { “list”: [{ “component”: “list-item”, “content”: { “text” }}]}} | Listenelement | optional |
"content": { component: “quote” , “content”: { “text” }} | Zitat im Artikel | optional |
"content": { component: “quote” , “content”: { “source” }} | Autor:in/Quelle des Zitats | optional |
"content": { component: "question" , "content": { "text" }} | Frage | optional |
"content": { component: "answer" , "content": { "text" }} | Antwort | optional |
"content": {"component": "infobox", | Infobox im Artikel (in PRINT NGEN als eigenständiger Artikel) | optional |
Die Schnittstelle liefert an PRINT NGEN die Artikel-JSONs zurück, z. B.:
{
"systemdata": {
"projectId": 16,
"channelId": 16,
"documentId": 44,
"contentType": "print",
"documentType": "article",
"design": {
"name": "berliner-zeitung",
"version": "0.0.100"
}
},
"metadata": {
"title": "Title",
"publications": [{
"object": "BZ",
"name": "Berliner Zeitung",
"value": "Berliner Zeitung",
"category": "Berlin",
"printContentType": "Standard",
"pageIndex": "1"
},
{ "object": "BK",
"name": "Berliner Kurier",
"value": "Berliner Kurier",
"category": "Berlin",
"printContentType": "Aufmacher",
"pageIndex": "3",
"collective": "Sonderthema XYZ"
}
],
"publish-date": "2020-03-17T10:35:00.000Z",
"expire-date": "2020-04-30T09:35:00.000Z"
},
"livingdoc": {
"content":
{
"id": "doc-1e3k0qt0h0",
"component": "head",
"content": {
"catchline": "Catchline",
"title": "Title",
"lead": "Lead",
"author": "Lukas Peyer",
"authorShortnames": "LP"
},
"position": "fixed"
},
{
"id": "doc-1e3k0qt0i0",
"component": "lead-p",
"content": {
"opener": "Lead Paragraph",
"text": "Text"
}
},
{
"id": "doc-1e3k0qt0i1",
"component": "p",
"content": {
"text": "Text"
}
},
{
"id": "doc-1e3k0ts9b0",
"component": "image",
"content": {
"image": {
"originalUrl": "http://livingdocs-images-dev.s3.amazonaws.com/2020/1/28/6c0b3ce3-0289-44da-9610-91f1d9773419.jpeg",
"url": "https://livingdocs-dev.imgix.net/2020/1/28/6c0b3ce3-0289-44da-9610-91f1d9773419.jpeg?rect=0%2C20%2C1200%2C675&auto=format",
"width": 1200,
"height": 714,
"mimeType": "image/jpeg",
"imageService": "imgix",
"crop": {
"x": 0,
"y": 20,
"width": 1200,
"height": 675,
"name": "16:9"
}
"origins": [
{
"name": "archiv A",
"identifier": "abc-123"
}]
},
"caption": "Image Caption",
"labelSource": "Source",
"source": "Agency"
}
},
{
"id": "doc-1e3k0sng70",
"component": "quote",
"content": {
"text": "Quote",
"source": "Quote Author"
}
},
{
"component": "question",
"id": "doc-1e3k0sng70",
"content": {
"text": "Frage Inhalt."
}
},
{
"component": "answer",
"id": "doc-1e3k0sng70",
"content": {
"text": "Antwort Inhalt."
}
},
{
"id": "doc-1e3k0sveu0",
"component": "subtitle",
"content": {
"title": "Subtitle"
}
},
{
"id": "doc-1e3k0s91s0",
"component": "list",
"content": {
"title": "List Title"
},
"containers": {
"list": [
{
"id": "doc-1e3k0sacb0",
"component": "list-item",
"content": {
"text": "Item 1"
}
},
{
"id": "doc-1e3k0sgrn0",
"component": "list-item",
"content": {
"text": "Item 2"
}
}
]
}
}
],
"design": {
"name": "berliner-zeitung",
"version": "0.0.100"
},
"layout": "print"
}
}Auch die im Artikel-JSON angegebenen Bilder werden nach PRINT NGEN importiert. Hierfür wird der Pfad “originalURL” verwendet.
Wird ein HTTP-Fehler “404 (NOT FOUND)” zurück geliefert, wird dieser Artikel übersprungen. Wird ein anderer HTTP-Fehler zurück geliefert, versucht PRINT NGEN erneut, den Artikel abzurufen.
FAQ
Verwandte Seiten
Nur für PEIQ Mitarbeiter:innen: