Anhang B: Cloud Trigger API

Um den Druck mit Cloud-Trigger zu ermöglichen, verwenden Sie ein Integrationssystem (Loftware Automation), das vor Ort installiert ist, um Daten aus Ihren Geschäftssystemen zu empfangen und zu verarbeiten. Loftware Automationstellt APIs zur Verfügung, mit denen Sie sich über Cloud-Trigger-APIs aus Ihren Cloud-Geschäftsanwendungen verbinden können.

Zusätzlich zum Etikettendruck bieten Ihnen die APIs folgende Möglichkeiten:

• Etikettenvorschauen abrufen (PDF, PNG oder JPEG)

• Live-Status von Etikettendruckern anzeigen

• Listen aller Etiketten in Ihrem Dokumentenmanagementsystem (DMS) erstellen

• Listen der verfügbaren Drucker abrufen

• Listen der in Ihrem Etikett definierten Variablen abrufen

• Druckaufträge bereitstellen (binär)

Ausführen von Cloud-Trigger-APIs

Jeder Cloud-Trigger wird durch einen eindeutigen Namen identifiziert. Sie müssen den eindeutigen Namen in jeder HTTP-Anfrage an unsere Cloud-Trigger-API angeben.

Ersetzen Sie im folgenden Beispiel den Teil „unique_name_of_the_Cloud_trigger“ durch den tatsächlichen eindeutigen Cloud-Trigger-Namen, der in Ihrer Loftware Automation Konfiguration (.MISX Datei) definiert ist.

Jeder in Ihrer Konfiguration definierte Cloud-Trigger bietet eine bestimmte API-Methode. Sie verwenden verschiedene Trigger für jede Methode. Ein Trigger für die PRINT-Methode, ein anderer für die PREVIEW-Methode, ein weiterer für die PRINTERS-Methode usw. Eindeutige Namen teilen Automation mit, welchen Trigger es ausführen muss.

Wenn Sie Ihre Automation -Konfiguration laden und bereitstellen/aktivieren, registriert Automation die Cloud-Trigger (eindeutige Namen) in Ihrem Loftware Cloud -Konto. Sie können mit Cloud-Trigger-APIs auf die Trigger zugreifen. Wenn Sie Cloud-Trigger-APIs ausführen, weiß Ihr Loftware Cloud -Konto, wo Ihr registrierter Automation ausgeführt wird und leitet Daten an Ihren Trigger weiter.

Sie können mehrere lokale Loftware Automation Server haben, die die gleiche Konfiguration zur gleichen Zeit ausführen, wobei die automatische Lastverteilung per DNS aktiviert ist.

URL	https://labelcloudapi.onnicelabel.com/Trigger/v1/CloudTrigger/<unique_Cloud_Trigger_name>

Sie müssen den folgenden benutzerdefinierten HTTP-Header in jede Anforderung einfügen:

Ocp-Apim-Subscription-Key

<Subscription key is generated on the Developer Portal when you register "Cloud Integration" developer from the Control Center>

Sie müssen die POST-Methode verwenden und die JSON- oder XML-Daten in Ihren Nachrichtentext einfügen.

Registrierung als Integratoren

Um Cloud-Trigger-APIs auszuführen, müssen Sie sich als Entwickler registrieren und einen Abonnementschlüssel erhalten. Sie können diesen Vorgang selbst abschließen, sobald Sie sich bei Ihrem Loftware Cloud Konto anmelden können und wenn Sie Ihr Konto in unserem Entwicklerportal eingerichtet haben.

Weitere Informationen über den Registrierungsprozess finden Sie unter Cloud Integrations und Cloud Trigger.

API-Methoden

Mit unseren API-Methoden können Sie die Strukturen der zwischen Ihren Geschäftsanwendungen und Loftware Automation übertragenen Nachrichten testen und verstehen. Wir bieten Beispiele und Beschreibungen von eingehenden Anfragen und Loftware Automation Feedback-Strukturen.

Sie können JSON- und XML-Datenstrukturen mit unseren API-Methoden verwenden.

Weitere Informationen über eingehende Nutzdaten finden Sie unter Datenstrukturen.

PRINTERS-Methode

Diese Methode ruft Listen der verfügbaren Drucker ab, die Loftware Automation verwenden kann. Die Listen enthalten die Namen der Druckertreiber, die auf dem Computer installiert sind, auf dem Loftware Automation ausgeführt wird.

