.gitlab-ci.yml

@@ -108,3 +108,15 @@ deploy-test-02:
   environment:
     name: test-02
     url: https://naming-test-02.cslab.esss.lu.se
+
+deploy-ce-test:
+  extends: .deploy
+  script:
+    - >
+      TOWER_OAUTH_TOKEN=$CE_TOWER_OAUTH_TOKEN awx job_templates launch deploy-ce-naming-test 
+      --extra_vars "naming_container_image_tag: $CI_COMMIT_REF_SLUG"
+      --job_tags ce-naming-backend
+      --monitor
+  environment:
+    name: ce-naming-test
+    url: https://ce-naming-test.cslab.esss.lu.se

CONFIGURATION.md

+### Configuration
+
+Configuration may be set using SpringBoot's configuration file (`application.properties`) and environment variables.
+
+##### Environment variables
+
+| Variable                            | Default                                     | Description                                                                                                            |
+|-------------------------------------|---------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
+| **Application**                     |                                             |                                                                                                                        |
+|                                     |                                             |                                                                                                                        |
+| NAMING_DATABASE_URL                 | jdbc:postgresql://postgres:5432/discs_names | JDBC URL for the database connection                                                                                   |
+| NAMING_DATABASE_USERNAME            | discs_names                                 | user name for the database connection                                                                                  |
+| NAMING_DATABASE_PASSWORD            | discs_names                                 | password for the database connection                                                                                   |
+| NAMING_LOGGING_LEVEL                | INFO                                        | log level for application                                                                                              |
+| NAMING_LOGGING_FILTER_INCLUDES      | org.openepics.names                         | comma-separated list of strings to filter stack trace for inclusion (ref. whitelist)                                   |
+| NAMING_LOGGING_FILTER_EXCLUDES      | org.openepics.names.util.ExceptionUtil      | comma-separated list of strings to filter stack trace for exclusion (ref. blacklist)                                   |
+| NAMING_LOGGING_STACKTRACE_LENGTH    | 20                                          | max number of stack trace elements to log, negative value will log entire stack trace                                  |
+| NAMING_MAIL_ADMINISTRATOR           |                                             | comma-separated list of administrator email addresses                                                                  |
+| NAMING_MAIL_NOTIFICATION            | false                                       | true/false if mail notications are to be sent                                                                          |
+| NAMING_MAIL_NOTIFICATION_NAMES      |                                             | comma-separated list of email addresses to which to send notications about changes for names                           |
+| NAMING_MAIL_NOTIFICATION_STRUCTURES |                                             | comma-separated list of email addresses to which to send notications about changes for structures                      |
+| NAMING_NOTIFY_SCHEDULE              | 0 0 5 * * *                                 | schedule for notification job, cron expression with six or seven fields to describe individual details of the schedule |
+| NAMING_SMTP_HOST                    | mail.esss.lu.se                             | DNS name of server that accepts connections for SMTP                                                                   |
+| NAMING_SMTP_PORT                    | 587                                         | port to use for SMTP, 587 for SMTP Secure                                                                              |
+| NAMING_SMTP_USERNAME                |                                             | username for SMTP server                                                                                               |
+| NAMING_SMTP_PASSWORD                |                                             | password for SMTP server                                                                                               |
+|                                     |                                             |                                                                                                                        |
+| **Springdoc, Swagger**              |                                             |                                                                                                                        |
+|                                     |                                             |                                                                                                                        |
+| NAMING_SWAGGER_URL                  | http://localhost:8080/swagger-ui.html       | default url for Swagger UI                                                                                             |
+| API_DOCS_PATH                       | /api-docs                                   | custom path of the OpenAPI documentation in JSON                                                                       |
+| SWAGGER_UI_PATH                     | /swagger-ui.html                            | custom path of the swagger-ui documentation in HTML                                                                    |
+|                                     |                                             |                                                                                                                        |
+| **Security**                        |                                             |                                                                                                                        |
+|                                     |                                             |                                                                                                                        |
+| NAMING_SECURITY_ENABLED             | false                                       | enable security for application                                                                                        |
+| AES_KEY                             | aes_secret_key                              | secret that is used to hash the tokens in the JWT token                                                                |
+| JWT_SECRET                          | secret_password_to_hash_token               | secret that is used sign the JWT token                                                                                 |
+| JWT_EXP_MIN                         | 240                                         | time interval until the JWT token is valid (in minutes)                                                                |
+| RBAC_SERVER_ADDRESS                 |                                             | RBAC server address used for log in users if NAMING_SECURITY_ENABLED is enabled                                        |

Dockerfile.integrationtest

+# ------------------------------------------------------------------------------
+# Copyright (C) 2021 European Spallation Source ERIC.
+# ------------------------------------------------------------------------------
+
+FROM openjdk:17
+
+# deployment unit
+COPY target/naming-backend-*.jar /naming/naming-backend.jar
+
+# code coverage
+COPY target/jacoco/jacocoagent.jar /naming/jacocoagent.jar
+
+CMD ["java", "-jar", "/naming/naming-backend.jar", "--spring.config.name=application"]

README.md

@@ -6,72 +6,73 @@ The purpose of Naming is to handle Naming of ESS wide physical and logical devic
 
 Naming backend is a web application implemented as a REST style web service backed by a relational database. The web service is implemented as a Spring Boot application and the database is available as PostgreSQL.
 
-Background and motivation, application and database design, and more, is available through content in docs folder.
+See `docs` and sub folders to learn how ESS Naming Convention is implemented in Naming backend.
 
 ### Environment
 
 Tools
-* Java  17   (openjdk)
-* Maven 3.8+ (e.g. 3.8.5)
-* PostgreSQL (9.6 client lib)
-* Docker     (docker, docker-compose)
-* Git
-
-Dependencies
-* postgresql
-* springdoc
-* springframework
-* testcontainers
-
-### Set up development environment and test
 
-#### Checkout and build
+* Java 17 - openjdk
+* Maven 3.8+
+* PostgreSQL - client lib 9.6
+* Docker - engine 18.06.0+ or later, compose 2.21.0 or later, compose file version 3.7 to be supported
+* Git
 
-* ```git clone https://gitlab.esss.lu.se/ics-software/naming-backend.git```
-* ```cd directory```
-* ```mvn clean install```
+More on configuration and setting of environment variables is available in [Configuration](CONFIGURATION.md).
 
