Upgrade Steps

eSign 1.9.x brings a significant set of improvements to the solution, namely a simplification of the required configurations to launch a fully-functional eSign instance, and as such, some changes need to be applied on existing instances.
When migrating to this version no code changes are expected in existing project developments.

This guide assumes that you are either migrating from version 1.7.x or 1.8.x.

Mandatory Steps

Please apply all the steps listed below to ensure that all capabilities are correctly upgraded.

1. Change Environment Variable

Starting in 1.8.x eSign no longer uses SAFEHUB environment variable.
We now use ESIGN_HOME environment variable.

Additionally, SAFEHUB pointed to the parent folder of the eSign configurations folder. Now ESIGN_HOME must point to the eSign configurations folder itself.

Before: SAFEHUB pointing to parent folder of eSign

SAFEHUB=/my/path/SafeHub
env var old

Now: ESIGN_HOME pointing to eSign folder

ESIGN_HOME=/my/path/SafeHub/esign
env var new

2. Update Log4j

Replace the old environement variable with the new one in eSign logging file.

  1. Open <ESIGN_HOME>/config/log4j2.xml

  2. Replace ${sys:SAFEHUB}/esign with ${sys:ESIGN_HOME}

Below is the expected output:

<!DOCTYPE project>
<configuration status="error">
	<Properties>
		<Property name="log-path">${sys:ESIGN_HOME}/logs</Property>
	</Properties>
	<appenders>

		...

	</appenders>
	<loggers>

		...

	</loggers>
</configuration>
If you have changed this file to point to your own logging folder, this step might not be required.

3. Delete Configurator from esign.config

If you are using configurations stored in database then your esign.config file has a reference to the Hibernate configuration.
This configurator is now installed by default and must not be included in the esign.config folder.

  1. Open <ESIGN_HOME>/config/esign.config

  2. Remove entire "configurators" section

{
  "extensions":[ ... ],
  "modules":[ ... ],
  "addins":[ ... ],
  "tsa":[ ... ],

  DELETE THIS!
  "configurators": [
  {
    "class": "novabase.connect.paperless.esign.configuration.hibernate.HibernateConfigurationSource",
    "params" : {
      "interval": "60000"
    }
  }
  ],

  "properties":{
    ...
  }
}

Database configuration refresh rate:

If you had customized the parameter 'interval' of this configurator, you can replicate the behavior by creating the following property in esign.config:

"persistence.hibernate.configuration.interval" : 60000

4. Remove references to Product Database Extensions

In version 1.7 it was necessary to explicitly activate database (hibernate) implementations of all the product components.
Since version 1.9 the database implementations are active by default and any explicit mentions in project configurations must be removed.

  1. Open <ESIGN_HOME>/config/esign.config

  2. Remove from "extensions" all references to Hibernate classes:

    1. HibernateRepository

    2. HibernateLicenseRepository

    3. HibernateStatisticsRepository

    4. HibernateAuditor

    5. HibernateRepository

    6. HibernateSignatureRepository

    7. HibernateTrustCertificateStore

    8. …​

  3. Remove from "modules" all references to Hibernate classes:

    1. ANALYTICS

    2. ARTIFACT_REPOSITORY

    3. AUDITOR

    4. LICENSE_REPOSITORY

    5. SIGNATURE_REPOSITORY

    6. STATISTICS_REPOSITORY

    7. TRUST_CERTIFICATE_STORE

    8. …​

If your project uses database configurations the analogous steps must be performed on the database. Remove the entries referred above from tables: CONFIG_EXTENSION and CONFIG_MODULE.

5. Database Configuration

Since 1.9 the esign.hibernate.cfg.xml file, previously used to configure the database, has been deprecated. It is now possible to configure the database connection using properties in <ESIGN_HOME>/config/esign.config.

To configure the database connection the following properties can be used:

  • database.dialect: matches property 'hibernate.dialect' from legacy hibernate file.

  • database.driver: matches property 'hibernate.connection.driver_class' from legacy hibernate file

  • database.url: matches property 'hibernate.connection.url' from legacy hibernate file

  • database.user: matches property 'hibernate.connection.username' from legacy hibernate file

  • database.password: matches property 'hibernate.connection.password' from legacy hibernate file

