Reports (Main.Reports)

== Introduction ==

La plateforme REQUEA integre le moteur de reporting JasperReports.

Ce moteur vous permet de créer des rapports sous forme de liste, graphiques ou détail d'un enregistrement. Ces rapports peuvent être générés sous forme de PDF, stockés dans la base ou envoyés par email.

5

6

Ces rapports JasperReports sont définis sous forme de fichier .jrxml. Ils sont typiquement crées avec l'outil de conception des rapports iReport.

7

8

9

NOTE: La documentation iReport est disponible sous forme de livre que nous recommandons d'acheter:

10

11

[[http://www.jaspersoft.com/ireport-ultimate-guide documentation iReport sur le site JasperSoft]]

12

13

'''Requea ne fournit aucun support ou assistance sur la conception des rapports iReport / JasperReports'''.

14

15

Veuillez consulter la documentation iReport, acheter les livres édités par JasperSoft, ou acheter du service ou de la formation iReport / JasperSoft si vous en avez besoin.

16

iReport est un outil open source développé par JasperSoft qui offre un certain nombre de services autour de son outil. Requea ne fournit pas de services autour de iReport, ni payant et encore moins gratuit.

== Installation ==

NOTE: Versions de iReport / JaspertReports

23

iReport est un outil qui évolue vite. En particulier depuis le passage à NetBeans. Pour ces raisons, le plugin en version 3.0.0 n'est plus maintenu.

24

25

A la place, nous intégrons une version sous forme de module netbeans qui fait l'intégration iReport / dynapage. Cette intégration offre les fonctionalités suivantes:

26

27

- connection Dynapage pour faire des query HQL (DynapageQL) sur le modèle Dynapage.

28

29

- autodescription du modèle de données via HTTP / HTTPS permettant de concevoir des rapports sur un serveur hébergé.

30

31

Pour installer le module netbeans:

32

33

* télécharger le module netbeans à l'adresse suivante:

34

* télécharger iReport depuis le site de JasperReports.

35

* Dans le menu Tools / Plugins, dans l'onglet "Downloaded", cliquer sur le bouton Add Plugins..., sélectionner le module .nbm

36

* Puis sélectionner le plugin et cliquer sur install.

37

38

(((

39

(% class="Apple-style-span" style="line-height: 19px;" %)[[image:VoilaCapture25.png]]

)))

[[image:VoilaCapture26.png]]

== HQL vs SQL ==

Vous avez le choix entre 2 langages de query pour vos rapports:

==== SQL ====

'''Avantages''':

* plus puissant, plus souple

'''Inconvénients''':

* pas portable d'un moteur de base de données à un autre (Oracle / mySQL / MSSQL)

62

* les expressions SQL sont plus lourdes

63

* les libellés d'options ne sont pas repris

64

* vous devez utiliser un outil d'introspection de la base afin de connaitre le nom des tables et champs (même si ceux ci sont directement calqués sur le nom des entités et propriétés

65

66

==== HQL (Hibernate Query Language) ====

Avantages

* portable d'un moteur de base de données à l'autre

71

* expressions plus simple (en particulier sur les jointures)

Inconvénients

* moins connu: documentation disponible sur : [[http://docs.jboss.org/hibernate/core/3.3/reference/en/html/queryhql.html Documentation Hibernate Query Language sur le site de JBoss]]

76

* le modèle de données doit inclure toutes les relations. Il n'est pas possible de construire des jointures "au vol". Vous ne pouvez utiliser que les relations définies sous forme de référence dans Requea

==== Conclusion ====

* Utilisez le SQL si vous êtes dans le cadre d'un '''projet''' (un seul client) et que vous êtes à l'aise avec

81

* Utilisez le HQL si vous êtes dans le cadre d'un '''produit''' (qui sera potentiellement utilisé par plusieurs clients)

82

83

== Création d'une connexion ==

84

85

La création d'une source de données se fait en cliquant sur le bouton correspondant dans la barre d'outils de iReport:

86

87

[[image:jsr-tool.jpg]]

88

89

En cliquant sur le bouton "New", vous pouvez alors créer votre datasource: JDBC pour une connexion SQL, ou "Dynapage Instance" pour une connexion qui utilisera le language HQL.

90

91

[[image:jsr-datasource.jpg]]

92

93

[[image:jsr-sourceinst.jpg]]

== Query Dynapage ==

Une fois que vous êtes dans votre rapport (après avoir fait "New" par exemple), vous pouvez créer la requête qui vous permettra de récupérer les données de la base.

100

101

[[image:jsr-queryl.jpg]]

102

103

=== Choix du language de query ===

104

105

Attention pour le HQL sur la base Requea, il faut choisir "Dynapage QL" et non "Hibernate Query Language (HQL)"

=== Query ===

Voici un exemple (simple) de query. A droite, un arbre affiche les propriétés disponibles. Note: il faut parfois modifier légèrement la query à gauche (tapper un espace et l'enlever) pour que l'arbre se rafraichisse en particulier quand il est vide)

111

112

[[image:jsr-query.jpg||alt="png"]]

113

114

==== Sélection de champs ====

115

116

[[image:jsr-queryfields.jpg]]

117

118

==== Références / Champs distants ====

119

120

Double click sur une référence de cardinalité 1: vous permet d'aller chercher directement les champs de l'objet référencé.

121

122

[[image:jsr-field.jpg]]

123

124

==== Traitement des options ====

125

126

Par défaut, la valeur retournée est la valeur stockée dans la base (valeur interne). Dans le cas ou vous avez une option, vous pouvez double cliquer sur le champ pour avoir accès à la propriété "title". Elle retournera le libellé de l'option correspondant à la valeur interne

127

128

[[image:jsr-opttitle.jpg]]

129

130

==== Utilisation des champs ====

131

132

Une fois que vous avez sélectionné vos champs (et les avoir ajouté en cliquant sur le bouton "Add selected fields", vous pouvez les utiliser dans votre rapport.

133

134

[[image:jsr-fields.jpg]]

== Sous rapports ==

Dans Jasperreports, les sous listes et les graphiques doivent être traitées comme des sous rapports. Vous allez donc très rapidement être amené à intégrer des sous rapports dans vos rapports.

140

141

Pour l'utilisation des sous rapports, voir la documentation iReport (JasperSoft).

142

143

Les seuls points important sont:

144

145

* le répértoire de base du sous rapport qui doit être spécifié pour que le déploiement du rapport soit possible sur la plateforme Requea "SUBREPORT_DIR"

146

* la connexion

147

148

Ci dessous les étapes de création d'un sous rapport.

149

150

[[image:jsr-subreport1.jpg]]

151

152

[[image:jsr-subreport2.jpg]]

153

154

[[image:jsr-subreport3.jpg]]

155

156

[[image:jsr-subreport4.jpg]]

==== SUBREPORT_DIR ====

161

162

Ce paramètre est obligatoire pour que le rapport principal puisse trouver le rapport sur le serveur une fois déployé.

163

164

Nous vous conseillons de le définir dans tous vos rapports. (Il est obligatoire dans tout rapport qui va inclure des sous rapports, donc le définir une fois au début permet d'éviter de l'oublier).

165

166

Mettez pour valeur par défaut le répertoire qui contient vos rapports:

167

168

[[image:jsr-subreportdir.jpg]]

169

170

171

A noter: le subreport_dir doit aussi être utilisé pour les images fixes (Propriété "Image Expression"):

172

173

[[image:jsr-subreportdir2.jpg]]

174

175

== Déploiement sur plateforme cible ==

176

177

Le déploiement sur la plateforme Requea se fait par la création d'une entité "JasperReports".

178

179

Dans le menu "Design / Rapports et graphiques" lorsque vous êtes connecté comme "RequeaDev"

180

181

182

[[image:jsr-deploy1.jpg]]

183

184

[[image:jsr-deploy2.jpg]]

185

186

187

Les champs importants sont:

188

189

* Le bundle est le bundle dans lequel le rapport sera placé.

190

* Le format (par défaut, PDF)

191

* Le fichier est le fichier jrxml du rapport principal

192

* les sous rapports et logos doivent être uploadés

193

* les paramètres. A noter la possibilité de mettre des valeurs de type ${xxx} qui seront évaluées lors de la génération du rapport.

194

195

[[image:jsr-deploy3.jpg]]

196

197

== Génération du rapport ==

198

199

Les rapports peuvent être générés dans une action (sur click puis download du résultat par l'utilisateur), ou dans une opératio, ce qui permet de mettre le résultat en attachement d'un objet et donc de le stocker ou de l'envoyer via un workflow par exemple.

=== Dans une action ===

204

205

Dans une action, le rapport peut être généré en utilisant une étape de type "Print".

206

207

208

Par exemple, essayons d'imprimer un rapport qui contient 2 paramètres de type date à saisir par l'utilisateur.

209

210

Dans cet exemple, nous avons un rapport jrxml qui utilise les 2 paramètres de type java.util.Date: parameter1 et parameter2

211

212

213

[[image:jsr-deploy4.jpg]]

214

215

216

==== définition du rapport ====

217

218

Dans Design / Rapports et graphiques / Rapports Jasper, on crée un nouveau rapport:

219

220

[[image:jsr-deploy5.jpg]]

221

222

223

A noter les 2 paramètres qui sont définis : parameter1 et parameter2 et les expressions pour les valeurs (plus d'explications dans la suite)

224

225

==== définition de l'entité qui va permettre la saisie des paramètres ====

226

227

Les 2 paramètres doivent être saisis par l'utilisateur. Pour cela on crée une entitée non persistée.

228

229

[[image:jsr-deploy6.jpg]]

230

231

On lui ajoute 2 propriétés de type date: Param1 et Param2. Dans cet exemple, l'entité a été crée dans le bundle customisations, dont le préfixe est "cust". Le nom complet des propriétés est donc custParam1 et custParam2. D'ou le nom et la syntaxe des expressions des 2 paramètres. A adapter en fonction de vos entités.

232

233

[[image:jsr-deploy6.jpg]]

234

235

236

Puis on crée une action testPrint:

237

238

[[image:jsr-deploy8.jpg]]

239

240

241

La première étape construit un objet custTestReportParams en mémoire et le stocke dans la variable "params"

242

243

La seconde étape permet la saisie des 2 parametres par l'utilisateur de l'objet stocké dans "params"

244

[[image:jsr-deploy9.jpg]]

245

246

247

La 3ème étape déclache la géneration du rapport. Sa définition est la suivante:

248

249

[[image:jsr-deploy10.jpg]]

250

251

A noter le champs Entrée qui permet de préciser l'objet utilisé pour évaluer les expressions de valeur de paramètre (ici "params").

252

C'est cet objet qui servira de base au calcul des ${custParam1} défini dans l'objet "JasperReport" et dont les valeurs seront passées à JasperReports comme paramètres du rapport.

Le résultat est alors le suivant:\\

257

258

[[image:jsr-deploy11.jpg]]

259

260

[[image:jsr-deploy12.jpg]]

261

262

=== Dans une opération ===

263

264

Dans une opération, la génération du rapport se fait par du script:

265

266

// retrieve the report

267

var report = sysReport.Get("402881ff1cbdc5aa011cbde9dfc915ac");

268

// retrieve the PDF result

269

var result = report.PrintReport(data);

270

// set the report as an attachement

271

data.custFile = result.sysData;//

272

273

Dans cet exemple, le rapport est attaché dans la propriété custFile de l'objet

274

275

276

==== Valorisation des paramètres dans l'appel d'opération ====

277

278

Les paramètres peuvent être valorisés de 2 manières:

279

280

* soit en passant un objet en contexte. Les définitions de paramètres seront utilisées et les expressions ${xxxx} seront valorisées par rapport à cet objet.

281

282

// retrieve the PDF result

283

var result = report.PrintReport(data); // the params are calculated based on 'data'

284

285

286

* soit en passant un tableau de paramètres en utilisant un objet avec une notation JSON

287

// retrieve the PDF result

288