[0-17] INBOUND Schnittstelle zu Living-Docs API | Artikel mit Bilder

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}”
  z. B.: “livingdocs-123456_infobox1”

Folgende Metadaten der Livingdocs Artikel-Daten können in PRINT NGEN dargestellt werden:

• Dokument-Id 

• Objekt/Ausgabe

• Ressort

• Ressortindex

• Erscheinungstag

• Formatname (Infoboxen erhalten immer den Formatnamen “Infobox”)

• Kollektiv/Sonderthema

• Teilseiten-Name

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.

Enthält ein Livingdocs-Artikel Bilder, dann werden diese nach PRINT NGEN importiert und an den Artikel gehängt. Für den Import der Bilder wird der Pfad “originalUrl” aus dem Artikel-JSON verwendet. Wenn das Bild aus “originalUrl” nicht gefunden wird, wird das Bild aus “url” abgeholt.

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:

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: Mitwirkungspflichten: [0-17] INBOUND Living-Docs API | Artikel mit Bilder

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 “id.gt”-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?id.gt=[event.id]

Das JSON, das an PRINT NGEN zurück geliefert wird, enthält folgende Felder:

Metadaten:

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-JSON abzufragen, z. B.:

GET v1/print/document?documentId=44

Beim Import nach PRINT NGEN wird das JSON in ein XML umgewandelt. Danach läuft ein XSLT-Stylesheet, das die übergebenen Inhalte in die entsprechenden Bereiche und Tags umwandelt (siehe Produktübergreifender Standard: Tags/Makros/Bereiche für XSLT Stylesheets).

Das JSON, das an PRINT NGEN zurück geliefert wird, enthält folgende Felder:

Metadaten:

Inhalt:

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"
    }
}

Fehlerbehandlung

HTTP-Fehler

Wird ein HTTP-Fehler “404 NOT FOUND” zurückgeliefert, wird dieser Artikel übersprungen.

Wird ein anderer HTTP-Fehler (z.B. “500 Internal Server Error“) zurückgeliefert, versucht PRINT NGEN erneut, den Artikel abzurufen, bis er importiert werden kann. Diese Fehlercodes sollten nämlich nur kommen, wenn der Service kurzfristig nicht erreichbar ist (z.B. Neustart/Wartung). Daher werden diese Artikel nicht übersprungen, sondern dann importiert, wenn der Server wieder erreichbar ist.

Inhaltliche Fehler

Bei inhaltlichen/syntaktischen Fehlern im Artikel-JSON, ist das XML nicht gültig und kann damit nicht verarbeitet werden. Das XSLT zum Umwandeln der Bereiche und Tags kann nicht ablaufen und der Artikel kann somit nicht importiert werden. Es wird ein Fehlerartikel in NGEN angelegt, der mit der gleichen Namenskonvention “livingdocs-{Livingdocs-Document-ID}” gefunden werden kann. In dem Fehlerartikel steht die Ursache, weshalb der Import fehlgeschlagen hat, z.B.

"Fehler bei der Verarbeitung des Inhalts: Fehler beim Ausführen des Xslt 'Default#Master.Livingdocs':'„' is an unexpected token. The expected token is '"' or '''. Line 1, position 1496."

FAQ

Verwandte Seiten

• Page:
  [0-17] INBOUND Schnittstelle zu Livingdocs API | Artikel mit Bilder
• Page:
  [0-20] INBOUND / OUTBOUND via SFTP
• Page:
  [1-28] INBOUND Anzeigenimport von kaufmännischem System
• Page:
  [0-2] INBOUND Agenturmeldungen, Agenturbilder
• Page:
  [0-8] INBOUND Azure AD / SAML App
• Page:
  [0-18] INBOUND Schnittstelle zu huGO API | Artikel (als Agenturmeldungen) mit Bildern
• Page:
  Mitwirkungspflichten: [0-17] Livingdocs API - Artikelvorlagen und Autor:innen
• Page:
  Mitwirkungspflichten: [0-17] Livingdocs API - Formatname
• Page:
  Customizing Livingdocs
• Page:
  [0-8] Redaktionelle Eingangskanäle
• Page:
  [0-10-4] INBOUND Bilder mit Metadaten-XML

^{Nur für PEIQ Mitarbeiter:innen:}

[0-17] INBOUND Living-Docs API | Artikel mit Bilder