To migrate the database properties:

  1. Open <ESIGN_HOME>/config/esign.config

  2. Add the database entries referred above

  3. Delete <ESIGN_HOME>/resources/esign.hibernate.cfg.xml

Example of database configurations in esign.config:

{
  "extensions":[ ... ],
  "modules":[ ... ],
  "addins":[ ... ],

  "properties":{
    "database.dialect" : "org.hibernate.dialect.PostgreSQLDialect",
    "database.driver" : "org.postgresql.Driver",
    "database.url" : "jdbc:postgresql://localhost:5432/esign",
    "database.user" : "...",
    "database.password" : "...",

    ...

  }
}

Alternative: Using database connection with JNDI Datasource

To configure a connection to a JNDI datasource use the database.dataSource property.
However, notice that the 'dialect' and 'driver' still need to be explicitly configured.

{
  "extensions":[ ... ],
  "modules":[ ... ],
  "addins":[ ... ],

  "properties":{
    "database.dialect" : "org.hibernate.dialect.PostgreSQLDialect",
    "database.driver" : "org.postgresql.Driver",
    "database.dataSource" : "java:comp/env/jdbc/esign"

    ...

  }
}
The esign.hibernate.cfg.xml will still be used if present in <ESIGN_HOME>/resource, but this behavior will be discontinued in the next version.
Make sure you remove this file from <ESIGN_HOME>/resource to prevent unpredictable behaviors.

7. Database Connection Pool (Hikari)

If your project is using JNDI datasources, this section can be skipped.

Starting in 1.9 eSign already ships with an Hikari connection pool to manage the database connections.

To configure the connection pool of the application add the following properties to esign.config (properties not specified will use the default values):

Property Description Default

database.pool.maximumPoolSize

Maximum size that the pool is allowed to reach

10

database.pool.minimumIdle

Minimum number of idle connections that HikariCP tries to maintain in the pool

same as maximumPoolSize

database.pool.idleTimeout

Maximum amount of time that a connection is allowed to sit idle in the pool

60000 (10 minutes)

database.pool.connectionTimeout

Maximum number of milliseconds that eSign will wait for a connection from the pool

30000 (5 minutes)
If until now your project was explicitly adding hikari jars to eSign extensions, this must be reverted to avoid conflicts:
Delete <ESIGN_HOME>/extensions/<your_hikari_jars>

8. Database Auto-Deploy

Starting in 1.9 eSign will auto deploy database scripts unless if explicitly configured not to.
eSign will be able to manage which scripts were already executed or not between restarts, redeploys and future version upgrades. Additionally this allows projects to have less steps when performing upgrades across environments.

If your are upgrading from a previous eSign version you most likely have already installed scripts for previous versions manually, which may cause conflicts with the new automation feature. To fix this there are two options available:

  1. Disable the auto-deploy feature (continue applying scripts manually)

  2. Use auto-deploy and specify which scripts to be skip (skip scripts already applied manually)

Alternative 1: Disable the auto-deploy

To disable auto-deploy perform the following steps:

  1. Add to esign.config the following property:

    "database.autodeploy" : false

  2. Manually install the database scripts for version 1.8 and 1.9, included in the deliverable esign-safehub available in nexus.

Alternative 2: Use auto-deploy

To allow eSign to start installing scripts automatically after a given version, you must exclude the scripts of the versions already installed manually by adding the list of excluded version in esign.config:

"database.autodeploy.context" : "skip-<script_version_number>,..."

This will vary based on which eSign version you are upgrading from:

  1. Upgrading from 1.7:

    "database.autodeploy.context" : "skip-1.0.0,skip-1.4.0,skip-1.7.0"

  2. Upgrading from 1.8:

    "database.autodeploy.context" : "skip-1.0.0,skip-1.4.0,skip-1.7.0,skip-1.8.0"

9. Services Authentication

Starting from version 1.9 all service APIs are authenticated by default.
The default implementation is basic authentication, and the default credentials are: admin / admin

eSign highly recommends that the API layer is authenticated, however it is a project’s choice to disable it.

