IEventSubscriberAddin

@Since 1.11.2

Addin capable of subscribing to events occuring in eSign and execute custom actions (synchronous or asynchronously).

Trigger Event(s): Document Created, Document Cancelled, Document Delete, Document Submitted, Document Read, Document Signed, Document Unsigned, …​

How it works

This works the same as other addins (see: My First Addin).

However it requires the developer to explicitly specify the events they wish to subscribe using the @eSignEventSubscriber annotation.

If your extension has no @eSignEventSubscriber annotation it will be ignored by eSign.

Subscriber definition

The subscriber annotation @eSignEventSubscriber contains the following properties:

Name Type Default Description

events

List<eSignEventType>

<null>

List of events subscribed by the addin.
(see all available event types here)

trigger

eSignEventTrigger

DEFAULT

Determines how the subscriber is called.
(see all available trigger types here)
Show/Hide - Annotations example 
@eSignExtension(name = "my-event-subscriber")
@eSignEventSubscriber(events = eSignEventType.DOCUMENT_CREATED) (1)
public class MyEventSubscriber implements IEventSubscriberAddin {

	...

}
1 Addin subscribes all events of type DOCUMENT_CREATED

Multiple Subscribe annotations

If you need to subscribe specific event types with different trigger types you don’t necessarily need to implement two addins with the same code. Instead, you may choose to add multiple @eSignEventSubscriber annotations to the addin.

In the example below you can see an example of an addin that subscribes asynchronously to some events, and synchronously to others.

Show/Hide - Multiple annotations example 
@eSignExtension(name = "my-event-subscriber")
@eSignEventSubscriber(events = {
	eSignEventType.DOCUMENT_CREATED,
	eSignEventType.DOCUMENT_CANCELLED,
	eSignEventType.DOCUMENT_DELETED }) (1)
@eSignEventSubscriber(events = eSignEventType.DOCUMENT_SUBMITTED, trigger = eSignEventTrigger.SYNCHRONOUS_FAIL_ON_ERRORS) (2)
public class MyEventSubscriber implements IEventSubscriberAddin {

	...

}
1 Uses DEFAULT trigger for events of type DOCUMENT_CREATED, DOCUMENT_CANCELLED and DOCUMENT_DELETED
2 Uses SYNCHRONOUS_FAIL_ON_ERRORS trigger for events of type DOCUMENT_SUBMITTED.
If the same addin shares event types between annotations, the same event will still be handled only for this addin.
The trigger type with the highest priority will take effect for that event.

Execution order

If your solution has multiple addins subscribing the same event types they will all execute asynchronously and without an assured order.

However, specifically for synchronous triggers types, you can determine the execution order between addins using the priority property of the @eSignExtension annotation.
The higher the priority value the more priority the subscriber will have.

API Specification

The interface already provides default empty implementations for each method.
Developers only need to implement the methods matching the events they wish to subscribe.

Below follows a list of all methods available in the `IEventSubscriberAddin`interface:

Supports

Optional validation to determine if an event should be handled by this subscriber

Use cases
Implementing this method may be useful if you want this subscriber to only act over documents with special characteristics.

For instance, you only want your subscriber to be triggered for documents containing the variable DOCUMENT_TYPE=ONBOARDING. Instead of implementing this check in all subscriber methods, you may simply define it in this support method.

This method is always checked prior to executing any subscriber action.

If not defined will always handle all subscribed events.

Show/Hide - Interface Definition
supports(event) Type Description

Input

DocumentEvent

Payload of the event triggered

Output

boolean

True if event should be processed by this addin. Otherwise, false.

Document Created

Triggered on event type DOCUMENT_CREATED.

Occurs when a document is created in eSign (when a document to be signed is uploaded into eSign).

Show/Hide - Interface Definition
documentCreated(event) Type Description

Input

CreatedDocumentEvent

Payload of the created event containing information about the created document

Document Cancelled

Triggered on event type DOCUMENT_CANCELLED.

Occurs when a document is cancelled in eSign.

Show/Hide - Interface Definition
documentCancelled(event) Type Description

Input

DocumentEvent

Payload of the cancellation event containing information about the cancelled document

Document Deleted

Triggered on event type DOCUMENT_DELETED.

Occurs when a document is deleted in eSign.

Show/Hide - Interface Definition
documentDeleted(event) Type Description

Input

DocumentEvent

Payload of the deletion event containing information about the deleted document

Document Submitted

Triggered on event type DOCUMENT_SUBMITTED.

