La demande d’intégration de rapports et de gestion de contenu au sein d’une application web est aujourd’hui incontournable. Cependant plusieurs problématiques telles que la gestion des ressources permettant la génération des rapports, la gestion des droits ou bien encore la gestion des différents formats de sortie souhaités peuvent vite devenir complexes à mettre en œuvre et à maintenir. Cet article a pour objectif de présenter une solution simple et efficace d’intégration de rapport par l’utilisation de l’API REST de JasperServer (version 4.5 Community Edition).

# Présentation de JasperServer

JasperServer (disponible sous deux licences : GPL et commerciale) est la plateforme décisionnelle de JasperSoft, elle propose des fonctionnalités de reporting et d’analyse.

JasperServer est un serveur de rapports interactif, autonome et ad hoc intégrable permettant d’obtenir des informations adéquates liées à un besoin, en temps réel. L’interface n’utilise pas de portail tiers contrairement aux autres plates-formes. On dispose ici d’une application web développée spécifiquement qui permet de créer de nouvelles analyses, de publier de nouveaux documents, de gérer les comptes utilisateurs, leurs rôles, ainsi que les droits d’accès aux différents répertoires et fichiers du référentiel.

screenshoot_jasperserver_1

JasperServer intègre également la gestion des paramètres nécessaires à la génération de rapport. Les contrôles d’entrée des rapports peuvent être mono ou multi-valués, le peuplement des contrôles peut se faire soit par une liste de valeurs pré-définies par le créateur, soit afficher le résultat issu d’une requête effectuée sur une base de données.

screenshoot_jasperserver_2

 

# L’API REST

Depuis la version 4, JasperServer met à disposition une API RESTful basée sur les standards offerts par le protocole HTTP (utilisation de GET, POST, PUT, DELETE pour la gestion des ressources).

Chaque service offre toutes les fonctions basiques de JasperServer tel que l’exécution, l’ajout ou la suppression de rapport, une gestion complète de son arborescence, etc…

URL type d’accès à l’API REST:

http://<host>:<port>/jasperserver/rest/

Une illustration de l’appel vers chacun des services sera réalisé par un outil appelé REST Client qui est un plugin de FireFox permettant de concevoir des requêtes HTTP basées sur RFC2616 (HTTP/1.1).

# L’authentification

L’accès aux ressources par le service REST n’est possible que pour un utilisateur de JasperServer déjà identifié.

A ce titre, l’API offre deux types d’authentifications possibles sur le même service :

URL du service d’authentification
http://<host>:<port>/jasperserver/rest/login/
Méthode Description
POST Méthode d’authentification a privilégier, celle ci retourne un jeton de session réutilisable.
GET Méthode d’authentification de test. Celle-ci est facilement appelable depuis un navigateur web, cependant aucun jeton de session n’est renvoyé.
Argument Type Description
j_username Text Login de l’utilisateur
j_password Text Mot de passe de l’utilisateur

 

# L’accès aux ressources

L’API permet d’interroger l’entrepôt de JasperServer afin d’obtenir une description détaillée des ressources présentes.

Chacune des ressources est identifiée par un chemin interne du référentiel de JasperServer.

Il existe deux niveaux de détail pour l’interrogation des ressources.

# Interrogation sur un dossier

L’API REST fournit une description XML (que nous décrirons plus tard) de toutes les ressources disponibles à partir du chemin d’un dossier spécifié dans l’URL d’appel du service.

Méthode URL
GET http://<host>:<port>/jasperserver/rest/resources/chemin/vers/dossier/
Argument Type Descrition
q Texte Retourne uniquement les ressources qui possèdent ce texte dans leur nom ou leur description
type wsType Ne retourne que les ressources correspondant au type précisé. (datasource, folder, etc…)
recursive 0 ou 1 Si ce paramètre est précisé à 1, les ressources des sous-dossiers seront elles aussi renvoyées. Si cet argument n’est pas précisé, il est considéré comme étant à 0 et retournera uniquement les ressources appartenant au dossier.
limit Integer positif Définit le nombre maximum de résultats renvoyés. Si cet argument n’est pas précisé, il est considéré comme étant à 0 ce qui équivaut à ne pas avoir de limite de résultat.

 

# Interrogation détaillée d’une ressource.

Même principe que pour l’interrogation d’un dossier vu précédemment, JasperServer fournit un descriptif plus détaillé d’une ressource bien localisée sur son entrepôt de données. Cette description est bien évidement toujours sous un format XML.