Sie müssen einen leeren Nutzdateninhalt senden, damit die API feststellen kann, welche Art von Antwort Sie benötigen.

Anfrage-URL

https://labelcloudapi.onnicelabel.com/Trigger/v1/CloudTrigger/CloudTrigger/Api-CloudIntegrationDemo-Printers

JSON-Nutzdaten

{}

XML-Nutzdaten

<?xml version="1.0" encoding="utf-8"?>

PRINT-Methode

Mit dieser Methode werden Ihre Etiketten gedruckt. In den Nutzdaten geben Sie Folgendes an:

• Name des Etiketts:

• Versionen des Etiketts

• Druckernamen

• Alle zu druckenden Etikettendaten

Anfrage-URL

https://labelcloudapi.onnicelabel.com/Trigger/v1/CloudTrigger/Api-CloudIntegrationDemo-Print

JSON-Nutzdaten

{
    "FilePath": "/folder/label.nlbl",
    "FileVersion": "",
    "Quantity": “1”,
    „Drucker“: " ZEBRA R-402",
    "PrinterSettings": "",
    "PrintJobName": "",
    "Variables": [
        {
            "Name": "FIELD1",
            "Wert": "Value1"
        },
        {
            "Name": "FIELD2",
            "Wert": "Value2"
        }
    ]
}

XML-Nutzdaten

<?xml version="1.0" encoding="utf-8"?>
<PrintData>
    <FilePath>/folder/label.nlbl</FilePath>
    <FileVersion></FileVersion>
    <Quantity>1</Quantity>
    <Printer>ZEBRA R-402</Printer>
    <PrinterSettings></PrinterSettings>
    <PrintJobName></PrintJobName>
    <Variables>
        <Variable Name="FIELD1">Value1</Variable>
        <Variable Name="FIELD2">Value2</Variable>
    </Variables>
</PrintData>

LABELCATALOG-Methode

Diese Methode liefert Listen der verfügbaren Etikettenvorlagen in bestimmten Ordnern (und Unterordnern) aus Ihrem DMS.

Anfrage-URL

https://labelcloudapi.onnicelabel.com/Trigger/v1/CloudTrigger/Api-CloudIntegrationDemo-LabelCatalog

JSON-Nutzdaten

{
    "CatalogRoot": "/folder/subfolder",
    "SubscriptionKey": "your_subscription_key"
}

XML-Nutzdaten

<?xml version="1.0" encoding="utf-8"?>
<PrintData>
    <CatalogRoot>/folder/subfolder</CatalogRoot>
    <SubscriptionKey>your_subscription_key</SubscriptionKey>
</PrintData>

PREVIEW-Methode

Diese Methode liefert Etikettenvorschauen in dem von Ihnen gewünschten Format. Wie bei der Methode PRINT müssen Sie Etikettennamen, Versionen und Datenwerte angeben. Unterstützte Vorschauformate sind PDF, JPG und PNG.

Anfrage-URL

https://labelcloudapi.onnicelabel.com/Trigger/v1/CloudTrigger/Api-CloudIntegrationDemo-Preview

JSON-Nutzdaten

{
    "FilePath": "/folder/label.nlbl",
    "FileVersion": "",
    "Quantity": “1”,
    "Printer": "",
    "PrinterSettings": "",
    "PreviewFormat": "",
    "Variables": [
        {
            "FIELD1": "Value1",
            "FIELD2": "Value2"
        }
    ]
}

XML-Nutzdaten

<?xml version="1.0" encoding="utf-8"?>
<PrintData>
    <FilePath>/folder/label.nlbl</FilePath>
    <FileVersion></FileVersion>
    <Quantity>1</Quantity>
    <Printer></Printer>
    <PrinterSettings></PrinterSettings>
    <PreviewFormat></PreviewFormat>
    <Variables>
        <Variable Name="FIELD1">Value1</Variable>
        <Variable Name="FIELD2">Value2</Variable>
    </Variables>
</PrintData>

PRINTJOB-Methode

Diese Methode liefert Ihre Etiketten in Druckaufträge für Zieldrucker umgewandelt. Wenn Ihr Zieldrucker zum Beispiel Zebra ist, wird Ihr Inhalt in ZPL (Zebra Programming Language) ausgegeben. Sie geben Etikettennamen, Versionen und Datenwerte wie bei der PRINT-Methode an.

Anfrage-URL

https://labelcloudapi.onnicelabel.com/Trigger/v1/CloudTrigger/Api-CloudIntegrationDemo-PrintJob

