Руководство прикладного разработчика#

Системные требования#

Системные требования представлены в разделе «Системные требовния» документа Руководство по установке.

Подключение и конфигурирование#

Информация о способах подключения и конфигурирования USSX для промышленной среды приведена в документе Руководство по установке.

Настройка рабочего места разработчика#

Создание структуры каталогов#

Необходимо создать показанную следующую структуру каталогов:

D:\prog (базовый каталог с общим ПО)

  • orcl (Oracle Database или PSQL)

  • putty (Putty)

  • name (где name − наименование интегрированной среды разработки)

D:\work (базовый каталог разработки)

  • key (каталог)

  • prj (проекты)

  • prj\bosfor (проект USSX)

  • prj\aj (проект Application Journal)

  • env (окружение, необходимое для запуска и работы USSX)

  • env\nodejs (NodeJS)

Настройка переменных среды#

Так как пользователь не имеет прав администратора, то настраивать можно только переменные среды текущего пользователя. Для этого в Панели управления в разделе Учетные записи пользователей необходимо выбрать раздел Изменение переменных среды.
Необходимо создать следующие переменные:

  • USS_HOME — путь к каталогу с конфигурационными файлами;

  • USS_ENV — путь к каталогу, где располагается ПО для запуска и работы;

  • USS_PRJ — путь к каталогу с файлами проекта.

Далее необходимо дополнить пользовательскую переменную Path значением D:\work\env\nodejs.

Установка ПО#

Необходимо выполнить установку требуемого ПО, содержащегося в каталоге с дистрибутивами.

Установка СУБД#

Необходимо выполнить установку СУБД PSQL или СУБД Oracle Database.

Установка СУБД PSQL#

Процесс установки подробно описан в документации к компоненту Pangolin (PSQL) продукта Platform V Pangolin SE (PSQ).

Установка СУБД Oracle Database#

Необходимо выполнить установку Oracle Database версии 12c.

На время установки должна быть запущена служба «Сервер», которая по умолчанию отключена.

Установку имеет смысл выполнять под учетной записью пользователя. Для этого, войдя в систему под учетной записью администратора, нужно включить пользователя в локальные администраторы. Затем необходимо войти под учетной записью пользователя и запустить установку.

Установка Putty#

Если данное ПО не установлено, то необходимо выполнить установку Putty.

Для этого требуется из каталога с дистрибутивами распаковать архив putty.zip в папку D:\prog\putty.

Установка Node.JS#

Необходимо выполнить установку Node.JS. Для этого требуется из каталога с дистрибутивами распаковать архив nodejs.zip в папку D:\work\env\nodejs. Далее необходимо убедиться, что в значениях переменной среды Path присутствует путь nodejs.

Установка интегрированной среды разработки#

Если интегрированная среда разработки не установлена, то для установки требуется из каталога с дистрибутивами распаковать ее архив.

Настройка проекта#

Создание SSH-ключей#

Необходимо сгенерировать ключ с помощью Puttygen (кнопка generate в интерфейсе).

Приватный и публичный ключи необходимо сохранить в папке D:\work\key.

Настройка Gitlab CE#

Необходимо войти в управление учетной записью Gitlab CE и в разделе SSH keys добавить свой публичный ключ. Для этого необходимо нажать кнопку Add key, в открывшемся окне ввести ключ в поле Key.

Клонирование репозитория#

Для клонирования репозитория необходимо выполнить следующие действия:

  1. Убедиться в наличии прав на репозиторий USSX.

  2. Войти в Gitlab CE в репозиторий USSX и скопировать SSH-ссылку для клонирования репозитория.

  3. Запустить интегрированную среду разработки и в пункте Check out from Version Control выбрать Git.

  4. Клонировать проект, используя ранее скопированный URL и каталог расположения проекта D:\work\prj\bosfor.

Настройка локальных БД#
Установка JDBC драйверов#

