Info |
---|
This article is in English HBW widget integration manual |
Общая схема
- При открытии страницы приложения с виджетом, приложение-хост, используя public_url из конфига, запросит фронт виджета. Для аутентификации используются логин и токен из конфига
- Когда загрузится фронт виджета, он будет посылать запросы с url вида '/widget/...' в ЛК, запросы такого вида принимаются прокси-контроллером (hbw_controller.rb) и перенаправляются в бекэнд виджета.
Конфигурируемые параметры
Данные параметры используются для подключения приложения к HydraOMS:
hbw_url
– адрес HOMS адрес HydraOMS (например, http://localhosthoms:3000);hbw_assetspublic_pathurl
– адрес статических файлов HOMS (обычно совпадает сhbw_assets_path
, по которому HydraOMS доступна из браузера (используется для получения статических файлов и открытия вебсокетов, например, https://some.domain:8100 или https://homs.some.domain. Значенияhbw_url
иhbw_public_url
могут совпадать);hbw_login
– логин (например, user@example.com);hbw_token
– токен (например, renewmeplease).
...
entity_class
– тип интеграции (например, billing_customer, crm_account, (интеграция с ООС Гидры), self_care_customer (интеграция с ЛК Гидры), customer_care_portal (интеграция с Порталом обслуживания абонентов Гидры) или любое другое строковое значение, используемое в сторонней системе);entity_type
– тип сущности (например, customer, account, operator или любое другое строковое значение).
...
Данные параметры описывают конкретную сущность, идентификатор которой будет передан в запускаемый бизнес-процесс при запуске, а также тип бизнес-процесса:
entity_code
– уникальный идентификатор или код сущности;bp_code
– код типа бизнес-процессаuser_identifier
- email пользователя, от имени которого запускается бизнес-процесс (обычно совпадает сhbw_login
);initial_variables
– дополнительные параметры, с которыми создается будет запущен бизнес-процесс.
Хелперы
Методы, которые выполняют отправку GET, POST и PUT
запросов POST, PUT и DELETE запросов к бэкенду HOMSHydraOMS:
Code Block | ||
---|---|---|
| ||
def getrequest_bpmwidget_backend(path, method = :get, parameters = {}) request_params = request_params(path).merge({ method: :get method, payloadurl: parameters ) return response(params) end def postbuild_bpm_backendwidget_path(path), parameters = {}) user: params = request_params(path).merge( bpm_config.hbw_login, methodpassword: :post,bpm_config.hbw_token } payload: parameters if method )== :get return response(params) end def put_bpm_backend(path, parameters = {} request_params.merge!({headers: {params: parameters.merge(bpm_parameters)}}) paramselse = request_params(path).merge( method: :put, !({payload: parameters ).merge(bpm_parameters)}) return response(params) end private def response(params) response = RestClient::Request.execute(request_params) end returnprivate { code: response.code, headers: response.headers, body: response.body } end def request_params(path) return def bpm_parameters { urluser_identifier: build_bpm_widget_path(path)config[:hbw_login], userentity_type: configurationparams[:loginentity_type], passwordentity_code: configuration params[:passwordentity_code], headersentity_class: { 'Content-Type': 'application/json' } } end params[:entity_class] } end def build_bpm_widget_path(path = '') return URI.join(configuration[:url]bpm_config.url, '/widget/', path) end def configuration return { url: "http://localhost:3000", # hbw_url login: "user@example.com", # hbw_login password: "renewmeplease" # hbw_token } end def with_user_identifier(parameters) return parameters.merge( user_identifier: session[:email] # email of current user ) end def allow_params(*allowed_params) return with_user_identifier(params.slice(*allowed_params)) end |
...
.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 | ||
---|---|---|
| ||
# ButtonsANY controller # GET /match 'widget/buttons*path' def list_buttons(params)proxy method = request.method.downcase.to_sym returnresult get= request_bpm_backend('buttons', allow_params('entity_class', 'entity_type', 'entity_code')) end # POST /widget/buttons def start_process(params) return post_bpm_backend('buttons', allow_params('entity_class', 'entity_type', 'entity_code', 'bp_code', 'initial_variables')) end # Tasks controller # GET /widget/tasks def list_tasks(params) return get_bpm_backend('tasks', allow_params('entity_class', 'entity_code')) end # GET /widget/tasks/:id/form def fetch_task_form(params) return get_bpm_backend('tasks/#{params[:id]}/form', allow_params('entity_class', 'id')) end # PUT /widget/tasks/:id/form def save_task_form(params) return put_bpm_backend('tasks/#{params[:id]}/form', allow_params('entity_class', 'form_data', 'id')) end # GET /widget/tasks/:id/lookup def fetch_lookup_value(params) return get_bpm_backend('tasks/#{params[:id]}/lookup', allow_params('entity_class', 'name', 'q', 'id')) end # Users controller # GET /widget/users/check def check_user_access(params) return get_bpm_backend('users/check') 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_assetspublic_pathurl}/assets/hbw.js"></script> <link rel="stylesheet" type="text/css" href="${hbw_assetspublic_pathurl}/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 = ...; // SetЗдесь hereдолжен idбыть orуказан otherуникальный uniq value of entityидентификатор сущности, likeнапример 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: { // YouТакже canвозможно passустановить otherдополнительные usefulпараметры, informationкоторые toбудут processпереданы initialпри variablesстарте процесса value: 'initialValue', type: 'string' } } } }); window.hbw_widget.render(); // IfЕсли youвиджет useвстраивается someв kindSPA ot SPA(Single Page Appllication), callнеобходимо thisвызвать beforeследующую pageфункцию unmount:перед закрытием текущей страницы. // window.hbw_widget.unmountWidget(); </script> </body> </html> |
...