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.

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.

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

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]"
       }
   }
  ...
}

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:

docker run -d --mount source=vol[UID],target=/tmp -p [PORT]:8080 --memory=[MEMORY] [IMAGE_ID] --einvoice-integration-client.service.domain=[SAAS_DOMAIN] \ 
// optional parameters
--mount type=bind,source=[PATH_TO_WORK_FOLDER],target=/home \
--server.host.port=[HOST]:[PORT] \
--hot.folder.enabled=[HT_ENABLED] \
--einvoice-integration-client.hot.folder.documents.processing.threshold=[DOC_THRESHOLD] \
--einvoice-integration-client.scheduler.task.handleSignatureTasks.lock-time=[LOCK_TIME] \
--einvoice-integration-client.scheduler.task.processHotFoldersByDocumentThreshold.cron-expression=[DOC_THRESHOLD_FREQUENCY] \
--force.database.recreate=[DB_RECREATE]

Execution example using staging environment:

docker run -d --mount source=vol1,target=/tmp --mount type=bind,source=C:/temp,target=/home -p 8081:8080 --memory=4g teammust/einvoice:integration-client-ws-eeeb1c66db7fc864d4203c3e857b095f29a7a2e6-87 --server.host.port=127.0.0.1:8081 --einvoice-integration-client.service.domain=https://staging.must.digital/ --hot.folder.enabled=TRUE

Execution example using all optional parameters in staging environment:

docker run -d --mount source=vol1,target=/tmp --mount type=bind,source=C:/temp,target=/home -p 8081:8080 --memory=4g teammust/einvoice:integration-client-ws-eeeb1c66db7fc864d4203c3e857b095f29a7a2e6-87 --server.host.port=127.0.0.1:8081 --einvoice-integration-client.service.domain=https://staging.must.digital/ --hot.folder.enabled=TRUE --einvoice-integration-client.hot.folder.documents.processing.threshold=1000 --einvoice-integration-client.scheduler.task.handleSignatureTasks.lock-time=1 --einvoice-integration-client.scheduler.task.processHotFoldersByDocumentThreshold.cron-expression="0 0/5 * * * ?" --force.database.recreate=FALSE

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: