Загальний Trembita SOAP-конектор: Trembita SOAP connector

На цій сторінці:

1. Загальна інформація
2. Налаштування делегата
3. Використання у бізнес-процесі на прикладі надсилання запита до сервісу ЄДР

1. Загальна інформація

Конектор можна використати для інтеграції з будь-яким SOAP-сервісом, зареєстрованим у СЕВ ДЕІР "Трембіта". Є делегатом.

Детальніше про налаштування взаємодії з "Трембітою" див. на сторінці Налаштування взаємодії з реєстрами через ШБО "Трембіта" у Control Plane.

Trembita SOAP connector — інтеграційне розширення-делегат ${trembitaSoapConnectorDelegate}, призначене для виклику зовнішнього SOAP-сервісу через ШБО "Трембіта". Воно налаштовується у бізнес-процесі за допомогою шаблону Trembita SOAP connector (trembitaSoapConnectorDelegate.json).

2. Налаштування делегата

Делегат конфігурується за допомогою спеціального шаблону-розширення для сервісної (системної) задачі бізнес-процесу.

Створіть Service Task (Сервісну задачу).
На панелі справа натисніть Select, оберіть та налаштуйте шаблон Trembita SOAP connector зі списку:
У полі Name секції General вкажіть назву задачі. Наприклад, Відправлення запита до ЄДР.

Розділ Custom properties:

У полі Trembita system name вкажіть назву зовнішньої системи-учасника СЕВ ДЕІР "Трембіта", з якою встановлено підключення через адміністративну панель Control Plane. Наприклад, trembita-registry-test.

У полі Trembita service name вкажіть назву сервісу зовнішньої системи "Трембіта", куди необхідно виконати запит. Наприклад, testAction.

Назва сервісу = SOAP Action. Вона визначає, який процес або програму необхідно викликати, коли запит надсилається клієнтом сервісу.

У полі Content type визначається формат представлення даних та кодування. За замовчуванням — text/xml;charset=UTF-8;.

У полі Request payload вкажіть змінну, яка містить дані запита. Наприклад, ${requestPayload}.

${requestPayload} формується попередньо у скрипті (див. детальніше — Скрипт для виконання запита через Trembita SOAP-конектор).

Тіло запита може виглядати так:

Приклад 1. Тіло запита згідно з контрактом для сервісу ЄДР

<ns2:SearchSubjects xmlns:ns2="http://nais.gov.ua/api/sevdeir/EDR" xmlns:ns3="http://x-road.eu/xsd/xroad.xsd" xmlns:ns4="http://x-road.eu/xsd/identifiers">
	<ns2:code>$edrpou</ns2:code>
</ns2:SearchSubjects>

У полі Result variable вкажіть змінну, до якої необхідно записати відповідь від сервісу. Наприклад, edrResponseBody.

Приклад 2. Відповідь від API згідно з контрактом для сервісу ЄДР

<soap11env:Envelope xmlns:soap11env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tns="http://nais.gov.ua/api/sevdeir/EDR" xmlns:xroad="http://x-road.eu/xsd/xroad.xsd" xmlns:id="http://x-road.eu/xsd/identifiers">
   <soap11env:Header>
        ...
   </soap11env:Header>
   <soap11env:Body>
      <tns:SearchSubjectsResponse>
         <tns:SubjectList>
            <tns:SubjectInfo>
               <tns:state>1</tns:state>
               <tns:state_text>зареєстровано</tns:state_text>
               <tns:name>Сидоренко Василь Леонідович</tns:name>
               <tns:url>http://zqedr-api.nais.gov.ua/1.0/subjects/2222</tns:url>
               <tns:code>2222</tns:code>
               <tns:id>2222</tns:id>
            </tns:SubjectInfo>
         </tns:SubjectList>
      </tns:SearchSubjectsResponse>
   </soap11env:Body>
</soap11env:Envelope>

Делегат повертає відповідь у вигляді об’єкта типу SpinXmlElement.

3. Використання у бізнес-процесі на прикладі надсилання запита до сервісу ЄДР

Розглянемо приклад використання розробленого інтеграційного конектора у бізнес-процесі, який має взаємодію із SOAP-сервісом ЄДР (тут — виконує пошук інформації про посадову особу за кодом ЄДРПОУ (атрибутом edrpou)).

Скористайтеся референтними прикладами бізнес-процесу та UI-форм для кращого розуміння деталей моделювання:

Бізнес-процес: trembita-connector.bpmn
Форма введення даних: soap-http-connector-edrpou-search-in-edr.json
Форма перегляду результату: soap-http-connector-edrpou-edr-result-view.json

