Create your first add-in

Available since version 1.11.0

In this section you will be given a tutorial on how to make a simple add-in to add custom functionality to eSign. The add-in you will create is a very simple one, just to give you the tools to build your own, more complex and demanding, custom interactions with eSign.

For this tutorial purposes, we will be creating an add-in that will allow you to store a signed document on your file system as soon as the document is submitted. add a new. This is based on the IArtifactSubmitAddin interface that allows us to interact with the artifact submission request and change it to suit our purposes. If you want to learn more about the different add-in interfaces, go to the Add-in Interfaces.

You will start by setting up the necessary dependencies, configuring this new add-in and its parameters on the esign.config and finally, you will work on the code needed to make your new add-in functionality actually do something.

Before you Start

This guide assumes:

  • You already have an eSign instance (see: Deployment)..

  • You already have an [ESIGN_HOME] folder with your configurations (see: eSign Home).

Dependencies

For the purpose of this tutorial we assume developers use Maven.

Maven Settings

The eSign artifacts exist in a private repository, hence we have to update the maven settings.xml to add the private repository to the list of maven repositories.

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <servers>
    <server>
     <id>esign.celfocus.com</id>
      <username>[REPLACE WITH USERNAME]</username>
      <password>[REPLACE WITH PASSWORD]</password>
    </server>
  </servers>
  <profiles>
    <profile>
      <id>esign</id>
      <repositories>
        <repository>
          <id>esign.celfocus.com</id>
          <url>https://support-omnifs.westeurope.cloudapp.azure.com/nexus/repository/maven-esign</url>
        </repository>
      </repositories>
    </profile>
  </profiles>
  <activeProfiles>
    <activeProfile>esign</activeProfile>
  </activeProfiles>
</settings>

Maven Project

In order for your new add-in to implement the IArtifactSubmitAddin, you need access to this interface. eSign provides a toolkit that gives you access to, among other things, all the add-in interfaces available.

Therefore, in order to proceed with the creation of a custom add-in, you need the esign-toolkit dependency on your project. Add to your project’s pom.xml the following dependency:

<dependency>
  <groupId>novabase.connect.paperless.esign</groupId>
  <artifactId>esign-toolkit</artifactId>
  <version>[YOUR ESIGN VERSION]</version>
</dependency>

Implementation

To start with, you need to create a new class that will implement the IArtifactSubmitAddin interface.

public class MySubmitAddin implements IArtifactSubmitAddin {

}

Every eSign add-in, regarless of its type, requires the following methods to be implemented:

Method Description

getName()

Method returning a friendly name that identifies this add-in (used mainly for debugging and troubleshooting)

init(Map<String, String> parameters)

Method receiving configurable parameters that can be associated with this add-in (see: Configuration)

Additionally, the IArtifactSubmitAddin specifically requires two additional methods to be implemented:

Method Description

submitStep(ArtifactDetails details, short step)

Method that gives you an access point to the artifact when it moves to the next step (if your document was configured to have more that one step). We will not go into further detail at this point.

submitArtifact(ArtifactDetails details)

Method gives you an access point to the artifact when it is being submitted. You can access the artifact details on this method.

By now your class should be shaping to be something like this:

public class MySubmitAddin implements IArtifactSubmitAddin {

	private static final String NAME = "FileSystem Submit Artifact Addin";

	@Override
	public String getName() {
		return NAME;
	}

	@Override
	public void init(Map<String, String> parameters) throws eSignException {
	}

	@Override
	public boolean submitArtifact(ArtifactDetails details) {
		return true;
	}

	@Override
	public boolean submitStep(ArtifactDetails details, short step) {
		return true;
	}
}

In this example we want the folder to where the submitted documents go to be configurable, hence we will assume that a property called, let’s say, submit_folder will be provided as parameter of the init() method, and that this property will contain the absolute path of where to store the documents.

@Override
public void init(Map<String, String> parameters) throws eSignException {
	String folder = parameters.get("submit_folder");
	this.destination = new File(folder);
}

Additionally, for each document that is submitted, we want to implement the following actions:

  • Store the PDF document in the submit_folder

  • Store a metadata file with information regarding the number of fields in the document and the user that is submitting the document.

@Override
public boolean submitArtifact(ArtifactDetails details) {
	try {
		// Unique Artifact Id
		String artifactId = details.getArtifactId();

		// Current session information
		SessionSource session = SecurityManager.getSession();

		// Save artifact to destination folder
		byte[] pdf = details.getArtifact();
		String fileName = artifactId + "-document.pdf";
		FileUtils.writeByteArrayToFile(new File(destination, fileName), pdf);

		// Save metadata to destination folder
		String metadata = "Fields Count: " + details.getFields().size() +"\nSubmitted by: " + session.getUsername();
		String metadataName = artifactId + "-metadata.txt";
		FileUtils.writeByteArrayToFile(new File(destination, metadataName), metadata.getBytes());

	} catch (Throwable t) {
		LOGGER.error("Well, that wasn't supposed to happen...", t);
		return false;
	}

	return true;
}