Méthode URL
GET http://<host>:<port>/jasperserver/rest/resource/chemin/vers/resource/
Argument Type Description
file Texte Permet de télécharger directement la ressource sous sa forme originale
… … D’autres arguments peuvent être utilisés dans le cas de la gestion des contrôles d’entrée de JasperServer.

 

# Analyse du XML d’une ressource

Balise ressource descriptor :

Cette balise représente la ressource elle-même. Elle est définie par ses attributs:

name: représente le nom de la ressource dans l’entrepôt JasperServer.

wsType: représente le type de ressource (reportUnit pour un rapport, datasource pour une connexion à une base de données, folder pour un dossier, etc…).

uriString: représente le chemin interne de la ressource dans l’entrepôt JasperServer.

resourceProperty: balise contenant certaines propriétés de la ressource tel que son dossier parent, si la ressource est une référence, etc…

Autres balises enfants :

label: Nom de la ressource définie par le créateur

description: Description de la ressource définie par le créateur

creationDate: nombre de millisecondes écoulées depuis 1970

resourceProperty: Propriété spécifique de la ressource. Les propriétés dépendent du type de ressources

resourceDescriptor: Une autre ressource nécessaire au bon fonctionnement de la ressource courante (exemple, une connexion à une base de données pour un rapport)

exemple de réponse de l’API pour une ressource:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
<resourceDescriptor name="rapport_test0" wsType="reportUnit" uriString="/********/rapport_test0" isNew="false">
        <label><![CDATA[R00 - Liste exploitations en 2011]]></label>
        <creationDate>1354285109117</creationDate>
        <resourceProperty name="PROP_RESOURCE_TYPE">
                <value><![CDATA[com.jaspersoft.jasperserver.api.metadata.jasperreports.domain.ReportUnit]]></value>
        </resourceProperty>
        <resourceProperty name="PROP_PARENT_FOLDER">
                <value><![CDATA[/*********]]></value>
        </resourceProperty>
        <resourceProperty name="PROP_VERSION">
                <value><![CDATA[0]]></value>
        </resourceProperty>
        <resourceProperty name="PROP_RU_ALWAYS_PROPMT_CONTROLS">
                <value><![CDATA[true]]></value>
        </resourceProperty>
        <resourceProperty name="PROP_RU_CONTROLS_LAYOUT">
                <value><![CDATA[1]]></value>
        </resourceProperty>
        <resourceDescriptor wsType="datasource" isNew="false">
                <resourceProperty name="PROP_REFERENCE_URI">
                        <value><![CDATA[/**********/ressources/bdaplat]]></value>
                </resourceProperty>
                <resourceProperty name="PROP_IS_REFERENCE">
                        <value><![CDATA[true]]></value>
                </resourceProperty>
        </resourceDescriptor>
        <resourceDescriptor name="rapport_test0_jrxml" wsType="jrxml" uriString="/***********/rapport_test0_files/rapport_test0_jrxml" isNew="false">
                <label><![CDATA[Main jrxml]]></label>
                <description><![CDATA[Main jrxml]]></description>
                <creationDate>1354285109117</creationDate>
                <resourceProperty name="PROP_RESOURCE_TYPE">
                        <value><![CDATA[com.jaspersoft.jasperserver.api.metadata.common.domain.FileResource]]></value>
                </resourceProperty>
                <resourceProperty name="PROP_PARENT_FOLDER">
                        <value><![CDATA[/*************/rapport_test0_files]]></value>
                </resourceProperty>
                <resourceProperty name="PROP_VERSION">
                        <value><![CDATA[0]]></value>
                </resourceProperty>
                <resourceProperty name="PROP_IS_REFERENCE">
                        <value><![CDATA[false]]></value>
                </resourceProperty>
                <resourceProperty name="PROP_HAS_DATA">
                        <value><![CDATA[true]]></value>
                </resourceProperty>
                <resourceProperty name="PROP_ATTACHMENT_ID">
                        <value><![CDATA[attachment]]></value>
                </resourceProperty>
                <resourceProperty name="PROP_RU_IS_MAIN_REPORT">
                        <value><![CDATA[true]]></value>
                </resourceProperty>
        </resourceDescriptor>
</resourceDescriptor>

Récupération d’un rapport

L’obtention d’un rapport se fait en 2 étapes (c.a.d en 2 appels) par l’API REST.

Une première étape consiste à générer le rapport selon les paramètres et le format souhaité.

La deuxième étape permettra de télécharger directement le document final sur le serveur jasper.