Конектор можна використати для інтеграції з будь-яким SOAP-сервісом, зареєстрованому у СЕВ ДЕІР "Трембіта".

Створіть бізнес-процес і додайте пул до панелі моделювання.

Створіть стартову задачу для ініціювання процесу.

Для того, щоб використовувати змінну initiator у бізнес-процесі, необхідно визначити її на стартовій події як initiator у полі Start initiator.

soap http 2 1

3.1. Користувацька задача введення даних для пошуку в іншому реєстрі

Далі змоделюйте користувацьку задачу (User Task), оберіть шаблон User Form (користувацька UI-форма) та виконайте налаштування.

Введіть назву задачі. Наприклад, Ввести ЄДРПОУ для пошуку.
У полі ID введіть ідентифікатор задачі (activity_id). Його ви можете використовувати надалі у бізнес-процесі відповідно до вашої логіки. Наприклад, searchEdrpouCodeOfficer.
У полі Form key введіть службову назву UI-форми вводу даних. Наприклад, soap-http-connector-edrpou-search-in-edr.
У полі Assignee введіть токен ініціатора процесу — ${initiator}.

soap http 3

Приклад UI-форми на інтерфейсі користувача може виглядати так:

3.2. Скрипт для виконання запита через Trembita SOAP-конектор

Далі сформуйте Groovy-скрипт, в якому необхідно визначити параметри, а саме тіло запита й опціонально — заголовки, які будуть використані SOAP-конектором для отримання даних в іншому реєстрі.

Делегат автоматично додасть наступні системні заголовки при виконанні запита до SOAP-сервісу.

Перелік і структура заголовків

<xro:client iden:objectType="?" xmlns:xro="http://x-road.eu/xsd/xroad.xsd" xmlns:iden="http://x-road.eu/xsd/identifiers">
    <iden:xRoadInstance>?</iden:xRoadInstance>
    <iden:memberClass>?</iden:memberClass>
    <iden:memberCode>?</iden:memberCode>
    <iden:subsystemCode>?</iden:subsystemCode>
</xro:client>
<xro:service iden:objectType="SERVICE" xmlns:xro="http://x-road.eu/xsd/xroad.xsd" xmlns:iden="http://x-road.eu/xsd/identifiers">
    <iden:xRoadInstance>?</iden:xRoadInstance>
    <iden:memberClass>?</iden:memberClass>
    <iden:memberCode>?</iden:memberCode>
    <iden:subsystemCode>?</iden:subsystemCode>
    <iden:serviceCode>?</iden:serviceCode>
    <iden:serviceVersion>?</iden:serviceVersion>
</xro:service>
<xro:userId xmlns:xro="http://x-road.eu/xsd/xroad.xsd">?</xro:userId>
<xro:id xmlns:xro="http://x-road.eu/xsd/xroad.xsd">?</xro:id>
<xro:protocolVersion xmlns:xro="http://x-road.eu/xsd/xroad.xsd">?</xro:protocolVersion>

Створіть скрипт-задачу (Script Task).
Введіть назву. Наприклад, Підготувати дані для запита.

Відкрийте візуальний редактор скриптів та напишіть необхідний скрипт.

soap http 4

Загалом скрипт може виглядати так:

trembita connector 3

3.1. Отримуємо значення коду edrpou, який ввели на першій формі вводу даних (formData):
```
def edrpou = submission('searchEdrpouCodeOfficer').formData.prop('edrpou').value()
```

3.2. Отримуємо токен авторизації для доступу до сервісу за допомогою JUEL-функції get_trembita_auth_token().

def registryAuthSecretValue = get_trembita_auth_token('trembita-registry-test')

Функція get_trembita_auth_token() дозволяє отримати токен авторизації для доступу до сервісів СЕВ ДЕІР "Трембіта", з якими попередньо налаштовано взаємодію у Control Plane (див. детальніше — bp-modeling/bp/modeling-facilitation/modelling-with-juel-functions.adoc).

3.3. Створюємо шаблон заголовка SOAP-запита із токеном авторизації.

def authHeaderTagTemplate = """
        <ns2:AuthorizationToken xmlns:ns2="http://nais.gov.ua/api/sevdeir/EDR" xmlns:ns3="http://x-road.eu/xsd/xroad.xsd" xmlns:ns4="http://x-road.eu/xsd/identifiers">
            $registryAuthSecretValue
        </ns2:AuthorizationToken>
"""

3.4. Заповнюємо шаблон заголовка із токеном авторизації.
```
def headerString = sprintf(authHeaderTagTemplate, registryAuthSecretValue)
```

3.5. Створюємо шаблон тіла SOAP-запита для пошуку суб’єкта за кодом ЄДРПОУ.

