GÉNÉRALITÉS

Starpage Web Service permet par une URL de requêter la création d’un PDF renvoyé selon la méthode d’un service Web conforme à la recommandation REST.

Le produit StarPage WS a été conçu et testé, à ce jour, pour Debian 9, RedHat 6, Windows 2012.

Il exploite Java 8 ou 9 et une plateforme applicative de publication Tomcat (validé sur v9) ou WebSphere (validé sur v8)

Le produit est composé de deux parties : le binaire Starpage adapté au WebServices et le module java pour l’exposition aux requêtes WebService.

Ce document concerne plutôt une installation sur Linux mais le produit est disponible sur Windows. Le module java est naturellement identique.

Tomcat ou Websphere est installé et fonctionnel avant d’aborder l’installation de Starpage WS.

Comptage des pages

Starpage WS se valide pour un certain nombre de documents par an, renouvelé à date anniversaire de validation.

La partie Web ne fait pas encore de comptage par appelant et ne remonte pas encore le nombre de pages restantes.

ARCHITECTURE

Lors d’une demande de génération d’un PDF la requête http du client envoie : les data en base 64,

le scenario Starpage appelé “type”,

le format attendu (PDF ou PDF-C ou PDF-A ou DOC) la clé publique attribuée au site

une empreinte de tout cela

Le site Starpage WS

évalue le demande,

dépose le fichier data en ASCII dans le sous-répertoire ~starjet/forms/WS, lance Starpage WS,

récupère le PDF généré dans ~starjet/OUTWS, le renvoie au client,

journalise l’évènement

efface data et PDF un instant après.

Pour tester Starpage en dehors du contexte du service, la ligne de commande est

~starjet/starpagews Scenario SourceData Type DestinationFichierPDF Type :

1. pour PDF N&B
2. pour PDF Couleur 3 pour PDF A

(4 pour DOC – à venir )

INSTALLATION (LINUX)

Sur le serveur linux, la plateforme applicative doit d’abord être fonctionnelle, OS, Java, Websphere ou Tomcat.

Installation du moteur de composition

Etre loggé en root
Copier le tar fourni sur /tmp (linuxMoteurStarpgeWS.tar, le nom peut changer) et dé-tarer
Lancer /tmp/sjet_setup
Répondre aux questions. A la question sur le home directory du user starjet qui va être créé, répondre

/home/starjet, ou autre selon le choix de l’administrateur.

A la fin de l’installation la validation du produit est proposée (choix 1: StarpageWS)

Le code fourni devra être échangé avec le support Appic pour obtenir la clé de validation (support@appic.com).

Ce même menu de validation est récupérable par la commande ~starjet/starpagews -l Des options (PDF-C …) pourrons être validées selon la même procédure d’échange de clés. NB: vous devrez aussi valider le choix 2 (option PDF) de ~starjet/starpage -l

Vérifier la présence des répertoires ou les créer :

~starjet/OutWS

~starjet/forms/WS

~starjet/logfiles/starpagews

avec des droits tel que l’utilisateur applicatif Tomcat ou WebSphere puissent créer, modifier, effacer des fichiers sur OutWS et WS (entrée et sortie)

Il vous appartient de vous assurer de ce dernier point.

Transfert / mise à jour d’un projet de composition Starpage

Copier le ou les projets Starpage : fichiers sp, sjp, le cas échéant les tiff, sur ~starjet/forms. Après le transfert (de Windows vers unix) passer la commande ‘dos2unix *.sp *.sjp’.

(Attention ces fichiers sont créés sur Windows, Linux est ‘case dependant’ )

Sur cet aspect des fonds de page, les projets Starpage sont les mêmes que ceux utilisables sur Starpage standard. Ils se créent et s’utilisent de la même façon.

Installation de la partie exposition Web

Copier le fichier .war fourni (starpageWS.war) dans le répertoire de publication. A priori “webapps” dans le home directory du user tomcat. (ou équivalent dans Websphere)