Occurs when a document is submitted in eSign.

Show/Hide - Interface Definition
documentSubmitted(event) Type Description

Input

SubmitDocumentEvent

Payload of the submission event containing information about the submitted document.
This payload also includes the binary of the submitted artifact.

Document Signed

Triggered on event type DOCUMENT_SIGNED.

Occurs when a document is signed in eSign.

Show/Hide - Interface Definition
documentSigned(event) Type Description

Input

SignDocumentEvent

Payload of the signing event containing information about the signed document.
Also contains information regarding the field signed.

Document Unsigned

Triggered on event type DOCUMENT_UNSIGNED.

Occurs when a document is unsigned in eSign.

Show/Hide - Interface Definition
documentUnsigned(event) Type Description

Input

SignDocumentEvent

Payload of the unsigned event containing information about the unsigned document.
Also contains information regarding the field unsigned.

Document Field Change

Triggered on event type DOCUMENT_FIELD_CHANGED.

Occurs when a document field changes value.

Show/Hide - Interface Definition
documentFieldChange(event) Type Description

Input

FieldChangedDocumentEvent

Payload of the field change event containing information about the document field change.
Also contains information regarding the field changed and its current value.

Document Page Change

Triggered on event type DOCUMENT_PAGE_CHANGED.

Occurs when a user changes page in a document.

Page changes are user operations that may occur even when the is no Internet connectivity.
Hence, the payload of this event contains a list of page change events, each with the pages viewed and the instant it was viewed.
Show/Hide - Interface Definition
documentPageChange(event) Type Description

Input

PageChangedDocumentEvent

Payload of the page change event containing information about the document page change.

Document Read

Triggered on event type DOCUMENT_READ.

Occurs when a document is retrieved (usually by a system).

Show/Hide - Interface Definition
documentRead(event) Type Description

Input

DocumentEvent

Payload of the read event containing information about the retrieved document.

Document User Opened

Triggered on event type DOCUMENT_USER_OPENED.

Occurs when a document is accessed by a user.

The event payload contains information information about the user accessing the document (username) that should not be confused with the user that registered the optioning action (eventUsername).
Show/Hide - Interface Definition
documentUserOpened(event) Type Description

Input

UserSessionDocumentEvent

Payload of the user opened event containing information about the accessed document by a user.

Document User Closed

Triggered on event type DOCUMENT_USER_CLOSED.

Occurs when a document is closed after being accessed by a user.

The event payload contains information information about the user accessing the document (username) that should not be confused with the user that triggered the closing action (eventUsername).
Must times they are the same, but when a session is force closed by eSign the eventUsername will be a system user.
Show/Hide - Interface Definition
documentUserClosed(event) Type Description

Input

UserSessionDocumentEvent

Payload of the user closed event containing information about the closed document after being accessed by a user

Event Types

Below is the full list of event types that can be subscribed by this addin:

Event Type Description

DOCUMENT_CREATED

Triggers when a document is created.

DOCUMENT_CANCELLED

Triggers when a document is cancelled.

DOCUMENT_DELETED

Triggers when a document is deleted.

DOCUMENT_SUBMITTED

Triggers when a document is submitted.

DOCUMENT_READ

Triggers when a document is read.

DOCUMENT_SIGNED

Triggers when a document is signed.

DOCUMENT_UNSIGNED

Triggers when a document is unsigned.

DOCUMENT_FIELD_CHANGED

Triggers when a document field changes its value.

DOCUMENT_PAGE_CHANGED

Triggers when a user changes the page in a document.

DOCUMENT_USER_OPENED

Triggers when a user opens a document.

DOCUMENT_USER_CLOSED

Triggers when a user closes a document.

Trigger Types

The trigger type of a subscriber determines how your subscriber will be executed.

By default your subscriber will execute, asynchronously, immediately after the event occurs. And in the majority of cases this is exactly what you need.
However, sometimes you might be faced with more specific uses cases.

Examples:

  • Execute different subscribers in a specific order

  • Modify variables of the document

  • Force the inherent action to fail if your subscriber does not execute correctly

To fulfill these type of scenarios you can change the execution type of your addin using the trigger property.

If you are not sure of which type of trigger to use leave it unassigned or as DEFAULT.
Changing the trigger type incorrectly may cause eSign to under perform, or stop working altogether.

Below is the full list of trigger types that can be used by this addin.

Event Type Priority Description

DEFAULT

0

Default trigger.
Same as ASYNCHRONOUS.