def bodyTemplate = """
 <ns2:SearchSubjects xmlns:ns2="http://nais.gov.ua/api/sevdeir/EDR" xmlns:ns3="http://x-road.eu/xsd/xroad.xsd" xmlns:ns4="http://x-road.eu/xsd/identifiers">
            <ns2:code>$edrpou</ns2:code>
        </ns2:SearchSubjects>
"""

3.6. Заповнюємо шаблон тіла SOAP-запита зі значенням edrpou.
```
def bodyString = sprintf(bodyTemplate, edrpou)
```
3.7. Створюємо шаблон SOAP-запита зі згенерованим заголовком та тілом.
```
String requestTemplate = """
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header>
        $headerString
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        $bodyString
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
"""
```
Змінні headerString та bodyString формуються з шаблонів authHeaderTagTemplate та bodyTemplate відповідно, де змінні $registryAuthSecretValue і $edrpou замінюються на значення змінних registryAuthSecretValue та edrpou, що були отримані на попередніх етапах у скрипті.
3.8. Далі формуємо запит на отримання інформації про суб’єкт за його ЄДРПОУ.
```
def requestPayload = sprintf(requestTemplate, headerString, bodyString)
```
Запит формується за допомогою змінної requestTemplate, в якій змінні $headerString і $bodyString замінюються на їх відповідні значення.

3.9. Кінцевий запит зберігаємо у змінній requestPayload і додаємо до тимчасових змінних за допомогою функції set_transient_variable(). Значення цієї змінної ми використаємо як вхідний параметр запита у налаштуваннях Trembita SOAP-конектора (див. детальніше — Налаштування делегата).

set_transient_variable('requestPayload', requestPayload)

Тимчасові змінні дозволяють зберігати дані на певний час, щоб вони були доступні наступним етапам скрипту (до наступної користувацької задачі), але не були збережені назавжди.

3.3. Сервісна задача для відправлення пошукового запита до іншого реєстру

Далі необхідно створити сервісну задачу, застосувати та налаштувати делегат для Trembita SOAP-конектора.

Див. детальніше у розділі Налаштування делегата.

3.4. Скрипт для виводу даних на UI-форму користувача

Далі необхідно передати дані на UI-форму, отримані в іншому реєстрі за допомогою SOAP-http-конектора. Для цього спочатку сформуйте відповідний скрипт, який зможе це зробити.

Створіть скрипт-задачу (Script Task).
Введіть назву. Наприклад, Підготовка отриманих даних для виведення на форму.

Відкрийте візуальний редактор скриптів та напишіть необхідний скрипт.

soap http 6

Загалом скрипт може виглядати так:

trembita connector 4

3.1. Формуємо JSON-об’єкт із параметрами state, name, code, id, щоб передати їх на форму.

3.2. Зберігаємо об’єкт до змінної payload, яку ми й використаємо як вхідний параметр для передачі даних на форму.

Скрипт для виводу даних на UI-форму користувача

def payload = [:]

        payload['state'] = getValueByPropertyName("state_text")
        payload['name'] = getValueByPropertyName("name")
        payload['code'] = getValueByPropertyName("code")
        payload['id'] = getValueByPropertyName("id")

        set_transient_variable('payload', S(payload, 'application/json'))

        def getValueByPropertyName(String propName) {
            return edrResponseBody.childElement("Body")
            .childElement("http://nais.gov.ua/api/sevdeir/EDR", "SearchSubjectsResponse")
            .childElement("SubjectList")
            .childElement("SubjectInfo")
            .childElement(propName)
            .textContent()
}

3.5. Користувацька задача передачі даних на UI-форму

Насамкінець необхідно вивести отримані в іншому реєстрі та опрацьовані скриптом дані на UI-форму користувача.

Змоделюйте користувацьку задачу (User Task), оберіть шаблон User Form (користувацька UI-форма) та виконайте налаштування.

Введіть назву задачі. Наприклад, Переглянути дані з ЄДР.
У полі ID введіть ідентифікатор задачі (activity_id). Наприклад, writeResultForm.
У полі Form key введіть службову назву UI-форми вводу даних. Наприклад, soap-http-connector-edrpou-edr-result-view.
У полі Assignee введіть токен ініціатора процесу — ${initiator}.
У полі Form data pre-population вкажіть як змінну об’єкт із параметрами, які необхідно передати на форму, — ${payload}.

Змінна формується у задачі Скрипт для виводу даних на UI-форму користувача.

soap http 7

Приклад UI-форми на інтерфейсі користувача може виглядати так:

Змоделюйте задачу завершення процесу та збережіть зміни.