Page History

Для интеграции виджета HBW во внешние системы необходимо:

• сделать прокси-контроллеры, через которые встроенный виджет будет делать запросы в бэкенд HOMS с базовой аутентификацией (используя пароль и логин из конфига);
• встроить JS виджета и отрендерить.

...

Общая схема

Image Added

1. При открытии страницы приложения с виджетом, приложение-хост, используя public_url из конфига, запросит фронт виджета. Для аутентификации используются логин и токен из конфига
2. Когда загрузится фронт виджета, он будет посылать запросы с url вида '/widget/...' в ЛК, запросы такого вида принимаются прокси-контроллером (hbw_controller.rb) и перенаправляются в бекэнд виджета.

Конфигурируемые параметры

Данные параметры используются для подключения приложения к HydraOMS:

• hbw_url – адрес HOMS адрес HydraOMS (например, http://localhost:3002, указывается в конфигеhoms:3000);

• hbw_assetspublic_pathurl – адрес статичесаких файлов HOMS (указывается в конфиге, по которому 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 – уникальный идентификатор или код для создания заказасущности;

• bp_code – код бизнес-процессаuser_identifier - email пользователя, от имени которого запускается бизнес-процесс (обычно совпадает с hbw_login);

• initial_variables – дополнительные параметры, с которыми создается будет запущен бизнес-процесс.

Прокси-контроллеры

Прокси-контроллер служит прослойкой между внешней системой и HOMS, где задаются необходимые параметры для работы с заказами и идентификации пользователя.

Необходимо разработать следующие методы:

• методы, которые делают GET, POST и PUT запросы в бэкенд HOMS:
  • параметры, которые передаются в GET запросы должны задаваться в заголовке запроса;
  • параметры, которые задаются в POST и PUT запросы должны задаваться в теле запроса.

...

Хелперы

Методы, которые выполняют отправку GET, POST, PUT и DELETE запросов к бэкенду HydraOMS:

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

# 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>
<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: 

...

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

...

'crm_account',
      entity_type: 'customer',
 

...

...

container_id: 'hbw-container', // Совпадает с идентификатором <div> контейнера
    

...

...

 userIdentifier: 'user@example.com', // e-mail пользователя, которой 

...

использует 

...

виджет
      locale: 

...

• методы, которые работают с кнопками начала бизнес-процесса

• • метод, который делает запрос для получения (GET) кнопок для начала бизнес-процесса, необходимые параметры: entity_class, entity_type, entity_code

     

get_request_bpm_backend('buttons', allow_params('entity_class', 'entity_type', 'entity_code'))

• • метод, который начинает бизнес-процесс 

post_request_bpm_backend('buttons', allow_params('entity_class', 'entity_type', 'entity_code', 'bp_code', 'initial_variables'))

• методы для работы с формами заказа

• получение всех заказов – GET запрос c параметрами entity_class, entity_code:

get_request_bpm_backend('tasks', allow_params('entity_class', 'entity_code'))

• • получение формы текущего заказа –  GET запрос c параметрами entity_class, id:

get_request_bpm_backend("tasks/#{params[:id]}/form", allow_params('entity_class', 'id'))

• • обновление формы текущего заказа – put запрос с параметрами entity_class, form_data, id

put_request_bpm_backend("tasks/#{params[:id]}/form", allow_params('entity_class', 'form_data', 'id'))

• получение информации для лукапов – GET запрос с параметрами entity_class, name, q, id

get_request_bpm_backend("tasks/#{params[:id]}/lookup", allow_params('entity_class', 'name', 'q', 'id'))

• • метод для проверки прав пользователя.

get_request_bpm_backend('users/check')

Встраивание JS

Необходимо включить в HTML страницы внешней системы JS и CSS виджета:

<script type="text/javascript" src="<%= '\<\%\= hbw_assets_path \%\>' %>assets/hbw.js"></script>
<link reluser_identifier="stylesheet" type="text/css" href="<%= '\<\%\= hbw_assets_path \%\>' %>assets/hbw.css">

{
		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>