Для установки JDBC драйверов необходимо распаковать из каталога с дистрибутивами архив jdbc-drivers.zip в папку с настройками интегрированной среды разработки, например, \config\jdbc-drivers.

Настройка подключения к СУБД в интегрированной среде разработки#

Для подключения к Oracle Database (PostgreSQL, PSQL) необходимо использовать значения параметров, как на рисунке, приведенном ниже (Data Source: orcl, пароль orcl):

Создание базы USSX#

Для создания базы USSX необходимо выполнить следующие действия:

  1. Создать 2 папки: USS_T, USS_L в директории data в инсталляции БД.

  2. Создать одноименные tablespaces.

  3. Создать пользователя USS.

  4. Дать пользователю права на чтение и запись.

  5. Дать пользователю все гранты для тейблспейсов uss_t, uss_l.

  6. В командной строке ОС (рекомендовано использование ОС Альт 8 СП) перейти в каталог [project_bosfor]\z_build\DB и выполнить следующую команду:

java -jar liquibase.jar 
        --classpath=pjdbc.jar 
        --driver=org.postgresql.Driver 
        --url=jdbc:postgresql://localhost:<значение>/postgres 
        --username=<значение> 
        --password=<значение> 
        --changeLogFile=./liquibase/changelog.xml
        update
Создание базы Application Journal#

Для создания базы Application Journal необходимо выполнить следующие действия:

  1. Распаковать архив aj.zip в каталог D:\work\prj\aj\db.

  2. В командной строке ОС (например, Альт 8 СП) перейти в каталог, указанный в предыдущем шаге, и выполнить команду:

dbupdate
        --classpath=pjdbc.jar
        --driver=org.postgresql.Driver
        --url=jdbc:postgresql://localhost:<значение>/postgres
        --username=<значение>
        update
Настройка параметров проекта#
Maven settings#

В настройках интегрированной среды разработки необходимо указать путь к проектному файлу settings.xml (находится в корневой папке проекта).

Run configuration#

Запуск приложения происходит силами Spring Boot с указанием следующих необходимых настроек в application-properties:

  1. Убедиться в том, что если выбран Oracle, то PostgreSQL выключен.

    Postgres.enabled=false (если выбран PostgreSQL − true)

  2. Проверить настройки подключения к БД.

    Datasource.main.url=connectionString
Datasource.main.user=login
Datasource.main.password=pass

Datasource.standin.url=connectionString
Datasource.standin.user=login
Datasource.standin.password=pass

  3. Указать настройки для авторизации.

    clipas.spas_server_url=url
clipas.secret_key=key

Значения для параметров авторизации необходимо уточнять у администраторов компонента Объединенный сервис авторизации (ОСА) (AUTZ) продукта Platfrom V IAM SE (IAM).

Настройка плагина SonarQube для интегрированной среды разработки#

Код должен соответствовать требованиям SonarQube. SonarQube анализирует общее качество кода, ошибки высвечиваются при нарушении основных правил (например, дублирование кода или заведомо очевидные уязвимые места). Не должно быть критических и блокирующих замечаний. Для упрощения контроля необходимо установить плагин SonarQube. После установки его необходимо настроить для подключения к SonarQube и изменить отображение ошибок как на рисунках ниже:

Сборка и запуск#

Для сборки и запуска проекта необходимо выполнить следующие действия:

  1. Собрать проект с помощью Maven. При этом необходимо установить параметры, указанные на изображении:

  2. Запустить Run configuration ErrorProcessingApplication, UssApplication:

  3. В браузере перейти по ссылке http://localhost:<значение>.

Миграция на текущую версию#