-#### Start application (with database)
+### Start application
 
-Either
+Start the application and database via Docker. For first time users, the recommended way is to use demo content. See Note for more on configuration.
 
-* start the application and database
-  * ```docker-compose up --build```
+* build and run
+    * `mvn clean install`
+    * `docker-compose up --build`
+    * `docker-compose -f docker-compose-demo.yml up --build`
+*  browse to
+    * `http://localhost:8080/swagger-ui.html`
 
-or
+More on how to start the application is available in [Start application](START_APPLICATION.md).
 
-* make sure database available as in ```src/main/resources/application.properties```
-* start the application
-  * ```java -jar target/naming-backend-*.jar```
+### Integration tests with Docker containers
 
-Then
+Purpose of integration tests is to ensure REST API works as expected for parts and as a whole by running tests against running instances of application and database.
 
-* browse to ```http://localhost:8080/swagger-ui.html```
+See `src/test/java` and package `org.openepics.names.docker`.
 
-#### Integration tests with Docker containers
+Integration tests start docker containers for Naming backend and Postgresql database and run http requests (GET) and curl commands (POST, PUT, PATCH, DELETE) towards the application to test behavior (CRUD - create, read, update, delete) and replies are received and checked if content is as expected.
 
-See ```src/test/java``` and packages
-* ```org.openepics.names.docker```
-* ```org.openepics.names.docker.complex```
+There are tests for names and structures separately and in combination.
 
-JUnit tests start a docker container for the application (Naming backend) and another docker container for the database (Postgresql) through ```docker-compose-integrationtest.yml```.
+Integration tests can be run in IDE and via Maven.
 
 ```
-    @Container
-    public static final DockerComposeContainer<?> ENVIRONMENT =
-        new DockerComposeContainer<>(new File("docker-compose-integrationtest.yml"))
-            .waitingFor(ITUtil.NAMING, Wait.forLogMessage(".*Started NamingApplication.*", 1));
+mvn failsafe:integration-test -DskipITs=false
 ```
 
-Thereafter a number of http requests (GET) and curl commands (POST, PUT, PATCH, DELETE) are run towards the application to test behavior (CRUD - create, read, update, delete) and replies are received and checked if content is as expected.
+See
+* [How to run Integration test with Docker](src/test/resources/INTEGRATIONTEST_DOCKER_RUN.md)
+* [Tutorial for Integration test with Docker](src/test/resources/INTEGRATIONTEST_DOCKER_TUTORIAL.md)
+
+### Note
 
-#### Note
+* Configuration
+    * Application and database may be started separately, with or without Docker, in which case configuration set by environment variables, docker compose files and `application.properties` must reflect this. An example of this is hostname/ip address/port for database that is to be available for application. Configuration must not be in conflict with environment in which application and database run.
+* Pre-populated database to be available if data to be available at start of application. Otherwise database may be populated through `curl` at command line or Swagger UI.
+    * See `src/main/resources` and `src/test/resources` and sub folders for database scripts. This includes scripts for database schema, migration and example content.
+    * If no prior database is available, see integration tests for examples on how to populate database. E.g. tests may be debugged and database content may be examined at any debug point. It's possible to backup database at such debug point and later restore it outside test. In such way, database may be set to state of choice.
 
-* Pre-populated database to be available if data to be available at start of application. Otherwise database may be populated through ```curl``` at command line or Swagger UI.
-  * See ```src/main/resources``` and sub folders for database scripts.
-  * If no prior database is available, see integration tests for examples on how to populate database. E.g. tests may be debugged and database content may be examined at any debug point. It's possible to backup database at such debug point and later restore it outside test. In such way, database may be set to state of choice.
+ ```
+   postgres:
+     volumes:
+       - ./src/test/resources/data/db/dump-discs_names_namesit.sql:/docker-entrypoint-initdb.d/dump-discs_names_namesit.sql
+ ```
 
-#### Recommentation
+* Test
+    * Integration tests and code coverage for unit and integration tests are disabled by default and can be enabled separately and together.
+    * Code coverage for unit tests is enabled by `-Djacoco.skip=false`. Result is available in `target/site/jacoco` folder and includes code coverage execution data and reports.
 
-* Have local docker-compose file for database alone if there is need to backup or restore database.
+### Recommendation
 
+* Have local docker-compose files - `.gitignore` contains `docker-compose-local*`
+    * for application and database together that may contain local configuration
+    * for database alone if there is need to backup or restore database

START_APPLICATION.md

+### Start application
+
+For first time users, the recommended way to start the application and database is with Docker and demo content.
+
+##### With Docker
+
+To start the application with an existing database.
+
+```
+docker-compose up --build
+```
+
+To start the application with an empty database.
+
+```
+docker-compose -f docker-compose-integrationtest.yml up --build
+```
+
+To start the application with a database with demo content.
+
+```
+docker-compose -f docker-compose-demo.yml up --build
+```
+
+Browse to `http://localhost:8080/swagger-ui.html`.
+
+##### With `java -jar`
+
+Make sure the database is available as in `src/main/resources/application.properties`.
+
+To start the application.
+
+```
+java -jar target/naming-backend-*.jar
+java -jar -Dspring.datasource.url=jdbc:postgresql://localhost:5432/discs_names target/naming-backend-*.jar
+```
+
+Browse to `http://localhost:8080/swagger-ui.html`.

docker-compose-demo.yml

+# ------------------------------------------------------------------------------
+# Copyright (C) 2022 European Spallation Source ERIC.
+# ------------------------------------------------------------------------------
+
+version: '3.7'
+services:
+  naming:
+    container_name: "naming"
+    build: ./
+    networks:
+      - naming-net
+    ports:
+      - "8080:8080"
+    depends_on:
+      postgres: 
+        condition: service_healthy
+    command: "java -jar /naming/naming-backend.jar"
+  
+  postgres:
+    container_name: "postgres"
+    image: "postgres:9.6.7"
+    networks:
+      - naming-net
+    ports:
+      - "5432:5432"
+    environment:
+      POSTGRES_DB: discs_names
+      POSTGRES_USER: discs_names
+      POSTGRES_PASSWORD: discs_names
+      PGDATA: /var/lib/postgresql/data/pgdata
+    healthcheck: 
+      test: ["CMD-SHELL", "pg_isready -U discs_names"]
+      interval: 10s
+      timeout: 5s
+      retries: 10    
+    volumes:
+      - ./src/test/resources/data/db/dump-discs_names_namesit.sql:/docker-entrypoint-initdb.d/dump-discs_names_namesit.sql
+
+volumes:
+  naming-data:
+
+networks:
+  naming-net:
+    driver: bridge
+

