Is a new version of the batch service required? Or is it possible to use the one used for Cashback?
The new version of the batch service is necessary.
What's the required Java version to execute the Batch Acquirer?
The Batch Acquirer is built with Java 1.8 compatibility. However we test and actively support only Java 11 so we encourage to adopt a JRE version 11.
What are the requirements to build the Batch Service executable from source?
To build the Batch Acquirer from source code the only requirements are a JDK 1.8+ and Maven. We strongly encourage however to use a JDK 11 since we test and actively support only Java 11.
It is possible to run the Batch Acquirer behind a HTTP proxy?
Yes, see the relevant HPAN_SERVICE_PROXY_* options in the section.
Are wire transfers included in the flow?
No
is it possible to provide encrypted PANs?
No, In the input file the information must be provided unencrypted, in the output file the information will be hashed.
What is the maximum file size supported by the Batch Service?
Possible reports on records by the Agenzia delle Entrate:
Tax code not valid on the date of the transaction
VAT number non-existent
VAT number ceased
VAT number and fiscal code inconsistent
In this case the records are not rejected by the Agenzia delle Entrate.
Are there any example files?
Under ops_resources/example_files there are example for an input, panlist and output files, all without encryption, and under the configuration expected when calling the remote services (transactions with clear pan, and a pan list with the hashing already applied), the output is also defined without encryption, please refer to the guideline for further details on how to manage the input/output possibilities.
It is necessary to correct the the merchant's data.
In case of rejection of the record by the Agenzia delle Entrate, is it necessary to proceed with a new submission?
No
Permission errors while reading/writing a file
Those kind of errors occur when the Batch Acquirer attempts to read/write to a file that is placed in a location for which the process does not have permissions.
Double-check that the paths defined with the following variables are existent and writable by the process:
ACQ_BATCH_TRX_INPUT_PATH
ACQ_BATCH_OUTPUT_PATH
ACQ_BATCH_TRX_LOGS_PATH
ACQ_BATCH_HPAN_INPUT_PATH
ACQ_BATCH_SENDER_ADEACK_OUTPUT_PATH
What the SkipLimitExceededException exception means?
org.springframework.batch.core.step.skip.SkipLimitExceededException: Skip limit of 'N' exceeded
This error occurs when an error is encountered, while processing the transaction records, that exceeds the configuration for the process fault tolerance, defined by the following property:
The stack-trace following the exception indicates the cause of the error that exceeded the defined limit.
BIN validation error
bin: must match "([0-9]{6}|[0-9]{8})"
This occurs when inserting a Bank Identification Number that does not match the expected length (the standard value is 8, but 6 is at the moment also allowed). In cases where the value has fewer characters, the value must be juxtaposed with zero-padding. See the page.
Missing datasource
Error creating bean with name 'scopedTarget.dataSource' defined in class path resource [org/springframework/boot/autoconfigure/jdbc/DataSourceConfiguration$Hikari.class]: Bean instantiation via factory method failed; nested exception is org.springframework.beans.BeanInstantiationException: Failed to instantiate [com.zaxxer.hikari.HikariDataSource]: Factory method 'dataSource' threw exception; nested exception is java.lang.IllegalStateException: Cannot load driver class: org.postgresql.Driver
This error occurs when defining a configuration for the datasource for a database that is not the default in-memory one (HBSQL). In the standard release the drivers for any specific vendor has to be included when starting the Batch Acquirer process.
Logback DBAppender error on Oracle
at java.sql.SQLException: Invalid argument(s) in call at oracle.jdbc.driver.AutoKeyInfo.getNewSql(AutoKeyInfo.java:187) at oracle.jdbc.driver.PhysicalConnection.prepareStatement(PhysicalConnection.java:4342) at ch.qos.logback.core.db.DBAppenderBase.append(DBAppenderBase.java:97) at ch.qos.logback.core.UnsynchronizedAppenderBase.doAppend(UnsynchronizedAppenderBase.java:84) at ch.qos.logback.core.spi.AppenderAttachableImpl.appendLoopOnAppenders(AppenderAttachableImpl.java:51) at ch.qos.logback.classic.Logger.appendLoopOnAppenders(Logger.java:270) at ch.qos.logback.classic.Logger.callAppenders(Logger.java:257) at ch.qos.logback.classic.Logger.buildLoggingEventAndAppend(Logger.java:421) at ch.qos.logback.classic.Logger.filterAndLog_0_Or3Plus(Logger.java:383) at ch.qos.logback.classic.Logger.log(Logger.java:765) at org.apache.commons.logging.LogAdapter$Slf4jLocationAwareLog.info(LogAdapter.java:454)
This error occurs when using an Oracle Database, and it's related to the usage of a driver version that does not match the one required for the database and java versions. Check the list of available drivers, and refer to the Logback Appenders Documentation.
Oracle error ORA-08177
java.sql.SQLException: ORA-08177: can't serialize access for this transaction
This is a known issue for the Spring Batch Framework. Refer to the note in the Database connection paragraph, and the official Issue Thread.
Cron expression rule error
org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'transactionFilterBatch' defined in URL [jar:file:/app/spe/CAE/semafori/batch-transaction-filter.jar!/BOOT-INF/lib/rtd-ms-transaction-filter-api-batch-1.0-SNAPSHOT.jar!/it/gov/pagopa/rtd/transaction_filter/batch/TransactionFilterBatch.class]: Initialization of bean failed;nested exception is java.lang.IllegalStateException: Encountered invalid @Scheduled method 'launchJob': Cron expression must consist of 6 fields (found 1 in "0")
This error occurs when configuring a scheduled execution, with an invalid cron expression. Refer to the related Oracle Guidelines to create a valid expression.
Validation error
APPLICATION FAILED TO START
Description:
The bean 'jobLauncher', defined in class path resource [it/gov/pagopa/rtd/transaction_filter/batch/TransactionFilterBatch.class], could not be registered. A bean with that name has already been defined in class path resource [org/springframework/batch/core/configuration/annotation/SimpleBatchConfiguration.class] and overriding is disabled.
Action:
Consider renaming one of the beans or enabling overriding by setting spring.main.allow-bean-definition-overriding=true
This error occurs when the default configuration is overwritten, without introducing some of the properties required to execute the process. The following properties are required:
Please refer to the example in ops_resources/example_config
PAN List validation error
Recovered PAN list exceeding a day
When encountering this message “java.lang.Exception: Recovered PAN list exceeding a day” there is a failure in the validation process for the downloaded PAN list.
It’s not a blocking mistake but to delete it you should set the environment variable ACQ_BATCH_HPAN_LIST_DATE_VALIDATION as false
Feign error: read timeout
This error occurs generally during the download phase when calling the endpoint to recover the hpan list. due to the file volume it's expected to wait a substantial amount of time, and both the application ad eventual proxies need to tolerate this wait. For the batch application, the read timeout can be configured with the property feign.client.config.hpan-service.readTimeout.
Out of memory errors
The error occurs when trying to process the hpan files without enough space reserved for the Java process. Try to raise the allocated heap space defined by the variable JAVA_TOOL_OPTIONS (see link).
JDBC error: unable to acquire JDBC connection
The error occurs when using a connection pool that is undersized for the operations to be executed inside the database. In case this error occurs, the suggested action is to extend the connection pool, using the config property spring.datasource.hikari.maximumPoolSize.
It's possible to disable polling on the input files folder?
Yes. To achieve this you should set the variable ACQ_BATCH_SCHEDULED to false. In this way the Batch Service will process one file per execution.
Testing
Will the CSTAR-CLI tool (indicated in the UAT test phase) have to be installed on the same machines where the Batch Service will be installed?
CSTAR-CLI contains both shell and python scripts.
An actual installation is needed only for generating input and example output files. This procedure can be executed on a second machine and then the generated files can be copied on the machine running the batch service.
Shell scripts are designed in order to be lightweight and should be executed directly on the machine running the Batch Service. This will ensure accurate results.
If I get certificate expired error what should I do?
When encountering this message “To connect to api.uat.cstar.pagopa.it insecurely, use `--no-check-certificate’.” while testing the 001-mAuth-check-UAT/script.sh you should remove the row that start with wget command and insert the new command below:
The same thing if you encounter the error while you are testing the scripts “scripts/002-API-key-check-UAT/script.sh” remove the row that start with the wget command and insert:
Certificate renewal
Generate the CSR file from the template as described here
After the request is sent, wait to receive a mail with the signed certificate
Run the scripts to verify PagoPa integration, follow the steps here
Once the scripts pass, prepare the JKS file as described here
Update the environment variables (file setenv):
Restart the Batch Service instance. Make sure that only one instance is running.