document

This application was generated using JHipster 6.5.1, you can find documentation and help at https://www.jhipster.tech/documentation-archive/v6.5.1.

This is a "microservice" application intended to be part of a microservice architecture, please refer to the Doing microservices with JHipster page of the documentation for more information.

This application is configured for Service Discovery and Configuration with Consul. On launch, it will refuse to start if it is not able to connect to Consul at http://localhost:8500. For more information, read our documentation on Service Discovery and Configuration with Consul.

Development

To start your application in the dev profile, simply run:

./gradlew

For further instructions on how to develop with JHipster, have a look at Using JHipster in development.

Doing API-First development using openapi-generator

OpenAPI-Generator is configured for this application. You can generate API code from the src/main/resources/swagger/api.yml definition file by running:

./gradlew openApiGenerateDocument

Then implements the generated delegate classes with @Service classes.

To edit the api.yml definition file, you can use a tool such as Swagger-Editor. Start a local instance of the swagger-editor using docker by running: docker-compose -f src/main/docker/swagger-editor.yml up -d. The editor will then be reachable at http://localhost:7742.

Refer to Doing API-First development for more details.

Building for production

Packaging as jar

To build the final jar and optimize the documents application for production, run:

./gradlew -Pprod clean bootJar

To ensure everything worked, run:

