Déclencheur Web Service

Pour en savoir plus sur les déclencheurs en général, consulter l'article Comprendre les déclencheurs.

L'événement de déclencheur Web Service survient si un socket surveillé (adresse IP et numéro de port) reçoit des données. Les données doivent respecter la notation SOAP, données XML encodées dans les messages HTTP). L'interface du Web Service est décrite dans le document WSDL. Ce document est disponible avec chaque déclencheur Web Service défini.

Le déclencheur Web Service fournit un retour d'informations sur l'état du travail d'impression, mais il faut activer le mode de traitement synchrone. Pour plus d'informations, consulter l'article Retour d'informations sur le travail d'impression.

Généralement, les programmeurs utilisent le Web Service pour intégrer l'impression d'étiquettes à leurs propres applications. Un système existant exécute une transaction, qui envoie les données au serveur NiceLabel Automation sur un socket spécifique. Les données envoyées sont formatées en message SOAP. Le contenu de données peut être structuré en format CSV, XML etc., ou il peut être structuré en utilisant l'un des anciens formats. Dans chaque cas, NiceLabel Automation lit les données, analyse les valeurs en utilisant des filtres et les imprime sur les étiquettes. Pour plus d'informations concernant l'analyse et l'extraction de données, consulter l'article Comprendre les filtres.

Communication

Note

Ce déclencheur est compatible avec le protocole Internet version 6 (IPv6).

Cette section permet de configurer le numéro du port obligatoire et les paramètres facultatifs de retour d'informations.

Port : Spécifie le numéro du port qui accepte les données entrantes. Utiliser un numéro de port qui n'est pas utilisé par une autre application. Si le port sélectionné est utilisé, il sera impossible de démarrer le déclencheur dans Automation Manager. Pour plus d'informations concernant les problèmes de sécurité, voir l'article Sécuriser l'accès aux déclencheurs.

Note

S'il y a un hébergement multiple activé sur le serveur (plusieurs adresses IP sur une ou plusieurs cartes réseau), NiceLabel Automation répondra au port défini pour toutes les adresses IP.

Connexion sécurisée (HTTPS) : Elle active la couche de transport sécurisée pour vos messages HTTP et évite l'écoute clandestine. Pour plus d'informations sur la manière de paramétrer une connexion sécurisée, voir l'article Utilisation de la couche de transport sécurisée (HTTPS).
Nombre maximum d'appels simultanés : Spécifie le nombre maximum de connexions acceptées. Autant de clients peuvent envoyer des données au déclencheur simultanément.
Données de réponse : Définit la réponse personnalisée qui peut être utilisée avec les méthodes ExecuteTriggerWithResponse et ExecuteTriggerAndSetVariablesWithResponse. La réponse est fournie dans la zone de texte. Elle peut comporter des valeurs fixes, des valeurs variables et des caractères spéciaux. Pour insérer (ou créer) des variables et des caractères spéciaux, cliquer sur le bouton flèche à droite de la zone de texte. La réponse peut contenir des données binaires, telles qu'une image d'aperçu de l'étiquette et le fichier d'impression (*.PRN).

Retour d'informations sur l'état

Par sa conception, le déclencheur Web Service renvoie des informations sur les travaux d'impression créés. Le déclencheur acceptera les données fournies et les utilise pour exécuter les actions définies. Vous pouvez superviser l'exécution des actions, le déclencheur renvoie des informations d'état positif pour chaque événement survenant lors de l'exécution. Pour activer le rapport d'état lors du processus d'impression, activer Mode d'impression synchrone.

Le déclencheur Web Service expose les méthodes suivantes (fonctions) :

ExecuteTrigger : (exécuter le déclencheur) Cette méthode accepte l'introduction de données dans le traitement et renvoie en option le rapport d'informations de l'état. L'un des paramètres d'entrée active ou désactive le retour d'informations. Si l'option est activée, le retour d'informations contient l'ID d'erreur et une description détaillée de l'erreur. Si l'ID d'erreur est égale à 0, il n'y a pas eu de problème lors de la création du fichier d'impression. Si l'ID est supérieure à 0, une erreur est survenue lors du processus d'impression. Dans cette méthode, la réponse du Web Service n'est pas configurable, elle contiendra toujours l'ID d'erreur et la description de l'erreur.

