Installation

Adabas Audit Data Viewer's installation package is provided as a WAR file which should be installed in a Java Application Server.

The tool was tested on web browsers: Chrome 72.0+, Firefox 60.0+, IE 77.0+, Safari 12.0+.

To ensure the proper and secure usage of AAV it is very important to follow also the installation and configuration instructions of chosen Java Application Server. The Java Application Server shall be installed, configured and operated only by qualified system administrator.

The configuration of secure TLS communication is recommended, but is not a part of this documentation. For that please refer to the instruction corresponding to chosen Java Application Server.

Installation requirements

The following components have to be installed:

  • JDK (Java Development Kit) or JRE (Java Runtime Environment),
  • Java Application Server.

Installation process

AAV installation package consist of two parts:

  • WAR file that contains the AAV backend application, which must be deployed on Java Application Server,
  • Web application, that contains static files and can be deployed on any web server (including Java Application Server).

Configuration process

  1. AAV backend configuration

    The backend configuration is placed in the application.yml file.

    In application.yml file the administrator can define the following parameters:

    1. BQL.SQL - allows to enable SSL globally. Defines keystore and truststore paths and passwords. If it is set to true, the (absolute) paths to the keystore/truststore must be provided. 

      

bql
:
  
ssl
:
    
enabled
: 
true
    
keystore
: 
      
path
:
      
password
:
    
truststore
:
      
path
:
      
password
:

    2. Endpoints

      • IP – IP address, where AAR subsystem can be reached (range: 10.0.0.0 – 10.255.255.255),
      • PORT – port number on the z/OS side where AAR subsystem can be reached (range 0 – 65535),
      • SSID – AAR subsystem ID,
      • APPL – application identifier (B97_AAV)
      • SSL - defines if the SSL connection shall be used. If this parameter is set to true, it has to be also enabled globally by means of the parameter bql.sql, by default it is set to false
      

server
:
  
tomcat
:
    
basedir
: 
tomcat
    
accesslog
:
      
directory
: 
logs
      
enabled
: 
true
      
pattern
: 
common

endpoints
:
  
Adabas_Data_Viewer_Demo_System
:
    
ip
:
    
port
:
    
ssid
:
    
aapl
:
  
demo
:
    
ip
:
    
port
:
    
ssid
:
    
aapl
:
    
ssl
:

      Remark: The port number (together with bind address and IP stack) is defined on the z/OS side via the B97_TCPIP_PORT_AAV parameter.

    3. Client: allowed-origins

      The client allowed-origins defines the URLS which can connect to AAV’s backend.

      The following values can be defined for this parameter:

      • list of all allowed URLs,

        
 
client
:
    
allowed-origins
: 
"http://aav.test.com;http://aav.test2.com"

      • all URLs allowed (can be used only for testing purposes).

        

client
:
  
allowed-origins
: 
"*"

    4. User: inactivity

      The time (in seconds) of user inactivity after which the user will be automatically logged out from the AAV.

      

user
:
   
inactivity
: 
3600

    5. Folder caching

      This section of application.yml allows to improve the system performance by enabling Folder Tree caching mechanism:

      • interval: the time after which the list of database folders is updated with newest data,
      • enabled (true/false): enabling/disabling caching mechanism,
      • limit: determines the maximum number of user sessions for which the cache mechanism is enabled, this parameter protects against overuse of a server resources.

      Example: If the number of users exceeds a set value, then the last logged-in users take over the resources of the first ones. 

      
 
folder
:
    
caching
:
      
interval
: 
300
      
enabled
: 
true
      
limit
: 
50

  2. AAV frontend configuration

    Depending on how the frontend files are served, the configuration must be changed accordingly. Frontend configuration is available in config.js file in the frontend directory. This file contains information about the AAV backend (WAR) URL and at which base path the frontend is served on. These values are from the user’s perspective, because of this URLs and paths configured here are the public accessible URLs, as typed in browser address bar, not local file-system paths.

    • Setting API endpoint:

      API_URL defines the path or URL at which the API server is accessible. URL can be relative if the backend is hosted on the same domain or absolute if server is hosted on another domain. When AAV backend server is served from another domain, ensure that CORS is properly configured so that it can be accessed.

      For example, if frontend is available at yourserver.com/aav and backend server is on the same domain at yourserver.com/aav-api, then set API_URL variable as below: 

      

window
.
config 
= 
{

// ...

API_URL
: 
'/aav-api'
,

// ...

};

      If backend is on a different domain, set API_URL to a full URL, as in:

      

window
.
config 
= 
{

// ...

API_URL
: 
'//api.yourserver.com/aav'
,

// ...

};

    • Setting Web App base path

      BASE_PATH defines path at which the AAV webapp is available on your domain. By default, it assumes it is available at “/”, the root directory. If it is installed in a subdirectory, the configuration must be changed as described below.

      If it is available on yourserver.com/aav, then set this value to /aav: 

      

