The data model defines the structure for the scenarios to import into the application. For more details, refer to Section Managing the Application Data.

In a .jdl file, names should be declared without any whitespace. This includes the:

JDL declarations can be annotated using DOM tags to provide information to DOC generator. For more details, refer to Section Generating the Application Structure.

	Note that, while the data model is described using a JDL file, DOC does not rely on JHipster to generate the application.

The following examples show how DOM tags are inserted in JDL:

entity ResourceUsagePerDay {
  // DOM [primary.keys] : [day]
  day Integer,
  numberOfHours Integer,
}

relationship ManyToOne {
  // DOM [affects.primary.key] : [true]
  Requirement{activity} to Activity{requirements},
  ...
}

The following JDL text provides you with an example of a simple data model:

application {
  // DOM [java.collectorClass] : [<%=collectorClass%>]
}

entity Country {
  // DOM [primary.keys] : [id]
  id String required,
  name String
}

entity Plant {
  // DOM [primary.keys] : [plantId]
  plantId String required,
}

entity Resource {
  // DOM [primary.keys] : [id]
  id String required,
  name String
}

entity ResourceCapacity {
  quantity Integer
}

entity Activity {
  // DOM [primary.keys] : [id]
  id String required,
  name String,
  durationInHours Double
}

entity Precedence {
}

entity Requirement {
  quantity Integer
}

entity Schedule {
  start Instant,
  end Instant
}

entity SolutionSummary {
  // DOM [single.row] : [true]
  start Instant,
  end Instant,
  timespan Integer
}

entity ResourceUsagePerDay {
  // DOM [primary.keys] : [day]
  day Integer,
  numberOfHours Integer,
}

relationship ManyToOne {
  // DOM [affects.primary.key] : [true]
  Requirement{activity} to Activity{requirements},
  // DOM [affects.primary.key] : [true]
  Requirement{resource} to Resource{requirements},
  // DOM [affects.primary.key] : [true]
  Precedence{first} to Activity{successors},
  // DOM [affects.primary.key] : [true]
  Precedence{second} to Activity{predecessors},
  // DOM [affects.primary.key] : [true]
  Schedule{resource} to Resource{schedules}
  // DOM [affects.primary.key] : [true]
  Schedule{activity} to Activity{schedules}
  // DOM [affects.primary.key] : [true]
  ResourceUsagePerDay{resource} to Resource{usagePerDay}
  // DOM [affects.primary.key] : [true]
  Plant{country} to Country{plants}
  // DOM [affects.primary.key] : [true]
  Activity{plant} to Plant{activities}
}

relationship OneToOne {
  // DOM [affects.primary.key] : [true]
  ResourceCapacity{resource} to Resource{capacity}
}

A JDL file should contain exactly one application definition block. In a composite data model, the application block must be placed in the main JDL file.

In DOC context, the collector class name will be injected during the generation of the application. For this injection to succeed, the <%=collectorClass%> placeholder must be provided.

application {
   // DOM [java.collectorClass] : [<%=collectorClass%>]
 }

Any other information is ignored.

	Note that the following application DOM tags are recognized: [java.collectorClass] : [a class name] [java.collectorInterfaces] : [list of comma-separated interface names]

Entities are related to tables in the SQL world and to classes in the java world.

Entities are declared one after the other. The order of the declaration has no impact on the application generation. Entities are described by a unique name and by a set of attributes of elementary types. Attributes that are part of a relationship to another entity are declared separately. Additional information can be provided using DOM tags or annotations.

Valid elementary types for attributes are:

More information on the data types can be found in Section Understanding Data Types

The following sample code declares an entity named Resource which has two attributes:

The DOM tag states that the id attribute is part of the Resource primary key.

entity Resource {
     // DOM [primary.keys] : [id]
     id String required,
     name String
}

	Note that, if Resource was also part of the primary key, then id would have to be replaced by [id, name].

@Description("My entity description")
entity MyEntity {
    @Description("My attribute description \n in multiple lines.")
    myAttribute String
}

@Description("""
        This is a "multiline"
        description.
        """)

entity XXXXX {
   ...
   @DefaultValue("value1")
   attribute1 <elementaryType>
   ...
   @DefaultValue("value2")
   attribute2 <elementaryType>
   ...
}