В каждой новой версии USSX требуется:

  • Обновить БД. Для обновления БД используется LiquiBase, запускающийся вручную (подробности в инструкции \DB\Readme.txt) либо преднастроенным шагом задания Jenkins установки приложения;

  • Обновить ролевую модель в компоненте Объединенный сервис авторизации (ОСА) (AUTZ) продукта Platfrom V IAM SE (IAM), файл из дистрибутива: \config\roleModel.xml;

  • Обновить модули USSX и ERRM: \modules;

  • Загрузить файл настроек обработки, файл из дистрибутива \doc*файл загрузки внутренних справочников.xlsx.

Если Разработчиком используется локальная установка, то требуется только обновить БД и скачать последнюю версию проекта из репозитория.

Разработка первого приложения с использованием USSX#

Вызов USSX для регистрации отклонения#

Для вызова USSX для регистрации отклонения используется API ErrorProcessing, метод registerError с вызовом по json-rpc.

Зависимость для MAVEN:

<dependency>
  <groupId><значение></groupId>
  <artifactId><значение></artifactId>
  <version>{версия 4.7.5 и выше}</version>
</dependency>

Пример реализации вызова USSX для регистрации отклонения приведен ниже. В примере подключается API USSX и заполняется DTO ErrorInfoDto, далее вызывается метод registerError для передачи инцидента в USSX:

package com.sbt.uss.jsonrpc.controller;

import com.sbt.uss.errorprocessor.jsonrpc.api.ErrorProcessing;
import com.sbt.uss.errorprocessor.jsonrpc.dto.CorrectiveServiceDto;
import com.sbt.uss.errorprocessor.jsonrpc.dto.ErrorFieldDto;
import com.sbt.uss.errorprocessor.jsonrpc.dto.ErrorInfoDto;
import com.sbt.uss.errorprocessor.jsonrpc.dto.ProcessStatusDto;
import org.apache.commons.lang.RandomStringUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.Date;
import java.util.HashMap;
import java.util.LinkedHashMap;
import java.util.Map;

@RestController
public class MMTController {

    @Autowired
    private ErrorProcessing errorProcessing;

    @GetMapping("/json-rpc/simple")
    public ProcessStatusDto testJsonRpc4GenerationSimple() {

        ErrorInfoDto errorInfoDto = new ErrorInfoDto();
       errorInfoDto.setBpmsProcessName("common_error_processing_job");
       errorInfoDto.setClientName("Тест Тестов Тестович");
       errorInfoDto.setErrorBusinessInfo("Истекло время ожидания от Автотранзакции");
       errorInfoDto.setErrorTechnoInfo("Connection Timeout");
       errorInfoDto.setOperDay(new Date());
       errorInfoDto.setClientId(24234234234234L);
       errorInfoDto.setDateTime(new Date());
       errorInfoDto.setTimeZone("Europe/Moscow");
       errorInfoDto.setNeedApprove(false);
       errorInfoDto.setModuleFrom("Платформа");
       errorInfoDto.setOperId("bbb");
       errorInfoDto.setErrorCode("101");
       errorInfoDto.setOperCode("1111111");
       errorInfoDto.setServiceCode("SRV-T-SD-Seizure-4gen");
       errorInfoDto.setServiceName("Тест1");
       errorInfoDto.setInnerProcessName("DELAYED_CALL");
       errorInfoDto.setServiceTypeCode("18080003");
       errorInfoDto.setServiceTypeName("Расчетный Центр");
       errorInfoDto.setProductTypeCode("");
       errorInfoDto.setServiceId("643");
       errorInfoDto.setSelectedCorrectiveServiceName("Корректирующий сценарий 1");
       errorInfoDto.setTb("32");
       errorInfoDto.setOsb(RandomStringUtils.randomNumeric(4));
       errorInfoDto.setVsp(RandomStringUtils.randomNumeric(4));


        Map<String, ErrorFieldDto> errorFieldDto = new LinkedHashMap<>();
        ErrorFieldDto errorFieldDto;
       errorFieldDto = new ErrorFieldDto();
       errorFieldDto.setValue("1");
       errorFieldDto.setRusName("Значение 1");
       errorFieldDto.put("1", errorFieldMmt);
       errorFieldDto = new ErrorFieldDto();
       errorFieldDto.setValue("2");
       errorFieldDto.setRusName("Значение 2");
       errorFieldDto.put("2", errorFieldMmt);
       errorFieldDto = new ErrorFieldDto();
       errorFieldDto.setValue("3");
       errorFieldDto.setRusName("Значение 3");
       errorFieldDto.put("3", errorFieldMmt);
       errorFieldDto = new ErrorFieldDto();
       errorFieldDto.setValue("4");
       errorFieldDto.setRusName("Значение 4");
       errorFieldDto.put("4", errorFieldMmt);
       errorFieldDto = new ErrorFieldDto();
       errorFieldDto.setValue("0");
       errorFieldDto.setRusName("Повторный вызов через (мс)");
       errorFieldDto.put(ErrorInfoDto.DELAY, errorFieldMmt);

       errorInfoDto.setErrorFieldMap(errorFieldMap);

        CorrectiveServiceDto cs1 = new CorrectiveServiceDto();
        cs1.setName("Корректирующий сценарий 1");
        cs1.setMmtApiService("");
        cs1.setMmtModule("url");

        HashMap<String, CorrectiveServiceDto> correctiveServiceMmtHashMap = new HashMap<>();
        correctiveServiceMmtHashMap.put("corServ1", cs1);

       errorInfoDto.setCorrectiveServices(correctiveServiceMmtHashMap);
       errorInfoDto.setSelectedCorrectiveServiceName("corServ1");
        HashMap<String, String> operationContext = new HashMap<>();
        operationContext.put("Кинем исключение", "aaaaa");
       errorInfoDto.setOperationContextMap(operationContext);
        System.out.println("Создание ошибки: " + errorInfoDto);
        ProcessStatusDto response = errorProcessing.registerError(errorInfoDto);
        System.out.println(response.getStatus());
        System.out.println(response.getMessage());
        System.out.println(response.getErrorID());
        return response;
    }
}