# Génération du rapport

Dans un premier temps il est indispensable que le serveur compile le rapport puis le génère. Pour cela il est impératif de lui préciser le format de sortie souhaité et éventuellement fournir au rapport les paramètres nécessaires à sa construction.

Méthode URL
PUT http://<host>:<port>/jasperserver/rest/report/
Argument Type/Value Description
RUN_OUTPUT_FORMAT Texte Format de sortie désiré. Les valeurs possibles sont PDF, XLS,RTF, CSV, XML, HTML. Par défaut le format de sortie est PDF.
Ressource Descriptor Texte (XML) Description XML de la ressource souhaitée. Le XML est basé sur la même structure que le ressource descriptor. Il doit absolument contenir le chemin vers la ressource, son wsType ainsi que les éventuels paramètres à fournir pour la génération (mono ou multi valué). Cette description XML est passée dans le corps de la requête.
PAGE Integer > 0 Lorsque ce paramètre est précisé, seule la page portant le numéro passé en paramètre sera généré.
onePagePerSheet true / false Argument valable uniquement pour les exports sous format XLS. Lorsque la valeur est précisée à true, chaque page du rapport sera sur une feuille de calcul différente. Si le paramètre n’est pas précisé ou qu’il est mis à false, toutes les pages du rapport seront sur la même feuille de calcul. (De préférence, il est conseillé de préciser cet argument à true lorsque le rapport contient un grand volume de données afin d’éviter une erreur mémoire)

La réponse de ce service est une description XML du document généré. Le XML contient un identifiant unique (UUID) pour le document. Cet UUID n’est connu que pour l’utilisateur courant, il n’est utilisable que par ce dernier. L’UUID sera réutilisé pour télécharger le document final sur le serveur.

Exemple de réponse du service:

1
2
3
4
5
6
7
8
<report>
        <uuid>6f018326-a51b-4512-b601-f22caeb15fed</uuid>
        <originalUri>/**********/rapport_test0</originalUri>
        <totalPages>99</totalPages>
        <startPage>1</startPage>
        <endPage>99</endPage>
        <file type="application/pdf"><![CDATA[report]]></file>
</report>

# Récupération du rapport

Il ne reste plus maintenant qu’à télécharger le document final par une simple requête HTTP (GET) en utilisant l’UUID précédemment obtenu.

Méthode URL
GET http://<host>:<port>/jasperserver/rest/report/<UUID>

Le retour de ce service est le document final généré par JasperServer.

Gestion des contrôles d’entrée

Les contrôles d’entrée sont considérés comme des ressources à part entière. Les descriptions et la récupération des données sont disponibles en appelant le service « Interrogation détaillée d’une ressource ».

Facilement interrogeable, ces derniers peuvent très bien s’intégrer aux sein d’une application web métier.

Écran de gestion depuis JasperServer:

 

Ci-dessous un exemple d’écran de gestion depuis une application web:

# Encore plus de services par l’API

Outre la gestion des rapports (contrôles d’entrées et génération selon le format de sortie), JasperServer propose une gestion complète (listing, création, modification et suppression) des utilisateurs et des rôles par l’API REST (utilisation des GET, PUT, POST et DELETE).

Cela permet de piloter entièrement les utilisateurs et leurs droits en s’affranchissant du back-end d’administration mis à disposition par JasperServer.

# Intégration au sein d’une application web métier

L’intégration de génération de rapports peut s’intégrer facilement dans un portail web 2.0 au moyen d’AJAX. L’architecture typique de mise en place de cette solution se fera dans la plupart des cas de cette manière.

# Bilan

Avec la mise en place de son API RESTful, JasperServer 4.5 à su proposer un ensemble de services répondant aux besoins majeurs pour une intégration simple aux application web 2.0. Cependant cette version souffrait encore de quelques manques, comme par exemple la gestion des valeurs par défaut des contrôles d’entrées ou l’impossibilité de gérer des taches planifiées.

L’API a ainsi été enrichie dans JasperServer 4.7 (Juillet 2012): elle propose ainsi un service REST entièrement remanié avec un nouveau service appelé « rest_v2 » offrant une plus grande simplicité d’interrogation des services, une réponse possible des services sous format JSON, la gestion complète des taches planifiées, etc.

En résumé, JasperServer grâce à son architecture étendue de services Web REST offre des performances et une convivialité hors pair pour l’intégration à des applications mobiles natives et Web.

Tweetez
Partagez
Partagez
0 Partages