Immédiatement la tache de fond tomcat (ou Websphere) se déclenche et après quelques instants la publication est disponible.

Configuration du webservice

Il faut paramétrer le webservice via le fichier de configuration /WEB-INF/classes/config.properties.

#Type de serveur (tomcat, websphere, …). (juin 2018 – info uniquement) server=tomcat

#Environnement d’exécution (unix, windows) env=unix

#Répertoire d’installation de starjet path_app=/home/starjet

#Chemin complet vers l’application starjet path_launcher=/home/starjet/starpageWS #Répertoire où créer les fichier .dat path_data=/home/starjet/forms/WS/

#Répertoire par défaut où seront stockés les scénarios starpage .sp path_scenario=/home/starjet/forms/

#Répertoire où seront stockés les fichiers générés path_out=/home/starjet/OutWS/

#Répertoire où seront créés les fichiers de logs path_logs=/home/starjet/logfiles/starpagews/

#Activation des logs logs_active=true (true ou false)

#Password de l’application pour cryptage des appels : clé privée security_key=Xw^j!w9Y8sKEh3jpYVjxygIgo?d3[A

#Durée de conservation des fichiers générés et .dat sur le serveur (en ms) security_tmp_file_duration=60000

Une modification dans le fichier de configuration prend effet sans redémarrage du service de publication (testé sous Tomcat 9, à confirmer selon version ou particularité de la plateforme).

Activation des logs : possible de le mettre à false après le période de test

Password / clé privée : c’est la clé unique identifiant les clients au site WebService

Durée de conservation des fichiers (données et PDF) : les fichiers ne sont pas conservés, après un délai ils sont effacés. L’exemple de 60000 correspond à 1 mn. Zéro est possible mais des problèmes de transfert pourraient se produire sur des PDF de plusieurs dizaines de pages, conseillé de 15000 à 60000.

Si le webservice passe False à “deleteFile”, il n’y a pas d’effacement

Les listes suivantes montrent les droits souhaités sur les fichiers : Dans le home directory de starjet :

drwxrwxrwx	starjet starjet	logfiles
drwxrwxrwx	starjet starjet	OutWS
-rwsr-xr-x	root root	sjet_ex01
-rwsr-xr-x	root root	sjet_ex02
-rw-r–r–	root root	sj.lic
-rw-r–r–	root root	sjsys
-rwxr-xr-x	root root	starjet
-rwsr-xr-x	root root	starpage
-rw-r–r–	root root	starpage_lock
-rwxr-xr-x	root root	starpagews

Dans ~starjet/logfiles :

drwxr-x— tomcat tomcat starpagews ou utilisateur de Websphere ou Libertycore à la place de tomcat

Dans ~starjet/forms :

drwxrwxrwx tomcat tomcat WS ou utilisateur de Websphere ou Libertycore à la place de tomcat

APPEL DU WebService

L’appel du WebService se fait par l’application métier qui réunit les éléments et les envoie.

Evaluation du fonctionnement, Postman

Pour évaluer le fonctionnement et simuler l’application métier, des outils gratuits tels que Postman ou SoapUI peuvent être utilisés.

Pour des détails sur ces produits, vous pouvez vous reporter à une recherche sur internet.

Voici des copies d’écran pour Postman

Il s’agit d’une commande POST.

Dans l’adresse mettre le EndPoint correct. Pour Tomcat, il sera de la forme : http://<server>:<port>/starpageWS/api/documents

Le port tomcat est 8080 par défaut

Le format est “PDF” ou “PDF-C” (sortie PDF noir et blanc ou couleur). Evolutions PDF-A et DOC à venir

Data contient une longue chaine qui est les données ASCII du document à composer encodés en base 64.

Type contient le fichier sp (Starpage). Pour un projet ~forms/ext.sp, on écrit ext.

Si on écrit, par exemple, nantes/docrh cela fait référence à un fichier à ~starjet/forms/nantes/docrh.sp

