Create your first add-in

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.

Dependencies

For the purpose of this tutorial we assume developers user 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;
}

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

Configuration

At this point all that is left is to tell eSign to use your add-in instead of the default one.

Register Extension

Navigate to your esign-home/config folder and open the esign.config configuration file.

Your first step is adding the add-in you have just created as an eSign extension. You need to create a JSON object with three properties:

Entry Description

name

A friendly name of your add-in

class

The fully qualified name of the class that implements the add-in

params

A map of all the parameters that will be received in the init(Map<String, String> parameters) method of your add-in

By now, your configuration should look like this:

"extensions": [

  ...

  {
    "name": "my-artifact-submit-addin",
    "class": "com.celfocus.test.MySubmitAddin",
    "params": {
      "submit_folder":"/opt/esign/mydocuments"
    }
  }
]
Remember the submit_folder folder mentioned in the implementation phase? This is how we specify its value.

Set Extension as Default Addin

After that, if you want this to be your default artifact submit add-in, you need to register it in the default add-ins section. Like before, create a JSON object with two properties in the addins array:

Entry Description

type

Type of add-in (you can check the full list of add-in types in the Add-in Interfaces section).

extension

Default add-in to be used (must match an add-in registered in the extensions section previously mentioned.

The extension is an identifier link to object we created on the extensions array.

"addins": [
	{
		"type": "artifact_submit",
		"extension": "my-artifact-submit-addin"
	}
]

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.