docker-compose-integrationtest.yml

@@ -5,16 +5,31 @@
 version: '3.7'
 services:
   naming:
-    build: ./
+    build:
+      context: .
+      dockerfile: Dockerfile.integrationtest
+    networks:
+      - naming-net
     ports:
-      - "8080:8083"
+      - "8080:8080"
+    environment:
+      NAMING_LOGGING_LEVEL: TRACE
+      NAMING_MAIL_ADMINISTRATOR: abcd@efgh.ijkl
+      skipITCoverage: "true"
     depends_on:
       postgres: 
         condition: service_healthy
-    command: "java -jar /naming/naming-backend.jar"
-  
+    command: >
+      /bin/bash -c "
+        if [ ${skipITCoverage} == false ]; then
+          export JAVA_TOOL_OPTIONS=-javaagent:/naming/jacocoagent.jar=destfile=/naming/jacoco.exec,output=file,append=false
+        fi
+        java -jar /naming/naming-backend.jar"
+
   postgres:
     image: "postgres:9.6.7"
+    networks:
+      - naming-net
     ports:
       - "5432:5432"
     environment:
@@ -28,10 +43,23 @@ services:
       timeout: 5s
       retries: 10    
     volumes:
-      - ./src/test/resources/db/schema_migration/V1__Initial.sql:/docker-entrypoint-initdb.d/V1__Initial.sql
-      - ./src/test/resources/db/schema_migration/V2__Commit_Msg_to_Device.sql:/docker-entrypoint-initdb.d/V2__Commit_Msg_to_Device.sql
-      - ./src/test/resources/db/schema_migration/V3__Notification_CC_List.sql:/docker-entrypoint-initdb.d/V3__Notification_CC_List.sql
-      - ./src/test/resources/db/schema_migration/V4__Schema_data_migration.sql:/docker-entrypoint-initdb.d/V4__Schema_data_migration.sql
+      - ./src/main/resources/db/migration/V1__Initial.sql:/docker-entrypoint-initdb.d/V1__Initial.sql
+      - ./src/main/resources/db/migration/V2__Commit_Msg_to_Device.sql:/docker-entrypoint-initdb.d/V2__Commit_Msg_to_Device.sql
+      - ./src/main/resources/db/migration/V3__Notification_CC_List.sql:/docker-entrypoint-initdb.d/V3__Notification_CC_List.sql
+      - ./src/main/resources/db/migration/V4__Schema_data_migration.sql:/docker-entrypoint-initdb.d/V4__Schema_data_migration.sql
+      - ./src/main/resources/db/migration/V5.2__Data_transformation_status_deleted.sql:/docker-entrypoint-initdb.d/V5.2__Data_transformation_status_deleted.sql
+      - ./src/main/resources/db/migration/V6.2__Schema_data_migration_audit.sql:/docker-entrypoint-initdb.d/V6.2__Schema_data_migration_audit.sql
+      - ./src/main/resources/db/migration/V7__Remove_user_notification_cc_list.sql:/docker-entrypoint-initdb.d/V7__Remove_user_notification_cc_list.sql
 
 volumes:
   naming-data:
+
+networks:
+  naming-net:
+    driver: bridge
+
+
+# ------------------------------------------------------------------------------
+# Note
+# ------------------------------------------------------------------------------
+# container_name property is not supported by Testcontainers

docker-compose.yml

@@ -5,9 +5,12 @@
 version: '3.7'
 services:
   naming:
+    container_name: "naming"
     build: ./
+    networks:
+      - naming-net
     ports:
-      - "8080:8083"
+      - "8080:8080"
     depends_on:
       - postgres
     command: "java -jar /naming/naming-backend.jar"
@@ -15,6 +18,8 @@ services:
   postgres:
     container_name: "postgres"
     image: "postgres:9.6.7"
+    networks:
+      - naming-net
     ports:
       - "5432:5432"
     environment:
@@ -27,3 +32,7 @@ services:
 
 volumes:
   naming-data:
+
+networks:
+  naming-net:
+    driver: bridge

docs/db/Schema_data_migration.txt

