2. Knowledge Base
  3. Integrationshandbuch
  4. Schnittstellen
  5. Import-Tool für Inhalte

Import-Tool für Inhalte

Schnittstellen NGSBP
Zurück
Allgemeines

Hier sind Sie richtig, falls Sie einen komfortablen Weg suchen, Ihre OXOMI Inhalte, anstatt über die übliche Web-Oberfläche, mithilfe eines kleinen Zusatzprogramms zu synchronisieren und auf diese Weise Ihre Inhalte automatisierbar immer auf dem aktuellsten Stand halten zu können.

Mit dem hier beschriebenen Werkzeug spielt es keine Rolle, ob Sie eine einzelne Datei importieren möchten oder ganze Ordnerstrukturen synchronisieren wollen, beides wird unterstützt.

Anwendungsfälle
Das OXOMI Import-Tool bietet Ihnen die Möglichkeit auf einfache Weise automatisierbare Integrationen mit verschiedenen Systemen zur Verwaltung digitaler Inhalte und Ressourcen einzurichten. Folgende Anwendungsfälle sind dabei denkbar:
  • Anbindung eines Medien-Asset-Management-Systems (MAM)
  • Anbindung eines Digital-Asset-Management-Systems (DAM)
  • Anbindung eines Product-Information-Management-Systems (PIM)
  • Anbindung eines klassischen Fileservers
  • Und viele weitere ...
Installation

Voraussetzung für das Ausführen des Import-Tools ist eine installierte Java-Laufzeitumgebung (JRE) mit Version 21 oder höher. Diese erhalten Sie beispielsweise kostenlos unter: Adoptium Releases

Das Import-Tool können Sie anschließend hier herunterladen:  oxomi-cli.jar

Legen Sie die heruntergeladene jar-Datei entweder in ein neutrales Verzeichnis oder ein übergeordnetes Verzeichnis Ihrer zu synchronisierenden Inhalte ab.

Konfiguration

Erstellen Sie im Haupt- oder einem übergeordneten Verzeichnis Ihrer zu synchronisierenden Inhalte eine Datei mit dem Namen oxomi.conf. Füllen Sie diese anschließend mit folgendem Inhalt und passen Sie die vordefinierten Werte entsprechend den dazugehörigen Kommentaren an. Falls Sie Fragen zu der Notation der Konfiguration haben, finden Sie weitere Details hier: HOCON-Format

Vergewissern Sie sich, dass die Datei als UTF-8 kodiert ist und ihr Zeilenumbruch (EOL) dem Betriebssystem entspricht, auf dem das Tool verwendet wird:

  • Windows: CR + LF
  • Unix/macOS: LF
Wichtiger Hinweis
Entfernen Sie nicht die "-Zeichen um die Werte der Parameter. Diese sind notwendig, damit die Parameter trotz Leerzeichen korrekt gelesen werden. 
# Enthält die OXOMI Benutzerdaten
oxomi {
    # Geben Sie hier den Benutzernamen des Mandanten an
    user = "username"
    # Geben Sie hier das Passwort des Mandanten an
    password = "PASSWORD"
}

# Geben Sie hier den vorzunehmenden Vorgang an
# (document, video, document-sync oder video-sync)
task = TASK

# Geben Sie hier den Unterordner für die Synchronisation oder Pfad + Dateiname bei Einzelaufruf an.
# Dieser ist immer relativ zum Speicherort dieser oxomi.conf Datei.
filePath = "test/"

# Geben Sie hier eventuelle Zusatzmodi für den aktuellen Vorgang an
# mode = MODE

# Enthält Daten für den Import oder die Synchronisation von Dokumenten
document {
    # Sollen Dokumente an Partner weitergegeben werden?
    forwarding = false

    # Sollen lokal gelöschte Dokumente in OXOMI archiviert oder komplett gelöscht werden?
    deleteOld = false

    # In OXOMI angezeigter Name der Dokumente
    publicName = "name"

    # Marke der Dokumente
    brandName = "marke"

    # Handelsstufe der Dokumente (END_CUSTOMER, RETAIL od. WHOLESALE)
    targetLevel = RETAIL

    # Dokumententyp
    type = catalog
}

# Enthält Daten für den Import oder die Synchronisation von Videos
video {
    # Sollen Videos an Partner weitergegeben werden?
    forwarding = false

    # Sollen lokal gelöschte Videos in OXOMI archiviert oder komplett gelöscht werden?
    deleteOld = false

    # In OXOMI angezeigter Name der Videos
    publicName = "name"

    # Beschreibungstext
    description = "Dies ist eine Beschreibung."

    # Marke der Videos
    brandName = "marke"

    # Handelsstufe der Videos (END_CUSTOMER, RETAIL od. WHOLESALE)
    targetLevel = RETAIL

    # Videotyp
    type = webtv
}

