Для интеграции виджета HBW во внешние системы необходимо:
- сделать прокси-контроллеры, через который встроенный виджет будет делать запросы в бэкенд HOMS;
- встроить JS виджета и отрендерить.
Прокси-контроллеры
Прокси-контроллер служит прослойкой между внешней системой и HOMS, где задаются необходимые параметры для работы с заказами и идентификации пользователя.
Необходимо разработать следующие методы:
метод, в котором ко всем параметрам запросов будут добавляться идентификатор пользователя
Code Block def with_user_identifier(parameters) parameters.merge( 'user_identifier' => Lib::GetSession.(params[:payload][:token])[:session][:vc_email] ) end
метод, который делает запрос для получений (
GET)
кнопок для начала бизнес-процесса, необходимые параметры:entity_class
(идентификатор интеграции),entity_type
(),entity_code
– уникальный код для создания заказа
(ссылка)
делать запрос (ссылка)
tasks
get tasks (ссылка)
получать форму – get 'tasks/#{params[:id]}/form', а также в заголовок запроса подмерживаются параметры:
entity_class
id
(ссылка)
обновлять форму – post 'tasks/#{params[:id]}/form', где в теле запроса должны быть:
entity_class
form_data
id
(ссылка)
lookup? get tasks/#{params[:id]}/lookup (ссылка)
(ссылка)
users
проверять пользователя (ссылка)
bpm_connector – обарабтывать запросы и ответы от HOMS (put_request_bpm_backend и др) (ссылка)
Info |
---|
This article is in English HBW widget integration manual |
Общая схема
- При открытии страницы приложения с виджетом, приложение-хост, используя public_url из конфига, запросит фронт виджета. Для аутентификации используются логин и токен из конфига
- Когда загрузится фронт виджета, он будет посылать запросы с url вида '/widget/...' в ЛК, запросы такого вида принимаются прокси-контроллером (hbw_controller.rb) и перенаправляются в бекэнд виджета.
Конфигурируемые параметры
Данные параметры используются для подключения приложения к HydraOMS:
hbw_url
– адрес HydraOMS (например, http://homs:3000);hbw_public_url
– адрес, по которому HydraOMS доступна из браузера (используется для получения статических файлов и открытия вебсокетов, например, https://some.domain:8100 или https://homs.some.domain. Значенияhbw_url
иhbw_public_url
могут совпадать);hbw_login
– логин (например, user@example.com);hbw_token
– токен (например, renewmeplease).
Фиксированные параметры
Данные параметры описывают, какое приложение подключается к HydraOMS и с какой сущностью будет работать бизнес-процесс:
entity_class
– тип интеграции (например, billing_customer (интеграция с ООС Гидры), self_care_customer (интеграция с ЛК Гидры), customer_care_portal (интеграция с Порталом обслуживания абонентов Гидры) или любое строковое значение, используемое в сторонней системе);entity_type
– тип сущности (например, customer, account, operator или любое другое строковое значение).
Динамические параметры
Данные параметры описывают запускаемый бизнес-процесс:
entity_code
– уникальный идентификатор или код сущности;user_identifier
- email пользователя, от имени которого запускается бизнес-процесс (обычно совпадает сhbw_login
);initial_variables
– дополнительные параметры, с которыми будет запущен бизнес-процесс.
Хелперы
Методы, которые выполняют отправку GET, POST, PUT и DELETE запросов к бэкенду HydraOMS:
Code Block | ||
---|---|---|
| ||
def request_widget_backend(path, method = :get, parameters = {})
request_params = {
method: method,
url: build_bpm_widget_path(path),
user: bpm_config.hbw_login,
password: bpm_config.hbw_token
}
if method == :get
request_params.merge!({headers: {params: parameters.merge(bpm_parameters)}})
else
request_params.merge!({payload: parameters.merge(bpm_parameters)})
end
RestClient::Request.execute(request_params)
end
private
def bpm_parameters
{
user_identifier: bpm_config[:hbw_login],
entity_type: params[:entity_type],
entity_code: params[:entity_code],
entity_class: params[:entity_class]
}
end
def build_bpm_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 :bad_request
end
else
render json: result
end
end
private
def permitted_params
params.symbolize_keys.except(*service_params)
end
def service_params
%i[controller action path format]
end |
Встраивание JS
Ниже приведен пример встраивания виджета в веб-страницу. После загрузки JS и CSS из HydraOMS выполняется инициализация виджета данными приложения и сущности, после чего вызывается функция render()
.
Code Block | ||||
---|---|---|---|---|
| ||||
<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 соединения
entity_class: 'crm_account',
entity_type: 'customer',
container_id: 'hbw-container', // Совпадает с идентификатором <div> контейнера
userIdentifier: 'user@example.com', // e-mail пользователя, которой использует виджет
locale: {
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: `#${config.container_id}`,
widgetURL: config.widgetURL,
widgetPath: '/widget',
entity_class: config.entity_class,
entity_type: config.entity_type,
entity_code: `${entityId}`,
locale: config.locale,
payload: {
variables: {
someInitialVariable: { // Также возможно установить дополнительные параметры, которые будут переданы при старте процесса
value: 'initialValue',
type: 'string'
}
}
}
});
window.hbw_widget.render();
// Если виджет встраивается в SPA (Single Page Appllication), необходимо вызвать следующую функцию перед закрытием текущей страницы.
// window.hbw_widget.unmountWidget();
</script>
</body>
</html>
|