1 Hot-Folder Asynchronous Mode
- 1.1 Architecture
- 1.2 Hardware Requirements
- 1.3 Software Requirements
- 1.4 Configuration File
- 1.5 Running Docker image
- 1.6 Signature integration scheme
- 1.7 Signature response handling

Hot-Folder Asynchronous Mode

Hot-folder mode adds to Async Mode the ability to process files directly from/to a set of configured input/output folders.

Useful in situations where the number of files is large (>2500) and a strategy of input/output folders processing is suitable.

This mode requires, in addition to the configuration file created for the asynchronous mode, that 3 folders be added to the [PATH_TO_WORK_FOLDER] directory, in particular:

Input folder: It is the input interface with the client service and stores the documents to be signed.
Backup folder: Keeps a copy of each file processed. In case of success, only the original file is moved, otherwise, an text file with details of the error is attached.
Output folder: It is the output interface with the client service and stores the signed documents or a text file, named as the original file, with details about the error that occurred.

To enable this mode it is necessary to include the following parameter in addition to those of the ASYNC mode and then set it to TRUE.

Parameter	Description

Parameter	Description
hot.folder.enabled	Turn on/off the hot folder mode (default: FALSE).
einvoice-integration-client.hot.folder.documents.processing.threshold (optional)	Minimum number of files existing in the input folder for start processing. (default: 1000)
einvoice-integration-client.scheduler.task.handleSignatureTasks.lock-time (optional)	Lock time in minutes for the signature cron. (default: 1440) _Obs:_{For proxy versions older than v1.15+b112, the lock time property is in days for the signature cron. (default: 1)}
einvoice-integration-client.scheduler.task.processHotFoldersByDocumentThreshold.cron-expression (optional)	Frequency to check files existing in the input folder. (default: 0 0/5 * * * ?, run every 5 minute)
force.database.recreate (optional)	Force deleting the database file and recreating a new one (default: FALSE)

Architecture

The Sign’Stash Proxy components are in gray background, the Sign’Stash SaaS is in green background, and the blue background pertains to the client service components.

This execution mode only allows ACTIVE/PASSIVE clustering for a given input folder location.

Hardware Requirements

This mode requires the following specifications in terms of disk space consumption (container volume):

Internal database: ~2MB/request with 1000 files (a significant percentage is reclaimed monthly by applying database housekeeping strategies automatically).
Temporary files: Extrapolated according the rule Double(Maximum load in number of files x File average size). E.g., 2x(20.000 files x 200KB) = 8GB.
Throughput: >30files/s

Ideally, the processor used by this service must have intensive processing capacities such as the following models:

Intel Xeon Skylake
Intel Xeon Broadwell

Scenario	Page size of 1000 (container memory)

Scenario

Page size of 1000 (container memory)

Input folder with ~10.000 files

Minimum:
- 2GB
Recommended:
- 4GB

Input folder with ~2.000.000 files

Minimum:
- 4GB
Recommended:
- 8GB

Based on internal stress tests, there are significant improvements in the metrics related to signature time when a request aggregates multiple documents. It means that it is significantly worse to create 50 requests with just one document each than to create a single request with 50 documents.

This aspect must be considered in order to optimize the performance and the load of the systems involved.

Software Requirements

Please refer to https://must.atlassian.net/wiki/spaces/SIGNSTASH/pages/590184469/Sign+Stash+Proxy+Service+Execution#Execution-Requirements

Configuration File

This mode requires to update the configuration file using the following parameters related with the additional folders created.

[INPUT_FOLDER_NAME]: States the relative path of the folder from which the files to be signed will be obtained (e.g. /inputFolder)
[BACKUP_FOLDER_NAME]: States the relative path of the folder to which the processed files will be secured (e.g. /backupFolder)
[OUTPUT_FOLDER_NAME]: States the relative path of the folder to which the signed files (or errors) will be saved (e.g. /outputFolder)

{
  "[CLIENT_SERVICE_ID]": {
      "secret": "[CLIENT_SERVICE_SECRET]",
      "inputFolder": "[INPUT_FOLDER_NAME]",
      "backupFolder": "[BACKUP_FOLDER_NAME]",
      "outputFolder": "[OUTPUT_FOLDER_NAME]"
  }
  ...
}

Optionally, it is also possible to expand this configuration with information to enable visible signatures attributes for PDF documents, using:

[LOCATION_TYPE]: States which type of location strategy will be used to set the visible signature. Allowed values: SIGN_FIELD, COORDINATE, PLACEHOLDER.
[LOCATION_VALUE]: States the location value for the appropriate locationType defined (e.g. page=1,x=100,y=200).
[VISIBLE_TEXT_TEMPLATE_TYPE]: States the type of signature template to be used. Allowed values: ONE_OFF, SERVICE_CUSTOMIZATION.
[ONE_OFF_TEMPLATE_TEXT]: If templateType=ONE_OFF, then set the text value format to display (e.g. Digitally Signed by $certificate.getCommonName()).

{
  "[CLIENT_SERVICE_ID]": {
      "secret": "[CLIENT_SERVICE_SECRET]",
      "inputFolder": "[INPUT_FOLDER_NAME]",
      "backupFolder": "[BACKUP_FOLDER_NAME]",
      "outputFolder": "[OUTPUT_FOLDER_NAME]",
      "padesVisibleSignature": {
          "locationType": "[LOCATION_TYPE]",
          "locationValue": "[LOCATION_VALUE]",
          "templateType": "[VISIBLE_TEXT_TEMPLATE_TYPE]",
          "oneOffTemplate": "[ONE_OFF_TEMPLATE_TEXT]"
       }
   }
  ...
}

It is possible to find additional information about these parameters through the Swagger documentation exposed by the service’s REST API.

Running Docker image

Start the service by defining the docker command according to the following format:

docker run -d --mount source=vol[UID],target=/tmp --mount type=bind,source=[PATH_TO_WORK_FOLDER],target=/home -p [PORT]:8080 --memory=[MEMORY] [IMAGE_ID] --server.host.port=[HOST]:[PORT] --einvoice-integration-client.service.domain=[SAAS_DOMAIN] --einvoice-integration-client.rest.provider.proxy.hostname=[PROXY_HOSTNAME] --einvoice-integration-client.rest.provider.proxy.port=[PROXY_PORT] --hot.folder.enabled=[HT_ENABLED]

Format using all optional parameters:

Execution example using staging environment:

Execution example using all optional parameters in staging environment:

Signature integration scheme

Typical interactions between systems in this mode are presented in the following sequence diagram:

Each document(s) signature request will produce a new operation in the system that could later be consulted on the backoffice.

Signature response handling

General response handling overview:

These are the responses to errors in the signature request that can be found in the files generated with errors:

INVALID_CERT_SERVICE_CREDS: Certificate service access credentials invalid or expired.
CERT_SERVICE_GLOBAL_ERROR: Generic error accessing the certificate service.
CONFIGURATION_SIGN_ERROR: Signature requet contains configuration errors.
TIMESTAMP_SIGN_ERROR: Error accessing the timestamping service.
INVALID_CERTIFICATE_SIGN_ERROR: Error using the signing certificate.
STORAGE_SERVICE_GLOBAL_ERROR: Error storing the signed document.

These are the response in the signature operation:

RECEIVED: Document has been received but no further action was taken.

ERROR_SIGNING: An error has occured when signing was attempted.

SIGNED: A digital signature was successfully applied to the document.

SignStash

Asynchronous Mode (Hot-Folder)