Um die Konfiguration Ihren Wünschen und Ihrem Einsatzzweck anzupassen, nutzen Sie die nachfolgend beschriebenen Parameter. Wir unterscheiden zwischen notwendigen und zusätzlichen Parametern.

Allgemein

Die nachfolgende Tabelle enthält eine Übersicht über die verfügbaren Parameter. Fett gedruckte Parameter sind Pflichtparameter. Die Beschreibung der Parameter enthält Informationen über den Typ des Parameters, die möglichen Werte und die Bedeutung sowie weitere Verwendungshinweise.

Parameter Parametertyp Beschreibung
oxomi.user string Der Loginname des OXOMI Benutzers, für den Dokumente oder Videos importiert werden sollen.
oxomi.password string Das Passwort des OXOMI Benutzers.
filePath string Dieser Parameter gibt bei Einzeldatei-Vorgängen den kompletten Pfad inklusive Dateiname und bei Synchronisierungs-Vorgängen den Pfad zum abzugleichenden Ordner, jeweils relativ zum Pfad der Konfigurationsdatei, an.
task string

Der Vorgang, der vom Import-Tool durchgeführt werden soll. Hierfür haben Sie folgende vier Möglichkeiten:

Wert Beschreibung
document Ein einzelnes Dokument in OXOMI importieren.
video Ein einzelnes Video in OXOMI importieren.
document-sync Die Dokumente eines gesamten Verzeichnisses mit OXOMI abgleichen.
video-sync Die Videos eines gesamten Verzeichnisses mit OXOMI abgleichen.
server.host url

Die komplette OXOMI-URL inklusive Protokoll.

Durch Angabe dieses Parameters können Sie den Standardwert von https://oxomi.com überschreiben.

mode string

Definiert einen zusätzlichen Modus.

Durch Angabe dieses Parameters und einem der im folgenden genannten Parameter können Sie die Ausführung des festgelegten Vorgangs ("task-Pflichtparameter") beeinflussen.

Wert Beschreibung
force Ignoriert bei Synchronisierungs-Vorgängen (z. B. „document-sync“) die History der letzten Synchronisation, wodurch eine erneute vollständige Synchronisierung erzwungen wird.
Dokumente

Sollten Sie Dokumente mit dem Tool synchronisieren wollen, sind die nachfolgenden Konfigurationswerte möglich.

Hinweis
Die optionalen Parameter in der nachfolgenden Tabelle ergeben nur im Fall eines Imports einzelner Dokumente Sinn.

Die nachfolgende Tabelle enthält eine Übersicht über die verfügbaren Parameter. Fett gedruckte Parameter sind Pflichtparameter. Die Beschreibung der Parameter enthält Informationen über den Typ des Parameters, die möglichen Werte und die Bedeutung sowie weitere Verwendungshinweise.

Parameter Parametertyp Beschreibung
document.forwarding boolean

Gibt an, ob die Dokumente an Partner weitergeleitet werden sollen.

Hinweis:

  • Wird dieser Parameter auf true gesetzt, wird der Inhalt an Partner weitergeleitet.
  • Wird dieser Parameter auf false gesetzt, sind die Dokumente nur für den eigenen Gebrauch und für Partner nicht sichtbar.
document.targetLevel string

Bestimmt die Handelsstufe, für die die Dokumente sichtbar sein sollen. Folgende Werte sind möglich:

Wert Beschreibung
WHOLESALE Nur für den Großhandel sichtbar.
RETAIL Sowohl für den Einzel- als auch für den Großhandel sichtbar.
END_CUSTOMER Für Großhandel, Einzelhandel und Endkunden sichtbar.

Mehr Informationen zu der Funktionsweise von Handelsstufen finden Sie auf der verlinkten Seite.

document.type string

Definiert den Typ des Dokuments. Die verfügbaren Werte können hier eingesehen werden: Dokumenttypen

document.publicName string

Bestimmt den in OXOMI angezeigten Namen für das Dokument.

Wird weder ein publicName noch ein internalName gesetzt, wird automatisch ein passender Name aus dem Dateinamen der Dokument-Datei gebildet.

document.internalName string

Sollten Sie zwei Bezeichnungen für ein Dokument verwenden wollen, definieren Sie mit diesem Parameter eine nur intern sichtbare Bezeichnung. Der Parameter publicName wird dann zur veröffentlichten Bezeichnung.

document.code string

Ergänzend zur ID des Dokuments können Sie hier einen Code vergeben, über den Sie den Inhalt in Integrationen gezielt ansprechen können.

document.brandName string

