> For the complete documentation index, see [llms.txt](https://documentation.efalia.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.efalia.com/documentations/efalia-compose/appic/installation-et-administration/starpage/webservice.md). # Webservice ### 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 (). 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\://:/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 ```json { "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.
The procedure to generate this key is MD5([type][data][password])", "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. These settings are required for document generation." }, "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 .sp file without the extension.
The file must be accessible from the directory defined in the webservice configuration.
If the scenario file is in a subfolder, it is possible to specify its relative path.
Example : myScenarios/contract", "example" : "contract" }, "data" : { "type" : "string", "description" : "This is the content of your data file. It must be encoded in base64.", "example" : "SGVyZSBpcyB0aGUgY29udGVudCBvZiBteSBkYXRhIGZpbGUu" } } } } } } ``` ## JOURNAL Le journal est stocké dans \~starjet/logfiles/starpagews. Il est créé un fichier par jour. DocumentsHistory\_.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** | | -------- | -------------------------------- | | 200 | ![](/files/fUP2oHbjkSvAhIxO1CxZ) | | 201 | ![](/files/mmXYf4LPq2flgQEjzIfd) | | 204 | ![](/files/UKgfKFZMks96pLWJeYd2) | | **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

| --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://documentation.efalia.com/documentations/efalia-compose/appic/installation-et-administration/starpage/webservice.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.