deleteFile à false conserve les fichiers data et PDF sur le serveur. Si absent ou pas égal à false, il est tenu compte de la valeur dans /WEB-INF/classes/config.properties security_tmp_file_duration

La securityKey est une clé MD5 composée de la concaténation d’un clé publique propre à l’installation, du format attendu et du type.

La connaissance de la clé publique permet aux applications appelantes d’accéder au Webservice. Elle est dans le fichier de configuration sur le serveur et les appels codent de leur côté cette clé.

Le retour est un PDF renvoyé dans le flux plus certaines informations dont le nombre de pages.

Outil de génération d’empreinte pour les tests

Appic fourni un exécutable StarpageWSRequestCreator.exe qui permet de récupérer les données en base 64 et la security key dans le but de les recopier dans l’interface Postman ou SoapUI.

METHODES EXPOSEES

Les méthodes suivantes sont à ce jour mises en œuvre.

Création PDF et effacement du serveur StarpageWS
Création PDF sans effacement du serveur StarpageWS
Effacement des fichiers data et PDF du serveur
Récupération d’un PDF précédemment créé et non effacé

Interface du WS

{
"openapi" : "3.0.0",
"info" : {
"version" : "1.0",
"title" : "Starpage document management",
"description" : "The purpose of this API is to create, view, or delete starpage documents. To do this, several methods are available and described below."
},
"paths" : {
"/api/documents" : {
"post" : {
"summary" : "Create document",
"description" : "From this API, you will be able to generate a document from certain parameters.\n",
"parameters" : [ {
"in" : "header",
"name" : "securityKey",
"description" : "This key is required to validate all transactions with the webservice.<br>The procedure to generate this key is <code><strong>MD5([type][data][password])</strong></code>",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"requestBody" : {
"content" : {
"application/x-www-form-urlencoded" : {
"schema" : {
"$ref" : "#/components/schemas/Document"
}
}
},
"description" : "Below is the list of parameters to fill in the HTTP body. <strong>These settings are required for document generation.</strong>"
},
"responses" : {
"200" : {
"description" : "Document is created correctly and returned",
"headers" : {
"duration" : {
"schema" : {
"type" : "integer"
},
"description" : "Duration of document creation (in second(s))",
"example" : 3
},
"nbPages" : {
"schema" : {
"type" : "integer"
},
"description" : "Number of pages",
"example" : 4
},
"size" : {
"schema" : {
"type" : "integer"
},
"description" : "Size of document (octet)",
"example" : 256000
},
"fileId" : {
"schema" : {
"type" : "string"
},
"description" : "Unique ID of generated document (not is name on server)",
"example" : 5.032018172742146E15
}
},
"content" : {
"application/" : {
"schema" : {
"format" : "binary"
}
}
}
},
"201" : {
"description" : "Document is created correctly and not returned",
"headers" : {
"duration" : {
"schema" : {
"type" : "integer"
},
"description" : "Duration of document creation (in second(s))",
"example" : 3
},
"nbPages" : {
"schema" : {
"type" : "integer"
},
"description" : "Number of pages",
"example" : 4
},
"size" : {
"schema" : {
"type" : "integer"
},
"description" : "Size of document (in ko)",
"example" : 256000
},
"fileId" : {
"schema" : {
"type" : "string"
},
"description" : "Unique ID of generated document (not is name on server)",
"example" : 5.032018172742146E15
}
},
"content" : {
"application/json" : {
"schema" : {
"type" : "object",
"properties" : {
"fileId" : {
"type" : "string",
"description" : "Unique ID of generated document (not is name on server)",
"example" : 5.032018172742146E15
}
}
}
}
}
},
"204" : {
"description" : "Document is created correctly and returned but it is empty",
"headers" : {
"duration" : {
"schema" : {
"type" : "integer"
},
"description" : "Duration of document creation (in second(s))",
"example" : 3
},
"nbPages" : {
"schema" : {
"type" : "integer"
},
"description" : "Number of pages (always 0 in this case)",
"example" : 0
},
"size" : {
"schema" : {
"type" : "integer"
},
"description" : "Size of document (in ko)",
"example" : 256000
},
"fileId" : {
"schema" : {
"type" : "string"
},
"description" : "Unique ID of generated document (not is name on server)",
"example" : 5.032018172742146E15
}
},
"content" : {
"application/" : {
"schema" : {
"format" : "binary"
}
}
}
},
"400" : {
"description" : "\\\"format\" or \"type\" or \"data\"is missing in the request"
},
"401" : {
"description" : "\\\"securityKey\" is missing or invalid"
},
"404" : {
"description" : "\\\"format\" or \"type\" or \"data\" is invalid"
},
"500" : {
"description" : "Internal error"
}
}
}
}
},
"components" : {
"schemas" : {
"Document" : {
"type" : "object",
"required" : [ "format", "data", "type" ],
"properties" : {
"format" : {
"type" : "string",
"description" : "It defines the document format to be generated.",
"example" : "PDF",
"enum" : [ "PDF", "PDF-C", "PDF-A", "DOC" ]
},
"type" : {
"type" : "string",
"description" : "This is the name of the <em>.sp</em> file without the extension.<br>The file must be accessible from the directory defined in the webservice configuration. <br>If the scenario file is in a subfolder, it is possible to specify its relative path.<br><code>Example : myScenarios/contract</code>",
"example" : "contract"
},
"data" : {
"type" : "string",
"description" : "This is the content of your data file. It must be <em>encoded in base64</em>.",
"example" : "SGVyZSBpcyB0aGUgY29udGVudCBvZiBteSBkYXRhIGZpbGUu"
}
}
}
}
}
}

JOURNAL

Le journal est stocké dans ~starjet/logfiles/starpagews. Il est créé un fichier par jour.

DocumentsHistory_<date>.csv

exemple: DocumentHistory_28-02-2018.csv L’application n’efface pas les logs.

Les champs sont:

Date	Jour, heure, minute,seconde
Action	Création ou effacement
Type	Scénario de mise en page
Format	PDF,PDF-C, (…)
File	ID Numéro unique de job
Number of pages
Size (octet)
Duration (s)	`Temps pour générer le PDF sur le serveur`
Full File name	Nom complet sur le serveur

CODES RETOUR

Les erreurs techniques de Starpage WS sont dans le fichier ~starjet/logfiles/starpage/starpageWS.log.

-100	Le fichier sj.lic n’a pas pu être ouvert
-101	Problème pour decrypter la chaine
-102	Le nom de la machine ne correspond pas à celui enregistré
-103	Le compteur de pages est inférieur à 0
-104	Le compteur de pages a atteint son maximum
-105	Problème lors de la mise à jour du fichier sj.lic
-106	Problème lors de la définition PDF
-107	Problème pour charger PDFLIB
-108	CLNBD2 dans la base de registre non trouvé (windows only)
-109	DocCount dans la base de registre non trouvé (windows only)
-110	Les compteurs ne sont pas en phase
-111	Impossible d’ouvrir le fichier temporaire généré par sjet_ex02

Les erreurs fonctionnelles sont retournées sur le WebService selon les codes suivants :

Code	Description
400	*“format” or “type” or “data”is missing in the request*
401	*“securityKey” is missing or invalid*
404	*“format” or “type” or “data” is invalid*
500	*Internal error : StarpageWS licence is not valid* Le produit StarpageWS n’est pas validé. Contacter le support APPIC
500	*Internal error : PDFLib licence file not found* Fichier de licence non trouvé ou inadapté. Mauvais package d’installation ou procédure d’installation non suivie.
500	*Internal error : SP file (type) not found* Fichier scénario Starpage (*.sp) non chargé ou vérifier le chemin dans la configuration du WebService
500	*Internal error : StarpageWS is not installed or not found* Installer le binaire StarpageWS ou vérifier le chemin dans la configuration du WebService

Code	Description
200
201
204