window
.
config 
= 
{

// ...

BASE_PATH
: 
'/aav'
,

// ...

};

      Additionally, index.html file must also be updated with new path.

      Replace <base href="/"/> with: 

      

<
base 
href
=
"/aav/"
/>

      The path must end with slash character /.

    • Routing configuration

      AAV web app uses browser-side routing (html5 history). For this to work, your web server must serve index.html at paths that don't exist. AAV web app comes with WEB-INF directory, that redirects any invalid paths to index.html, which should work with most Java Application Servers.

Example of minimal configuration in Tomcat

  1. If not installed, install JDK (Java Development Kit) or JRE (Java Runtime Environment).

  2. If not installed, install Tomcat v.8.0+.

    Links:

    • JDK installation: https://www.oracle.com/java/technologies/javase-jdk14-downloads.html
    • Tomcat installation: https://tomcat.apache.org/download-90.cgi

    Remark: During installation process, please ensure that the versions of Java and Tomcat (32-bit or 64-bit) will correspond to the operating system installed on the target computer.

  3. Put files from AAV installation package to the Tomcat root folder (path_to_tomcat/).

    Remark: The AAV installation package for Tomcat contains the additional file context.patch. This file contains the information about the updates which should be done in context.xml file. The updates in context.xml file can be done manually (described in next step) or automatically (execution of the context.patch file).

  4. Enable/Disable the usage of the SSL connection by means of the BQL.SQL parameter.

  5. Define endpoints:

    • update context.xml file with a path to application.yml file: 
    

<Context>
  ...
   
<Parameter 
name=
"spring.config.location" 
value=
"path_to_application.yml/
>
  ...

</Context>
    • define endpoints in application.yml file. 
    
 
server
:
    
tomcat
:
      
basedir
: 
tomcat
      
accesslog
:
        
directory
: 
logs
        
enabled
: 
true
        
pattern
: 
common
  
endpoints
:
    
Adabas_Data_Viewer_Demo_System
:
      
ip
:
      
port
:
      
ssid
:
      
aapl
:
    
demo
:
      
ip
:
      
port
:
      
ssid
:
      
aapl
:
      
ssl
:

    IP - IP address, where AAR subsystem can be reached (range: 10.0.0.0 – 10.255.255.255),

    PORT – port number on the z/OS side where AAR subsystem can be reached (range: 0 - 65535)

    SSID – AAR subsystem ID

    APPL – application identifier (B97_AAV)

    SSL - defines if the SSL connection shall be used. If this parameter is set to true, it has to be also enabled globally by means of the parameter bql.sql, by default it is set to false

    Remark: The port number (together with bind address and IP stack) is defined on the z/OS side via the B97_TCPIP_PORT_AAV parameter.

  6. Configure in conf/application.yml file a client allowed-origins.

    The client allowed-origins defines the URLs which can connect to AAV’s backend.

    It should be defined as follows: - list of allowed URLs,

    

client
:
  
allowed-origins
: 
"http://aav.test.com;http://aav.test2.com"
    • all URLs allowed (only for testing purposes).
    

client
:
  
allowed-origins
: 
"*"

  7. Configure in conf/application.yml file a user session inactivity parameter.

    The time (in seconds) of user inactivity after which the user will be automatically logged out from the AAV.

    

user
:
  
inactivity
: 
3600

  8. Configure in conf/application.yml a folder caching parameter.

    This section of conf/application.yml allows to improve the system performance by enabling Folder Tree caching mechanism:

    • interval: the time after which list of database folders is updated with newest data,
    • enabled (true/false): enabling/disabling caching mechanism,
    • limit: determines the maximum number of user sessions for which the cache mechanism is enabled, this parameter protects against overuse of a server resources.

    Example:

    If the number of users exceeds a set value, then the last logged-in users take over the resources of the first ones.

    

folder
:
  
caching
:
    
interval
: 
300
    
enabled
: 
true
    
limit
: 
50

  9. Start (if Tomcat was installed in step 2) or restart Tomcat.

  10. Configure AAV web application config.js.

    Depending on the release contents:

    • if the release package directory contains page directory and app.war file (pre 1.0):

    Set API_URL to /app and BASE_PATH to /page in config.js: 

    

window
.
config 
= 
{
    
API_URL
: 
'/app'
,
    
BASE_PATH
: 
'/page'
,

};

    And replace <base href="/"/> in index.html with: 

    

<
base 
href
=
"/page/"
/>
    • If the release package webapps directory contains aav directory and aav-api.war file (starting with v1.0):

    Set API_URL to /aav-api and BASE_PATH to /aav in config.js: 

    

window
.
config 
= 
{        
    
API_URL
: 
'/aav-api'
,        
    
BASE_PATH
: 
'/aav'
,        

};

    And replace <base href="/"/> in index.html with: 

    

<
base 
href
=
"/aav/"
/>

  11. To configure the secured TLS connection please refer to the following instruction:

    https://tomcat.apache.org/tomcat-9.0-doc/ssl-howto.html