Реализация корректирующего сценария#

Реализация корректирующего сценария возможна в двух вариантах:

  • с использованием библиотеки mmt-lite - в этом случае корректирующий сценарий имплементирует метод runScenario(CorrectInfoDto correctInfoDto, @CallbackArg BiConsumer<CorrectStatusDto, Throwable> callback); и асинхронный ответ с результатом работы корректирующего сценария CorrectStatusDto возвращается методом callback.accept(correctStatusDto, null) через библиотеку mmt-lite;

  • без использования библиотеки mmt-lite - в этом случае корректирующий сценарий имплементирует метод runCorrectionScenario(CorrectInfoDto correctInfoDto); и возвращает асинхронный ответ с результатом работы корректирующего сценария CorrectStatusDto через вызов нотификации USSX NotifyCorScenarioResult(correctStatusDto). При этом библиотека mmt-lite не используется.

Реализация корректирующего сценария с использованием библиотеки mmt-lite#

Корректирующий сценарий с использованием библиотеки mmt-lite должен имплементировать API ErrorCorrection метод runScenario(CorrectInfoDto correctInfoDto, @CallbackArg BiConsumer<CorrectStatusDto, Throwable> callback) с аргументом-callback. При этом используется API ErrorCorrection версии 4.7.5 или выше.

Настройки для Maven:

<dependency>
 	 <groupId>sbp.com.sbt.uss</groupId>
  	<artifactId>uss-orc-api</artifactId>
 	 <version>{версия 4.7.5 и выше}</version>
</dependency>

Использоване библиотеки transport-lite-client (mmt-lite) версии 5.1.5.

Настройки для Maven:

<dependency>
                <groupId>platform.core.transport</groupId>
                <artifactId>transport-lite-client</artifactId>
                <version>5.1.5</version>
            </dependency>

