This is an internal documentation. There is a good chance you’re looking for something else. See Disclaimer.

Add Customer Module¶

Adding a new module contains the following steps:

Nr	Required	Description
1	✔	Add Module in Backoffice
2	✔	Create Basic Folder Structure
3	✔	Add new Module to the Parent Pom
4		Add Content to module Folder
5		Add Java Source Folders
6	✔ if 5 is done	Include Resources in Maven Archive

Add Module in Backoffice¶

Each existing module (core, optional and core) must be documented in our Backoffice. This is important because depending on the documented modules the pom.xml will be generated for customer modules.

Open the Entity Module in the backoffice
Create a new Module entitiy
Set a good technical name. The technical name should be the same as it will be called in the folder structure of the nice project
Set the correct type of the module. One of core, optional, customer or between.
Add all required modules. Depending modules are all modules which are used by the new module. This is important because if this module later is added to a customer all depending modules also need to be added to the customer.

Create Basic Folder Structure¶

Create module file hierarchy:

$ mkdir customer/${CUSTOMER}
$ cd customer/${CUSTOMER}
$ ../../src/bin/mkappmodule.sh

This creates the following files within customer/${CUSTOMER}:

etc/application.properties	Customer specific application configuration
etc/customer.acl	Customer specific ACLs
etc/hikaricp.properties	DB connection settings
etc/hikaricp.history.properties	DB connection setting for secondary DB used to store a change history.
etc/s3.properties	S3 object storage configuration
module/module/desriptor/hivemodule.xml	HiveApp configuration
module/module/hiveapp-mount.properties	Make resources available in virtual filesystem provided by HiveApp. This allows mounting files and directories defined in other modules.
module/module/pom.xml	Configuration of resources.
impl/	Submodule containing customer specific implementations. Can be used to override classes defined elsewhere.
pom.xml	Module configuration including dependency configuration.

Add new Module to the Parent Pom¶

Each customer module must be registered in customer/pom.xml.

  <modules>
    <!-- ... more modules -->
    <module>maltech</module>
    <module>neptun</module>
    <module>nhk</module>
    <module>${MODULE}</module>
    <module>nvs</module>
    <module>odags</module>
    <module>odaszh</module>
    <!-- ... more modules -->
  </modules>

Add dependencies¶

As mentioned earlier, for every customer module you create, there needs to be a corresponding module defined in BO. This definition includes dependencies on all optional modules (called marketing modules in BO) that a customer has licensed. This information can be used to generate the dependencies for inclusion in pom.xml. For this go to the customer module and generate the dependencies as shown in the following screenshot:

../../../_images/generate_pom.png — POM generation in BO¶

Important

The generated dependencies can be incorrect under certain circumstances. Go through them and ensure they are correct.

Add dependencies to existing customer/${CUSTOMER}/pom.xml:

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

  <!-- … -->

  <dependencies>
    <!-- add generated dependencies here -->
  </dependencies>

  <!-- … -->

</project>

Configure Application¶

${CUSTOMER}/etc/application.properties was created, edit it as needed:

i18n.locale.available=de-CH,en,fr-CH,it-CH  # languages available on the system
i18n.locale.default=de-CH                   # fall back language

email.default.from=info@CUSTOMER.ch         # global fallback sender address
email.noreply.from=noreply@CUSTOMER.ch      # default noreply mail address
email.allowedFromDomainsRegex=CUSTOMER\.ch  # regex of domains: domain1\.ch|domain2\.net

nice2.dbrefactoring.businessunits=unit1,unit2  # comma separated list of Business Units

Languages and business units can bo found in BO on Installation.

Add Content to module Folder¶

Inside the module folder customer/${CUSTOMER}/module/module different folders which configure the module can be added. Here are the most common use cases:

model

The model folder must be added as soon as you need to

add or adjust entities or relations -> see Entities and Relations
add or adjust text resources -> see Text-Resources
add or adjust forms (list, search, detail) -> see Forms
add or extend a menu (settings or modules) -> see Menu
add reports -> see Reports

db Inside the db folder changesets are placed. See document Changesets.

acl Inside the acl folder all acl rule files are located. See chapter ACL

resources Inside the resources folder JS files are placed. For actions and public flows.

outputtemplate Inside this folder FTL templates are placed which for example can be used for reports.

Add Java Source Folders¶

As soon as any Java code is needed (e.g. for listeners, actions, services, rest-resources, …) a Java module has to be added to the module. There are three different types of Java modules which can be added.

impl -> the implementation of the module specific Java code

To add a new impl module, create customer/${CUSTOMER}/module/impl and add the following folder structure.

../../../_images/impl-folder-structure.png

Open the file customer/${CUSTOMER}/module/impl/pom.xml and add the following content.

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

  <modelVersion>4.0.0</modelVersion>

  <groupId>ch.tocco.nice2.customer.${CUSTOMER}</groupId>
  <artifactId>nice2-customer-${CUSTOMER}-impl</artifactId>
  <packaging>jar</packaging>
  <version>1.0-SNAPSHOT</version>

  <name>nice2-customer-${CUSTOMER}-impl</name>

  <parent>
    <groupId>ch.tocco.nice2</groupId>
    <artifactId>nice2</artifactId>
    <version>1.0-SNAPSHOT</version>
    <relativePath>../../../../pom.xml</relativePath>
  </parent>

  <dependencies>
    <!-- Add module dependencies -->
  </dependencies>

</project>

Now the impl module has to be added to the module pom. Open the file customer/${CUSTOMER}/pom.xml and add the impl module to the modules element.

<modules>
  <module>module</module>
  <module>impl</module>
</modules>

Now the impl module also has to be added as dependency to the module pom. Open the file customer/${CUSTOMER}/module/module/pom.xml and add the impl module as dependency.

<dependencies>
  <dependency>
    <groupId>ch.tocco.nice2.customer.${CUSTOMER}</groupId>
    <artifactId>nice2-customer-${CUSTOMER}-impl</artifactId>
    <version>${project.version}</version>
    <type>jar</type>
    <scope>compile</scope>
  </dependency>
</dependencies>

Now Java files can be added in the folder java.

Include Resources in Maven Archive¶

All resources must be included in the Maven Archive to ensure they are shipped with the archive which is used to ship the application during deployments. Otherwise, resources may be missing during runtime. Usually, resources have one of these file extensions: *.xml, *.acl, *.properties, *.js, *.ftl.

To include files or directories into the archive, declare the resources in customer/${CUSTOMER}/module/module.

Add all resource types you have added in your module folder by appending them to the build element. Take a look at the following example:

 <build>
   <resources>
     <resource>
       <directory>descriptor</directory>
       <includes>
         <include>hivemodule.xml</include>
       </includes>
       <targetPath>.</targetPath>
     </resource>
     <resource>
       <directory>model</directory>
       <includes>
         <include>**/*.xml</include>
         <include>**/*.properties</include>
       </includes>
       <targetPath>model</targetPath>
     </resource>
     <resource>
       <directory>acl</directory>
       <includes>
         <include>*.acl</include>
       </includes>
       <targetPath>acl</targetPath>
     </resource>
     <resource>
       <directory>db</directory>
       <includes>
         <include>**/*.xml</include>
       </includes>
       <targetPath>db</targetPath>
     </resource>
  </resources>
</build>

create a resource element for each folder with resources
inside the directory element the folder which contains any resources must be set.
inside the include element it is specified what kind of files from this folder are included in the archive.