ASYNCHRONOUS

0

The subscriber will execute asynchronously immediately after the event is persisted in eSign’s repository.

SYNCHRONOUS_IGNORE_ERRORS

1

The subscriber will execute synchronously before the event is persisted in eSign’s repository.

This type should only be used for very specific use cases, be sure that you know what you are doing!

Pros:
- Developers can change document variables using subscribers.
- Developers can determine the order by which subscribers execute and can use changes from subscribers that already executed in the chain.

Cons:
- Overall solution’s performance might be affected by the execution time of the subscriber.
- Developers can apply changes that can break the correct execution of eSign or other add-ins.

It does not stop interrupt eSign business logic if the subscriber execution fails.

SYNCHRONOUS_FAIL_ON_ERRORS

2

Same behavior as SYNC_ASYNCHRONOUS_IGNORE_ERRORS.

However, it will interrupt eSign business logic if the subscriber execution fails.
This means the other existing subscribers of lower priority will not reach execution if your addin throws an exception.

Examples

This section is dedicated to some examples of IEventSubscriberAddin 's for different purposes.

Multi-event Addin

Below is an example of an addin that registers two events (DOCUMENT_CREATED and DOCUMENT_SUBMITTED) to perform custom actions when they occur.

import java.util.Map;

import novabase.connect.paperless.esign.events.eSignEventSubscriber;
import novabase.connect.paperless.esign.events.eSignEventType;
import novabase.connect.paperless.esign.events.dto.CreatedDocumentEvent;
import novabase.connect.paperless.esign.events.dto.SubmitDocumentEvent;
import novabase.connect.paperless.esign.exceptions.eSignException;
import novabase.connect.paperless.esign.extensions.eSignExtension;
import novabase.connect.paperless.esign.extensions.addins.IEventSubscriberAddin;

@eSignExtension(name = "my-event-subscriber") (1)
@eSignEventSubscriber(events = { eSignEventType.DOCUMENT_CREATED, eSignEventType.DOCUMENT_SUBMITTED }) (2)
public class MyEventSubscriber implements IEventSubscriberAddin {

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

	/
	 * Triggered when a document is created
	 * @param event Event payload
	 */
	public void documentCreated(CreatedDocumentEvent event) {
		// Do something
	};

	/
	 * Triggered when a document is submitted
	 * @param event Event payload
	 */
	public void documentSubmitted(SubmitDocumentEvent event) {
		// Do something
	};

}
1 This registers your class as an eSign extension (with a name of your choice).
2 This determines which events will be subscribed by this addin.
If you implement a method for a specific event, but you do not subscribe the matching event type in @eSignEventSubscriber your method will not be called.

Document-specific Subscriber

Sometimes you want a subscriber that must only execute on specific types of documents (for example, only on documents related to an Onboarding business process).

To easily achieve this you can use the supports() method.

The supports() method will be evaluated every time an event subscribed by your addin occurs. If the evaluation is false your addin will not be executed.

Event Subscriber addin for 'Onboarding' documents
import java.util.Map;

import novabase.connect.paperless.esign.events.eSignEventSubscriber;
import novabase.connect.paperless.esign.events.eSignEventType;
import novabase.connect.paperless.esign.events.dto.CreatedDocumentEvent;
import novabase.connect.paperless.esign.events.dto.SubmitDocumentEvent;
import novabase.connect.paperless.esign.exceptions.eSignException;
import novabase.connect.paperless.esign.extensions.eSignExtension;
import novabase.connect.paperless.esign.extensions.addins.IEventSubscriberAddin;

@eSignExtension(name = "my-event-subscriber")
@eSignEventSubscriber(events = { eSignEventType.DOCUMENT_CREATED, eSignEventType.DOCUMENT_SUBMITTED })
public class AllEventsSubscriber implements IEventSubscriberAddin {

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

	@Override
	public boolean supports(DocumentEvent event) {
		return Objects.equals(event.getDocument().getVariables().getVariable("DOCUMENT_CATEGORY"), "Onboarding"); (1)
	}

	/
	 * Triggered when a document is created
	 * @param event Event payload
	 */
	public void documentCreated(CreatedDocumentEvent event) {
		// Do something
	};

	/
	 * Triggered when a document is submitted
	 * @param event Event payload
	 */
	public void documentSubmitted(SubmitDocumentEvent event) {
		// Do something
	};

}
1 Addin will only handle subscribed events regarding documents that have a variable named DOCUMENT_CATEGORY with value Onboarding.