Особенности реализации:

  1. Вызов корректирующего сценария com.sbt.uss.common.jsonrpc.orc.api.ErrorCorrection/runScenario выполняется с лямбда-функцией для асинхронного ответа, поэтому вместо традиционного json–запроса из USSX отправляется бинарный запрос, который должен обрабатываться особым образом на стороне Synapse-Ingress корсценария.

  2. Требуется использовать кастомный образ Synapse-Ingress (Envoy).

  3. EnvoyFilter для бинарного запроса должен работать через sbt_auth, а не стандартный ext_auth и в with_request_body: должен быть установлен флаг pack_as_bytes: true.

  4. Если используется ОТТS, то по умолчанию в приложение запрос поступает с ОТТ-сертификатами в заголовке. Поэтому следует либо настроить отбрасывание ОТТ-сертификатов, либо увеличить размер заголовков (хедеров) до 2 МВ в конфигах (для запросов может потребоваться до 10 МВ): server.max-http-header-size= 2MB.

В приведенном примере подключаются API USSX ErrorCorrection, имплементируется метод runScenario(CorrectInfoDto correctInfoDto, @CallbackArg BiConsumer<CorrectStatusDto, Throwable> callback) с аргументом-callback, а асинхронный ответ возвращается из кор. сценария в USSX по JSON+RPC отдельным асинхронным методом callback.accept(correctStatusDto, null). В асинхронном ответе возвращается DTO correctStatusDto с результатом выполнения кор. сценария. Имплементация класса ErrorCorrection обязательно помечается аннотацией @ApiLite и @JsonRpcApi.

package com.sbt.uss.jsonrpc.orc;

import com.sbt.core.transport.jsonrpc.api.JsonRpcApi;
import com.sbt.core.transport.lite.api.annotation.ApiLite;
import com.sbt.uss.common.jsonrpc.orc.api.ErrorCorrection;
import com.sbt.uss.common.jsonrpc.orc.dto.CorrectInfoDto;
import com.sbt.uss.errorprocessor.jsonrpc.dto.CorrectStatusDto;
import java.util.function.BiConsumer;

@ApiLite
@JsonRpcApi
public class ErrorCorrectionImpl implements ErrorCorrection {

    @Override
    public void runScenario(CorrectInfoDto correctInfoDto, BiConsumer<CorrectStatusDto, Throwable> callback) {
        System.out.println(correctInfoDto);
        try {
            Thread.sleep(20_000);
        } catch (InterruptedException ex) {
            //No-op
        }
        System.out.println("Sending result back to error-processor with status 0...");
        CorrectStatusDto correctStatusDto = new CorrectStatusDto();
        correctStatusDto.setErrorID(correctInfoDto.getErrorID());
        correctStatusDto.setRequestID(correctInfoDto.getRequestID());
        correctStatusDto.setStatus(0);
        correctStatusDto.setMessage("Сценарий успешно отработал!");
        callback.accept(correctStatusDto, null);
    }
}

Реализация корректирующего сценария без использования библиотеки mmt-lite#

Если не используется библитека mmt-lite, то реализация вызовов происходит только через json-rpc (json-сериализация) без дополнительных настроек Istio. При реализации корректирующего сценария необходимо обработку запроса runCorrectionScenario выполнять в новом потоке, чтобы не блокировать синхронный ответ с технической квитанцией на запрос runCorrectionScenario. В приведенном примере подключаются API USSX CorrectionScenario, имплементируется метод runCorrectionScenario(CorrectInfoDto correctInfoDto), обработка выполняется в отдельном потоке, а асинхронный ответ с результатами работы корсценария возвращается методом notifyCorrScenarioResult(CorrectStatusDto correctStatusDto) API ErrorProcessing.

Используется API CorrectionScenario версии 4.7.5 или выше.

Настройки для Maven:

<dependency>
  <groupId>sbp.com.sbt.uss</groupId>
  <artifactId>uss-orc-api</artifactId>
  <version>{версия 4.7.5 и выше}</version>