ExecuteTriggerWithResponse : (exécuter le déclencheur avec réponse) Cette méthode accepte l'introduction de données dans le traitement et renvoie les informations personnalisées. La réponse de Web Service est configurable. Vous pouvez répondre en utilisant n'importe quel type de données organisées dans n'importe quelle structure disponible. Il est possible d'utiliser des données binaires dans la réponse.
ExecuteTriggerAndSetVariables : Similaire à ExecuteTrigger ci-dessus, ce Web Service expose des paramètres entrants supplémentaires qui acceptent les listes de paires formatées nom-valeur. Le déclencheur analyse automatiquement la liste, extrait les valeurs et les sauvegarde dans les variables de même nom, inutile donc de créer de filtre d'extraction vous-même.
ExecuteTriggerAndSetVariablesWithResponse : Similaire à ExecuteTriggerWithResponse ci-dessus, ce Web Service expose des paramètres entrants supplémentaires qui acceptent les listes de paires formatées nom-valeur. Le déclencheur analyse automatiquement la liste, extrait les valeurs et les sauvegarde dans les variables de même nom, inutile donc de créer de filtre d'extraction vous-même.

Pour plus d'informations concernant la structure des messages en utilisant l'une ou l'autre méthode ci-dessus, consulter le chapitre WSDL ci-dessous.

WSDL

Le WSDL (Web Service Description Language) spécifie le style des messages SOAP. Il peut être soit un style de Remote Procedure Call (RPC), soit un style de document. Choisir le style que supporte votre application fournissant les données.

Le document WSDL définit les paramètres d'entrée et sortie du Web Service.

Après avoir défini le déclencheur Web Service sur le port 12345, le déployer dans Automation Manager et le lancer. Le WSDL devient disponible sur :

http://localhost:12345

Le WSDL présente les différentes méthodes qui fournissent des données au déclencheur. Choisir la méthode la plus appropriée pour ce que vous tentez d'accomplir.

Les méthodes ayant WithResponse (avec réponse) dans leurs noms permettent d'envoyer des réponses personnalisées, tels que des messages d'erreur personnalisés, des aperçus d'étiquette, des fichiers PDF, des fichiers d'impression (*.PRN) et similaires. Les méthodes sans WithResponse dans leur nom renverront aussi des informations, mais qui ne sont pas personnalisables. Le rapport contiendra des messages d'erreur par défaut.
Les méthodes ayant SetVariables dans leurs noms vous permettent de fournir une liste de variables dans deux formats prédéfinis. Automation extrait automatiquement les valeurs et les cartographie vers les variables appropriées. Cela vous fait gagner du temps puisqu'il ne faut pas définir de filtre pour extraire et relier les données. Pour les méthodes sans SetVariables dans leurs noms, il faut définir le filtre vous-même.

L'interface Web Service définit les méthodes suivantes :

Méthode ExecuteTrigger (exécuter le déclencheur)

La partie principale de la définition est la suivante :

<wsdl:message name="WebSrviTrg_ExecuteTrigger_InputMessage">
    <wsdl:part name="text" type="xsd:string"/>
    <wsdl:part name="wait" type="xsd:boolean"/>
</wsdl:message>
<wsdl:message name="WebSrviTrg_ExecuteTrigger_OutputMessage"
    <wsdl:part name="ExecuteTriggerResult" type="xsd:int"/
    <wsdl:part name="errorText" type="xsd:string"/>
</wsdl:message>

Il y a deux variables d'entrée (il faudra fournir les valeurs) :

texte : Le filtre dans la configuration analyse la chaîne d'entrée. En général, la chaîne d'entrée est structurée en tant que fichier CSV ou XML, ce qui facilite l'analyse. Vous pouvez aussi utiliser n'importe quel format de fichier texte.
attendre : C'est un champ bouléen qui spécifie deux choses :
- Si vous voulez attendre la réponse de l'état du travail d'impression ou non.
- Si le Web Service doit fournir un retour d'informations ou non.
En cas de True (vrai), utiliser 1. En cas de False (faux), utiliser 0. Selon le type de méthode sélectionné, il y a soit une réponse prédéfinie, soit une réponse personnalisée.