JSON-Nutzdaten

{
    "FilePath": "/folder/label.nlbl",
    "FileVersion": "",
    "Quantity": "1",
    "Printer": "",
    "PrinterSettings": "",
} „Variablen“: [
    {
        "FIELD1": "Value1",
        "FIELD2": "Value2"
    }
]

XML-Nutzdaten

<?xml version="1.0" encoding="utf-8"?>
<PrintData>
    <FilePath>/folder/label.nlbl</FilePath>
    <FileVersion></FileVersion>
    <Quantity>1</Quantity>
    <Printer></Printer>
    <PrinterSettings></PrinterSettings>
    <Variables>
        <Variable Name="FIELD1">Value1</Variable>
        <Variable Name="FIELD2">Value2</Variable>
    </Variables>
</PrintData>

VARIABLES-Methode

Diese Methode liefert eine Liste der Variablen, die in den von Ihnen angegebenen Etiketten definiert sind. Möglicherweise müssen Sie die in Ihren Etiketten definierten Variablen kennen, damit Sie ihnen bei der Ausführung der Methode PRINT Werte zuweisen können.

Anfrage-URL

https://labelcloudapi.onnicelabel.com/Trigger/v1/CloudTrigger/Api-CloudIntegrationDemo-Variables

JSON-Nutzdaten

{
    "FilePath": "/folder/label.nlbl",
    "FileVersion": "",
}

XML-Nutzdaten

<?xml version="1.0" encoding="utf-8"?>
<PrintData>
    <FilePath>/folder/label.nlbl</FilePath>
    <FileVersion></FileVersion>
</PrintData>

PRINTERSTATUS-Methode

Diese Methode liefert die von Ihren Druckern gemeldeten aktuellen Druckerstatus. Nicht alle Drucker können ihren Status melden.

Anfrage-URL

https://labelcloudapi.onnicelabel.com/Trigger/v1/CloudTrigger/Api-CloudIntegrationDemo-PrinterStatus

JSON-Nutzdaten

{
    „Drucker“: "ZEBRA ZD420-300dpi ZPL"
}

XML-Nutzdaten

<?xml version="1.0" encoding="utf-8"?>
<PrintData>
    <Printer>ZEBRA ZD420-300dpi ZPL</Printer>
</PrintData>

Datenstrukturen

Ihre API-Konfiguration akzeptiert JSON- und XML-Nutzdaten. Ihre Konfiguration bestimmt automatisch Ihren Nutzdatentyp und antwortet mit demselben Typ.

Eingehende Nutzdaten

Die unten aufgeführten Datenstrukturen enthalten alle möglichen Felder. Die von Ihnen verwendeten Felder hängen von Ihrer API-Methode ab. Im Kapitel API-Methoden finden Sie eine Liste der Felder, die für Ihre spezielle API-Methode gelten.

JSON-Nutzdatenstruktur

{
    "FilePath": "/folder/label.nlbl",
    "FileVersion": "",
    "Quantity": "1",
    "Printer": "",
    "PrinterSettings": "",
    "PrintJobName": "",
    "PreviewFormat": "",
    "CatalogRoot": "",
    "SubscriptionKey": "",
    "Variables": [
        {
            "Variable1": "Value1",
            "Variable2": "Value2"
        }
    ],
    "Report": [
        {
            "Pos": "01",
            "Code": "100"
            "Name": "Produkt 1"
        },
        {
            "Pos": "02",
            "Code": "200"
            "Name": "Produkt 2"
        }
    ]
}

Sie können das optionale JSON-Report-Objekt verwenden, wenn Sie Versanddokumente wie Packzettel und Lieferscheine drucken.

Elemente in JSON-Report-Objekten werden in Strukturen umgewandelt, die für Report-Objekte auf Ihren Etikettenvorlagen geeignet sind. Zum Beispiel werden die Variablen „Pos“, „Code“ und „Name“ aus dem Beispiel im Report-Objekt mit denselben Namen verwendet. Sie können auch Ihre eigenen Variablennamen verwenden. Wenn Sie keine Report-Objekte in Ihrer Etikettenvorlage verwenden möchten, können Sie das JSON-Report-Objekt auslassen.

XML-Nutzdatenstruktur

