PART 7: SETUP ANALYZERS

Accessing analyzers on OpenELIS

1. Type in your username and password and click on the Submit button.

2. Once you connect to OpenELIS Global, the instance is set-up to receive some analyzer results from analyzers. Click on the results menu items then click on analyzers. The existing setup analyzers will be displayed.

3. The OpenELIS new front-end user interface (UI) is also set up with analyzers under the results tab. To access analyzers, click on the  menu icon at the top left side of the screen.

4. Click on the Results drop-down menu item.

5. Click on analyzer

How to build and compile  OpenELIS analyzers 

1. To get started with setting up analysers, type OpenELIS/Global on your web browser

2. Click on the Openelisglobal-plugins repository on GitHub 

3. Clone the repository locally

4. Run a Git Clone command under the respective directory in your local machine

5. Open  the directory where you cloned the project. At this juncture, all that needs to be done is build the project by running maven clean install to compile the sub-modules in the root  directory of the project. 

However, the path: <systemPath>/home/runner/work/openelisglobal-plugins/openelisglobal-plugins/lib/openelisglobal-2.7.3.8.jar</systemPath>

Will fail  the build using maven clean install since it is meant to be executed under GitHub actions. For testing purposes this needs to be modified to be a local value. 

6. To modify this, click on the lib folder then click on file openelisglobal-2.7.3.8.jar file and copy the path.

7. Paste the path under systemPath and  save.

After saving, run Maven clean install. This action will generate plugin files under the plugin directory. 

8. These plugins can not be used due to the difference between the java version of the local development machine and the OpenELIS  instances which are at Java version 11.  Until that changes, we need to compile the jars under a java version which matches the deployment version. Therefore, the jar files should be deleted. Select the jar files and click on the Delete option 

9. Confirm the deletion by clicking on the Move to recycle Bin button. The jar files will be deleted successfully. 

Note: If Java 11 was locally available on the development machine, that would have been all that is necessary. However, since this is not the case, we shall run a docker file which will build in a  docker container using jdk 11 this will create the same files in a different folder.

Note: The systemPath under the pom.xml file  is the local path as set earlier on. This is not what will be in the docker build.

Note: The docker build has the lib directory put in build/lib

10. Copy the path above and paste under the systemPath up to the lib portion.

11. Upon pasting the docker path, run a sudo docker build command in the current directory. This action will build the docker image.

12. Delete the cached values of the jar files since they are no longer needed.

Note: The Maven clean install will be ran in the docker container

Note: upon successful build of the docker image, the plugin directory will be put under build/plugins/ which is not mounted by default.

13. Run the docker container using sudo docker compose -up -d -- build command 

Note: The --build will skip the step to build the image and uses the cached version hence the build finishes quickly. The plugin container will be built and started.

14. Drop into the plugin container by executing the command docker exec -it plugin bash to get a bash session. 

15. Execute the command ls /build/plugins/ to list all the jar files under the plugins container

