Transact

⌘K
  1. Home
  2. Transact
  3. Developer Documentation
  4. Custom Plugins
  5. Creating Custom Plugins

Creating Custom Plugins

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:

To install Maven, perform the following steps:

  1. Open Eclipse.
  2. Go to Help > Eclipse Marketplace.
  3. Search “Maven”.
  4. Click Install on “Maven Integration for Eclipse”.
  5. Follow the installation steps as prompted.
  6. 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

  1. Open Eclipse.
  2. Click File > New.
  3. Select Maven Project.

SelectMavenProject2

Figure 1. Create a Maven Project

  1. Select Use default Workspace location.

DefautWorkSpace

Figure 2. Use Default Workspace Location

  1. Select the quickstart Maven archetype. The Artifact ID is maven-archetype-quickstart.

QuickStartMaven

Figure 3. Select Quickstart Maven Archetype

  1. 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.
    1. Group ID: com.ephesoft.customplugin
    2. Artifact ID: ephesoft-custom-plugin

GroupIdArticatId

Figure 4. Enter Group ID and Artifact ID

  1. Your Eclipse project workspace should now look like this:

MavenProjectWorkspace

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.

  1. Open your project folder. Right-click on ephesoft-custom-plugin.
  2. Select Build Path > Configure Build Path.
  3. Select the Libraries tab.
  4. Click Add External Jars.
  5. Navigate to [Ephesoft_Directory]\Application\WEB-INF\lib.
  6. Select all JAR files.
  7. Click Open.
  8. Click OK.

Create a New Interface

Perform the following steps to create a new Java interface for your custom plugin.

  1. Open your package. Right-click on com.ephesoft.customplugin.ephesoft.custom_plugin.
  2. Select New > Interface.
  3. Set the Name to “CustomPlugin”.

MavenNewInterface

Figure 6. New Java Interface

  1. Click Finish.
  2. 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;
}

MavenCustomPlugin

Figure 7. Replace File Contents

Create a Java Class

Perform the following steps to create a Java class to implement the CustomPlugin interface.

  1. Open your package. Right-click on com.ephesoft.customplugin.ephesoft.custom_plugin.
  2. Click New > Class.
  3. Set the Name to “CustomePluginImpl”.

MavenCustomPluginImpl

Figure 8. New Java Class

  1. Click Finish.
  2. 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;
    }

MavenCustomPluginImplCode

Figure 9. Replace File Contents

Create Folder Structure for XML Resources

Perform the following steps to create a folder structure for your XML resources.

  1. Right-click on your project in the Project Explorer.
  2. Click New > Source Folder.
  3. Set the Folder Name to “src/main/resources”.

MavenSRCXML

Figure 10. New Source Folder

  1. Click Finish.
  2. Create a META-INF folder:
    1. In the project folder you just created, right-click src/main/resources.
    2. Click New > Folder.
    3. Set the Folder Name to “META-INF”.
    4. Click Finish.
  3. Create a subfolder under META-INF.
    1. Right-click the META-INF folder.
    2. Select New > Folder.
    3. Set the Folder Name to “ephesoft-custom-plugin” (or the name of your project, if different).
    4. Click Finish.

Create XML Files

Perform the following steps to create the XML resources.

ephesoft-custom-plugin.xml

  1. Right-click on src/main/resources.
  2. Select New > XML File.

Note: If “XML File” is not available, click Other and search for “XML File”.

  1. Set the Name to “ephesoft-custom-plugin.xml” (or the name of your project, if different).
  2. Click Finish. You can now add elements, attributes, entities, and notations to the XML file.
  3. 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>
  1. 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”.

MavenprojectName

Figure 11. Edit XML File

applicationContext-ephesoft-custom-plugin.xml

  1. Right-click on the META-INF folder you created.
  2. Select New > XML File.
  3. Set the Name to “applicationContext-<name of your project>.xml”. For example “applicationContext-ephesoft-custom-plugin.xml”.
  4. Click Finish.
  5. 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>

MavenApplicationContextProjectName

Figure 12. applicationContext.xml File

applicationContext.xml

  1. Right-click on the META-INF subfolder ephesoft-custom-plugin (or the name of your project, if different).
  2. Select New > XML File.
  3. Name the file “applicationContext.xml”.
  4. Click Finish.
  5. 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:

MavenFolderStructure2

Figure 13. Folder Structure

pom.xml

  1. Locate the pom.xml under your project. It should already exist.
  2. 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>

MavenpomXML

Figure 14. pom.xml

Compile the Project

  1. Copy and paste the ephesoft.jar file from [Ephesoft_Directory]\Application\WEB-INF\lib to your project src/main/resources Folder.
  2. Right-click on the project folder.
  3. Select Run As > Maven build.
  4. Set Goals as “clean install”.
  5. Click Apply.
  6. Click OK.

Note: After compiling you may need to refresh your project to update the folder structure.

Import the Plugin into Transact

  1. After compiling your project in Eclipse, locate the ephesoft-custom-plugin.0.0.1-SNAPSHOT.jar file under the target folder.
  2. Temporarily copy the file to your Desktop.
  3. Rename the JAR from “ephesoft-custom-plugin.0.0.1-SNAPSHOT.jar” to “ephesoft-custom-plugin.jar”.
  4. Locate ephesoft-custom-plugin.xml under your project.
  5. Temporarily copy the file to your Desktop.
  6. 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”.

MavenCompresedZip

Figure 15. Create a Zipped Folder

  1. In Ephesoft Transact, go to System Configuration > Workflow Management.
  2. Drag and drop your created ZIP file into the Import Plugin section.
  3. Restart Transact.