evru-dashboard/README.md

# Создание БД проекта

Создание роли для основной схемы БД проекта

```
CREATE ROLE "<your-project-main-role>" WITH
  LOGIN
  NOSUPERUSER
  INHERIT
  NOCREATEDB
  NOCREATEROLE
  NOREPLICATION
  PASSWORD '<your password>';
```

Создание роли для схемы безопасности БД проекта

```
CREATE ROLE "<your-project-security-role>" WITH
  LOGIN
  NOSUPERUSER
  INHERIT
  NOCREATEDB
  NOCREATEROLE
  NOREPLICATION
  PASSWORD '<your password>';
```

Создание БД проекта

```
CREATE DATABASE "<your-project-db>"
    WITH 
    OWNER = "<your-project-main-role>";
```

ВНИМАНИЕ: в общем случае, отдельную БД для безопасности создавать не нужно. В конфигурации источника данных security-ds в файле standalone.xml в качестве имени базы данных используйте базу данных приложения.

Предоставление необходимых прав для роли &lt;your-project-security-role&gt;

```
GRANT CREATE ON DATABASE "<your-project-db>" TO "<your-project-security-role>";
```

Создание таблицы shedlock для автосинхронизации

```
CREATE TABLE shedlock
(
   name       varchar not null
       constraint tasks_lock_pkey
           primary key,
   lock_until timestamp,
   locked_at  timestamp,
   locked_by  varchar
);

comment on table shedlock is 'Таблица для синхронизации выполнения запланированных задач между нодами.';

ALTER TABLE shedlock
   OWNER to "owner";
```

## Дополнительные ограничения базы секьюрити

Логин пользователя &lt;user_account.username&gt; и имена ролей &lt;user_role.name&gt; не должны совпадать, так как в ходе работы jbpm-а они сохраняются в одну и ту же таблицу.
Пример ошибки при совпадении: username = 'qa_test' и role_name = 'qa_test' (роль привязана к этому пользователю). Ошибка возникает при запуске любого процесса под этим пользователем.

```
ERROR [errorhandling.ExceptionHandlerController] (default task-5) [19usm9-bgyi63] 
Organizational entity already exists with [GroupImpl:'qa_test'] id, 
please check that there is no group and user with same id: 
java.lang.RuntimeException: Organizational entity already exists with [GroupImpl:'qa_test'] id, 
please check that there is no group and user with same id
```

## Создание нового администратора

Создайте группу &lt;your-admin-group&gt; и предоставьте ей права в модуль администрирования. Для этого выполните в БД проекта

```
INSERT INTO security.user_group(
    user_group_id, name, access_level_id)
    (SELECT uuid_in(md5(random()::text || clock_timestamp()::text)::cstring), 
    '<your-admin-group>', access_level_id FROM security.access_level where level=999);
```

```
INSERT INTO security.link_user_group_user_role(
    link_user_group_user_role_id, user_group_id, user_role_id)
    (SELECT uuid_in(md5(random()::text || clock_timestamp()::text)::cstring), 
    (SELECT user_group_id FROM security.user_group WHERE name = '<your-admin-group>'), 
    (SELECT user_role_id FROM security.user_role WHERE name = 'Security - User Admin'));
```

```
INSERT INTO security.link_user_group_user_role(
    link_user_group_user_role_id, user_group_id, user_role_id)
    (SELECT uuid_in(md5(random()::text || clock_timestamp()::text)::cstring), 
    (SELECT user_group_id FROM security.user_group WHERE name = '<your-admin-group>'), 
    (SELECT user_role_id FROM security.user_role WHERE name = 'Security - Group Admin'));
```

```
INSERT INTO security.link_user_group_user_role(
    link_user_group_user_role_id, user_group_id, user_role_id)
    (SELECT uuid_in(md5(random()::text || clock_timestamp()::text)::cstring), 
    (SELECT user_group_id FROM security.user_group WHERE name = '<your-admin-group>'), 
    (SELECT user_role_id FROM security.user_role WHERE name = 'Security - Role Admin'));
```