<?xml version="1.0" encoding="utf-8"?>
<PrintData>
    <FilePath>/folder/label.nlbl</FilePath>
    <FileVersion>1</FileVersion>
    <Quantity>1</Quantity>
    <Printer></Printer>
    <PrinterSettings></PrinterSettings>
    <PrintJobName></PrintJobName>
    <PreviewFormat></PreviewFormat>
    <CatalogRoot></CatalogRoot>
    <SubScriptionKey></SubscriptionKey>
    <Variables>
        <Variable Name="Variable1">Value1</Variable>
        <Variable Name="Variable2">Value2</Variable>
    </Variables>
    <Report>
        <Item>
             <Pos>01</Pos>
             <Code>100</Code>
             <Name>Product 1</Name>
        </Item>
        <Item>
             <Pos>02</Pos>
             <Code>200</Code>
             <Name>Product 2</Name>
        </Item>
    </Report>
</PrintData>

Feldbeschreibungen

NAME	BESCHREIBUNG
FilePath	Vollständiger Pfad- und Etikettenname aus dem Dokumentenspeicher.
FileVersion	Dateiversion des Etiketts. Wenn Sie eine Major-/Minor-Version verwenden, geben Sie die Version als „0.1“ oder „1.1“ an. Wenn Sie die Major-Version verwenden, geben Sie die Version als „1“ oder „2“ an. Wenn Sie keine Werte angeben, wird die letzte verfügbare Version verwendet. Wenn Sie Genehmigungs-Workflows einsetzen, wird die letzte genehmigte Etikettenversion verwendet.
Quantity	Anzahl der auszudruckenden Etiketten.
Printer	Name des Druckers, auf dem Ihre Etiketten gedruckt werden. Hierbei muss es sich um den genauen Druckernamen handeln, der auf Ihrem Windows-Computer mit installiert ist. Loftware Automation
PrinterSettings	Base64-kodierte DEVMODE-Struktur. Ermöglicht das Außerkraftsetzen von Druckereinstellungen, die in Ihrer Etikettenvorlage gespeichert sind oder von Ihrem Druckertreiber abgerufen werden. Hinweis Sie können PowerForms-Anwendungen erstellen, um Druckereinstellungen zu konfigurieren und Einstellungen in DEVMODE zu exportieren. Außerdem können Sie mit einer Anwendung, die Sie von unserer Website herunterladen können (Downloads > Utilities and Support Software), Einstellungen aus Ihrem Druckertreiber in DEVMODE exportieren.
PrintJobName	Auftragsdateinamen, die im Windows Spooler angezeigt werden. Wenn Sie diese Angabe weglassen, ist der Auftragsname standardmäßig der Name Ihrer Etikettendatei.
PreviewFormat	Format der Etikettenvorschau. Zu den verfügbaren Formaten gehören PDF, PNG und JPEG. Falls nicht angegeben, ist PDF das Standardformat.
CatalogRoot	Startordner, in dem Sie Ihren Etikettenkatalog erstellen. Ihr Katalog enthält außerdem Etiketten aus allen Unterordnern. Hinweis Wenn Sie Etikettenkataloge aus großen Dokumentenspeichern abrufen, kann es einige Augenblicke dauern, bis Ihre Anfrage abgeschlossen ist.
SubscriptionKey	Ein Abonnementschlüssel zur Erstellung des Etikettenkatalogs. Die Konfiguration von Automation nutzt die Dokumenten-API, um den Etikettenkatalog zu generieren. Zur Authentifizierung wird ein Abonnementschlüssel benötigt. Sie können Ihren Abonnementschlüssel über das Entwicklerportal abrufen.
Variablen	Name-Wert-Paare für Ihre Etikettenvariablen. Für jeden „Namen“ müssen Sie einen passenden „Wert“ angeben. Alle Name-Wert-Paare senden Sie an Ihr Etikett, um sie mit Variablen zu verwenden, die mit demselben „Namen“ definiert sind. Die Zuordnung der Werte erfolgt automatisch anhand der übereinstimmenden Namen.
Report	Mehrere Elemente, die Name-Wert-Paare für die im Report-Objekt in der Etikettenvorlage verwendeten Variablen liefern. Jedes „Element“ wird als neue Zeile im Report-Objekt verwendet. Hierbei handelt es sich um ein optionales Feld.

Feedback-Meldungen

Automation stellt die Ergebnisse der Datenverarbeitung in synchronen Antworten für Geschäftsanwendungen bereit. Die Antworten entsprechen immer den Strukturen der eingehenden Nutzdaten. Wenn Sie Anforderungen im JSON-Format senden, erhalten Sie JSON-Antworten. Wenn Sie Anforderungen im XML-Format senden, erhalten Sie XML-Antworten.

