Для интеграции виджета HBW во внешние системы необходимо:
- сделать прокси-контроллеры, через который встроенный виджет будет делать запросы в бэкенд HOMS;
- встроить JS виджета и отрендерить.
...
Info |
---|
This article is in English HBW widget integration manual |
Общая схема
Image Added
- При открытии страницы приложения с виджетом, приложение-хост, используя public_url из конфига, запросит фронт виджета. Для аутентификации используются логин и токен из конфига
- Когда загрузится фронт виджета, он будет посылать запросы с url вида '/widget/...' в ЛК, запросы такого вида принимаются прокси-контроллером (hbw_controller.rb) и перенаправляются в бекэнд виджета.
Конфигурируемые параметры
Данные параметры используются для подключения приложения к HydraOMS:
hbw_url
– адрес HOMSадрес HydraOMS (например, http://localhosthoms:30023000);
hbw_assetspublic_pathurl
– адрес статичесаких файлов HOMS, по которому HydraOMS доступна из браузера (используется для получения статических файлов и открытия вебсокетов, например, https://some.domain:8100 или https://homs.some.domain. Значения hbw_url
и hbw_public_url
могут совпадать);
hbw_login
– fs логин (например, user@example.com);
hbw_token
– токен (например, renewmeplease);.
Фиксированные параметры
Данные параметры описывают, какое приложение подключается к HydraOMS и с какой сущностью будет работать бизнес-процесс:
entity_class
– идентификатор интеграции (указывается в конфигетип интеграции (например, billing_customer (интеграция с ООС Гидры), self_care_customer (интеграция с ЛК Гидры), customer_care_portal (интеграция с Порталом обслуживания абонентов Гидры) или любое строковое значение, используемое в сторонней системе);
entity_type
– тип заказа (указывакется в конфиги или в месте монтирования);сущности (например, customer, account, operator или любое другое строковое значение).
Динамические параметры
Данные параметры описывают запускаемый бизнес-процесс:
entity_code
– уникальный идентификатор или код для создания заказасущности;
bp_code
– код заказаuser_identifier
- email пользователя, от имени которого запускается бизнес-процесс (обычно совпадает с hbw_login
);initial_variables
– параматерыдополнительные параметры, с которыми создается будет запущен бизнес-процесс.
Прокси-контроллеры
Прокси-контроллер служит прослойкой между внешней системой и HOMS, где задаются необходимые параметры для работы с заказами и идентификации пользователя.
Необходимо разработать следующие методы:
- методы, которые делают
GET,
POST и PUT
запросы в бэкенд HOMS:- параметры, которые передаются в
GET
запросы должны задаваться в заголовке запроса; - параметры, которые задаются в
POST и PUT
запросы должны задаваться в тело запроса.
...
Хелперы
Методы, которые выполняют отправку GET, POST, PUT и DELETE запросов к бэкенду HydraOMS:
Code Block |
---|
|
def request_widget_backend(path, method = :get, parameters = {})
params = request_params(path).merge( = {
method: method: :get,
headersurl: { build_bpm_widget_path(path),
paramsuser: parameters bpm_config.hbw_login,
}
)
rest_rack_response(params)password: bpm_config.hbw_token
}
end if method == :get
def post_request_bpm_backend(path, parameters = {}params.merge!({headers: {params: parameters.merge(bpm_parameters)}})
else
params = request_params(path).merge(
method: :post,
!({payload: parameters
).merge(bpm_parameters)})
end
rest_rack_response(RestClient::Request.execute(request_params)
end
private
def put_request_bpm_backend(path, parameters
= {})
params = request_params(path).merge(
method: :putuser_identifier: bpm_config[:hbw_login],
entity_type: payload: parametersparams[:entity_type],
entity_code: )params[:entity_code],
entity_class: rest_rack_response(params)params[:entity_class]
}
end
private
def restbuild_rackbpm_response(params)
response = RestClient::Request.execute(params)
[response.code, response.headers, [response.body]]
end
def request_params(path)
{
url: build_bpm_widget_path(path),
widget_path(path = '')
URI.join(bpm_config.url, '/widget/', path).to_s
end
def bpm_config
YourApplication::Config.widgets.bpm
end |
Параметры GET и DELETE запросов должны передаваться в query-части url, например:
GET /widget/tasks?user_identifier=user@example.com&entity_type=&entity_code=ORD-6&entity_class=billing_customer
Параметры POST и PUT запросов должны задаваться в теле (body) запроса. Тело запроса передается с content-type
= application/json.
Р
езультат из HydraOMS приходит с content-type
=
application/json
.
Прокси-контроллер
Прокси-контроллер служит прослойкой между внешней системой и HydraOMS. Он проверяет параметры, переданные из виджета, и передает их в бэкенд HydraOMS, добавляя к ним заголовок аутентификации и другие данные, необходимые для работы стыковки.
Code Block |
---|
|
# ANY match 'widget/*path'
def proxy
method = request.method.downcase.to_sym
result = request_bpm_backend(params[:path], method, permitted_params)
if method == :put
if result
head :no_content
else
head |
...
...
...
...
result
end
end
private
def |
...
...
params.symbolize_keys.except(*service_params)
end
|
...
def service_params
%i[controller action path |
...
где
...
Встраивание JS
Ниже приведен пример встраивания виджета в веб-страницу. После загрузки JS и CSS из HydraOMS выполняется инициализация виджета данными приложения и сущности, после чего вызывается функция render()
.
Code Block |
---|
language | xml |
---|
title | Пример HTML страницы |
---|
|
<html>
<head>
<title>HydraOMS Widget</title>
<script type="text/javascript" src="${hbw_public_url}/assets/hbw.js"></script>
<link rel="stylesheet" type="text/css" href="${hbw_public_url}/assets/hbw.css">
</head>
<body>
<div class="hbw-styles">
<div id='hbw-container'>
</div>
</div>
<script type="text/javascript">
var config = {
widgetURL: 'https://homs.some.domain', // hbw_public_url, необходим для установки WebSocket соединения
|
...
...
- метод, в котором ко всем параметрам запросов будут добавляться идентификатор пользователя
...
'crm_account',
entity_type: 'customer',
|
...
...
container_id: 'hbw-container', // Совпадает с идентификатором <div> контейнера
|
...
...
userIdentifier: 'user@example.com', // e-mail пользователя, которой |
...
...
...
- методы, которые работают с кнопками начала бизнес-процесса
метод, который делает запрос для получений (GET) кнопок для начала бизнес-процесса, необходимые параметры: entity_class, entity_type, entity_code
Code Block |
---|
|
BPMConnector.call.get_request_bpm_backend('buttons', allow_params('entity_class', 'entity_type', 'entity_code')) |
- метод, который начинает бизнес-процесс
Code Block |
---|
title | post /widget/buttons |
---|
|
BPMConnector.call.post_request_bpm_backend('buttons', allow_params('entity_class', 'entity_type', 'entity_code', 'bp_code', 'initial_variables'))
|
методы для работы с формами заказа
- получение всех заказов –
GET
запрос c параметрами entity_class
, entity_code
:
Code Block |
---|
|
BPMConnector.call.get_request_bpm_backend('tasks', allow_params('entity_class', 'entity_code'))
|
- получение формы текущего заказа –
GET
запрос c параметрами entity_class
, id
:
Code Block |
---|
title | get /widget/tasks/:id/form |
---|
|
BPMConnector.call.get_request_bpm_backend("tasks/#{params[:id]}/form", allow_params('entity_class', 'id'))
|
- обновление формы текущего заказа – put запрос с параметрами
entity_class
, form_data
, id
Code Block |
---|
title | put /widget/tasks/:id/form |
---|
|
BPMConnector.call.put_request_bpm_backend("tasks/#{params[:id]}/form", allow_params('entity_class', 'form_data', 'id'))
|
Code Block |
---|
title | get /widget/tasks/:id/lookup |
---|
|
BPMConnector.call.get_request_bpm_backend("tasks/#{params[:id]}/lookup", allow_params('entity_class', 'name', 'q', 'id'))
|
- метод для проверки прав пользователя.
Code Block |
---|
|
BPMConnector.call.get_request_bpm_backend('users/check') |
Встраивание JS
Включить в HTML страницы внешней системы JS и CSS виджета:
Code Block |
---|
|
<script type="text/javascript" src="<%= '\<\%\= hbw_assets_path \%\>' %>assets/hbw.js"></script>
<link rel="stylesheet" type="text/css" href="<%= '\<\%\= hbw_assets_path \%\>' %>assets/hbw.css">
|
Добавить на страницу <div> с уникальным ID, например, bpmWidgetContainer
Вызвать функцию render
у объекта виджета:
Code Block |
---|
|
this.{
code: 'en', // locale code
dateTimeFormat: 'DD/MM/YYYY HH:mm' // формат, используемый date-fns, документация https://date-fns.org/v1.30.1/docs/format
}
};
var entityId = ...; // Здесь должен быть указан уникальный идентификатор сущности, например customerId
window.hbw_widget = new (modulejs.require('HBW'))({
userIdentifier: config.userIdentifier,
widgetContainer: `#${ |
thiswidgetContainerIdcontainer_id}`,
widgetURL: config.widgetURL,
widgetPath: '/widget',
|
'your_' 'operator' id i18nlanguage tokencookies.get('token'),variablessomeInitialVariable: { // Также возможно установить дополнительные параметры, которые будут переданы при старте процесса
|
id:{ `${id}` ,,,);
window.hbw_widget.render();
|
}, });
this.widget.render();
встраивается в SPA (Single Page Appllication), необходимо вызвать следующую функцию перед закрытием текущей страницы.
// window.hbw_widget.unmountWidget();
</script>
</body>
</html>
|