Prerequisites
Important: Before proceeding, read and agree to the Developer Disclaimer.
To create a custom plugin for Ephesoft Transact, you will need the following installed on your system:
- Java JDK
- Apache Maven
- Eclipse
- Maven
To install Maven, perform the following steps:
- Open Eclipse.
- Go to Help > Eclipse Marketplace.
- Search “Maven”.
- Click Install on “Maven Integration for Eclipse”.
- Follow the installation steps as prompted.
- After the installation is complete, go to Window > Preferences. You should see Maven listed in the left panel.
Create a Custom Plugin
Create a New Project
- Open Eclipse.
- Click File > New.
- Select Maven Project.
Figure 1. Create a Maven Project
- Select Use default Workspace location.
Figure 2. Use Default Workspace Location
- Select the quickstart Maven archetype. The Artifact ID is maven-archetype-quickstart.
Figure 3. Select Quickstart Maven Archetype
- Enter the Group ID and Artifact ID. The Group ID is the package structure for your project. The Artifact ID will be the name of your project, and the final source folder of your package. More information about the Java specification for package names can be found in this Oracle article.
- Group ID: com.ephesoft.customplugin
- Artifact ID: ephesoft-custom-plugin
Figure 4. Enter Group ID and Artifact ID
- Your Eclipse project workspace should now look like this:
Figure 5. Sample Eclipse Project
Add Ephesoft Libraries
Perform the following steps to add the Ephesoft Libraries to your Eclipse project.
Note: Custom script class files should not be added to any custom JAR files. Adding a custom script class file into any JAR file will cause issues, as the default location for the custom script class file is [Ephesoft_Directory]\JavaAppServer\temp\DynamicCodeCompiler.
- Open your project folder. Right-click on ephesoft-custom-plugin.
- Select Build Path > Configure Build Path.
- Select the Libraries tab.
- Click Add External Jars.
- Navigate to [Ephesoft_Directory]\Application\WEB-INF\lib.
- Select all JAR files.
- Click Open.
- Click OK.
Create a New Interface
Perform the following steps to create a new Java interface for your custom plugin.
- Open your package. Right-click on com.ephesoft.customplugin.ephesoft.custom_plugin.
- Select New > Interface.
- Set the Name to “CustomPlugin”.
Figure 6. New Java Interface
- Click Finish.
- Replace the file contents with the following code:
package com.ephesoft.customplugin.ephesoft_custom_plugin; import com.ephesoft.dcma.core.DCMAException; import com.ephesoft.dcma.da.id.BatchInstanceID; public interface CustomPlugin { void helloWorld(final BatchInstanceID batchInstanceID, final String pluginWorkflow) throws DCMAException; }
Figure 7. Replace File Contents
Create a Java Class
Perform the following steps to create a Java class to implement the CustomPlugin interface.
- Open your package. Right-click on com.ephesoft.customplugin.ephesoft.custom_plugin.
- Click New > Class.
- Set the Name to “CustomePluginImpl”.
Figure 8. New Java Class
- Click Finish.
- Replace the file contents with the following code:
package com.ephesoft.customplugin.ephesoft_custom_plugin; import org.springframework.util.Assert; import com.ephesoft.dcma.core.DCMAException; import com.ephesoft.dcma.core.annotation.PostProcess; import com.ephesoft.dcma.core.annotation.PreProcess; import com.ephesoft.dcma.core.component.ICommonConstants; import com.ephesoft.dcma.da.id.BatchInstanceID; import com.ephesoft.dcma.da.service.BatchClassPluginConfigService; import com.ephesoft.dcma.util.BackUpFileService; public class CustomPluginImpl implements CustomPlugin, ICommonConstants { private BatchClassPluginConfigService batchClassPluginConfigService; @PreProcess public void preProcess(final BatchInstanceID batchInstanceID, String pluginWorkflow) { Assert.notNull(batchInstanceID); BackUpFileService.backUpBatch(batchInstanceID.getID()); } @PostProcess public void postProcess(final BatchInstanceID batchInstanceID, String pluginWorkflow) { Assert.notNull(batchInstanceID); } public void helloWorld(BatchInstanceID batchInstanceID, String pluginWorkflow) throws DCMAException { //TODO Auto-generated method stub String name = ""; String propertyName = "app.name"; name = batchClassPluginConfigService.getPluginPropertiesForBatch(batchInstanceID.getID(), "EPHESOFT_CUSTOM_PLUGIN").get(propertyName); System.out.println("**** Ephesoft Custom Plugin: Hello " + name + " " + batchInstanceID.getID() + " *****"); } public BatchClassPluginConfigService getBatchClassPluginService() { return batchClassPluginConfigService; } public void setBatchClassPluginConfigService(BatchClassPluginConfigService batchClassPluginConfigService) { this.batchClassPluginConfigService = batchClassPluginConfigService; }
Figure 9. Replace File Contents
Create Folder Structure for XML Resources
Perform the following steps to create a folder structure for your XML resources.
- Right-click on your project in the Project Explorer.
- Click New > Source Folder.
- Set the Folder Name to “src/main/resources”.
Figure 10. New Source Folder
- Click Finish.
- Create a META-INF folder:
- In the project folder you just created, right-click src/main/resources.
- Click New > Folder.
- Set the Folder Name to “META-INF”.
- Click Finish.
- Create a subfolder under META-INF.
- Right-click the META-INF folder.
- Select New > Folder.
- Set the Folder Name to “ephesoft-custom-plugin” (or the name of your project, if different).
- Click Finish.
Create XML Files
Perform the following steps to create the XML resources.
ephesoft-custom-plugin.xml
- Right-click on src/main/resources.
- Select New > XML File.
Note: If “XML File” is not available, click Other and search for “XML File”.
- Set the Name to “ephesoft-custom-plugin.xml” (or the name of your project, if different).
- Click Finish. You can now add elements, attributes, entities, and notations to the XML file.
- Add the following content to the XML file:
<?xml version="1.0" encoding="UTF-8"?>
<plugin>
<jar-name>ephesoft-custom-plugin.jar</jar-name>
<plugin-name>EPHESOFT_CUSTOM_PLUGIN</plugin-name>
<plugin-desc>Ephesoft Custom Plugin</plugin-desc>
<plugin-workflow-name>CUSTOM_PLUGIN</plugin-workflow-name>
<plugin-service-instance>CustomPlugin</plugin-service-instance>
<method-name>helloWorld</method-name>
<is-scripting>FALSE</is-scripting>
<back-up-file-name>EphesoftCustomPlugin</back-up-file-name>
<script-name>N/A</script-name>
<application-context-path>applicationContext-ephesoft-custom-plugin.xml</application-context-path>
<plugin-properties>
<plugin-property>
<name>app.name</name>
<type>STRING</type>
<description>Name</description>
<is-mandatory>FALSE</is-mandatory>
<is-multivalue>FALSE</is-multivalue>
</plugin-property>
</plugin-properties>
<dependencies>
</dependencies>
</plugin>
- Configure the XML file. Refer to the following table for more information on configurable elements.:
Element | Description |
jar-name | Name of the JAR file containing your plugin code. This should be <name of the project>.jar |
plugin-name | Name of the plugin that will show in the workflow. In the CustomPluginImpl.java class, we used the name “EPHESOFT_CUSTOM_PLUGIN”. |
plugin-service-instance | Name of the bean identifier we will reference in the applicationContext.xml. |
method-name | Name of the method that will be first called when the plugin executes in the workflow. |
plugin-properties | Defines the properties of the plugin that will be configured in the UI. In the CustomPlugin.java class, we called on one property—”app.name”. |
Figure 11. Edit XML File
applicationContext-ephesoft-custom-plugin.xml
- Right-click on the META-INF folder you created.
- Select New > XML File.
- Set the Name to “applicationContext-<name of your project>.xml”. For example “applicationContext-ephesoft-custom-plugin.xml”.
- Click Finish.
- Add the following content to the XML file:
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:tx="http://www.springframework.org/schema/tx" xmlns:p="http://www.springframework.org/schema/p" xmlns:util="http://www.springframework.org/schema/util" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:aop="http://www.springframework.org/schema/aop" xmlns:context="http://www.springframework.org/schema/context" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-3.0.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop-3.0.xsd http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-3.0.xsd" default-autowire="byName">
<import resource="classpath:/META-INF/ephesoft-custom-plugin/applicationContext.xml"/>
</beans>
Figure 12. applicationContext.xml File
applicationContext.xml
- Right-click on the META-INF subfolder ephesoft-custom-plugin (or the name of your project, if different).
- Select New > XML File.
- Name the file “applicationContext.xml”.
- Click Finish.
- Add the following content to the XML file:
<?xml version="1.0" encoding="UTF-8"?>
<beans xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-3.0.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop-3.0.xsd http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-3.0.xsd" default-autowire="byName">
<import resource="classpath:/META-INF/applicationContext-data-access.xml"/>
<import resource="classpath:/META-INF/applicationContext-batch.xml"/>
<import resource="classpath:/META-INF/applicationContext-core.xml"/>
<bean id="CustomPlugin" class="com.ephesoft.customplugin.ephesoft_custom_plugin.CustomPluginImpl">
<property name="batchClassPluginConfigService" ref="batchClassPluginConfigService"/>
</bean>
<context:component-scan base-package="com.ephesoft.customplugin.ephesoft_custom_plugin"/>
</beans>
You should have a folder structure that looks like the following:
Figure 13. Folder Structure
pom.xml
- Locate the pom.xml under your project. It should already exist.
- Replace the contents of the pom.xml with the following:
<?xml version="1.0"?>
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.ephesoft.customplugin</groupId>
<artifactId>ephesoft-custom-plugin</artifactId>
<version>0.0.1-SNAPSHOT</version>
<packaging>jar</packaging>
<name>ephesoft-custom-plugin</name>
<url>http://maven.apache.org</url>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<dependencies>
<dependency>
<groupId>com.ephesoft.dcma</groupId>
<artifactId>dcma-core</artifactId>
<version>0.0.1</version>
<scope>system</scope>
<systemPath>${project.basedir}/src/main/resources/ephesoft.jar</systemPath>
</dependency>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-core</artifactId>
<version>3.0.5.RELEASE</version>
</dependency>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.8.1</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-beans</artifactId>
<version>3.0.5.RELEASE</version>
</dependency>
</dependencies>
</project>
Figure 14. pom.xml
Compile the Project
- Copy and paste the ephesoft.jar file from [Ephesoft_Directory]\Application\WEB-INF\lib to your project src/main/resources Folder.
- Right-click on the project folder.
- Select Run As > Maven build.
- Set Goals as “clean install”.
- Click Apply.
- Click OK.
Note: After compiling you may need to refresh your project to update the folder structure.
Import the Plugin into Transact
- After compiling your project in Eclipse, locate the ephesoft-custom-plugin.0.0.1-SNAPSHOT.jar file under the target folder.
- Temporarily copy the file to your Desktop.
- Rename the JAR from “ephesoft-custom-plugin.0.0.1-SNAPSHOT.jar” to “ephesoft-custom-plugin.jar”.
- Locate ephesoft-custom-plugin.xml under your project.
- Temporarily copy the file to your Desktop.
- Zip the ephesoft-custom-plugin.jar and ephesoft-custom-plugin.xml files together.
Note: The ZIP name must be the same as the JAR file. For example, “ephesoft-custom-plugin.zip”.
Figure 15. Create a Zipped Folder
- In Ephesoft Transact, go to System Configuration > Workflow Management.
- Drag and drop your created ZIP file into the Import Plugin section.
- Restart Transact.