SICS ADH Server

SICS ADH Server

Contents #

This document contains instructions on how to install and successfully configure an instance of SICS Automated Document Handling Server.

Requirements #

SICS ADH Server requires an Application Server running in a Java 21 or later runtime environment.

Installation #

SICS ADH Server is a Web Application and can potentially be deployed in any Application Server.

For deploying an instance of SICS ADH Server it is enough to deploy SicsADHServer.war using the standard procedure for the chosen Application Server.

The WAR file can be found in the SICS delivery folder.

Configuration #

Database connection #

SICS ADH Server requires a connection to the SICS database, in order to retrieve user access rights. It is therefore necessary to bind the JNDI resource named jdbc/sics to the correct JDBC resource. This can be done by editing META-INF/context.xml or though the application server administration pages.

One SICS ADH Server instance can serve only one SICS environment/database. The database schema to be used can be specified by editing WEB-INF/web.xml.

Like SICS API Server, SICS ADH Server can use an application managed DB connection. Please refer to SICS API Server documentation for finding out how.

Logging #

Server logging can be configured in WEB-INF/classes/log4j2.xml

Other configuration options #

Other settings for the Server, that can be set in WEB-INF/web.xml, are:

Setting Description Default value
SystemPoolInitialSize Sets the initial size of the System Pool.

This value indicates how many requests can be handled concurrently, since each request needs to get hold of a System in order to be processed.

Must be an integer greater than 0.		 3
CloseConnectionBeforeReestablishFromJndi SICS ADH Server reestablishes a database connection before processing a request if the database source is a JNDI source.

As a default the current connection will be closed before trying to request a new one. Set the value of this parameter to false to prevent closing the current connection.		 -
RefreshCachedMappingsInterval Interval (in minutes) to wait before forcing an automatic light refresh of the system.

A light refresh will make the server read Automated Document Handling mappings from the database, making sure that they are up-to-date.		 0
(no automatic refresh)
UserAuthorizationInterface The canonical classname of the class implementing the User Authorization Interface.

This parameter is not mandatory and should be set only if the current configuration requires the user used for logging to the database must receive authorization through the UserAuthorizationInterface.		 -
UserExitImplementation Name of Java class implementing a custom UserExit.
It must implement com.csc.cnu.base.domain.eventlog.impl.SicsUserExitInterface.
The DXC-provided default implementation does nothing.
In order to activate this interface, the name of the implementation must be provided (here),
and the Call User Exit option must be set in the Event Log Setup.		 com.csc.cnu.base.domain.eventlog.impl.SicsUserExitDefaultImpl
ExternalCallAuthorizationInterface The canonical classname of the class implementing the External Calls Authorization Inteface.

This parameter is mandatory and it has a default value. The client may create a Java implementation based on their own security configuration to authorize ADH external output pattern’s external calls. And plug-in the implementation here. Refer Authentication/authorization interface… for more details.		 com.csc.sics.externalcallauthorizationinterface.impl.SicsExternalCallAuthorizationInterfaceImpl
Security-Constraint This configuration enables the application to be exclusively accessed via HTTPS.

All HTTP connections will automatically be redirected to HTTPS.		 -

Checking server status (HTTP and JMX) #

At any time, the SICS ADH Server status can be checked using HTTP or JMX (if JMX is enabled in the host JVM).

The status page is accessible at the address:
http://<host>:<port>/<application_root>/status

The server will expose JMX beans for each installed instance of SICS ADH Server, using the application root for identifying each instance.

JMX beans can be access via third-party applications like jConsole or JAVA VisualVM, included in JAVA SDKs.

WebSphere-specific settings #

If you are using WebSphere, after installing the application enter in the WebSphere administration console and set the ADH Server application’s classloading option to “Classes loaded with application class loader first”, as shown in the screenshot below.

adh_server_1.png

REST API #

SICS ADH Server has a REST-based API which allows for easy import and transformation of XML and Excel files.

Import #

For an XML file, use POST or PUT.

Operation Relative URL Description
Import /document Will import an XML file and create an ADH document with a random UUID identifier.
Import /document/{docId} Will import an XML file and create an ADH document with the given identifier.

For an Excel file, use POST with media type “multipart/form-data” and relative URL /document.
The Excel file will be converted into XML format during import.

The multipart structure must contain a “file” part with the Excel file as a stream, with media type
application/vnd.ms-excel
(for an .xls file), or
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
(for an .xlsx file).

Other supported parts (all optional) are:

Part Description
docId Document identifier
fileName File name
params Additional parameters that will appear as XML elements in the generated XML structure.

Details about Excel params #

When provided, the “params” multipart part must be a string of key-value pairs delimited by semicolon. Each pair consists of a key and a value, separated by an equal sign.

For example:
mapping=GENERALI;uwYear=1997;contractRef=900491

  • Each key will become a tag/field added at the top of the input data (XML) created from the spreadsheet.
  • Each value will become the value of that tag.

This gives full flexibility to include any additional data desired, over and above the data in the spreadsheet.

Example XML input resulting from a REST call with fileName=‘TestExcel5.xlsx’, params=‘mapping=GENERALI;uwYear=1997;contractRef=900491’ and a spreadsheet where the first tab is named ‘Sheet1’:

<Output>
   <fileName>TestExcel5.xlsx</fileName>
   <params>
      <mapping>GENERALI</mapping>
      <uwYear>1997</uwYear>
      <contractRef>900491</contractRef>
   </params>
   <pages>
      <page name="Sheet1"
   ....

From this one can create Input Pattern fields ‘fileName’, ‘mapping’, ‘uwYear’, and ‘contractRef’, and use these in the transformation.

Keys may not contain: whitespace, null characters, semicolon, equal sign or single quote.

Values may be empty.

If - and only if - the value contains a semicolon, an equal sign, a leading single quote, or a leading or trailing whitespace, then the value must be surrounded by single quotes AND any single quote in the value itself must be replaced by two single quotes.

For example, if the contractRef is
310560A
then it must be included in the ‘params’ parameter as
contractRef=310560A

If the contractRef is
310=560A
then it must be included in the ‘params’ parameter as
contractRef='310=560A'

If the contractRef is
310'560A
then it must be included in the ‘params’ parameter as
contractRef=310'560A

If the contractRef is
‘310560A
then it must be included in the ‘params’ parameter as
contractRef='''310560A'

Import and Transform #

Same as above, except the relative URL is
/transform.