Il y a les variables de sortie facultatives suivantes (vous recevez leurs valeurs si vous en faites la demande en plaçant attendre sur 1) :

ExecuteTriggerResult : La réponse intégrale contient la valeur 0 en cas de rapport d'erreur(s) de traitement des données. Elle contient un nombre entier supérieur à 0 en cas d'erreurs. L'application qui exécute l'appel Web Service à NiceLabel Automation peut utiliser la réponse comme indicateur d'erreur.
errorText : Cette valeur de chaîne contient la réponse de l'état du travail d'impression si une erreur survient lors du traitement du déclencheur.

Note

Si une erreur survient durant le traitement du déclencheur, cet élément est inclus dans le message de réponse XML et sa valeur contient la description de l'erreur. Toutefois, s'il n'y a pas d'erreur, cet élément n'est pas inclus dans la réponse XML.

Méthode ExecuteTriggerWithResponse (exécuter le déclencheur avec réponse)

Cette méthode sera utilisée si le déclencheur envoie la réponse personnalisée après la fin de l'exécution.

Quelques exemples de réponse : messages d'erreur personnalisés, aperçu d'étiquette, fichiers PDF générés, fichier de flux d'impression (fichier spouleur), fichier XML avec les détails du générateur d'impression plus l'aperçu d'étiquette (encodé comme chaîne Base64), les possibilités sont infinies.

La partie principale de la définition est la suivante :

<wsdl:message name="WebSrviTrg_ExecuteTriggerWithResponse_InputMessage">
    <wsdl:part name="text" type="xsd:string"/>
    <wsdl:part name="wait" type="xsd:boolean"/>
</wsdl:message>
<wsdl:message name="WebSrviTrg_ExecuteTriggerWithResponse_OutputMessage">
    <wsdl:part name="ExecuteTriggerWithResponseResult" type="xsd:int"/>
    <wsdl:part name="responseData" type="xsd:base64Binary"/>
    <wsdl:part name="errorText" type="xsd:string"/>
</wsdl:message>

Dans l'exemple ci-dessus, il y a deux variables d'entrée (il faudra fournir les valeurs) :

texte : Le filtre dans la configuration analyse la chaîne d'entrée. En général, la chaîne d'entrée est structurée en tant que fichier CSV ou XML, ce qui facilite l'analyse. Vous pouvez aussi utiliser n'importe quel format de fichier texte.
attendre : C'est un champ bouléen qui spécifie deux choses :
- Si vous voulez attendre la réponse de l'état du travail d'impression ou non.
- Si le Web Service doit fournir un retour d'informations ou non.
En cas de True (vrai), utiliser 1. En cas de False (faux), utiliser 0. Selon le type de méthode sélectionné, il y a soit une réponse prédéfinie, soit une réponse personnalisée.

De plus, les variables de sorties facultatives suivantes sont incluses dans l'exemple ci-dessus.

Note

Vous recevez des valeurs de sortie facultatives si vous en faites la demande en plaçant la valeur du champ attendre sur 1.

ExecuteTriggerWithResponseResult : La réponse intégrale contient la valeur 0 s'il n'y a pas de problèmes lors du traitement des données. Cette réponse contient un nombre entier supérieur à 0 en cas d'erreurs. L'application qui exécute l'appel Web Service à NiceLabel Automation peut utiliser la réponse comme indicateur d'erreur.
responseData : La réponse personnalisée qui peut être définie dans la configuration du déclencheur Web Service. La réponse est encodée en base 64.
errorText : Si une erreur survient lors du traitement du déclencheur, la chaîne contient la valeur de la réponse de l'état du travail d'impression.

Note

S'il y a un rapport d'erreurs lors du traitement du déclencheur, le message de réponse XML inclut l'élément errorText. La valeur de cet élément contient la description de l'erreur. Toutefois, s'il n'y a pas d'erreur, cet élément n'est pas inclus dans la réponse XML.