• Erfolgreiche Ausführung. Wenn keine Datenverarbeitungsfehler vorliegen, erhalten die Geschäftssysteme Nachrichten im JSON- oder XML-Format. Die Struktur Ihrer Antwort hängt von der von Ihnen verwendeten API-Methode ab.

• Fehlerhafte Ausführung. Liegt ein Verarbeitungsfehler vor, wie z.B. „Etikett nicht gefunden“, „Drucker nicht verfügbar“ oder „falsche Daten für Etikettenobjekte“, gibt Ihr Loftware Automation Trigger einen Fehler aus und sendet Details in der Trigger-Antwort zurück.

Für XML Daten-Nutzdaten bietet die API eine Rückmeldung im HTTP-Header und im Nachrichtentext. Für JSON-Daten enthalten die Antworten HTML-Nachrichten ohne Fehlerdetails (eine kommende Loftware -Version wird JSON-Antworten mit Fehlerdetails enthalten).

Detaillierte Fehlerprotokolle finden Sie im Loftware Automation Manager für jeden Antworttyp.

PrinterList-Strukturen

Jeder Drucker verfügt über Drucker -Elemente.

NAME	BESCHREIBUNG
PrinterName	Der Windows-Druckertreibername, der für Loftware Automation sichtbar ist. Windows-Benutzer können diesen Namen ändern.
DriverName	Windows-Druckermodellname (vom Druckertreiber definiert). Windows-Benutzer können diesen Namen nicht ändern.

Variablen-Strukturen

Jede Variable auf Ihrem Etikett enthält Variable -Elemente.

Für weitere Informationen lesen Sie bitte unser Benutzerhandbuch:

• Kapitel Etiketteninformationen im Loftware Automation Benutzerhandbuch.

NAME	BESCHREIBUNG
Name	Name der Variablen.
Beschreibung	Variablenbeschreibungen
DefaultValue	Standardwert, der für Ihre Variable während des Etikettendesigns definiert wurde.
Format	Zulässige Arten von Variableninhalten (Zeichen).
IsPrompted	Gibt an, ob die Variable zum Zeitpunkt des Drucks abgefragt wird.
PromptText	Der Text, mit dem die Benutzer zur Eingabe eines Wertes aufgefordert werden.
CurrentValue	Aktueller Wert, der zum Drucken verwendet wird.
IncrementType	Gibt an, ob die Variable als Zähler definiert ist. Wenn sie als Zähler definiert ist, zeigt IncrementType den Zählertyp an.
IncrementStep	Informationen zum Zählerschritt. Ihr Zählerwert erhöht/verringert sich beim nächsten Etikett um diesen Wert.
IncrementCount	Informationen zur Erhöhung/Verringerung des Zählerwerts. Zähler ändern ihre Werte normalerweise für jedes Etikett, aber Sie können auch benutzerdefinierte Schritte wählen.
Length	Maximale Anzahl der gespeicherten Zeichen in der Variablen.
IsPickListEnabled	Gibt an, ob Ihre Benutzer Variablenwerte aus einer Auswahlliste auswählen.
PickListValues	Tatsächliche (auswählbare) Werte der Auswahlliste.

Etikettenkatalog-Strukturen

Unten sehen Sie eine Beispielstruktur, die für den Etikettenkatalog ausgegeben wird.

Die Automation -Konfiguration generiert den Etikettenkatalog mit Dokumenten-API aus dem Entwicklerportal (Sie müssen sich anmelden, um den Inhalt zu sehen). Das Beispiel verwendet eine kleine Teilmenge der von der Dokumenten-API bereitgestellten Daten.

Die Loftware -Konfiguration bietet die folgende Beispielstruktur:

NAME	BESCHREIBUNG
Id	Interne ID der Etikettenvorlagen, wie sie im Dokumentenverwaltungssystem generiert werden.
ItemPath	Der vollständige Pfad und Dateiname der Etikettenvorlage.
Erstellt	Zeitstempel der Erstellung.
Geändert	Zeitstempel der Änderung.
ModifiedBy	Kennung des Benutzers, der die Etikettenvorlage zuletzt geändert hat.
VersionNumber	Die Version der letzten Etikettenvorlage.
WorkflowName	Der Name eines Workflows, der für den Ordner definiert ist, in dem die Etikettenvorlage gespeichert ist.
WorkflowStepName	Der Name des Workflow-Schrittes, den die Etikettenvorlage einnimmt.