Name der Marke, unter der die Dokumente veröffentlicht werden.
document.brand string

Kann als Alternative zu dem Parameter document.brandName benutzt werden. In diesem Fall wird dann eine Marken-ID als Wert definiert.

document.category string

Definiert eine Kategorie (via ID) für das synchronisierte Dokument.
document.validDateFrom date

Definiert ein Datum, ab wann das Dokument sichtbar ist.

Eine solche Angabe könnte so aussehen: "22.07.2024"
document.validDateUntil date

Definiert ein Datum, bis wann das Dokument sichtbar ist.

Eine solche Angabe könnte so aussehen: "22.07.2024"
document.partnerRole string

Definiert eine Partnerrolle (via ID) für das Dokument.
document.locale_countries string

Definiert, für welche Länder dieses Dokument verfügbar ist. Der Wert ist eine kommaseparierte Liste 2-buchstabiger ISO-Codes, die verfügbaren Werte können hier eingesehen werden: ISO-Ländercodes

document.locale_lang string

Definiert, für welche Sprache dieses Dokument verfügbar ist. Der Wert ist ein 2-buchstabiger ISO-Code, die verfügbaren Werte können hier eingesehen werden: ISO-Sprachcodes

document.tags array

Definiert Tags für das Dokument. Der Wert ist eine kommaseparierte Liste von Tags.

Eine solche Angabe könnte so aussehen: ["#Tag1", "#Tag2", "#Tag3"]

document.additionalSearchTerms array

Definiert zusätzliche Suchbegriffe, über die das Dokument gefunden werden kann, die aber nicht bereits im Text des Dokuments enthalten sind. Der Wert ist eine kommaseparierte Liste einzelner Begriffe.

Eine solche Angabe könnte so aussehen: ["Suchbegriff1", "Suchbegriff2", "Suchbegriff3"]

Videos

Sollten Sie Videos mit dem Tool synchronisieren wollen, sind die nachfolgenden Konfigurationswerte möglich.

Hinweis
Die optionalen Parameter in der nachfolgenden Tabelle ergeben nur im Fall eines Imports einzelner Videos Sinn.

Die nachfolgende Tabelle enthält eine Übersicht über die verfügbaren Parameter. Fett gedruckte Parameter sind Pflichtparameter. Die Beschreibung der Parameter enthält Informationen über den Typ des Parameters, die möglichen Werte und die Bedeutung sowie weitere Verwendungshinweise.

Parameter Parametertyp Beschreibung
video.forwarding boolean

Gibt an, ob die Dokumente an Partner weitergeleitet werden sollen.

Hinweis:

  • Wird dieser Parameter auf true gesetzt, wird der Inhalt an Partner weitergeleitet.
  • Wird dieser Parameter auf false gesetzt, sind die Dokumente nur für den eigenen Gebrauch und für Partner nicht sichtbar.
video.targetLevel string

Bestimmt die Handelsstufe, für die die Videos sichtbar sein sollen. Folgende Werte sind möglich:

Wert Beschreibung
WHOLESALE Nur für den Großhandel sichtbar.
RETAIL Sowohl für den Einzel- als auch für den Großhandel sichtbar.
END_CUSTOMER Für Großhandel, Einzelhandel und Endkunden sichtbar.

Mehr Informationen zu der Funktionsweise von Handelsstufen finden Sie auf der verlinkten Seite.

video.type string

Definiert den Typ des Videos. Die verfügbaren Werte können hier eingesehen werden: Videotypen

video.publicName string

Bestimmt den in OXOMI angezeigten Namen für das Video.

Wird weder ein publicName noch ein internalName gesetzt, wird automatisch ein passender Name aus dem Dateinamen der Video-Datei gebildet.

video.internalName string

Sollten Sie zwei Bezeichnungen für ein Video verwenden wollen, definieren Sie mit diesem Parameter eine nur intern sichtbare Bezeichnung. Der Parameter publicName wird dann zur veröffentlichten Bezeichnung.

video.description string

Hier kann ein Text, der als Beschreibung für das Video benutzt wird, angegeben werden.

video.code string

Ergänzend zur ID des Videos können Sie hier einen Code vergeben, über den Sie den Inhalt in Integrationen gezielt ansprechen können.

video.brandName string

Name der Marke, unter der die Videos veröffentlicht werden.
video.brand string

Kann als Alternative zu dem Parameter video.brandName benutzt werden. In diesem Fall wird dann eine Marken-ID als Wert definiert.

video.category string

Definiert eine Kategorie (via ID) für das synchronisierte Video.
video.validDateFrom date

Definiert ein Datum, ab wann das Video sichtbar ist.

Eine solche Angabe könnte so aussehen: "22.07.2024"
video.validDateUntil date