entity ResourceCapacity {
    @DefaultValue("10")
    quantity Integer
}

entity Employee {
     // DOM [primary.keys] : [id]
     id String required,

     firstName String,
     lastName String,

     @Description("Example of computed field with firstname and lastname")
     @Formula("concat(first_name, ' ', last_name)")
     fullName String
}

entity Company {
     // DOM [primary.keys] : [id]
     id String required,

     @Description("Employees average age")
     @Formula("""
     (SELECT AVG(e.age)
       FROM employee e 
       WHERE e.company = db_gene_internal_id
         AND e.db_gene_internal_scenario_id = db_gene_internal_scenario_id)
     """)
     averageAge Double
}

entity Employee {
     // DOM [primary.keys] : [id]
     id String required,

     firstName String,
     lastName String,
     age Integer
}

relationship ManyToOne {
  // DOM [affects.primary.key] : [true]
  Employee{company} to Company{employees}
}

entity SolutionSummary {
  // DOM [single.row] : [true]
  start Instant,
  end Instant,
  timespan Integer
}

There are two kinds of relationships:

The following relationship DOM tags are recognized and optional:

When a relation is affecting the primary key, the relation is implicitly required (not nullable).

A relation that is not affecting the primary key is by default optional (nullable). To declare that a relation is not nullable, you need to use the required keyword as follows:

For example, the following sample code declares a OneToOne relationship between two entities:

entity Resource {
  // DOM [primary.keys] : [id]
  id String required,
  name String
}

entity ResourceCapacity {
  quantity Integer
}

relationship OneToOne {
  // DOM [affects.primary.key] : [true]
  ResourceCapacity{resource} to Resource{capacity}
}           

This declaration affects the entities as follows:

The following example declares a ManyToOne relationship between two entities:

entity Activity {
     // DOM [primary.keys] : [id]
     id String required,
     name String,
     durationInHours Integer
}
   
entity Precedence {
}

relationship ManyToOne {
  // DOM [affects.primary.key] : [true]
  Precedence{first required} to Activity{successors},
  // DOM [affects.primary.key] : [true]
  Precedence{second required} to Activity{predecessors}
}

This declaration affects the entities as follows:

DOC allows chunking the data model into different components that can depend on one another in a composite data model.

By default, a simple data model application declares only one scenario type while a composite data model declares several scenario types.

In a CDM, a scenario type only describes some entities of the data model. However, it can reference or be referenced by other scenario types to provide the user with all the relevant data when necessary.

This improves performances as it prevents duplicating data and allows synchronizing parts of the model for the purpose at hand. For example, instead of managing a large amount of scenarios with the same reccuring data everytime an operation is performed on an entity attribute, users only need the type of scenario that describes the entity in question.

This makes sense in the example below where the Plant and Country entities from the MasterData scenarios or the Truck Route in the DeliveryData scenarios are less likely to change overtime than the daily Schedule described in the PlanData scenarios.

Figure 2.1. Understanding the Composite Data Model

A composite data model is described across several JDL files, located in the gene-model/spec directory of the project, either directly or organized in subfolders.

Among the JDL files that define the data model description, exactly one must contain an application block. It is called the “main JDL file”, capacity_planning.jdl here.

In a CDM, as opposed to a simple data model, the application block should contain include statements that indicate the additional JDL files to consider in the definition of the data model. Here is an example:

application {
  // DOM [java.collectorClass] : [CapacityPlanning]

  include "master_data.jdl"
  include "delivery_data.jdl"
  include "transactional_data.jdl"
  include "plan_data.jdl"
}

The paths of the included JDL files are considered to be relative to the directory where the main JDL file is stored.

@Description("Master data of the application")
scenarioType MasterData {
}

@Description("Data that yields a new plan")
scenarioType TransactionalData {
   import MasterData
}

Usually, an application model evolves with new versions. Therefore, the database schema has to follow the model definition. This implies data structures and data need to be migrated. For this use case, we rely on the standard tool Flyway.

Flyway keeps trace of the current version of your schema. This allows Flyway to incrementally execute all the migration scripts from your current database schema version to the target schema version.

