Custom Plugin

A custom plugin is a scripted service that can process data in a customized manner using Java-programming constructs and provides an extension point for adding any customized data processing logic. You can write a Java logic that will execute the service. Java logic has an access to the script service, the context of the process flow this service belongs to, and input and output stream handlers that allow Java logic to access and manipulate input data to generate the output and pass it to another service in a process flow. 

You can create a custom plugin using the following three options:

• Script
• Custom APIs
• Spring Bean

To create a custom plugin:

1. Click Configure > EXTENSIONS > Custom Plugin.

2. Click Create Custom Plugin. 

3. Provide the name and description of the new custom plugin service in the Name and Description text boxes.
   
   
   
   
4. Type the encoding standard in Character Set Encoding and click Refresh. You can also use the default encoding standard UTF-8.

5. Type the variables' names and their values in the Variables table. 
   While writing the Javascript for a custom plugin, you do not need to hard code the values in the code. You can define variables and their values in a tabular format and can use those variables in the custom plugin script. Expand the following two sections to get more details on how you can work with variables and their values. 
   
   

    Encrypting the variables using Vault

   To encrypt the Variable Value using Vault, first create a vault and instead of writing the Value in plain text, write the aliasName and the key, which contains the Variable Value, in the following format:
   
   {Vault.aliasName.key}
   
   where,

   • Following an opening curly parentheses, 'Vault' is a keyword (V in 'Vault' is UPPERCASE).
   • aliasName is the Vault Alias, where the parameter is defined.
   • key is the parameter which stores the Variable Value.
   • Finally closed by a closing curly parentheses.
   • A period is used as a separator between Vault and aliasName; and aliasName and key.

   
   For example, while adding username in a Custom Plugin, provide its Value as {Vault.safe.client_key}
   
   

    Fetching the variables in the script

   Once the variables are defined in Step 5 above, you can fetch their values in the script through following syntax-

   service.getValueByName("VariableName");
   
   For example, if we need a script to print- "USERNAME adeptia", where adeptia is the vaule defined for username in Step 5, the syntax for this will be:

   String getname =service.getValueByName("username");
   System.out.println("USERNAME" + getname);

6. Select the Interpreter Type.
   The sections below discuss three different options to define a custom plugin. They also list out the pros and cons of each of the options and help you decide which one to be used.
   
   

    Script

   In this option, you need to define the Java code which is parsed and executed during the process flow execution.

   The following list gives you a clear idea about the pros and cons associated with this approach.

   Pros:

   • Dynamic execution of the full Java syntax, Java code fragments, as well as loosely typed Java and additional scripting conveniences.
     
   • Easy and rapid prototyping of the business logic.
     
   • No restart of Adeptia services is required after you make any update to the script.
     

   Cons:

   • Under heavy load, when multiple instances of the custom plugin script are running concurrently, the performance is degraded.
    Custom API

   Using this option enhances the performance of the process flow execution. In this option, you need to select the class and its method for the execution of the process flow. The process flow will be executed on the basis of the code implemented in the selected method.

   The Custom API approach uses the traditional Java Reflection technique to load the class dynamically, instantiate it, and invoke the specified method. This technique has a performance impact under heavy load and therefore has been marked as deprecated. This option is available in the custom plugin activity for backward compatibility purpose only.

   To create a custom plugin using custom APIs, first create a class with method(s) and put that in the .../<AdeptiaInstallFolder>/ServerKernel/customClasses/<ClassPackage> folder where <ClassPackage> is the package where you have defined the Java class. For example, if you have defined the Java class in the org.custom package then first create the org/custom folder in the .../<AdeptiaInstallFolder>/ServerKernel/customClasses folder and put the class in the custom folder. Ensure that the following conditions are fulfilled:

   • The class must implement PluginExecutor interface.

     public class <class_name> implements PluginExecutor

   • The method should accept only one parameter and that must have an object of ExecutionEvent.

     public boolean <method_name>(ExecutionEvent event) throws Exception

   • The method must be public.
     

   The following list gives you a clear idea about the pros and cons associated with this approach.

   Pros:

   • Works better than the script approach under high load. However, Adeptia recommends to use spring bean approach as it is more optimized and works better than a custom plugin.
     

   Cons:

   • Every time you need to either develop a new or update the existing Java bean class.
   • You must restart Adeptia services to bring the changes into effect.
   • It is slower in execution than Spring Bean approach.
    Spring Bean

   In this option, you need to define the spring bean file and place that in customClasses\custom\beans folder. This option improves the execution of custom plugin under heavy load of concurrent execution of process flows.

   To use Spring Bean in Custom Plugin, you first need to create a Custom Class file and place it customClasses\custom\beans folder.

   Follow the steps below to create the custom class:

   1. Create a new Java class into custom.beans package or its sub-package as shown below.
      In your spring bean class, it is mandatory to have custom.beans package.
      
      
      
      
      
      

   2. Implement the ScriptExecutor (com.adeptia.indigo.api.custom.ScriptExecutor) Interface.
      
      
      
      

      This class should define the execute method that accepts ExecutionEvent instance as an argument. The ExecutionEvent instance will be passed that contains information about the runtime variables that are required to execute the business logic. The variables are:
      

      • Process Flow Context - contains all the variables present in the Process Flow Context
      • Service instance - contains information like name and id of the custom plugin activity
      • Input Data Stream - a reference to the input data stream to the custom plugin activity
      • Logger - a reference to the Process Flow logger instance
   3. Apply the Spring @Component annotation to mark this class as Spring Bean.
      
      
      
      
   4. Write your business logic into the execute method.

   5. Compile the class.
      

      Ensure that you have the following Jars in the class path to successfully compile the above class.

      • BPMServer.jar (present in web/libs folder).
      • spring-context-xxx.RELEASE.jar (present in web/libs/spring folder)

   6. Put this class into the customClasses folder.
      

   Once you have created a custom class, perform the following steps to use it in Custom Plugin:

   • Create a custom\beans folder in the  .../<AdeptiaInstallFolder>/ServerKernel/customClasses path and place the spring bean file in customClasses\custom\beans folder which you can use as Spring Bean.

   • In case there is any further hierarchy in the package then you must create the sub-folder according to the package hierarchy within the custom/beans folder.
     
     

   Restart the Adeptia services to bring the changes into effect.

   Once defined, this bean name will be displayed in the Spring Bean Name drop-down list.
   

   
   

   The following list gives you a clear idea about the pros and cons associated with this approach.

   Pros:

   • High performance under heavy load of concurrent execution of process flows.

   Cons:

   • Every time you need to either develop a new or update the existing Java bean class.
     
   • You must restart Adeptia services to bring the changes into effect.
     
     

   In case of high-performance needs under heavy load, Adeptia recommends using the Spring Bean option where the class instantiation and management is done by Adeptia Spring container which is highly optimized.

   Click Hide Script if you want to hide the Script.

   
   

7. Expand Advanced Properties and select the Project from drop-down list of Project.
8. Click Save.