There are three options available:

  1. Disable authentication

  2. Use your custom authentication implementation

  3. Use out-of-the-box basic authentication

Alternative 1: Disable authentication

To simply disable authentication add the following property to esign.config:

"server.authenticate.services.extension" : "authentication-anon-default"

Alternative 2: Use custom authentication

To use your own custom authentication for the API layer add the following property to esign.config:

"server.authenticate.services.extension" : "<name_of_your_extension>"

Alternative 3: Basic authentication

When using the new default basic authentication addin (LocalSecurityAuthenticationAddin) eSign will, by default, creates the following users:

User Pass Description Role

admin

admin

Administrator user with permissions to access all services

admin

service

service

User that has access to the REST/SOAP services for managing documents and signatures (excludes all maintenance APIs: truststore, crl, configuration, scheduler)

service

viewer

viewer

User that has access to contracts that have been configured to use LocalSecurityAuthenticationAddin

viewer

Additionally, eSign will also creates the following roles:

Role Description Permissions

all

All permissions

*

service

Permissions to access business services

artifact:*,signature:*,compliance:*,batch:*,audit:*,log:*

maintenance

Permissions to access maintenance services

truststore:*,crl:*,configuration:*,scheduler:*

monitor

Permissions to access monitoring portal

analytics:*,monitor:*,configuration:*,log:read,scheduler:*

compliance

Permissions to access compliance portal

compliance:validate

viewer

Permissions to access the contract viewer

viewer:*
In productive environments the default users must ALWAYS be disabled.

To disable the default users and create new ones, the following configurations must be added to esign.config:

"security.local.defaults" : false,
"security.local.users": [
  "<user1>=<password1>,<role1>,<role1>,<roleN>",
  "<user2>=<password2>,<role>",
  ...
]

For example:

"security.local.defaults" : false,
"security.local.users": [
  "superadmin=superpass,admin",
  "eai=mypassword,service",
  "multipurpose=mypassword,service,maintenance",
  "john=johnpass,monitor",
  "mark=markpass,monitor"
]

10. Viewer Communication (Websockets)

Starting in version 1.8 the default implementation for realtime communication between frontend and backed was changed from Server-Sent Events to WebSockets. From now on this is the products recommended implementation due to performance and stability reasons, among others.

However it is still possible to revert to the old approach by adding the following configuration to esign.config:

"server.engine": "SSE"
If you are using a WebSphere version older than 9.x you will need to use SSE

11. Update CSS customization

In version 1.8 eSign underwent a frontend facelift. If you are migrating from version 1.7 and have customized some of the original look-and-feel by using the CSS (brand) customization provided by the product, you may need to revise your customizations.

Additional Steps

This section lists all changes that are highly advisable to be performed during this upgrade. The solution should work to a degree if they are not applied, but future versions may discontinue such capabilities at any time.

If these steps are not applied in this upgrade, they will not be mentioned again in future upgrade steps.

1. Named Extensions

eSign now allows assigning a unique name to a registered extension. The extension name is than used to associated with addins and modules.

By assigning names to extensions and referring them by name, instead of classname, it is easier to:

  • Update the implementation of an extension (without having to update all related references)

  • Update existing integration flows. Existing requests to create documents with a given addin do not need to be reviewed.

Purpose Before Now

esign.config

 
"extensions": [
  {
    "class":"my.class.MyAddin"
  }
]
 
"extensions": [
  {
    "name":"my-addin",
    "class":"my.class.MyAddin"
  }
]

API /create

 
{
 "artifact" : "JVBERi...",

 ...

 "addins" : [
  {
   "name":"ARTIFACT_SUBMIT",
   "value":"my.class.MyAddin"
  }
 ]
}
 
{
 "artifact" : "JVBERi...",

 ...

 "addins" : [
  {
   "name" : "ARTIFACT_SUBMIT",
   "value" : "my-addin"
  }
 ]
}

Troubleshooting

This section describes some of the system behaviors and most common error messages that may occur if the upgrade was not correctly performed.

Regardless of the information below, eSign will inform you of deprecated behavior by adding warning messages in the logs.
Keep track of these entries to ensure that you are not making use of deprecated capabilities that might be discontinued in future versions.