Auto-Register on Deployment

To inform eSign that you want your addin to become available as soon as it is deployed you need to add an @eSignExtension to your class.

@eSignExtension(name="my-artifact-submit-addin") (1)
public class MySubmitAddin implements IArtifactSubmitAddin {

	...

}
1 Registers your addin under the name my-artifact-submit-addin.

Auto-Detect

In order for eSign to automatically detect your annotated extension. You must inform eSign about the package names where it must look for annotations.

An a new entry to your esign.config name extensions.scanner.packages containing the list of all the packages that need be scanned.
(The esign.config configuration file exists in the folder [ESIGN_HOME]/config)

Example of packages for scanning
"extensions.scanner.packages" : [
	"my.test.package", (1)
	"my.other.package" (2)
]
1 Will scan for classes annotated with @eSignExtension in all subpackages of my.test.package.
2 Will scan for classes annotated with @eSignExtension in all subpackages of my.other.package.
eSign will scan the configured packages in depth.

Auto-Register as Default

eSign allows for multiple addin of the same type to be register, and normally you would have to specify for each create document which addin you want to use for submit.
However, you can register your addin as the default addin of that type, so it will always be used by default for all documents.

To do so, add attribute isDefault to true in the @eSignExtension:

@eSignExtension(name = "my-artifact-submit-addin", isDefault = true) (1)
public class MySubmitAddin implements IArtifactSubmitAddin {

	...

}
1 Informs eSign that this will be the default IArtifactSubmitAddin addin.

Auto-Register Priority

So, what happens if you already have another addin set as default for IArtifactSubmitAddin?

For such cases, you can set the priority of your addin. When two or more addins of the same type are registered as default, the one with the highest priority will win.

To set the priority of your add, add attribute priority and set a value:

@eSignExtension(name = "my-artifact-submit-addin", isDefault = true, priority = 100) (1)
public class MySubmitAddin implements IArtifactSubmitAddin {

	...

}
1 If there is no other addin of type IArtifactSubmitAddin with a higher priority level, this will become the default.
If no priority is set, your addin will be assigned with priority: 0.

Conditional Auto-Register

You may have use cases where you wish to dynamically configure when an addin should be enabled or disabled (meaning it will or will not be automatically registered).

One such use case is if you have addins that are for tests only, and should never be active in productive environments.

For these use cases you may assign the addin with the name of a configuration from esign.config.
(The esign.config configuration file exists in the folder [ESIGN_HOME]/config)

By doing so, your addin will only become enabled (auto-register) if:

  • The configuration does not exist

  • The configuration value is null

  • The configuration value is true

@eSignExtension(name = "my-artifact-submit-addin", isDefault = true, priority = 100, enabler = "myaddin.enabled") (1)
public class MySubmitAddin implements IArtifactSubmitAddin {

	...

}
1 This determines that your addin will only be available if the configuration myaddin.enabled is either null or true.

Addin Init Parameters

You can initialize your addin with parameters that may change from environment to environment.

For this purpose, you may add to esign.config entries with the following format:

"extensions.[your-addin-name].params.[your-param1]" : "[your-value1]"
"extensions.[your-addin-name].params.[your-param2]" : "[your-value2]"

  • your-addin-name: Is the name set in the @eSignExtension annotation

  • your-param1: Is the key of the entry in the Map received in the init(Map<String, String> parameters) method of your addin.

  • your-value1: Is the value of the entry in the Map received in the init(Map<String, String> parameters) method of your addin.

You may add as many parameter entries as you want.

For instance:

"extensions.my-artifact-submit-addin.params.submit_folder" : "/opt/esign/storage"
Remember the submit_folder folder mentioned in the implementation phase? This is how we specify its value.

Environment init values

You may assign parameters with values of environment variables to quickly change the values between environments:

"extensions.my-artifact-submit-addin.params.submit_folder" : "${env: MY_ENVIRONMENT_VARIABLE}"

Force disable Addin

You can even force-disable your addin using esign.config:

extensions.[your-addin-name].enabled: false
This will override any value assigned to the enabler entry in the @eSignExtension annotation of your addin.

Deployment

With our new add-in implemented, we can now build and deploy it into eSign.

For any add-in to be deployed, developers must simple copy the generated jar file into [ESIGN_HOME]/extensions.

If your jar requires other libraries that do not ship we eSign, you must either build your jar with dependencies, or add all required libraries to [ESIGN_HOME]/extensions

This should be everything you need to do to configure your new add-in.

If you follow these steps, the next time you start eSign and submit a artifact, it will be stored in the location specified in submit_folder.

For further information on the different types of add-in interfaces that are usable on eSign, please refer to our Add-in Interfaces documentation.