Introduction

This document describes the steps to create a plugin for OpenSpecimen. This guide is intended for developers or technical IT staff. To write a plugin one should be aware of the OpenSpecimen domain structure.

As a developer you are expected to have working knowledge of:

Using REST APIs.
Java Spring
Angular JS

Prerequisites

Following table lists prerequisites and their supported versions.

Pre-requisite	Version
JDK	1.8
Gradle	2.0

Environment Variables

Following table lists and describes environment variables

Environment Variable	Description
JAVA_HOME	Absolute path of directory where JDK is installed. For example`: '`C:\JDK1.8'

Please refer to following variables used throughout the document.

Keyword	Comment
`PLUGIN_HOME`	Directory where plugin source code is kept. For example, `F:\os-plugin`.
`JAVA_HOME`	Directory where JDK is installed. For example, `C:\JDK1.8`

Following are high level steps:

Install prerequisite software which can be downloaded from http://demo.openspecimen.org/releases/Prerequisites/
Download the plugin skeleton os-plugin.zip
Unzip the downloaded file into a directory.

Plugin directory structure

src/main/java: All the custom java classes should got under this directory
src/main/resources
2.1. errors/messages.properties: All the messages and labels should go in this file
2.2. pluginContext.xml: All the bean definition should go in this file.
build.gradle: This file contains the complete build script for compiling and building the plugin

Steps to add custom Java classes

Please add all your Java classes under PLUGIN_HOME/src/main/java/com/krishagni/openspecimen
All the Spring configuration should be done in PLUGIN_HOME/src/main/resources/pluginContext.xml

Steps to create plugin archive

The build system uses Gradle to manage code compilation, building plugin jar archive.

Open command prompt. Change your current directory PLUGIN_HOME.
Use the following commands to build the plugin archive:
gradle clean
gradle build
The above target will create the archive in the build directory under respective plugin module. e.g. For current plugin the jar will get created at ${PLUGIN_HOME}/build/libs/os-plugin*.jar

Plugin Example

Below is a step by step guide to create a plugin to add a custom print token:

Create a new project by using the attached skelton
Import this project into any IDE like eclipse

Add new class
3.1 Add custom token implementation class named SpecimenCollectionProcedurePrintToken.java in package com.krishagni.openspecimen.plugin.token, like below:

package com.krishagni.openspecimen.plugin.token;

import com.krishagni.catissueplus.core.biospecimen.domain.Specimen;
import com.krishagni.catissueplus.core.common.domain.AbstractLabelTmplToken;
import com.krishagni.catissueplus.core.common.domain.LabelTmplToken;


public class SpecimenCollectionProcedurePrintToken extends AbstractLabelTmplToken implements LabelTmplToken {

	@Override
	public String getName() {
		return "specimen_collection_procedure";
	}

	@Override
	public String getReplacement(Object object) {
		Specimen specimen = (Specimen)object;
		while (specimen.getParentSpecimen() != null) {
			specimen = specimen.getParentSpecimen();
		}

		return specimen.getCollectionEvent().getProcedure();
	}
}

3.2. Add message key for the newly added label token. To add the message key need to update messages.properties file available at PLUGIN_HOME/src/main/resources/errors. Below is the sample: Register the token into OpenSpecimen with LabelTmplTokenRegistrar. Below is the code:

print_specimen_collection_procedure=Collection Proceudre
 
Note: OpenSpecimen will use this value in the cmd files as the label for collection procedure value.

3.3. Now we need to register the above token into OpenSpecimen with LabelTmplTokenRegistrar. First create a package com.krishagni.openspecimen.plugin.init and write a class named PluginInitializer. This class will register the above token implementation with OpenSpecimen

package com.krishagni.openspecimen.plugin.init;

import org.springframework.beans.factory.InitializingBean;

import com.krishagni.catissueplus.core.common.domain.LabelTmplTokenRegistrar;
import com.krishagni.openspecimen.plugin.token.SpecimenCollectionProcedurePrintToken;


public class PluginInitializer implements InitializingBean {
  
  private LabelTmplTokenRegistrar specimenPrintLabelTokensRegistrar;
   
  public void setSpecimenPrintLabelTokensRegistrar(LabelTmplTokenRegistrar specimenPrintLabelTokensRegistrar) {
      this.specimenPrintLabelTokensRegistrar = specimenPrintLabelTokensRegistrar;
  }

  @Override
  public void afterPropertiesSet() throws Exception {
      specimenPrintLabelTokensRegistrar.register(new SpecimenCollectionProcedurePrintToken());
  }
}

3.4. We have created a custom class for the token and written a plugin initializer which will register the new token with the LabelTmplTokenRegistrar. To make Spring aware to load this class we need to update the spring context. For this we need to add below in file PLUGIN_HOME/src/main/resources/pluginContext.xml

<bean id="pluginInitializer" class="com.krishagni.openspecimen.plugin.init.PluginInitializer">
  <property name="specimenPrintLabelTokensRegistrar" ref="specimenPrintLabelTokensRegistrar"/>
</bean>

Now we are done with the coding. Its time to deploy and test the plugin. Open the command prompt and traverse to PLUGIN_HOME. Run below commands:
4.1. gradle clean This will cleaup the classes and any unneccessary files
4.2. gradle build This will create the plugin archive file at PLUGIN_HOME/build/libs/
Copy the os-plugin.jar and place it under plugin directory
Start the tomcat
Update the default_specimen_print_rules.csv and specify the newly added token specimen_collection_procedure and update the print rules file path from the settings
Access the OpenSpecimen application, select a specimen and print it. The output will looks like below:
```
Label Type=Std
Printer=default
Label=P0001-1
Specimen Type=Plasma
Collection Procedure=Surgical Resection
Location=Virtual
```
You can download the complete working example from here:

Browser not supported