# Настройка браузера для входа в систему с помощью Kerberos

1. Запустите браузер firefox.
2. В адресной строке введите about:config, нажать кнопку "я принимаю на себя риск"
3. С помощью поиска найдите параметр network.negotiate-auth.trusted-uris и в качестве значения ввести домен(например для домена  example.com надо ввести .example.com)
4. Откройте в браузере приложение. Пример http://app.example.com/ . Приложение должно открыться без запроса логина/пароля

# Восстановление структуры БД

На основе БД проекта с помощью jOOQ генерируются Java классы для каждого объекта БД. Это происходит по нажатию кнопки Обновить на панели БД в студии. При необходимости можно сформировать DDL на основе данных классов. Пример класса для генерации DDL

```
package ru.cg.webbpm.test_project.db_beans;

import org.jooq.*;
import org.jooq.impl.*;

public class Main {
  public static void main (String args []) {
    DefaultConfiguration defaultConfiguration = new DefaultConfiguration();
    defaultConfiguration.setSQLDialect(SQLDialect.POSTGRES);
    Queries ddl = DSL.using(defaultConfiguration).ddl(DefaultCatalog.DEFAULT_CATALOG);

    for (Query query : ddl.queries()) {
      System.out.println(query);
    }
  }
}
```

** ВНИМАНИЕ: **

- этим способом нельзя восстановить функции/процедуры БД

см. также [https://www.jooq.org/doc/latest/manual/sql-building/ddl-statements/generating-ddl/](https://www.jooq.org/doc/latest/manual/sql-building/ddl-statements/generating-ddl/)

# Сборка проекта
## В dev режиме 
```bash
mvn clean && mvn package
```
## В prod режиме
```bash
mvn clean && mvn package -Pprod -DngcCoreCount=4 -DpagePackSizeMb=24
```
ngcCoreCount - количество ядер, выделяемых процессу компиляции ngc. По умолчанию - количество ядер - 1  
pagePackSizeMb - размер пачки в МБ. По умолчанию - количество ядер - 24 МБ.

## С обновлением database beans
```bash
mvn clean && mvn package -Dwebbpm.generate-db-beans
```

# Версия проекта

Если версия проекта содержит SNAPSHOT (например 1.0-SNAPSHOT), то при установке такой версии на сервере приложений будет запущена процедура остановки запущенных процессов данной версии. Этот режим удобен при отладке процесса на рабочем месте аналитика.  
На боевом и тестовом стенде необходимо передавать дистрибутив проекта, с версией, которая не содержит SNAPSHOT. Например - 1.0

# Обновление платформы

## Обновления версии платформы

### С помощью студии

1. Откройте проект в студии. Версия платформы обновится автоматически

### Вручную

1. Обновите значение webbpm-platform.version в pom.xml. Пример
   
   ```xml
   <webbpm-platform.version>3.164.0-SNAPSHOT</webbpm-platform.version>
   ```

## Обновление базового пакета компонент

### С помощью студии

1. Откройте проект в студии. 

2. Откройте меню "Проект - Пакеты"

3. Нажмите обновить.


### Вручную

#### Из удаленного репозитория

```bash
mvn webbpm:update-package -DpackageVersion="3.158.8"
```

#### Из файла

```bash
mvn webbpm:update-package -DexecuteNpmInstall=false -Dpath=resources-<your-version>.jar
```

#### Руками

1. Измените версию платформы и backend модуля в файле [pom.xml](pom.xml) вашего проекта на нужную версию
2. Скопируйте ресурсы
```
из директории: webbpm-platform\components\resources\target\classes\
в директорию:  {your-project}\packages\ru.cg.webbpm.packages.base.resources\
```
3. Скопируйте фронт
```
из директории: webbpm-platform\components\frontend\dist 
в директорию:  {your-project}\frontend\node_modules\@webbpm\base-package\
```
4. Запретите выполнение npm install при запуске студии. Для этого добавьте параметр `-DexecuteNpmInstall=false` в настройках Run/Debug Configurations студии