Definiert ein Datum, bis wann das Video sichtbar ist.

Eine solche Angabe könnte so aussehen: "22.07.2024"
video.partnerRole string

Definiert eine Partnerrolle (via ID) für das Video.
video.locale_countries string

Definiert, für welche Länder dieses Video verfügbar ist. Der Wert ist eine kommaseparierte Liste 2-buchstabiger ISO-Codes, die verfügbaren Werte können hier eingesehen werden: ISO-Ländercodes

video.locale_lang string

Definiert, für welche Sprache dieses Video verfügbar ist. Der Wert ist ein 2-buchstabiger ISO-Code, die verfügbaren Werte können hier eingesehen werden: ISO-Sprachcodes

video.tags array

Definiert Tags für das Video. Der Wert ist eine kommaseparierte Liste von Tags.

Eine solche Angabe könnte so aussehen: ["#Tag1", "#Tag2", "#Tag3"]

Bedienung
Wichtiger Hinweis
Beim Import von Dokumenten und Videos mithilfe des Import-Tools muss mit besonderer Sorgfalt auf die richtige Konfiguration von Handelsstufen und Weitergabe-Einstellungen geachtet werden. Da Sie die Einstellungen einzelner Inhalte dann nicht mehr von Hand vornehmen, besteht ein erhöhtes Risiko Inhalte mit unerwünschten Einstellungen in OXOMI hochzuladen.
Schritt 1 Starten Sie eine Kommandozeile und begeben Sie sich mit cd /meine-inhalte zum Verzeichnis in dem Sie während der Installation die oxomi-cli.jar und oxomi.conf abgelegt haben.
Schritt 2 Starten Sie mit java -jar oxomi-cli.jar das Import-Tool. Anhand der Ausgabe started OXCLI können Sie erkennen, dass das Programm erfolgreich gestartet ist.
Schritt 3 Nun führt das Import-Tool den von Ihnen konfigurierten Vorgang aus und gibt währenddessen Zwischenstandsmeldungen und Fehler in der Kommandozeile aus.
Schritt 4 Traten beim Ausführen des Vorgangs keine Fehler auf, wurden Ihre Daten nach Ausgabe der Meldung finished OXCLI erfolgreich importiert. Sie können diese anschließend in der Oberfläche von OXOMI betrachten.
Expertenfunktionen

Die Ereignis- und Fehlernachrichten schreibt das Import-Tool instdoutund stdout. Um auf diese Meldungen auch nach Ende des Imports zugreifen und diese gegebenenfalls auswerten zu können, leiten Sie den kompletten Ausgabestrom des Programms einfach in eine Datei. Im Folgenden werden einige Möglichkeiten verschiedene Ausgaben in Dateien umzuleiten beschrieben.

Alle Meldungen in eine Datei ausgeben

Der Zusatz [startbefehl] &> ausgabe.txt bewirkt, dass alle Meldungen des Import-Tools anstatt in der Konsole in die angegebene Datei ausgegeben werden. Dies führt dazu, dass das Programm komplett still ausgeführt wird und alle Fehler ignoriert werden.

Ereignismeldungen in eine Datei ausgeben

Der Zusatz [startbefehl] 1> ausgabe.txt bewirkt, dass alle Zwischenstandsmeldungen des Import-Tools anstatt in der Konsole in die angegebene Datei ausgegeben werden. Es werden nur noch Fehlermeldungen in der Konsole ausgegeben. Das ist vor allem praktisch, wenn ein weiteres Programm für den Aufruf des Import-Tools zuständig ist und auf auftretende Fehlermeldungen reagieren soll.

Die in der Konfigurationsdatei oxomi.conf eingestellten Parameter dienen nur als Standard-Werte. Sie können diese durch das Beifügen von Parametern beim Start des Tools (Schritt 2) ergänzen, überschreiben oder vollständig ersetzen.

Hierzu fügen Sie die gewünschten Parameter im Format --parameter wert als Programmargumente, z.B.: java -jar oxomi-cli.jar [parameter] in den Start-Befehl des Import-Tools ein.

Beispiel 

java -jar oxomi-cli.jar --filePath pfad/zu/dokument/datei.pdf --task document --document.forwarding true
Überschreibt den Vorgang, Dateipfad und die Weitergabe-Parameter, um nach dem Start ein einzelnes Dokument zu importieren.

Um die Synchronisierung mittels des Tools zu automatisieren, verwenden Sie im besten Fall die Bordmittel Ihres Betriebssystems. Hierzu können Sie beispielsweise Cronjobs unter Linux oder geplante Aufgaben unter Windows verwenden.

Siehe auch
Enthält Informationen über die zur Verfügung stehenden Import-Schnittstellen für Inhalte.