The Global Search Service is designed to integrate ElasticSearch with bpm'online. It performs the following functions:
•Recording:
•Subscribes clients by creating an index in ElasticSearch and saves the connection between the index and the application.
•Disconnects clients by removing their index in ElasticSearch.
•Transporting:
•Participates in the indexing process by retrieving data from the application database (DB).
This article provides instructions on global search setup for users of bpm’online 7.11.3 and later versions.
Note
The global search setup for users of earlier bpm’online versions (up to version 7.11.2) is covered in a separate article. Read more >>>
You need to have a server (physical or virtual machine) with Linux OS installed. Docker software is used for deploying the global search components.
Note
Depending on your company needs you can use either Docker Community Edition (CE) or Enterprise Edition (EE). Learn more in the Docker Guide.
Attention
You need to have basic knowledge of Docker software and Linux OS administration to set up global search.
Recommended system server requirements for global search setup
| CPU | Pentium 4, Athlon 64 or higher with SSE2 support. |
| RAM | 3 GB |
| HDD | 20 GB |
| OS | Linux application setup files that support Docker. Supported Linux families are covered in the Docker guide. |
Global search components
gs-web-api – web-service for global search component configuration.
gs-scheduler – scheduler of data indexing from BPM into ElasticSearch.
gs-worker – component of data indexing from BPM into ElasticSearch as per the scheduler tasks.
gs-worker-replay – component processing indexing results (gs-worker operation results).
rabbitmq – message broker.
elasticsearch – search engine.
mysql – database of global search component configuration.
Attention
Gs-web-api, gs-scheduler, gs-worker, gs-worker-replay and components can be installed on the same server. We recommend deploying the ElasticSearch, RabbitMQ and MySQL components on separate servers in failover clusters. If the listed components are deployed separately, disable the deployment of these components in Docker container via the RUN_RABBITMQ, RUN_ELASTICSEARCH and RUN_MYSQL variables.
Attention
Use the following link to download files required for setup.
Global search setup procedure
1.Install Docker to physical or virtual machine with Linux OS. Read more >>>
2.Install ElasticSearch. Read more >>>
3.Install RabbitMQ. Read more >>>
4.Set up MySQL. Read more >>>
5.Set up the container variables. Read more >>>
6.Install and run the Global Search Service components. Read more >>>
7.Populate the database with initial data. Read more >>>.
8.Enable bpm’online global search function. Read more >>>
Contents
•Setting up container variables
•Running containers with the Global Search Service components
•Initial population of the database
•Connecting global search service to bpm’online
Install Docker to Linux OS to deploy the global search components. The installation is covered in the Docker documentation. Read more >>>
Run the docker --version command on linux machine to verify the installed Docker version.
Instructions on RabbitMQ cluster setup for Docker, are available in a separate guide. Read more >>>
Instructions on RabbitMQ cluster setup without Docker, are available in RabbitMQ guide documentation. Read more >>>
1.Install ElasticSearch version 5.6.8. See ElasticSearch documentation for more information on the setup procedure. Read more >>>
2.After installing ElasticSearch, install the plugin for morphology search. Download the current version of the Morphological Analysis Plugin for ElasticSearch using the following link. You can find the morphology plugin installation instruction in ElasticSearch guide. Read more >>>
3.Add the following command to ElasticSearch docker file to install the plugin:
RUN bin/elasticsearch-plugin install http://dl.bintray.com/content/imotov/elasticsearch-plugins/org/elasticsearch/elasticsearch-analysis-morphology/5.6.8/ela...
Instructions on MySQL cluster installation for Docker, are available in the Docker documentation. Read more >>>
To install MySQL cluster without Docker, use MySQL guide instruction. Read more >>>
Setting up container variables
All global search component containers are configured via a file with environment variables. The variables are contained in the Docker/linux/default-env base file. Set the variable values by editing the ./docker/linux/default-env file.
Setting up variables for Oracle.
Change the GS_WORKER_DB_CONNECTION_STRING_PATTERN variable in the Docker/linux/oracle-env file for bpm’online applications using Oracle DB.
Setting up variables for MS SQL
| gs_worker_db_connection_string_pattern | Bpm’online database connection template. Specify the [DBLogin] user, the [DBPassword] password, the [DBServerName] bpm’online database server (for example, dbserver\\mssql2016) and the [DBName] bpm’online database name. Since containers are run under Linux OS control, Windows does not support authorization. For authorization, create a new SQL user or use an existing one. |
| gs_es_url | Specify [LinuxHostName]. If the ElasticSearch component is deployed together with other components, it is either IP-address or hostname of linux machine. If ElasticSearch is deployed separately – it is the host IP where ElasticSearch is deployed. |
| run_rabbitmq | By default, the variable value is “1”. A container with RabbitMQ will run if the value is set to “1”. If you do not need to run the container with RabbitMQ, set the value to “0”. |
| run_elasticsearch | By default, the variable value is “1”. A container with ElasticSearch will run if the value is set to “1”. If you do not need to run the container with ElasticSearch, set the value to “0”. |
| run_mysql | By default, the variable value is “1”. A container with MySQL will run if the value is set to “1”. If you do not need to run the container with MySQL, set the value to “0”. |
Set the values of the below listed parameters only if the RabbitMQ, ElasticSearch or MySQL components are deployed separately.
| gs_es_login | If ElasticSearch does not require base64 authorization, leave the parameter unpopulated. |
| gs_es_password | If ElasticSearch does not require base64 authorization, leave the parameter unpopulated. |
| gs_rabbitmq_amqp | Access to external RabbitMQ. You need to change the parameter if the RabbitMq component is deployed separately. |
| gs_db_connection_string | MySQL connection string. Change this parameter in the Docker/linux/mysql-env file if the MySQL component is deployed separately. •Server=gs-mysql – host; •ser id=$MYSQL_USER – user; •pwd=$MYSQL_PASSWORD – password. |
Running containers with the Global Search Service components
Attention
You need to have port 81 vacant to successfully run the gs-web-api container. Otherwise, change the $WEB_API_PORT variable.
1.Copy the Docker folder from the application setup files to the linux machine.
2.If the bpm'online application is deployed on MS SQL, run the following command:
sh Docker/linux/run.sh mysql mssql 1.0
1.If the bpm'online application is deployed on Oracle, run the following command:
sh Docker/linux/run.sh mysql oracle 1.0
The following Docker volumes will automatically be mounted upon successful container running:
•globalsearch (using gs-web-api, gs-worker);
•es1, if RUN_ELASTICSEARCH=1 (es-node1);
•es2, if RUN_ELASTICSEARCH=1 (es-node2);
•mysql, if RUN_MYSQL=1;
•rabbitmq, if RUN_RABBITMQ=1.
Note
Mounting inside the global search containers is performed via the following path: /usr/share/globalsearch.
Docker volume inspect globalsearch provides information about the created volume.
If one of the containers (MySQL, RabbitMQ or ElasticSearch) stops working, the data will be stored on external disk outside the Docker-container. You can learn more about volumes in Docker guide. Read more >>>
Verifying successful running of containers
Enter the docker ps -a command in the console to see all the containers that have been run.
The following containers should be run:
•gs-scheduler;
•gs-worker:
•gs-worker1;
•gs-worker2;
•gs-worker3;
•gs-worker-replay;
•gs-web-api – by default external port 81;
•ES, if RUN_ELASTICSEARCH = 1:
•es-node1;
•es-node2;
•rabbitmq, if RUN_RABBITMQ = 1;
•gs-mysql, if RUN_MYSQL = 1;
Logging
By default logging is performed during the “stdout” container command execution.
Note
docker logs --tail 100 gs-worker displays 100 last log strings from the gs-worker container.
Initial population of the database
The database is populated with system records once the GSS is launched. Prior to that, there is not even a database file, since the DB is automatically generated.
Connecting global search service to bpm’online
To connect global search to bpm'online, perform the following steps on the server:
1.Install the curl utility for http queries.
apt-get install curl
1.Perform the AddSite API-operation and specify:
•[site name] – bpm’online database name, for example, SalesTeamENU;
•[gs-web-api] – external address of the gs-web-api container that was run earlier.
curl -v -X POST -d '{"ApiKey": "testKey", "SiteName": "[site name]"}' -H "Content-Type: application/json" http://[gs-web-api]:81/addsite
1.Perform the AddSite API-operation and specify:
•[site name] – bpm’online database name, for example, SalesTeamENU;
•[gs-web-api] – external address of the gs-web-api container that was run earlier.
curl -v -X POST -d '{"ApiKey": "testKey", "SiteName": "[site name]"}' -H "Content-Type: application/json" http://gs-web-api:81/addsearch
Note
The indicated query will return URL to the index created in ElasticSearch. Save the URL and use it in the below system setting installation SQL-script.
Perform the following actions on bpm'online side:
1.Enable the Feature Toggle function of the global search (GlobalSearch, GlobalSearch_V2) by running the following SQL script:
DECLARE @GlobalSearchFeature NVARCHAR(50) = 'GlobalSearch';
DECLARE @GlobalSearchFeatureId UNIQUEIDENTIFIER = (SELECT TOP 1 Id
FROM Feature WHERE Code = @GlobalSearchFeature);
DECLARE @GlobalSearchV2Feature NVARCHAR(50) = 'GlobalSearch_V2';
DECLARE @GlobalSearchV2FeatureId UNIQUEIDENTIFIER = (SELECT TOP 1 Id
FROM Feature WHERE Code = @GlobalSearchV2Feature);
DECLARE @allEmployeesId UNIQUEIDENTIFIER = 'A29A3BA5-4B0D-DE11-9A51-005056C00008';
IF (@GlobalSearchFeatureId IS NOT NULL)
BEGIN
IF EXISTS (SELECT * FROM AdminUnitFeatureState WHERE FeatureId =
@GlobalSearchFeatureId)
UPDATE AdminUnitFeatureState SET FeatureState = 1 WHERE FeatureId
= @GlobalSearchFeatureId
ELSE
INSERT INTO AdminUnitFeatureState (SysAdminUnitId, FeatureState,
FeatureId) VALUES (@allEmployeesId, '1',
@GlobalSearchFeatureId)
END
ELSE
BEGIN
SET @GlobalSearchFeatureId = NEWID()
INSERT INTO Feature (Id, Name, Code) VALUES
(@GlobalSearchFeatureId, @GlobalSearchFeature, @GlobalSearchFeature)
INSERT INTO AdminUnitFeatureState (SysAdminUnitId, FeatureState,
FeatureId) VALUES (@allEmployeesId, '1',
@GlobalSearchFeatureId)
END
IF (@GlobalSearchV2FeatureId IS NOT NULL)
BEGIN
IF EXISTS (SELECT * FROM AdminUnitFeatureState WHERE FeatureId =
@GlobalSearchV2FeatureId)
UPDATE AdminUnitFeatureState SET FeatureState = 1 WHERE FeatureId
= @GlobalSearchV2FeatureId
ELSE
INSERT INTO AdminUnitFeatureState (SysAdminUnitId, FeatureState,
FeatureId) VALUES (@allEmployeesId, '1',
@GlobalSearchV2FeatureId)
END
ELSE
BEGIN
SET @GlobalSearchV2FeatureId = NEWID()
INSERT INTO Feature (Id, Name, Code) VALUES
(@GlobalSearchV2FeatureId, @GlobalSearchV2Feature,
@GlobalSearchV2Feature)
INSERT INTO AdminUnitFeatureState (SysAdminUnitId, FeatureState,
FeatureId) VALUES (@allEmployeesId, '1',
@GlobalSearchV2FeatureId)
END
1.Run the following script to install the system settings (GlobalSearchUrl, GlobalSearchConfigServiceURL):
UPDATE SysSettingsValue
SET TextValue = [specify URL to the ElasticSearch index, string of the following type - http://elasticsearch.local:9200/indexnamelong]
WHERE SysSettingsId = (SELECT TOP 1 Id FROM SysSettings WHERE Code =
'GlobalSearchUrl')
UPDATE SysSettingsValue
SET TextValue = [specify URL to the Global Search Service, string of the following type - http://gs-web-api:81]
WHERE SysSettingsId = (SELECT TOP 1 Id FROM SysSettings WHERE Code ='GlobalSearchConfigServiceUrl')
1.Restart the bpm’online application, clear Redis and log into the application.
See also