Figure 2.2. Understanding the Flyway Migration

In this example, your database is already upgraded with a schema in version 1, if you run Flyway, it will migrate your database schema to version 2.

To achieve migrations, Flyway uses so-called migration scripts. Migration scripts are "sequentially ordered SQL scripts" that incrementally migrate your schema.

In order to recognize migration scripts, Flyway relies on the following naming convention:

Figure 2.3. Understanding the Flyway Migration Scripts Naming Convention

An example of migration script folder could be:

gene-model/gene-model-jpa ~> tree -L 1 flyway/db/migration
flyway/db/migration
- v1__Add_item_table.sql # First migration script that adds an 'Activity' table in the SQL schema.
- v2__Add_item_category_table.sql # Migration script that creates an activity table.

By this naming convention Flyway is able to determine that it has to run v2__Add_item_category_table.sql after v1__Add_item_table.sql and only if it has not already been run.

Let's take an example,

Imagine you already have a model with an Item table, and you want to introduce a Category table like in the following diagram.

Figure 2.4. Understanding the Flyway Migration Model

	Note that, in your migration scripts, you will have to migrate the schema AND the existing data.

See below the migration script that will allow us to upgrade V1 schema and data to V2.

It adds a category table and updates the item table accordingly. It also creates a default category and updates the existing Items with it.

-- v2__Add_category_table.sql
-- This migration script introduces item categories.
--

-- #################
-- # Category      #
-- #################

-- Introduce category table
create table category
(
    category_id text not null
        constraint category_pkey
            primary key,
    name text not null
);

alter table category owner to data_server;

create unique index uk_p8a7ixxjnxsm18wq9f1eobrmn
    on category (category_id);

create unique index idx_tdsi66b2e619y4cuympjbrfw7
    on category (name);

-- Create a default category
insert into category (category_id, name) values ('default_category', 'Default');

-- #################
-- # Item          #
-- #################

-- Update item table
alter table item add column category_id text
    constraint fk_1tgju5f47333ash49oqmv8vm2
        references category deferrable;

-- Very important  we migrate the data to (not only the structure). -
-- ------------------------------------------------------------------
-- Update the items accordingly
update item set category_id = 'default_category' where 1 = 1;

6.1. Integrating a Model in the Development Process

The following diagram shows you how to integrate a model in a DOC application.

Figure 2.5. Understanding the Flyway Migration Process

* The migration script generation gradle command is: ./gradlew :gene-model:gene-model-jpa:generateJPAForce

You can see that depending on if you already have a model definition (jdl file) or not;

You will have to launch a gradle task to create a new version in migration scripts and ensure to make the script incremental. The script generated when you edit your model is placed in the following location: gene-model/gene-model-jpa/flyway/db/migration/ and is called: V1.0.000__CREATE_TABLES_AND_CONSTRAINTS.sql.

For example, if I have created an application V1 and now I want to update the JDL with some modification of my data model V2 (e.g. add the category table) without losing the existing data.

1. I need to update the JDL file to implement my new model (V2).

2. I create a flyway migration script "V2.0.0.xxxx.sql" under the folder gene-model/gene-model-jpa/flyway/db/migration/ that will contain the SQL code required to update the schema accordingly to the new model and migrate the existing data (V1).

3. I can rebuild and restart the application with the new model.

	Note that the V1xxxx SQL script is generated only if the migration is empty; To force the regeneration of the V1xxx SQL Script you can use ./gradlew :gene-model:gene-model-jpa:generateJPAForce. This can be useful to generate a new SQL and manually extract the diff with an existing schema.

6.2. Using a Simplified Development Process

There are multiple cases where the migration of scenarios is not required:

• during development phases,

• when the targeted application relies on scenarios as volatile/short term data that does not need to be kept on the long term.

In those cases, developers may launch ./gradlew generateJPAForce after each model change and keep the "all in one" migration script.

In that case, to properly boot the application, the Data Service database must be emptied. A way to achieve this can be to delete the corresponding Docker volumes.

	Warning: Since Keycloak and the Data Service share the same database engine, deleting the volumes will delete the Keycloak configurations. For more details on how to save and restore this configuration, refer to Section Importing and Exporting User Data.