Méthode ExecuteTriggerAndSetVariables (exécuter le déclencheur et définir les variables)

La partie principale de la définition est la suivante :

<wsdl:message name="WebSrviTrg_ExecuteTriggerAndSetVariables_InputMessage">
    <wsdl:part name="text" type="xsd:string"/>
    <wsdl:part name="variableData" type="xsd:string"/>
    <wsdl:part name="wait" type="xsd:boolean"/>
</wsdl:message>
    <wsdl:message name="WebSrviTrg_ExecuteTriggerAndSetVariables_OutputMessage">
    <wsdl:part name="ExecuteTriggerAndSetVariablesResult" type="xsd:int"/>
    <wsdl:part name="errorText" type="xsd:string"/>
</wsdl:message>

Dans l'exemple ci-dessus, il y a trois variables d'entrée (il faudra fournir les valeurs) :

texte : Le filtre dans la configuration analyse la chaîne d'entrée. En général, la chaîne d'entrée est structurée en tant que fichier CSV ou XML, ce qui facilite l'analyse. Vous pouvez aussi utiliser n'importe quel format de fichier texte.
attendre : C'est un champ bouléen qui spécifie deux choses :
- Si vous voulez attendre la réponse de l'état du travail d'impression ou non.
- Si le Web Service doit fournir un retour d'informations ou non.
En cas de True (vrai), utiliser 1. En cas de False (faux), utiliser 0. Selon le type de méthode sélectionné, il y a soit une réponse prédéfinie, soit une réponse personnalisée.

variableData : C'est la chaîne de caractères contenant les paires nom:valeur. Le déclencheur lit toutes les paires et assigne les valeurs fournies aux variables ayant le même nom. Si la variable n'existe pas dans le déclencheur, le déclencheur élimine la paire nom:valeur. Si vous fournissez la liste de variables et leurs valeurs en utilisant cette méthode, vous n'avez pas besoin de définir d'extraction de données avec les filtres. Le déclencheur se charge de faire l'analyse.

Il y a deux structures disponibles pour le contenu variableData.
Structure XML
Le déclencheur fournit les variables dans l'élément racine <Variables /> du fichier XML. Le nom de la variable inclut le nom de l'attribut, et la valeur de la variable inclut la valeur de l'élément.

<?xml version="1.0" encoding="utf-8"?> <Variables> <variable name="Variable1">Value 1</variable> <variable name="Variable2">Value 2</variable> <variable name="Variable3">Value 3</variable> </Variables>

Note

Incorporer les données XML dans la section CDATA. CDATA, signifiant donnée de caractère, est une section de contenu d'élément qui est marquée pour que l'analyseur l'interprète seulement comme données XML de caractères, et non comme une balise. Par conséquent, le déclencheur gère tout le contenu en tant que donnée de caractère. Par exemple, <element>ABC</element> est interprété en tant que <element>ABC</element>. Chaque section CDATA commence par la séquence <![CDATA[ et se termine par la séquence ]]>. Pour résumer, placer simplement les données XML entre ces deux séquences.
Paires nom-valeur
Le déclencheur fournit les variables en utilisant un flux textuel. Chaque paire nom:valeur a sa propre ligne. Le nom de variable se situe à gauche du signe égal (=), la valeur de variable se situe à droite.

Variable1="Value 1" Variable2="Value 2" Variable3="Value 3"

Il y a trois variables de sortie facultatives :

Note

Vous recevez des variables facultatives si vous en faites la demande en plaçant attendre sur 1 :

ExecuteTriggerAndSetVariablesResult : La réponse intégrale contient la valeur 0 s'il n'y a pas de problèmes lors du traitement des données. Elle contient un nombre entier supérieur à 0 si le traitement des erreurs signale une ou plusieurs erreurs. L'application qui exécute l'appel Web Service à NiceLabel Automation peut utiliser la réponse comme indicateur d'erreur.
errorText : Cette valeur de chaîne contient la valeur de la réponse de l'état du travail d'impression si elle signale une erreur de traitement du déclencheur.

Note