java -jar build/libs/*.jar

Refer to Using JHipster in production for more details.

Packaging as war

To package your application as a war in order to deploy it to an application server, run:

./gradlew -Pprod -Pwar clean bootWar

Testing

To launch your application's tests, run:

./gradlew test integrationTest jacocoTestReport

For more information, refer to the Running tests page.

Code quality

Sonar is used to analyse code quality. You can start a local Sonar server (accessible on http://localhost:9001) with:

docker-compose -f src/main/docker/sonar.yml up -d

You can run a Sonar analysis with using the sonar-scanner or by using the gradle plugin.

Then, run a Sonar analysis:

./gradlew -Pprod clean check jacocoTestReport sonarqube

For more information, refer to the Code quality page.

Using Docker to simplify development (optional)

You can use Docker to improve your JHipster development experience. A number of docker-compose configuration are available in the src/main/docker folder to launch required third party services.

For example, to start a postgresql database in a docker container, run:

docker-compose -f src/main/docker/postgresql.yml up -d

To stop it and remove the container, run:

docker-compose -f src/main/docker/postgresql.yml down

You can also fully dockerize your application and all the services that it depends on. To achieve this, first build a docker image of your app by running:

./gradlew bootJar -Pprod jibDockerBuild

Then run:

docker-compose -f src/main/docker/app.yml up -d

For more information refer to Using Docker and Docker-Compose, this page also contains information on the docker-compose sub-generator (jhipster docker-compose), which is able to generate docker configurations for one or several JHipster applications.

Continuous Integration (optional)

To configure CI for your project, run the ci-cd sub-generator (jhipster ci-cd), this will let you generate configuration files for a number of Continuous Integration systems. Consult the Setting up Continuous Integration page for more information.

Document generation

MS config document folder structure

<TENANT>
├── document
│   ├── documents.yml -> document specifications config file
│   ├── lep
│   │   └── mapper
│   │       └── DocumentContextMapping$$TEST_DOCUMENT$$around.groovy -> document context mapping LEP
│   └── templates
│       └── jasper
│           └── test_document.jrxml -> JasperReports template

To generates document, describe document specification in the YAML file (documents.yml): Example:

TEST_DOCUMENT:
  allowedDocumentMimeTypes: [application/pdf, text/xml, application/octet-stream, application/vnd.openxmlformats-officedocument.wordprocessingml.document]
  defaultDocumentMimeType: application/pdf
  renderer: JASPER_REPORTS

where:

• TEST_DOCUMENT - unique key of the document specification used to specify which type of a document to generate
• allowedDocumentMimeTypes - list of the allowed document formats specified as MIME types (application/pdf, text/xml etc.)
• defaultDocumentMimeType - default document format to use if no is specified
• renderer - type of the renderer to use for document generation. Currently available (with supported mime types):
  • JASPER_REPORTS (application/pdf, application/xml)

To generates document with sub documents, describe document specification in the YAML file (documents.yml): Example:

TEST_PRIMARY_DOCUMENT:
  allowedDocumentMimeTypes: [application/pdf, text/xml, application/octet-stream, application/vnd.openxmlformats-officedocument.wordprocessingml.document]
  defaultDocumentMimeType: application/pdf
  renderer: JASPER_REPORTS
  subDocuments:
    -  refKey: TEST_SUB_DOCUMENT
       templateInjectionKey: options

TEST_SUB_DOCUMENT:
  allowedDocumentMimeTypes: [application/pdf, text/xml, application/octet-stream, application/vnd.openxmlformats-officedocument.wordprocessingml.document]
  defaultDocumentMimeType: application/pdf
  renderer: JASPER_REPORTS

where:

• TEST_PRIMARY_DOCUMENT - unique key of the document specification, which contains the sub documents
• subDocuments - list of sub documents
  • refKey - unique key of the sub document specification
  • templateInjectionKey - unique key for embedding a sub document in the main document as parameter
• TEST_SUB_DOCUMENT - unique key of the sub document specification used to specify which type of a document to generate

Injection sub document in main document jasper report example:

• Declare report parameter:

<parameter name="options" class="java.io.InputStream" isForPrompting="false"/> 

name - parameter name and equals to templateInjectionKey value

• Declare subreport block

<subreport>
    <reportElement positionType="Float" x="0" y="171" width="550" height="44" uuid="b1888517-25ee-41f2-a61a-f554961b5d07"/>
    <dataSourceExpression><![CDATA[((net.sf.jasperreports.engine.data.JsonDataSource)$P{REPORT_DATA_SOURCE}).subDataSource("options")]]></dataSourceExpression>
    <subreportExpression><![CDATA[$P{options}]]></subreportExpression>
</subreport>

How to generate documents with JasperReports

1. Describe document specification in the documents YAML file with renderer: JASPER_REPORTS

2. Add JasperReports .jrxml file to templates/jasper with document specification key in lower case as a filename (e.g. key = TEST_DOCUMENT - file = test_document.jrxml).

   You can create and edit JasperReports template with Jaspersoft Studio

3. (Optional) Add LEP script for mapping input document context to renderer specific model:

   • location: lep/mapper
   • script name format: DocumentContextMapping$${DOCUMENT_KEY}$$around.groovy
     • where {DOCUMENT_KEY} - key of the document specification

   Mapping script example:

   import static com.icthh.xm.tmf.ms.document.service.generation.util.DocumentContextMappingUtils.joinNullSafe
   
   def context = lepContext.inArgs.context
   
   Map<String, Closure> mappingFunctions = [
           'назва': { ctx ->
               ctx.article.name
           },
           'опис' : { ctx ->
               joinNullSafe(', ', ctx.article.first, ctx.article.second)
           }
   ]
   
   return mappingFunctions.collectEntries(new HashMap<String, String>(), {
       field, func -> [field, func(context)]
   })

   This example shows how you can create a simple map with friendly field names as keys from a complex document context object. Further this map will be passed to Jasper template where you can declare fields by map's keys (ex. $F{назва}).

4. Generate documents by REST endpoint:

   POST /api/documentManagement/binaryDocument/generate

   Request body:

   {
       "key": "TEST_DOCUMENT",
       "documentContext": {
           "article": {
               "name": "Назва статті",
               "first": "перша частина опису",
               "second": "друга частина опису"
           }
       },
       "documentMimeType": "application/pdf"
   }

   where:

   • key - document specification key
   • documentContext - arbitrary document context
   • (Optional) documentMimeType - document mime type

   Response: document file with expected mime type and with document specification key in lower case as a filename (e.g. key = TEST_DOCUMENT - filename = test_document)

FONTS ISSUE: There are several fonts that can be used in documents for all environments, see Default Fonts in JasperReports. For other fonts you need to explicitly add them to classpath of the application:

1. Find required fonts.
2. Export them as .jar via Jaspersoft Studio.
3. Add jar file to classpath of the application.
4. Now you can use them in your documents.

How to generate documents with Carbon

Carbone allow to build reports templates using LibreOffice, Microsoft Word, or Google Docs. Carbone could be used as cloud solution (pricing) or as on-premise installation.

On-premise installation is free to use (Community Edition). "Community Edition" features free of charge and without limits. Please note that advanced functions will not work.

Community vs Enterprise

Official docker

To set up carbon based renderer do the following:

1. Describe document specification in the documents YAML file with renderer: CARBONE

2. Add tenant specific configuration into tenant-config.yml

   renderer:
    carbone:
      url: "http://carbone:4000"
      headers:
       Authorization: "Bearer YOUR_API_TOKEN"

   Where:

   • url - address of carbone installation (https://api.carbone.io in case of using cloud)
   • headers.Authorization - optional parameter, used for cloud version (more info)

3. Add your template file to templates/carbone with document specification key in lower case as a filename (e.g. key = TEST_DOCUMENT - file = test_document.docx).

   You can create and edit template using LibreOffice, Microsoft Word, or Google Docs.

   or use Carbon Studio

ATTENTION: carbon renderer will work with ms-config version=>2.1.16 also environment variable APPLICATION_BINARY_FILE_TYPES should be set for ms-config. Example:

APPLICATION_BINARY_FILE_TYPES = .docx,.odt