</dependency>

Используется API ErrorProcessing версии 4.7.5 или выше.

Зависимость для MAVEN:

<dependency>
  <groupId><значение></groupId>
  <artifactId><значение></artifactId>
  <version>{версия 4.7.5 и выше}</version>
</dependency>

Имплементация класса ErrorCorrection обязательно помечается аннотацией @Api и @JsonRpcApi.

package com.sbt.uss.jsonrpc.orc;

import com.sbt.core.transport.jsonrpc.api.JsonRpcApi;
import com.sbt.core.transport.lite.api.annotation.Api;
import com.sbt.uss.common.jsonrpc.orc.api.CorrectionScenario;
import com.sbt.uss.common.jsonrpc.orc.dto.CorrectInfoDto;
import com.sbt.uss.errorprocessor.jsonrpc.api.ErrorProcessing;
import com.sbt.uss.errorprocessor.jsonrpc.dto.CorrectStatusDto;

import java.util.concurrent.Executor;
import java.util.concurrent.Executors;

@Api
@JsonRpcApi
public class CorrectionScenarioImpl implements CorrectionScenario {

    private final Executor executor = Executors.newFixedThreadPool(3);

    private final ErrorProcessing errorProcessing;

    public CorrectionScenarioImpl(ErrorProcessing errorProcessing) {
        this.errorProcessing = errorProcessing;
    }

    @Override
    public void runCorrectionScenario(CorrectInfoDto correctInfoDto) {
        System.out.println(correctInfoDto);
        executor.execute(() -> {
            try {
                Thread.sleep(20_000);
            } catch (InterruptedException ex) {
                //No-op
            }
            System.out.println("Sending result back to error-processor with status 0...");
            CorrectStatusDto correctStatusMmt = new CorrectStatusDto();
            correctStatusMmt.setErrorID(correctInfoDto.getErrorID());
            correctStatusMmt.setRequestID(correctInfoDto.getRequestID());
            correctStatusMmt.setStatus(0);
            correctStatusMmt.setMessage("Сценарий успешно отработал!");
            errorProcessing.notifyCorrScenarioResult(correctStatusMmt);
        });
    }
}

Быстрый старт#

Шаг 1. Установка ПО#

Для установки и настройки USSX потребуется развернуть необходимое ПО из раздела «Системные требования» документа Руководство по установке.

Шаг 2. Подключение и конфигурирование#

Информация о способах подключения и конфигурирования USSX для промышленной среды приведена в документе Руководство по установке.

Шаг 3. Настройка рабочего места разработчика#

Создайте структуру каталогов, приведенную в разделе Настройка рабочего места разработчика настоящего документа.

Шаг 4. Настройка переменных среды#

Так как прикладной разработчик не имеет прав администратора, настраивать можно только переменные среды текущего пользователя. Описание настройки переменных среды см. в разделе Настройка переменных среды настоящего документа.

Шаг 5. Установка#

Процесс установки описан в разделе «Установка» документа Руководство по установке.

Шаг 6. Реализация корректирующего сценария#

Реализация вызова USSX из приложения описана в разделе Вызов USSX для регистрации отклонения настоящего документа.

Использование программного компонента#

USSX — готовый инструмент для устранения инцидентов бизнес-процессов и доведения до 100% транзакций до завершения. USSX подходит для следующих потребителей:

  • юридических лиц;

  • банковских продуктов;

  • руководителей процессов и сопровождения.

Возможности USSX следующие:

  • прием инцидентов, возникших при выполнении бизнес-процессов;

  • автоматическая и ручная обработка инцидентов;

  • уведомление пользователей о событиях обработки;

  • сокращение количества инцидентов по клиентским транзакциям.

Часто встречающиеся проблемы и пути их устранения#

При старте серверов приложений необходимо анализировать логи на предмет отсутствия ошибок.