16. Move, from the build plugins all the files into our plugins directory by executing the command mv build/plugins/*  /plugins/

The plugin will be mounted on docker compose and the jar files will be listed as shown

17. The analyzer is successfully built. Execute the command exit to navigate to the project folder.

Deploying Analyzers to An OpenELIS instance

How to Upload Analyzers to An OpenELIS instance via drop-box

Note: To deploy the analysers, the easiest way is to take the jar files and upload them to dropbox then download them to an OpenELIS instance. The following steps illustrate how this is done.

1. Check the file permissions by executing the command; ls plugin/ -al . The files will be restricted for upload since they have a root permissions.

2. Execute the command to change permission to  the user. In this illustration the user permission is changed recursively to user Caleb (change to respective user) using the command sudo chown caleb:caleb -R plugins/ 

3.  Check the file permissions by executing the command; ls plugin/ -al . The file's permissions  will  be changed from the root directory to the user. The files can now be uploaded to drop-box and downloaded to an OpenELIS instance.

How to Upload Analyzers to An OpenELIS Instance Via Secure Copy

Note:In the following illustration, we shall be using a secure copy. not be copying the files to the drop-box but rather we shall be copying one file directly by using a secure copy. In this illustration, Mindray-0.1.jar will be copied.

1. Copy the path for a jar file and send it to a test instance of  OpenELIS under the home directory

2. Securely access the test instance through by executing the command ssh ubuntu@testing.openlis-global.org and entering the username and password

3. list the directory for the test server  by executing the ls command. The Mindray-0.1.jar file will be listed on the server.

4. Execute the command sudo mv var/lib/openelis-global/plugins/  to move the file to the right location.

5. Confirm the file has been moved by listing the directory. Execute the command ls var/lib/openelis-global/plugins/ the Mindray-0.1.jar file will be listed in the directory

Note: Moving the file to the directory is not enough since a quick reload of the OpenELIS instance and accessing the analyzers will not display the Mindray analyzer.

6. OpenELIS only loads the analyzer when it is starting. Therefore, restart the server. To do this, change the directory to the latest installer of OpenELIS by executing the command cd OpenELIS-Global_2.8.1.37_installer/

7. Due to the nature of Docker file caching, it is better to bring down the entire project then bring it up. Therefore, execute the command sudo docker compose down

8. Execute the sudo docker compose up -d to bring the project up

9. Check the log of the back-end service to make sure that the project has succeeded starting up. To do this, execute the command: Sudo docker logs openelis-global-webapp -- follow

Note: The startup logs will be displayed. 

10. A quick look at the OpenELIS new user interface (UI) will show that the front end has started up. However the version number will be missing. This is due to the fact that the version number is fetched from the back-end. Therefore, until the version number is displayed, the back-end has not finished starting up. This will take a few minutes to complete.

Note: As the startup is executing, revert the systemPath back to the initial path as found in the GitHub repository. This is not related to the startup completion. You might have noticed that the version of OpenELIS (openelisglobal-2.7.3.8.jar) is not the same as the testing server (OpenELIS-Global_2.8.1.37). The difference is insignificant unless there are  changes in the analyzer plugin portion of OpenELIS. This type of change does not happen frequently hence the use of an outdated version is allowed as long as it matches up. In the event you are working on new analysers and there is need for changes in OpenELIS to support functionality of the analyzers, you will need to make those changes in the OpenELIS code base hence the need to populate the jar file difference openelisglobal-x.x.x.x.jar  for it to be used. In this illustration, the openelisglobal-2.7.3.8.jar should be synonymous with the 2.8.1.37 we are running on the test instance.

Once the the back-end has finished starting up, the startup logs are displayed as shown 

11. Login to the new  UI OpenELIS. Notice the version number is now populated.

12. Upon successful login, click on the  menu icon at the top left side of the screen.

13. Click on the Results drop-down menu item. 

14. Click on the  analyzer drop-down menu item. The new analyser will be displayed.

How to Setup an ASTM Bridge 

Upon the successful setup of analyzers to submit to OpenELIS, OpenELIS  is able to accept  those connections. OpenELIS needs to know where to submit the results. There exists a number of ways for submitting results. The illustration below shows the submission of results through end points that are used for results submission.

•  The  /importAnalyzer is one of the main end-points

• The end-point is a PostMapping and accepts MultipartFile file. The end-point will support analysers that are done and generate a flat file of information with the results of analysis.

• It can submit that file into a queue which gets submitted to OpenELIS which comes to the same end-point where it determines which analyser it is sending to and records the information stored within.

• The end-point would typically be at the section of the URL as shown below

• The illustration below shows the URI  for the end-point that we will  post to using  a https request together with the files and OpenELIS will handle the rest using the jar file that was added to it.

Another way that OpenELIS accepts analyzer results is via /Analyzer/astm. In this method, Instead of receiving a file as in the case of  /importAnalyzer, ASTM compliant messages are received over http request.

Note: ASTM encompasses multiple standards both transmission protocol and message format hence the /analyzer/astm expects an ASTMS message format over http transmission standard.  It will not accept ASTM protocol messages at the /analyzer/astm end-point

Some analyzers only accept ASTM protocol. Having established that the /analyzer/astm end-point will not accept ASTM protocol messages, another component is required. The component once it transforms it to an ASTM message over HTTP it will send it to the  /analyzer/astm end-point and OpenELIS will pass the message. The illustration below shows the /analyzer/astm  endpoint URL 

Note: To get the ASTM, we shall need an ASTM HTTP bridge.

1. The ASTM HTTP bridge is a service running on Docker parallel to OpenELIS. Execute the command sudo docker ps.

The ASTM bridge container is displayed under the list of containers. It listens on two different end-points and forwards messages depending on the direction it is going. Mostly analyzers forward messages in one direction thus, results submission is done on port 12000 that receives ASTM protocol messages and transforms them to HTTP then forward them to the configured OpenELIS instance.

The configuration file leaves at vi /var/lib/openelis-global/astmbridge/configuration.yml if the file does not exist locally, you will be required to create it before making changes to it.

2. Enter the command vi /var/lib/openelis-global/astmbridge/configuration.yml

The file will be displayed in the terminal in the yml format. The key portion of the file is the forward-astm-server. That is, which HTTP server is forwarding ASTM protocol. The uri points to where the messages will be forwarded to. The authentications credentials are also provided.

The forward-astm-server is used when you want to forward messages to an ASTM server but receive HTTP. 

Note: We shall leave the file as it is. This is due to the fact that changes related to the file can be done under Docker compose

3. Enter the command vi docker-compose.yml. The file will be open on an editor

Note: The docker-compose file that is installed when you run the set-up script has a service called astm-http-bridge.openelis.org. The service exposes two ports. The configuration default port 12001 is where the service listens in the docker container. Outside the Docker container it listens to port 12000 on the host. Therefore, we can point our ASTM compliant analyzers to forward to wherever the service is running on 12000 and the service will forward it to the configured OpenELIS endpoint. The port can be edited. For example, if  an analyzer only supports a 4-digits port number and the file changes can be saved respectively.

Note: The file also has truststore set by default to use the same truststore and Keystore as OpenELIS. Hence, trust exists by default.

Note: If we had executed the setup script for OpenELIS the astm-http-bridge.openelis.org service will be commented out by default. This is due to the fact that the service is optional to be running only if the instance is using analysers that require an ASTM bridge.

4. The execution of setup.in scripts uncomments the astm-http-bridge.openelis.org service. Open the editor by executing the command vi setup.ini. 

5. Upon opening the file on the editor, set the activation status to true. By default, the status is false. This is the reason why the service is commented out. Upon setting the status to true, the service remains uncommented in subsequent runs of the setup script

6. If we have already executed the setup script previously, we shall need to change the setup of the setup.ini file in a different location. Ideally, the first run of the setup script copies the file to /etc/openeis-global/setup.ini. Open the file on an editor by executing vi /etc/openeis-global/setup.ini

If the setup script was executed once. We will need to make the change on activate_astm = true in the file.  If OpenELIS setup script was executed before, the header ADDITIONAL SERVICES will have to be added

Note: Any subsequent execution of the setup script through python using the command sudo python3 setup_OpenELIS.py  will read the value and uncomment it from docker-compose

Note: The file is normally located in the base template where it is read from. The base template can be accessed via an editor through the command: vi templates/docker-compose.yml

Note: The astm bridge is commented out but the comment will be removed.

At this juncture, the astm-bridge is running and it will be set up anytime we run the setup script. In the event you are using the docker-compose file and not using the setup script do not comment out the service. This way, the service should keep running