Missing ESIGN_HOME variable

This one is very self explanatory, if the ESIGN_HOME has not been defined eSign will start by writting an ERROR message explaining so.

INFO  [main] 2021-09-14 13:00:28.363    novabase.connect.paperless.esign.core.modules.ModuleLauncher - Module Home Manager loading...
ERROR [main] 2021-09-14 13:00:28.372    novabase.connect.paperless.esign.core.modules.ModuleLauncher - Module Home Manager failed.
novabase.connect.paperless.esign.exceptions.eSignException: Module (ESIGN_HOME) is missing the environment variable ESIGN_HOME
	at novabase.connect.paperless.esign.core.configurations.FolderHomeSource.<init>(FolderHomeSource.java:87) ~[classes/:?]

Fix: Check Change Environment Variable

ESIGN_HOME variable pointing to wrong location

This usually happens when the ESIGN_HOME variable is pointing to the parent folder of esign config folder instead of the folder itself.

Or it can also happens if, for some reason, ESIGN_HOME folder is pointing somewhere other than the esign folder.

WARN  [main] 2021-09-14 13:17:13.695    novabase.connect.paperless.esign.core.configurations.FolderHomeConfigurationSource - Could not find configurations file (null) using default configurations...
INFO  [main] 2021-09-14 13:17:13.695    novabase.connect.paperless.esign.configurations.ConfigurationManager - Loaded configuration source: novabase.connect.paperless.esign.core.configurations.FolderHomeConfigurationSource
ERROR [main] 2021-09-14 13:17:13.698    novabase.connect.paperless.esign.core.modules.ModuleLauncher - Module Configurations Manager failed.
java.lang.NullPointerException: null
	at novabase.connect.paperless.esign.core.configurations.FolderHomeConfigurationSource.getProperties(FolderHomeConfigurationSource.java:116) ~[classes/:?]

Fix: Check Change Environment Variable

Log4j file not updated

If the log-path property is not updated in log4j2.xml the log files and log console will continuously be prompt with error entries dictating that the logging file could not be created.

INFO  [main] 2021-09-14 13:28:35.802    novabase.connect.paperless.esign.core.modules.ModuleLauncher - Module Home Manager loading...
2021-09-14 13:28:35,829 main ERROR Invalid status level specified: ON. Defaulting to ERROR.
2021-09-14 13:28:35,870 main ERROR Unable to create file ${sys:SAFEHUB}/esign/logs/esign.log java.io.IOException: The filename, directory name, or volume label syntax is incorrect

Fix: Check Update Log4j

Legacy Hibernate extensions still mentioned

If the explicitly references to eSign database implementations (either in esign.config or in the database configurations) are not fully removed.
eSign will throw exception trying to load theses exceptions, which will prevent the correct functioning of eSign.

ERROR [main] 2021-09-14 17:08:14.200    novabase.connect.paperless.esign.extensions.ExtensionsManager - Failed to load extension: novabase.connect.paperless.esign.license.hibernate.HibernateLicenseRepository
novabase.connect.paperless.esign.exceptions.eSignException: Unable to instantiate class: novabase.connect.paperless.esign.license.hibernate.HibernateLicenseRepository
	at novabase.connect.paperless.esign.utils.ReflectionUtils.getInstance(ReflectionUtils.java:38) ~[classes/:?]

Fix:

  1. Check Remove references to Database Extensions

  2. Remove all references to Hibernate* extensions from esign.config

  3. Remove all references to Hibernate* extensions in eSign database tables: config_extension, config_extension_param and config_module

Mis-configured database auto-deploy

If your project installed database scripts manually and forgot to disable auto-deploy (or to skip the version executed manually) several exceptions will be written in the logs.

ERROR [main] 2021-09-14 19:07:42.288    novabase.connect.paperless.esign.repository.hibernate.base.persistence.PersistenceUtils - Failed to auto-deploy database scripts.
liquibase.exception.MigrationFailedException: Migration failed for change set liquibase/1.0.0/auditor/changelog-build.xml::AUDIT::admin:

Fix: Check Database Auto-Deploy