En cas d'erreur de traitement du déclencheur, cet élément est inclus dans le message de réponse XML. Sa valeur contient la description de l'erreur. Toutefois, s'il n'y a pas d'erreur, cet élément n'est pas inclus dans la réponse XML.

Méthode ExecuteTriggerAndSetVariablesWithResponse (exécuter le déclencheur et définir les variables avec réponse)

Cette méthode sera utilisée si le déclencheur doit envoyer la réponse personnalisée après la fin de l'exécution.

La partie principale de la définition est la suivante :

<wsdl:message name="WebSrviTrg_ExecuteTriggerAndSetVariablesWithResponse_
InputMessage">
    <wsdl:part name="text" type="xsd:string"/>
    <wsdl:part name="variableData" type="xsd:string"/>
    <wsdl:part name="wait" type="xsd:boolean"/>
</wsdl:message>
<wsdl:message name="WebSrviTrg_ExecuteTriggerAndSetVariablesWithResponse_
OutputMessage">
    <wsdl:part name="ExecuteTriggerAndSetVariablesWithResponseResult"
type="xsd:int"/>
    <wsdl:part name="responseData" type="xsd:base64Binary"/>
    <wsdl:part name="errorText" type="xsd:string"/>
</wsdl:message>

Il y a trois variables d'entrée (il faudra fournir les valeurs) :

texte : Le filtre dans la configuration analyse la chaîne d'entrée. En général, la chaîne d'entrée est structurée en tant que fichier CSV ou XML, ce qui facilite l'analyse. Vous pouvez aussi utiliser n'importe quel format de fichier texte.
attendre : C'est un champ bouléen qui spécifie deux choses :
- Si vous voulez attendre la réponse de l'état du travail d'impression ou non.
- Si le Web Service doit fournir un retour d'informations ou non.
En cas de True (vrai), utiliser 1. En cas de False (faux), utiliser 0. Selon le type de méthode sélectionné, il y a soit une réponse prédéfinie, soit une réponse personnalisée.

variableData : C'est la chaîne de caractères contenant les paires nom:valeur. Le déclencheur lit toutes les paires et assigne les valeurs fournies aux variables ayant le même nom. Si la variable n'existe pas dans le déclencheur, le déclencheur élimine la paire nom:valeur. Si vous fournissez la liste de variables et leurs valeurs en utilisant cette méthode, vous n'avez pas besoin de définir d'extraction de données avec les filtres. Le déclencheur se charge de faire l'analyse.

Il y a deux structures disponibles pour le contenu variableData.
Structure XML
Le déclencheur fournit les variables dans l'élément racine <Variables /> du fichier XML. Le nom de la variable inclut le nom de l'attribut, et la valeur de la variable inclut la valeur de l'élément.

<?xml version="1.0" encoding="utf-8"?> <Variables> <variable name="Variable1">Value 1</variable> <variable name="Variable2">Value 2</variable> <variable name="Variable3">Value 3</variable> </Variables>

Note

Incorporer les données XML dans la section CDATA. CDATA, signifiant donnée de caractère, est une section de contenu d'élément qui est marquée pour que l'analyseur l'interprète seulement comme données XML de caractères, et non comme une balise. Par conséquent, le déclencheur gère tout le contenu en tant que donnée de caractère. Par exemple, <element>ABC</element> est interprété en tant que <element>ABC</element>. Chaque section CDATA commence par la séquence <![CDATA[ et se termine par la séquence ]]>. Pour résumer, placer simplement les données XML entre ces deux séquences.
Paires nom-valeur
Le déclencheur fournit les variables en utilisant un flux textuel. Chaque paire nom:valeur a sa propre ligne. Le nom de variable se situe à gauche du signe égal (=), la valeur de variable se situe à droite.

Variable1="Value 1" Variable2="Value 2" Variable3="Value 3"

Il y a trois variables de sortie facultatives :

Note

Vous recevez leurs valeurs si vous en faites la demande en plaçant attendre sur 1 :