--- --------------------------------------------------------------------------------
--- About
---     migration script
---     postgresql 9.6.7
--- Content
---     structures
---     name
---     data structures level 1
---     data structures level 2
---     data structures level 3
---     data name level 1
---     data name level 2
---     data name level 3
---     index
---     latest
---     foreign key
---     index
---     sequence
---     primary key
---     function
--- Note
---     order of items is important
--- --------------------------------------------------------------------------------
-
--- --------------------------------------------------------------------------------
--- structures
--- --------------------------------------------------------------------------------
-CREATE TABLE systemgroup (
-    id bigint NOT NULL,
-    version integer,
-    uuid character varying(255),
-    name character varying(255),
-    mnemonic character varying(255),
-    mnemonic_equivalence character varying(255),
-    description character varying(255),
-    status character varying(255),
-    latest boolean NOT NULL,
-    deleted boolean NOT NULL,
-    requested timestamp without time zone,
-    requested_by character varying(255),
-    requested_comment character varying(255),
-    processed timestamp without time zone,
-    processed_by character varying(255),
-    processed_comment character varying(255)
-);
-CREATE TABLE system (
-    id bigint NOT NULL,
-    version integer,
-    uuid character varying(255),
-    parent_uuid character varying(255),
-    name character varying(255),
-    mnemonic character varying(255),
-    mnemonic_equivalence character varying(255),
-    description character varying(255),
-    status character varying(255),
-    latest boolean NOT NULL,
-    deleted boolean NOT NULL,
-    requested timestamp without time zone,
-    requested_by character varying(255),
-    requested_comment character varying(255),
-    processed timestamp without time zone,
-    processed_by character varying(255),
-    processed_comment character varying(255)
-);
-
-CREATE TABLE subsystem (
-    id bigint NOT NULL,
-    version integer,
-    uuid character varying(255),
-    parent_uuid character varying(255),
-    name character varying(255),
-    mnemonic character varying(255),
-    mnemonic_equivalence character varying(255),
-    description character varying(255),
-    status character varying(255),
-    latest boolean NOT NULL,
-    deleted boolean NOT NULL,
-    requested timestamp without time zone,
-    requested_by character varying(255),
-    requested_comment character varying(255),
-    processed timestamp without time zone,
-    processed_by character varying(255),
-    processed_comment character varying(255)
-);
--- --------------------------------------------------------------------------------
-CREATE TABLE discipline (
-    id bigint NOT NULL,
-    version integer,
-    uuid character varying(255),
-    name character varying(255),
-    mnemonic character varying(255),
-    mnemonic_equivalence character varying(255),
-    description character varying(255),
-    status character varying(255),
-    latest boolean NOT NULL,
-    deleted boolean NOT NULL,
-    requested timestamp without time zone,
-    requested_by character varying(255),
-    requested_comment character varying(255),
-    processed timestamp without time zone,
-    processed_by character varying(255),
-    processed_comment character varying(255)
-);
-
-CREATE TABLE devicegroup (
-    id bigint NOT NULL,
-    version integer,
-    uuid character varying(255),
-    parent_uuid character varying(255),
-    name character varying(255),
-    mnemonic character varying(255),
-    mnemonic_equivalence character varying(255),
-    description character varying(255),
-    status character varying(255),
-    latest boolean NOT NULL,
-    deleted boolean NOT NULL,
-    requested timestamp without time zone,
-    requested_by character varying(255),
-    requested_comment character varying(255),
-    processed timestamp without time zone,
-    processed_by character varying(255),
-    processed_comment character varying(255)
-);
-
-CREATE TABLE devicetype (
-    id bigint NOT NULL,
-    version integer,
-    uuid character varying(255),
-    parent_uuid character varying(255),
-    name character varying(255),
-    mnemonic character varying(255),
-    mnemonic_equivalence character varying(255),
-    description character varying(255),
-    status character varying(255),
-    latest boolean NOT NULL,
-    deleted boolean NOT NULL,
-    requested timestamp without time zone,
-    requested_by character varying(255),
-    requested_comment character varying(255),
-    processed timestamp without time zone,
-    processed_by character varying(255),
-    processed_comment character varying(255)
-);
-
--- --------------------------------------------------------------------------------
--- name
--- --------------------------------------------------------------------------------
-CREATE TABLE name (
-    id bigint NOT NULL,
-    version integer,
-    uuid character varying(255),
-    systemgroup_uuid character varying(255),
-    system_uuid character varying(255),
-    subsystem_uuid character varying(255),
-    devicetype_uuid character varying(255),
-    instance_index character varying(255),
-    convention_name character varying(255),
-    convention_name_equivalence character varying(255),
-    description character varying(255),
-    status character varying(255),
-    latest boolean NOT NULL,
-    deleted boolean NOT NULL,
-    requested timestamp without time zone,
-    requested_by character varying(255),
-    requested_comment character varying(255),
-    processed timestamp without time zone,
-    processed_by character varying(255),
-    processed_comment character varying(255)
-);
-
--- --------------------------------------------------------------------------------
--- data structures level 1
--- --------------------------------------------------------------------------------
-insert into systemgroup (
-    id,
-    version,
-    uuid,
-    name,
-    mnemonic,
-    mnemonic_equivalence,
-    description,
-    status,
-    latest,
-    deleted,
-    requested,
-    requested_by,
-    requested_comment,
-    processed,
-    processed_by,
-    processed_comment
-)
-select npr1.id, npr1."version", np1.uuid, npr1."name", npr1.mnemonic, npr1.mnemoniceqclass, npr1.description, npr1.status, false, npr1.deleted,
-npr1.requestdate, ua_r.username as requestedBy, npr1.requestercomment, npr1.processdate, ua_p.username as processedBy, npr1.processorcomment
-from namepartrevision npr1
-inner join namepart np1 on npr1.namepart_id = np1.id
-left join useraccount ua_r on npr1.requestedby_id = ua_r.id
-left join useraccount ua_p on npr1.processedby_id = ua_p.id
-where np1.nameparttype = 'SECTION' and npr1.parent_id is null;
-
-insert into discipline (
-    id,
-    version,
-    uuid,
-    name,
-    mnemonic,
-    mnemonic_equivalence,
-    description,
-    status,
-    latest,
-    deleted,
-    requested,
-    requested_by,
-    requested_comment,
-    processed,
-    processed_by,
-    processed_comment
-)
-select npr1.id, npr1."version", np1.uuid, npr1."name", npr1.mnemonic, npr1.mnemoniceqclass, npr1.description, npr1.status, false, npr1.deleted,
-npr1.requestdate, ua_r.username as requestedBy, npr1.requestercomment, npr1.processdate, ua_p.username as processedBy, npr1.processorcomment
-from namepartrevision npr1
-inner join namepart np1 on npr1.namepart_id = np1.id
-left join useraccount ua_r on npr1.requestedby_id = ua_r.id
-left join useraccount ua_p on npr1.processedby_id = ua_p.id
-where np1.nameparttype = 'DEVICE_TYPE' and npr1.parent_id is null;
-
--- --------------------------------------------------------------------------------
--- data structures level 2
--- --------------------------------------------------------------------------------
-insert into system (
-    id,
-    version,
-    uuid,
-    parent_uuid,
-    name,
-    mnemonic,
-    mnemonic_equivalence,
-    description,
-    status,
-    latest,
-    deleted,
-    requested,
-    requested_by,
-    requested_comment,
-    processed,
-    processed_by,
-    processed_comment
-)
-select npr2.id, npr2."version", np2.uuid, np22.uuid,
-npr2."name", npr2.mnemonic, npr2.mnemoniceqclass, npr2.description,
-npr2.status, false, npr2.deleted, npr2.requestdate, ua_r.username as requestedBy, npr2.requestercomment, npr2.processdate, ua_p.username as processedBy, npr2.processorcomment
-from namepartrevision npr2
-inner join namepart np2  on npr2.namepart_id = np2.id
-inner join namepart np22 on npr2.parent_id   = np22.id
-left join useraccount ua_r on npr2.requestedby_id = ua_r.id
-left join useraccount ua_p on npr2.processedby_id = ua_p.id
-where np2.nameparttype = 'SECTION' and npr2.parent_id in
-(select npr1.namepart_id from namepartrevision npr1, namepart np1 where npr1.namepart_id = np1.id and np1.nameparttype = 'SECTION' and npr1.parent_id is null);
-
-insert into devicegroup (
-    id,
-    version,
-    uuid,
-    parent_uuid,
-    name,
-    mnemonic,
-    mnemonic_equivalence,
-    description,
-    status,
-    latest,
-    deleted,
-    requested,
-    requested_by,
-    requested_comment,
-    processed,
-    processed_by,
-    processed_comment
-)
-select npr2.id, npr2."version", np2.uuid, np22.uuid,
-npr2."name", npr2.mnemonic, npr2.mnemoniceqclass, npr2.description,
-npr2.status, false, npr2.deleted, npr2.requestdate, ua_r.username as requestedBy, npr2.requestercomment, npr2.processdate, ua_p.username as processedBy, npr2.processorcomment
-from namepartrevision npr2
-inner join namepart np2  on npr2.namepart_id = np2.id
-inner join namepart np22 on npr2.parent_id   = np22.id
-left join useraccount ua_r on npr2.requestedby_id = ua_r.id
-left join useraccount ua_p on npr2.processedby_id = ua_p.id
-where np2.nameparttype = 'DEVICE_TYPE' and npr2.parent_id in
-(select npr1.namepart_id from namepartrevision npr1, namepart np1 where npr1.namepart_id = np1.id and np1.nameparttype = 'DEVICE_TYPE' and npr1.parent_id is null);
-
--- --------------------------------------------------------------------------------
--- data structures level 3
--- --------------------------------------------------------------------------------
-insert into subsystem (
-    id,
-    version,
-    uuid,
-    parent_uuid,
-    name,
-    mnemonic,
-    mnemonic_equivalence,
-    description,
-    status,
-    latest,
-    deleted,
-    requested,
-    requested_by,
-    requested_comment,
-    processed,
-    processed_by,
-    processed_comment
-)
-select npr3.id, npr3."version", np3.uuid, np32.uuid,
-npr3."name", npr3.mnemonic, npr3.mnemoniceqclass, npr3.description,
-npr3.status, false, npr3.deleted, npr3.requestdate, ua_r.username as requestedBy, npr3.requestercomment, npr3.processdate, ua_p.username as processedBy, npr3.processorcomment
-from namepartrevision npr3
-inner join namepart np3  on npr3.namepart_id = np3.id
-inner join namepart np32 on npr3.parent_id   = np32.id
-left join useraccount ua_r on npr3.requestedby_id = ua_r.id
-left join useraccount ua_p on npr3.processedby_id = ua_p.id
-where np3.nameparttype = 'SECTION' and npr3.parent_id in
-(
-select npr2.namepart_id from namepartrevision npr2, namepart np2 where npr2.namepart_id = np2.id and np2.nameparttype = 'SECTION' and npr2.parent_id in
-(select npr1.namepart_id from namepartrevision npr1, namepart np1 where npr1.namepart_id = np1.id and np1.nameparttype = 'SECTION' and npr1.parent_id is null)
-);
-
-insert into devicetype (
-    id,
-    version,
-    uuid,
-    parent_uuid,
-    name,
-    mnemonic,
-    mnemonic_equivalence,
-    description,
-    status,
-    latest,
-    deleted,
-    requested,
-    requested_by,
-    requested_comment,
-    processed,
-    processed_by,
-    processed_comment
-)
-select npr3.id, npr3."version", np3.uuid, np32.uuid,
-npr3."name", npr3.mnemonic, npr3.mnemoniceqclass, npr3.description,
-npr3.status, false, npr3.deleted, npr3.requestdate, ua_r.username as requestedBy, npr3.requestercomment, npr3.processdate, ua_p.username as processedBy, npr3.processorcomment
-from namepartrevision npr3
-inner join namepart np3  on npr3.namepart_id = np3.id
-inner join namepart np32 on npr3.parent_id   = np32.id
-left join useraccount ua_r on npr3.requestedby_id = ua_r.id
-left join useraccount ua_p on npr3.processedby_id = ua_p.id
-where np3.nameparttype = 'DEVICE_TYPE' and npr3.parent_id in
-(
-select npr2.namepart_id from namepartrevision npr2, namepart np2 where npr2.namepart_id = np2.id and np2.nameparttype = 'DEVICE_TYPE' and npr2.parent_id in
-(select npr1.namepart_id from namepartrevision npr1, namepart np1 where npr1.namepart_id = np1.id and np1.nameparttype = 'DEVICE_TYPE' and npr1.parent_id is null)
-);
-
--- --------------------------------------------------------------------------------
--- data name level 1
--- --------------------------------------------------------------------------------
-insert into name (
-    id,
-    version,
-    uuid,
-    systemgroup_uuid,
-    system_uuid,
-    subsystem_uuid,
-    devicetype_uuid,
-    instance_index,
-    convention_name,
-    convention_name_equivalence,
-    description,
-    status,
-    latest,
-    deleted,
-    requested,
-    requested_by,
-    requested_comment,
-    processed,
-    processed_by,
-    processed_comment
-)
-select dr.id, dr.version, d.uuid,
-np_s.uuid,
-null,
-null,
-np_d.uuid,
-dr.instanceindex, dr.conventionname, dr.conventionnameeqclass, dr.additionalinfo, null, false, dr.deleted,
-dr.requestdate, ua_r.username as requestedBy, null, null, null, dr.processorComment
-from devicerevision dr
-inner join device d on dr.device_id = d.id
-inner join namepart np_s on dr.section_id    = np_s.id
-left outer join namepart np_d on dr.devicetype_id = np_d.id
-left join useraccount ua_r on dr.requestedby_id = ua_r.id
-where dr.section_id in
-(
-select np.id from namepart np, namepartrevision npr where np.id = npr.namepart_id and npr.parent_id is null
-);
--- --------------------------------------------------------------------------------
--- data name level 2
--- --------------------------------------------------------------------------------
-insert into name (
-    id,
-    version,
-    uuid,
-    systemgroup_uuid,
-    system_uuid,
-    subsystem_uuid,
-    devicetype_uuid,
-    instance_index,
-    convention_name,
-    convention_name_equivalence,
-    description,
-    status,
-    latest,
-    deleted,
-    requested,
-    requested_by,
-    requested_comment,
-    processed,
-    processed_by,
-    processed_comment
-)
-select dr.id, dr.version, d.uuid,
-null,
-np_s.uuid,
-null,
-np_d.uuid,
-dr.instanceindex, dr.conventionname, dr.conventionnameeqclass, dr.additionalinfo, null, false, dr.deleted,
-dr.requestdate, ua_r.username as requestedBy, null, null, null, dr.processorComment
-from devicerevision dr
-inner join device d on dr.device_id = d.id
-inner join namepart np_s on dr.section_id    = np_s.id
-left outer join namepart np_d on dr.devicetype_id = np_d.id
-left join useraccount ua_r on dr.requestedby_id = ua_r.id
-where dr.section_id in
-(
-select np.id from namepart np, namepartrevision npr where np.id = npr.namepart_id and npr.parent_id in
-    (
-    select np2.id from namepart np2, namepartrevision npr2 where np2.id = npr2.namepart_id and npr2.parent_id is null
-    )
-);
-
--- --------------------------------------------------------------------------------
--- data name level 3
--- --------------------------------------------------------------------------------
-insert into name (
-    id,
-    version,
-    uuid,
-    systemgroup_uuid,
-    system_uuid,
-    subsystem_uuid,
-    devicetype_uuid,
-    instance_index,
-    convention_name,
-    convention_name_equivalence,
-    description,
-    status,
-    latest,
-    deleted,
-    requested,
-    requested_by,
-    requested_comment,
-    processed,
-    processed_by,
-    processed_comment
-)
-select dr.id, dr.version, d.uuid,
-null,
-null,
-np_s.uuid,
-np_d.uuid,
-dr.instanceindex, dr.conventionname, dr.conventionnameeqclass, dr.additionalinfo, null, false, dr.deleted,
-dr.requestdate, ua_r.username as requestedBy, null, null, null, dr.processorComment
-from devicerevision dr
-inner join device d on dr.device_id = d.id
-inner join namepart np_s on dr.section_id    = np_s.id
-left outer join namepart np_d on dr.devicetype_id = np_d.id
-left join useraccount ua_r on dr.requestedby_id = ua_r.id
-where dr.section_id in
-(
-select np.id from namepart np, namepartrevision npr where np.id = npr.namepart_id and npr.parent_id in
-    (
-    select np2.id from namepart np2, namepartrevision npr2 where np2.id = npr2.namepart_id and npr2.parent_id in
-        (
-        select np3.id from namepart np3, namepartrevision npr3 where np3.id = npr3.namepart_id and npr3.parent_id is null
-        )
-    )
-);
-
--- --------------------------------------------------------------------------------
--- index
--- --------------------------------------------------------------------------------
-CREATE INDEX systemgroup_id_idx ON public.systemgroup (id);
-CREATE INDEX systemgroup_uuid_idx ON public.systemgroup (uuid);
-CREATE INDEX systemgroup_mnemonic_idx ON public.systemgroup (mnemonic);
-CREATE INDEX systemgroup_status_idx ON public.systemgroup (status);
-CREATE INDEX systemgroup_deleted_idx ON public.systemgroup (deleted);
-
-CREATE INDEX system_id_idx ON public.system (id);
-CREATE INDEX system_uuid_idx ON public.system (uuid);
-CREATE INDEX system_parent_uuid_idx ON public.system (parent_uuid);
-CREATE INDEX system_mnemonic_idx ON public.system (mnemonic);
-CREATE INDEX system_status_idx ON public.system (status);
-CREATE INDEX system_deleted_idx ON public.system (deleted);
-
-CREATE INDEX subsystem_id_idx ON public.subsystem (id);
-CREATE INDEX subsystem_uuid_idx ON public.subsystem (uuid);
-CREATE INDEX subsystem_parent_uuid_idx ON public.subsystem (parent_uuid);
-CREATE INDEX subsystem_mnemonic_idx ON public.subsystem (mnemonic);
-CREATE INDEX subsystem_status_idx ON public.subsystem (status);
-CREATE INDEX subsystem_deleted_idx ON public.subsystem (deleted);
-
-CREATE INDEX discipline_id_idx ON public.discipline (id);
-CREATE INDEX discipline_uuid_idx ON public.discipline (uuid);
-CREATE INDEX discipline_mnemonic_idx ON public.discipline (mnemonic);
-CREATE INDEX discipline_status_idx ON public.discipline (status);
-CREATE INDEX discipline_deleted_idx ON public.discipline (deleted);
-
-CREATE INDEX devicegroup_id_idx ON public.devicegroup (id);
-CREATE INDEX devicegroup_uuid_idx ON public.devicegroup (uuid);
-CREATE INDEX devicegroup_parent_uuid_idx ON public.devicegroup (parent_uuid);
-CREATE INDEX devicegroup_mnemonic_idx ON public.devicegroup (mnemonic);
-CREATE INDEX devicegroup_status_idx ON public.devicegroup (status);
-CREATE INDEX devicegroup_deleted_idx ON public.devicegroup (deleted);
-
-CREATE INDEX devicetype_id_idx ON public.devicetype (id);
-CREATE INDEX devicetype_uuid_idx ON public.devicetype (uuid);
-CREATE INDEX devicetype_parent_uuid_idx ON public.devicetype (parent_uuid);
-CREATE INDEX devicetype_mnemonic_idx ON public.devicetype (mnemonic);
-CREATE INDEX devicetype_status_idx ON public.devicetype (status);
-CREATE INDEX devicetype_deleted_idx ON public.devicetype (deleted);
-
-CREATE INDEX name_uuid_idx ON public.name (uuid);
-
--- --------------------------------------------------------------------------------
--- latest
--- --------------------------------------------------------------------------------
-update systemgroup sg set latest = true where sg.id = (
-  select max(sg2.id) from systemgroup sg2 where sg2.uuid = sg.uuid and sg2.status = 'APPROVED'
-);
-update system sys set latest = true where sys.id = (
-  select max(sys2.id) from system sys2 where sys2.uuid = sys.uuid and sys2.status = 'APPROVED'
-);
-update subsystem sub set latest = true where sub.id = (
-  select max(sub2.id) from subsystem sub2 where sub2.uuid = sub.uuid and sub2.status = 'APPROVED'
-);
-
-update discipline di set latest = true where di.id = (
-  select max(di2.id) from discipline di2 where di2.uuid = di.uuid and di2.status = 'APPROVED'
-);
-update devicegroup dg set latest = true where dg.id = (
-  select max(dg2.id) from devicegroup dg2 where dg2.uuid = dg.uuid and dg2.status = 'APPROVED'
-);
-update devicetype dt set latest = true where dt.id = (
-  select max(dt2.id) from devicetype dt2 where dt2.uuid = dt.uuid and dt2.status = 'APPROVED'
-);
-
-update name en set latest = true where en.id = (
-  select max(en2.id) from name en2 where en2.uuid = en.uuid
-);
-
--- --------------------------------------------------------------------------------
--- foreign key
--- --------------------------------------------------------------------------------
-
--- --------------------------------------------------------------------------------
--- index
--- --------------------------------------------------------------------------------
-CREATE INDEX name_id_idx ON public.name (id);
-CREATE INDEX name_namepartrevision_systemgroup_uuid_idx ON public.name (systemgroup_uuid);
-CREATE INDEX name_namepartrevision_system_uuid_idx ON public.name (system_uuid);
-CREATE INDEX name_namepartrevision_subsystem_uuid_idx ON public.name (subsystem_uuid);
-CREATE INDEX name_namepartrevision_devicetype_uuid_idx ON public.name (devicetype_uuid);
-CREATE INDEX name_convention_name_idx ON public.name (convention_name);
-CREATE INDEX name_status_idx ON public.name (status);
-CREATE INDEX name_deleted_idx ON public.name (deleted);
-
-CREATE INDEX systemgroup_latest_idx ON public.systemgroup (latest);
-CREATE INDEX system_latest_idx ON public.system (latest);
-CREATE INDEX subsystem_latest_idx ON public.subsystem (latest);
-
-CREATE INDEX discipline_latest_idx ON public.discipline (latest);
-CREATE INDEX devicegroup_latest_idx ON public.devicegroup (latest);
-CREATE INDEX devicetype_latest_idx ON public.devicetype (latest);
-
-CREATE INDEX name_latest_idx ON public.name (latest);
-
--- --------------------------------------------------------------------------------
--- sequence
--- --------------------------------------------------------------------------------
-CREATE SEQUENCE systemgroup_id_seq
-    START WITH 1
-    INCREMENT BY 1
-    NO MINVALUE
-    NO MAXVALUE
-    CACHE 1;
-CREATE SEQUENCE system_id_seq
-    START WITH 1
-    INCREMENT BY 1
-    NO MINVALUE
-    NO MAXVALUE
-    CACHE 1;
-CREATE SEQUENCE subsystem_id_seq
-    START WITH 1
-    INCREMENT BY 1
-    NO MINVALUE
-    NO MAXVALUE
-    CACHE 1;
-CREATE SEQUENCE discipline_id_seq
-    START WITH 1
-    INCREMENT BY 1
-    NO MINVALUE
-    NO MAXVALUE
-    CACHE 1;
-CREATE SEQUENCE devicegroup_id_seq
-    START WITH 1
-    INCREMENT BY 1
-    NO MINVALUE
-    NO MAXVALUE
-    CACHE 1;
-CREATE SEQUENCE devicetype_id_seq
-    START WITH 1
-    INCREMENT BY 1
-    NO MINVALUE
-    NO MAXVALUE
-    CACHE 1;
-CREATE SEQUENCE name_id_seq
-    START WITH 1
-    INCREMENT BY 1
-    NO MINVALUE
-    NO MAXVALUE
-    CACHE 1;
-
-SELECT setval('systemgroup_id_seq', (select max(id) from systemgroup));
-SELECT setval('system_id_seq', (select max(id) from "system"));
-SELECT setval('subsystem_id_seq', (select max(id) from "subsystem"));
-SELECT setval('discipline_id_seq', (select max(id) from discipline));
-SELECT setval('devicegroup_id_seq', (select max(id) from devicegroup));
-SELECT setval('devicetype_id_seq', (select max(id) from devicetype));
-SELECT setval('name_id_seq', (select max(id) from "name"));
-
-ALTER SEQUENCE systemgroup_id_seq OWNED BY systemgroup.id;
-ALTER SEQUENCE system_id_seq OWNED BY system.id;
-ALTER SEQUENCE subsystem_id_seq OWNED BY subsystem.id;
-ALTER SEQUENCE discipline_id_seq OWNED BY discipline.id;
-ALTER SEQUENCE devicegroup_id_seq OWNED BY devicegroup.id;
-ALTER SEQUENCE devicetype_id_seq OWNED BY devicetype.id;
-ALTER SEQUENCE name_id_seq OWNED BY name.id;
-
-ALTER TABLE ONLY systemgroup ALTER COLUMN id SET DEFAULT nextval('systemgroup_id_seq'::regclass);
-ALTER TABLE ONLY system ALTER COLUMN id SET DEFAULT nextval('system_id_seq'::regclass);
-ALTER TABLE ONLY subsystem ALTER COLUMN id SET DEFAULT nextval('subsystem_id_seq'::regclass);
-ALTER TABLE ONLY discipline ALTER COLUMN id SET DEFAULT nextval('discipline_id_seq'::regclass);
-ALTER TABLE ONLY devicegroup ALTER COLUMN id SET DEFAULT nextval('devicegroup_id_seq'::regclass);
-ALTER TABLE ONLY devicetype ALTER COLUMN id SET DEFAULT nextval('devicetype_id_seq'::regclass);
-ALTER TABLE ONLY name ALTER COLUMN id SET DEFAULT nextval('name_id_seq'::regclass);
-
--- --------------------------------------------------------------------------------
--- primary key
--- --------------------------------------------------------------------------------
-ALTER TABLE public.systemgroup ADD CONSTRAINT systemgroup_pk PRIMARY KEY (id);
-ALTER TABLE public.system ADD CONSTRAINT system_pk PRIMARY KEY (id);
-ALTER TABLE public.subsystem ADD CONSTRAINT subsystem_pk PRIMARY KEY (id);
-
-ALTER TABLE public.discipline ADD CONSTRAINT discipline_pk PRIMARY KEY (id);
-ALTER TABLE public.devicegroup ADD CONSTRAINT devicegroup_pk PRIMARY KEY (id);
-ALTER TABLE public.devicetype ADD CONSTRAINT devicetype_pk PRIMARY KEY (id);
-
-ALTER TABLE public.name ADD CONSTRAINT name_pk PRIMARY KEY (id);
--- --------------------------------------------------------------------------------
-
--- --------------------------------------------------------------------------------
--- function
--- --------------------------------------------------------------------------------
-CREATE OR REPLACE FUNCTION get_mnemonic_path_system_structure(convention_name text)
-    RETURNS text
-    LANGUAGE plpgsql
-AS
-$$
-DECLARE
-    pos int;
-BEGIN
-    pos = strpos(convention_name, ':');
-    IF pos > 0  THEN
-        RETURN substr(convention_name, 1, pos-1);
-    END IF;
-    RETURN convention_name;
-END;
-$$;
-
-CREATE OR REPLACE FUNCTION get_mnemonic_path_device_structure(convention_name text)
-    RETURNS text
-    LANGUAGE plpgsql
-AS
-$$
-DECLARE
-    pos int;
-    mnemonic_path text;
-    nbr_delimiters int;
-BEGIN
-    pos = strpos(convention_name, ':');
-    IF pos > 0  THEN
-        mnemonic_path = substr(convention_name, pos+1);
-        nbr_delimiters = array_length(string_to_array(mnemonic_path, '-'), 1) - 1;
-        IF nbr_delimiters = 2 then
-            mnemonic_path = reverse(mnemonic_path);
-            mnemonic_path = substr(mnemonic_path, strpos(mnemonic_path, '-')+1);
-            RETURN reverse(mnemonic_path);
-        ELSIF nbr_delimiters = 1 then
-            return mnemonic_path;
-        ELSE
-            RETURN null;
-        END IF;
-    END IF;
-    RETURN null;
-END;
-$$;
-
-CREATE OR REPLACE FUNCTION public.get_instance_index(convention_name text)
- RETURNS text
- LANGUAGE plpgsql
-AS
-$$
-DECLARE
-    len int;
-    pos int;
-    mnemonic_path text;
-    nbr_delimiters int;
-BEGIN
-    pos = strpos(convention_name, ':');
-    IF pos > 0  THEN
-        mnemonic_path = substr(convention_name, pos+1);
-        nbr_delimiters = array_length(string_to_array(mnemonic_path, '-'), 1) - 1;
-        IF nbr_delimiters = 2 then
-            mnemonic_path = reverse(mnemonic_path);
-            len = length(mnemonic_path);
-            pos = strpos(mnemonic_path, '-');
-            mnemonic_path = reverse(mnemonic_path);
-            RETURN substr(mnemonic_path, len - pos + 2);
-        ELSE
-            RETURN null;
-        END IF;
-    END IF;
-    RETURN null;
-END;
-$$;
-
-CREATE OR REPLACE FUNCTION get_mnemonic_path_system(system_uuid text)
-    RETURNS text
-    LANGUAGE plpgsql
-AS
-$$
-DECLARE
-    system_mnemonic text;
-BEGIN
-    select mnemonic into system_mnemonic from "system" where uuid = system_uuid and latest = true;
-
-    if system_mnemonic is not null then
-        return system_mnemonic;
-    else
-        return null;
-    end if;
-END;
-$$;
-
-CREATE OR REPLACE FUNCTION get_mnemonic_path_subsystem(subsystem_uuid text)
-    RETURNS text
-    LANGUAGE plpgsql
-AS
-$$
-DECLARE
-    subsystem_mnemonic text;
-    system_uuid text;
-    system_mnemonic text;
-BEGIN
-    select parent_uuid, mnemonic into system_uuid, subsystem_mnemonic from subsystem where uuid = subsystem_uuid and latest = true;
-    select mnemonic into system_mnemonic from "system" where uuid = system_uuid and latest = true;
-
-    if system_mnemonic is not null and subsystem_mnemonic is not null then
-        return concat(system_mnemonic, '-', subsystem_mnemonic);
-    else
-        return null;
-    end if;
-END;
-$$;
-
-CREATE OR REPLACE FUNCTION get_mnemonic_path_devicegroup(devicegroup_uuid text)
-    RETURNS text
-    LANGUAGE plpgsql
-AS
-$$
-DECLARE
-    discipline_uuid text;
-    discipline_mnemonic text;
-BEGIN
-    select parent_uuid into discipline_uuid from devicegroup where uuid = devicegroup_uuid and latest = true;
-    select mnemonic into discipline_mnemonic from discipline where uuid = discipline_uuid and latest = true;
-
-    if discipline_mnemonic is not null then
-        return discipline_mnemonic;
-    else
-        return null;
-    end if;
-END;
-$$;
-
-CREATE OR REPLACE FUNCTION get_mnemonic_path_devicetype(devicetype_uuid text)
-    RETURNS text
-    LANGUAGE plpgsql
-AS
-$$
-DECLARE
-    devicetype_mnemonic text;
-    devicegroup_uuid text;
-    discipline_uuid text;
-    discipline_mnemonic text;
-BEGIN
-    select parent_uuid, mnemonic into devicegroup_uuid, devicetype_mnemonic from devicetype where uuid = devicetype_uuid and latest = true;
-    select parent_uuid, mnemonic into discipline_uuid from devicegroup where uuid = devicegroup_uuid and latest = true;
-    select mnemonic into discipline_mnemonic from discipline where uuid = discipline_uuid and latest = true;
-
-    if discipline_mnemonic is not null and devicetype_mnemonic is not null then
-        return concat(discipline_mnemonic, '-', devicetype_mnemonic);
-    elsif devicetype_mnemonic is not null then
-        return devicetype_mnemonic;
-    else
-        return null;
-    end if;
-END;
-$$;
\ No newline at end of file

docs/developer/naming-convention-tool/developer/application/README.txt

-Developer documentation
-
-    Purpose to help understand application, database and in between.
-
-    Created on Ubuntu 18.04 LTS with LibreOffice (6.0.7.3)(Draw, Writer), GNOME Screenshot,  Krita (4.3.0).
-    Document ".odt" exported to ".pdf".