View Source

To integrate the HBW widget in an external system, you need to:

make proxy controllers through which the built-in widget will make requests to the HOMS backend with basic authentication (using the password and login from the config);
build in JS widget and render it.

Значение параметров запросов:

hbw_url – HOMS url (e.g. http://localhost:3002, from config file);
hbw_assets_path – address to HOMS static files HOMS (from config file);
hbw_login – login (e.g. user@example.com, from config file);
hbw_token – token (e.g. renewmeplease, from config file);
entity_class – integration name (from config file);
entity_type – order type (specified in the config file or mount location);
entity_code – unique code to create an order;
bp_code – business process code;
initial_variables – the parameters with which the business process is created.

Proxy controllers

Proxy controller is a intermediary for requests from external systems to HOMS, where the necessary parameters for working with orders and user authentication are set

The following methods need to be developed:

methods, which make GET, POST and PUT requests to HOMS backend:
- parameters that are passed to the GET requests must be specified in the request url, e.g.
  GET /widget/tasks?user_identifier=user@example.com&entity_type=&entity_code=ORD-6&entity_class=billing_customer;
- parameters that are are passed to the POST and PUT requests must be specified in the request body.

      def get_request_bpm_backend(path, parameters = {})
        params = request_params(path).merge(
          method:  :get,
          headers: {
            params: parameters
          }
        )

        rest_rack_response(params)
      end

      def post_request_bpm_backend(path, parameters = {})
        params = request_params(path).merge(
          method:  :post,
          payload: parameters
        )

        rest_rack_response(params)
      end

      def put_request_bpm_backend(path, parameters = {})
        params = request_params(path).merge(
          method:  :put,
          payload: parameters
        )

        rest_rack_response(params)
      end

      private

      def rest_rack_response(params)
        response = RestClient::Request.execute(params)

        [response.code, response.headers, [response.body]]
      end

      def request_params(path)
        {
          url:      build_bpm_widget_path(path),
          user:     configuration[:login],
          password: configuration[:password]
        }
      end

 
      def build_bpm_widget_path(path = '')
        URI.join(configuration[:url], '/widget/', path).to_s
      end

where

configuration: {
            url:      "http://localhost:3002/" (hbw_url),
            login:    user@example.com (hbw_login),
            password: renewmeplease (hbw_token)
}

method in which the user id is added to all request parameters to HOMS

def with_user_identifier(parameters)
        parameters.merge(
          'user_identifier' => GetSession.(params[:payload][:token])[:session][:email]
        )
end      
 
def allow_params(*allowed_params)
        with_user_identifier(params.slice(*allowed_params))
end

methods that work with start buttons of a business process

- method that makes a request to get (GET request) buttons to start a business process, the necessary parameters: entity_class, entity_type, entity_code

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

- method that starts a business process

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

methods for working with order forms
- receiving all orders – GET request with parameters entity_class, entity_code:

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

- getting the current order form – GET request with parameters entity_class, id:

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

- update the current order form – PUT request with parameters entity_class, form_data, id

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

getting information for lookup – GET request with parameters entity_class, name, q, id

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

- method for checking user rights.

get_request_bpm_backend('users/check')

Embedding JS

It is necessary to include in the HTML pages of the external system JS and CSS of widget:

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

Add to the <div> page with a unique ID, for example, bpmWidgetContainer, so the widget is rendered.

Call the render function on the widget object:

this.widget = new (modulejs.require('HBW'))({
        widgetContainer: `#${this.widgetContainerId}`,
        widgetPath: '/widget',
        entity_class: 'your_entity_class',
        entity_type: 'operator',
        entity_code: `${id}`,
        locale: i18n.language,
        payload: {
          token: cookies.get('token'),
          variables: {
            id: {
              value: `${id}`,
              type: 'string',
            },
          },
        },
      });

this.widget.render();