ExecuteTriggerAndSetVariablesWithResponseResult : La réponse intégrale contient la valeur 0 s'il n'y a pas de problèmes lors du traitement des données. Elle contient un nombre entier supérieur à 0 si la réponse signale une ou plusieurs erreurs. L'application qui exécute l'appel Web Service à NiceLabel Automation peut utiliser la réponse comme indicateur d'erreur.
responseData : La réponse personnalisée qui peut être définie dans la configuration du déclencheur Web Service. La réponse est encodée en base 64.
errorText : Cette valeur de chaîne contient la valeur de la réponse de l'état du travail d'impression si elle signale une erreur de traitement du déclencheur.

Note

En cas d'erreur de traitement du déclencheur, cet élément est inclus dans le message de réponse XML. Sa valeur contient la description de l'erreur. Toutefois, s'il n'y a pas d'erreur, cet élément n'est pas inclus dans la réponse XML.

Autre

Les options de la section Commentaires du moteur d'impression spécifient les paramètres de communication qui vous permettent de recevoir un retour d'informations du moteur d'impression.

Impression supervisée : Active le mode d'impression synchrone. Utiliser cette option pour renvoyer les informations sur l'état du travail d'impression à une application tierce. Pour plus d'informations, consulter l'article Mode d'impression synchrone.

Les options de la section Traitement de données permettent de préciser s'il faut couper les données pour les ajuster à la variable, ou ignorer les variables manquantes dans l'étiquette. Par défaut, va dire qu'il y a une erreur et interrompre le processus d'impression en cas d'enregistrement de valeurs trop longues dans les variables d'étiquettes, ou de paramétrage de valeurs dans des variables inexistantes.

Ignorer le contenu variable excessif : tronque les valeurs des données qui dépassent la longueur de la variable telle que définie dans l'éditeur d'étiquettes pour qu'elles s'adaptent. Cette option s'applique lors du paramétrage de valeurs de variables dans les filtres des fichiers de commande et au paramétrage de valeurs de variables de déclencheurs dans les variables d'étiquette ayant le même nom.

Exemple 25. Exemple

La variable de l'étiquette accepte un maximum de 5 caractères. Avec cette option activée, toute valeur plus longue que 5 caractères est tronquée aux 5 premiers caractères. Si la valeur est 1234567, ignore les chiffres 6 et 7.
Ignorer les variables d'étiquettes manquantes : Lors de l'impression de fichiers de commande (tels qu'un fichier JOB), le processus d'impression ignore toutes les variables qui sont :
- spécifiées dans le fichier de commande (en utilisant la commande SET)
- non définies sur l'étiquette
La même chose se produit si vous définissez une zone d'assignation dans un filtre pour extraire toutes les paires nom-valeur, mais votre étiquette contient moins de variables.

Lorsque vous paramétrez des valeurs dans des variables d'étiquettes inexistantes, signale une erreur. Si cette option est activée, l'impression continue.

Les options dans la section Script spécifient les possibilités de script.

Langage de script : Sélectionne le langage de script pour le déclencheur. Toutes les actions Exécuter le script d'un même déclencheur utilisent le même langage.

Les options de la section Enregistrer les données reçues spécifient les commandes disponibles pour les données reçues par le déclencheur.

Enregistrer les données reçues par le déclencheur vers le fichier : Activer cette option pour enregistrer les données reçues par le déclencheur. L'option Variable active le nom de fichier variable. Sélectionner une variable qui contient le chemin et le nom du fichier.
En cas d'erreur, enregistrer les données reçues par le déclencheur vers le fichier : Activer cette option pour enregistrer les données dans le déclencheur si une erreur survient lors de l'action d'exécution. Activer cette option pour récupérer les données qui ont causé l'erreur et résoudre le problème.

Note

Il faut activer la prise en charge de l'impression supervisée. Autrement, Automation ne peut pas détecter d'erreurs lors de l'exécution. Pour plus d'informations, consulter l'article Mode d'impression synchrone.

Note

Automation enregistre les données reçues dans un fichier temporaire. Le fichier temporaire est supprimé immédiatement après la fin de l'exécution du déclencheur. La variable interne DataFileName pointe vers ce fichier. Pour plus d'informations, consulter l'article Variables internes.