Инструкция по интеграции HBW во внешнюю систему

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:

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, добавляя к ним заголовок аутентификации и другие данные, необходимые для работы стыковки.

# 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().

Пример 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 соединения
      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>

Page tree