AWS Mainframe Modernization Service (Managed Runtime Environment experience) is no longer open to new customers. For capabilities similar to AWS Mainframe Modernization Service (Managed Runtime Environment experience) explore AWS Mainframe Modernization Service (Self-Managed Experience). Existing customers can continue to use the service as normal. For more information, see [AWS Mainframe Modernization availability change](https://docs.aws.amazon.com/m2/latest/userguide/mainframe-modernization-availability-change.html).
# Set up configuration for AWS Transform for mainframe Runtime
The AWS Transform for mainframe Runtime and the client code are web applications using the [Spring Boot framework](https://docs.spring.io/spring-boot/docs/2.5.14/reference/html/). It leverages Spring capabilities to supply configuration, with several possible locations and precedence rules. There are also similar precedence rules for supplying many other files, such as groovy scripts, sql, etc.
The AWS Transform for mainframe Runtime also contains additional optional web applications, that can be opted-in if needed.
**Topics**
+ [Application configuration basics](#ba-runtime-config-app-basics)
+ [Application precedence](#ba-runtime-config-app-precedence)
+ [JNDI for databases](#ba-runtime-config-app-jndi)
+ [AWS Transform for mainframe Runtime secrets](ba-runtime-config-app-secrets.md)
+ [Other files (groovy, sql, etc.)](#ba-runtime-config-app-files)
+ [Additional web application](#ba-runtime-config-app-webapp)
+ [Enable properties for AWS Transform for mainframe Runtime](ba-runtime-key-value.md)
+ [Available Redis cache properties in AWS Transform for mainframe Runtime](ba-runtime-redis-configuration.md)
+ [Configure security for Gapwalk applications](ba-runtime-security.md)
## Application configuration basics
The default way to handle application configuration is through the use of dedicated YAML files to be supplied in the application server's `config` folder. There are two main YAML configuration files:
+ `application-main.yaml`
+ `application-profile.yaml` (where `profile` value is setup during application generation).
The first file configures the framework, i.e. `Gapwalk-application.war`, while the second one is for additional options specifically for the client application. This works with the use of spring profiles: the Gapwalk application uses the `main` profile, while the client application uses the `profile` profile.
The following example shows a typical main YAML file.
![\[Excerpt of a "main" YAML file.\]](http://docs.aws.amazon.com/m2/latest/userguide/images/main-yaml.png)
The following example shows a typical client YAML file.
![\[Client YAML example\]](http://docs.aws.amazon.com/m2/latest/userguide/images/client-yaml.png)
For information about the content of the YAML files, see [Enable properties for AWS Transform for mainframe Runtime](ba-runtime-key-value.md).
## Application precedence
For these configuration files, Spring precedence rules apply. Notably:
+ The `application-main` YAML file appears in the Gapwalk main war file with default values, and the one in the `config` folder supersedes it.
+ The same should be done for the client application configuration
+ Additional parameters may be passed on the command line at server launch time. They would override the YAML ones.
For more information, see [Official Spring Boot documentation](https://docs.spring.io/spring-boot/docs/2.5.14/reference/html/features.html#features.external-config).
## JNDI for databases
The database configuration might be supplied with JNDI in the context.xml file in Tomcat. Any such configuration would override the YAML one. But pay attention that using this will not allow to wrap your credentials in a secret manager (see below).
The following example shows sample configurations for JICS and Blusam databases.
```
```
jdbc/jics
Would be `jdbc/jics` for the JICS database and `jdbc/bluesam` (pay attention to the 'e') for the Blusam database.
url="jdbc:postgresql://XXXX.rds.amazonaws.com:5432/XXXX" username="XXXX" password="XXXX"
The database url, username and password.
# AWS Transform for mainframe Runtime secrets
Some of the resource configurations that contain credentials can be further secured by using AWS secrets. The idea is to store critical data in an AWS secret and have a reference to the secret in the YAML configuration so the secret content is picked up on the fly at Apache Tomcat startup.
## Secrets for Aurora
Aurora database configuration (for JICS, Blusam, customer db, and so on) will use the built-in [database secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_database_secret.html), which will populate all the relevant fields automatically from the corresponding database.
**Note**
The `dbname` key is optional, depending on your database configuration, it will get into the secret or not. You can add it there manually, or by supplying the name to the YAML file.
## Other secrets
Other secrets are for resources that have a single password (notably password-protected redis caches). In this case the [other type of secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html) must be used.
### YAML references to secrets
The `application-main.yml` can reference the secret ARN for various resources:
### JICS database
JICS database credentials with `spring.aws.jics.db.secret`
```
spring:
aws:
jics:
db:
dbname: jics
secret: arn:aws:secretsmanager:XXXX
```
Supported JICS database secret keys:
| Secret key | Secret key description |
| --- | --- |
| host | The host name |
| port | The port |
| dbname | The name of the database |
| username | The username |
| password | The password |
| engine | Database engine: Postgres, Oracle, Db2, Microsoft SQL Server |
| currentSchema | Specific schema to use (Db2 support only) |
| sslConnection | Whether to use SSL connection (Db2 support only) |
| sslTrustStoreLocation | The location of the truststore on the client (Db2 support only) |
| sslTrustStorePassword | The password for the truststore on the client (Db2 support only) |
**Note**
The name of the database is either supplied in the secret or in the yaml reference `spring.aws.jics.db.dbname`.
### Blusam database
Blusam database credentials with `spring.aws.client.bluesam.db.secret`
```
spring:
aws:
client:
bluesam:
db:
dbname: bluesam
secret: arn:aws:secretsmanager:XXXX
```
Supported Blusam database secret keys:
| Secret key | Secret key description |
| --- | --- |
| host | The host name |
| port | The port |
| dbname | The name of the database |
| username | The username |
| password | The password |
| engine | Database engine: Postgres |
**Note**
The name of the database is either supplied in the secret or in the yaml reference `spring.aws.client.bluesam.db.dbname`.
### Client database
The client `application-profile.yml` can reference the secret ARN for the client database. This requires an additional property to list the datasource names `spring.aws.client.datasources.names`. For each datasource name `ds_name` specify the secret ARN in the following property: `spring.aws.client.datasources.ds_name.secret`. Example:
```
spring:
aws:
client:
datasources:
names: primary,host
primary:
secret: arn:aws:secretsmanager:XXXX
host:
dbname: hostdb
secret: arn:aws:secretsmanager:XXXX
```
*names: primary,host*:
An example with two client datasources named primary and host, each with their database and credentials.
*dbname: hostdb*:
In this example, the name of the "host" database is not in the secret and is supplied here instead, while for the "primary" database it is in the secret.
Supported client database secret keys:
| Secret key | Secret key description |
| --- | --- |
| host | The host name |
| port | The port |
| dbname | The name of the database |
| username | The username |
| password | The password |
| engine | Database engine: Postgres, Oracle, Db2, Microsoft SQL Server |
| currentSchema | Specific schema to use (Db2 support only) |
| sslConnection | Whether to use SSL connection (Db2 support only) |
| sslTrustStoreLocation | The location of the truststore on the client (Db2 support only) |
| sslTrustStorePassword | The password for the truststore on the client (Db2 support only) |
### PGM utility database
The `application-utility-pgm.yml` can reference the secret ARN for various resources.
+ `spring.aws.client.datasources.primary`
+ `secret`
Secret ARN for the application database.
Type: string
+ `type`
Fully qualified name of the connection pool implementation to use.
Type: string
Default: `com.zaxxer.hikari.HikariDataSource`
+ `spring.aws.client.utility.pgm.datasources`
+ `names`
List of data source names.
Type: string
+ `dsname`
+ `dbname`
Name of the host.
Type: string
+ `secret`
Secret ARN of the host database.
Type: string
+ `type`
Fully qualified name of the connection pool implementation to use.
Type: string
Default: `com.zaxxer.hikari.HikariDataSource`
For a multi-datasources secret:
```
spring:
aws:
client:
primary:
secret: arn:aws:secretsmanager:XXXX
type: dataSourceType
utility:
pgm:
datasources:
names: dsname1,dsname2,dsname3
dsname1:
dbname: dbname1
secret: arn:aws:secretsmanager:XXXX
type: dataSourceType
dsname2:
dbname: dbname2
secret: arn:aws:secretsmanager:XXXX
type: dataSourceType
dsname3:
dbname: dbname3
secret: arn:aws:secretsmanager:XXXX
type: dataSourceType
```
### No XA supported secret keys
+ engine (postgres/oracle/db2/mssql)
+ port
+ dbname
+ currentSchema
+ username
+ password
+ url
+ sslConnection
+ sslTrustStoreLocation
+ sslTrustStorePassword
For `postgres` only the `sslMode` secret key value (`disable/allow/prefer/require/verify-ca/verify-full`) and the `spring.aws.rds.ssl.cert-path` YAML property make it possible to connect with SSL.
### XA supported secret keys
If the client database is using XA, the sub xa-properties are supported through secret values.
+ host
+ port
+ dbname
+ currentSchema
+ username
+ password
+ url
+ sslConnection (true/false)
+ sslTrustStoreLocation
+ sslTrustStorePassword
However, for other xa-properties ( for example `maxPoolSize` or `driverType`), the regular YAML key `spring.jta.atomikos.datasource.XXXX.unique-resource-name` must still be supplied.
The secret value overrides the YAML properties.
### Default Super Admin BAC and JAC
You can also configure application-main.yml to retrieve the username and the password of the default super admin user in the secret from AWS Secrets Manager by specifying the ARN. The following example shows how to declare this secret in a YAML file.
```
spring:
aws:
client:
defaultSuperAdmin:
secret: arn:aws:secretsmanager:XXXX
```
Supported default super admin database secret keys:
| Secret key | Secret key description |
| --- | --- |
| username | The username. |
| password | The password. |
### OAuth2
You can also configure `application-main.yml` to retrieve the OAuth2 client secret from AWS Secrets Manager by specifying the provider and ARN. The default value for the provider property is Amazon Cognito. The following is an example configuration for the OAuth2 provider Keycloak:
```
spring:
aws:
client:
provider: keycloak
keycloak:
secret: arn:aws:secretsmanager:XXXX
```
In this example, the client-secret for the OAuth2 provider Keycloak is retrieved from the specified ARN in AWS Secrets Manager. This configuration supports multiple providers by dynamically resolving the provider name and corresponding secret ARN.
Supported OAuth2 secret keys:
| Secret key | Secret key description |
| --- | --- |
| client-secret | The secret generated by the authorization server during the process of application registration. |
### Secret manager for Redis caches
The `application-main.yml` file can reference the secret ARN for Redis caches. The supported one are:
+ Gapwalk Redis credentials with `spring.aws.client.gapwalk.redis.secret`
+ Bluesam Redis credentials with `spring.aws.client.bluesam.redis.secret`
+ Bluesam locks Redis credentials with `spring.aws.client.bluesam.locks.redis.secret`
+ Dataset catalog Redis credentials with `spring.aws.client.dataset.catalog.redis.secret`
+ JICS Redis credentials with `spring.aws.client.jics.redis.secret`
+ Session Redis credentials with `spring.aws.client.jics.redis.secret`
+ Session tracker Redis credentials with `spring.aws.client.session.tracker.redis.secret`
+ JICS TS Queues Redis credentials with `spring.aws.client.jics.queues.ts.redis.secret`
+ JCL checkpoint Redis credentials with `spring.aws.client.jcl.checkpoint.redis.secret`
+ Gapwalk files locks Redis credentials with `spring.aws.client.gapwalk.files.locks.redis.secret`
+ Blu4IV locks Redis credentials with `spring.aws.client.blu4iv.locks.redis.secret`
The following example shows how to declare these secrets in a YAML file.
```
spring:
aws:
client:
gapwalk:
redis:
secret: arn:aws:secretsmanager:XXXX
bluesam:
locks:
redis:
secret: arn:aws:secretsmanager:XXXX
redis:
secret: arn:aws:secretsmanager:XXXX
dataset:
catalog:
redis:
secret: arn:aws:secretsmanager:XXXX
jics:
redis:
secret: arn:aws:secretsmanager:XXXX
session:
tracker:
redis:
secret: arn:aws:secretsmanager:XXXX
jics:
queues:
ts:
redis:
secret: arn:aws:secretsmanager:XXXX
jcl:
checkpoint:
redis:
secret: arn:aws:secretsmanager:XXXX
gapwalk:
files:
locks:
redis:
secret: arn:aws:secretsmanager:XXXX
blu4iv:
locks:
redis:
secret: arn:aws:secretsmanager:XXXX
```
Supported Redis secret keys:
| Secret key | Secret key description |
| --- | --- |
| hostname | The Redis server hostname. |
| port | The Redis server port. |
| username | The username. |
| password | The password. |
### Secret manager for SSL password settings
The `application-main.yml` file can reference the secret ARN for SSL password settings. The following is supported.
+ Gapwalk SSL credentials with `spring.aws.client.ssl.secret`
The following example shows how to declare these secrets in a YAML file.
```
spring:
aws:
client:
ssl:
secret: arn:aws:secretsmanager:XXXX
```
| Secret key | Secret key description |
| --- | --- |
| trustStorePassword | The truststore password. |
| keyStorePassword | The keystore password. |
### Secret manager for IBM MQ password settings
The `application-main.yml` file can reference the secret ARN for IBM MQ settings. The following is supported.
+ IBM MQ connections are defined as a list, and so are the credentials:
`mq.queues.jmsMQQueueManagers[N].secret:`
N starts at 0 for the first connection.
The following example shows how to declare these secrets in a YAML file.
```
mq.queues.jmsMQQueueManagers[0].secret: Secret-0-ARN
mq.queues.jmsMQQueueManagers[1].secret: Secret-1-ARN
```
For information about secret ARNs, see [What's in a Secrets Manager secret?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/whats-in-a-secret.html)
Properties defined in the secret will override their corresponding values in the `jmsMQ` YAML configuration.
If `queueManager` is set in the secret, it will override the `mq.queues.jmsMQQueueManagers[N].jmsMQQueueManager` value in the YAML file.
| Secret key | Secret key description |
| --- | --- |
| queueManager | The IBM MQ queue manager name. |
| appName | The IBM MQ application name. |
| channel | The IBM MQ channel name. |
| host | The IBM MQ hostname. |
| port | The IBM MQ port. |
| userId | The IBM MQ user name. |
| password | The IBM MQ user password. |
| maxPoolSize | The IBM MQ maximum pool size. |
| sslCipherKey | The IBM MQ SSL cipher suite. |
### JHDB database
The client `application-jhdb.yml` file can reference the secret ARNs for JHDB metadata databases. Each database connection requires a unique name and corresponding secret ARN containing the connection credentials. Database names are defined in a comma-separated list, with individual secret ARNs mapped to each database name.
```
spring:
aws:
jhdb:
cnxs:
datasources:
names: DBD1,DBD2
DBD1:
secret: arn:aws:secretsmanager:XXXX
DBD2:
secret: arn:aws:secretsmanager:XXXX
```
Supported client database secret keys:
| Secret key | Secret key description |
| --- | --- |
| host | The host name. |
| port | The port. |
| dbname | The name of the database. |
| username | The username. |
| password | The password. |
| engine | Database engine: Postgres(now support Postgres only). |
| currentSchema | Specific schema to use. |
## Other files (groovy, sql, etc.)
The other files used by the customer project use similar precedence rules as the ones for spring configuration. Examples:
+ Groovy scripts are `.groovy` files in the `scripts` folder or subfolders.
+ SQL scripts are `.sql` files in the `sql` folder or subfolders.
+ Daemon scripts are `.groovy` files in the `daemons` folder or subfolders.
+ Queries Database mapping file are files named `queries-database.mapping` files in the `sql` folder subfolders.
+ Jasper templates are `.jrxml` files in the `templates` folder or subfolders.
+ Dataset catalogs are `.json` files in the `catalog` folder.
+ Lnk files are `.json` files in the `lnk` folder.
All these locations can be overridden by way of a system property or a client YAML property.
+ For Groovy scripts: `configuration.scripts`
+ For SQL scripts: `configuration.sql`
+ For Daemon scripts: `configuration.daemons`
+ For Queries Database mapping file: `configuration.databaseMapping`
+ For Jasper templates: `configuration.templates`
+ For Dataset catalogs: `configuration.catalog`
+ For Lnk files: `configuration.lnk`
If the property is not found, the files will be taken from the default location mentioned above. The lookup will first be done with the tomcat working directory as a root, and lastly in the application war file.
## Additional web application
The AWS Transform for mainframe Runtime contains additional web applications in its `webapps-extra` folder. These applications are not served by default by the tomcat server.
Opting-in to these web applications is modernization project dependent and is done by moving the desired war file from the `webapps-extra` folder to the `webapps` folder. After that, the war will be served by the tomcat server at next startup.
Some project-specific additional configuration can also be added in a YAML configuration file for each additional war, as is done in the `application-main.yml` file and explained above. The additional wars are:
+ `gapwalk-utility-pgm.war`: contains support for ZOS utility programs and uses `application-utility-pgm.yaml` as its configuration.
+ `gapwalk-cl-command.war`: contains support for AS/400 utility programs and uses `application-cl-command.yaml` as its configuration.
+ `gapwalk-hierarchical-support.war`: contains IMS/MFS transaction support and uses `application-jhdb.yaml` as its configuration
# Enable properties for AWS Transform for mainframe Runtime
In Spring Boot applications `application-main.yml` is the configuration file in which we define different kinds of properties such as the listening port, database connectivity, and many more. You can use this page to learn about the available properties for AWS Transform for mainframe Runtime and how to enable them.
**Topics**
+ [YML notation](#ba-runtime-key-value-yml)
+ [Quick start / Use cases](#ba-runtime-key-value-use-cases)
+ [Available properties for the main application](#ba-runtime-key-value-main)
+ [Available properties for optional web applications](#ba-runtime-key-value-web)
+ [Available properties for the client application](#ba-runtime-key-value-client)
+ [Configure API access logging](#ba-runtime-api-access-logging)
## YML notation
In the following documentation, a property such as `parent.child1.child2=true` is written as follows in YAML format.
```
parent:
child1:
child2: true
```
## Quick start / Use cases
The following use cases show examples of the applicable keys and values.
+ Default application-main.yml
```
----
#### DEFAULT APPLICATION-MAIN.YML FILE #####
#### SHOWING USEFUL CONFIGURATION ELEMENTS #####
#### SHOULD BE OVERRIDDEN AND EXTERNALIZED #####
#################################
##### Logging configuration #####
#################################
logging:
config: classpath:logback-main.xml
level.org.springframework.beans.factory.support.DefaultListableBeanFactory : WARN
################################
##### Spring configuration #####
################################
spring:
quartz:
auto-startup: false
scheduler-name: Default
properties:
org.quartz.threadPool.threadCount: 1
jta:
enabled: false
atomikos.properties.maxTimeout : 600000
atomikos.properties.default-jta-timeout : 100000
jpa:
# DISABLE OpenEntityManagerInViewInterceptor
open-in-view: false
# Fix Postgres JPA Error:
# Method org.postgresql.jdbc.PgConnection.createClob() is not yet implemented.
properties.hibernate.temp.use_jdbc_metadata_defaults : false
#####################################
##### Jics tables configuration #####
#####################################
# The dialect should match the jics datasource choice
database-platform : org.hibernate.dialect.PostgreSQLDialect # org.hibernate.dialect.PostgreSQLDialect, org.hibernate.dialect.SQLServerDialect
# those properties can be used to create and initialize jics tables automatically.
# properties:
# hibernate:
# globally_quoted_identifiers: true
# hbm2ddl:
# import_files_sql_extractor : org.hibernate.tool.hbm2ddl.MultipleLinesSqlCommandExtractor
# import_files : file:./setup/initJics.sql
# auto : create
##########################
###### Level 2 cache #####
##########################
# cache:
# use_second_level_cache: true
# use_query_cache: true
# region:
# factory_class: org.hibernate.cache.ehcache.EhCacheRegionFactory
# javax:
# persistence:
# sharedCache:
# mode: ENABLE_SELECTIVE
##########################
###### Redis settings #####
##########################
session:
store-type: none #redis
# Secret manager configuration for global Redis cache
aws:
client:
gapwalk:
redis:
secret: arn:aws:secretsmanager:XXXX
#########################################
##### JICS datasource configuration #####
#########################################
datasource:
jicsDs:
driver-class-name : org.postgresql.Driver # org.postgresql.Driver, com.microsoft.sqlserver.jdbc.SQLServerDriver
url: jdbc:postgresql://localhost/jics # jdbc:postgresql://localhost:5433/jics, jdbc:sqlserver://localhost\SQLEXPRESS:1434;databasename=jics;
username: jics
password: jics
type : org.postgresql.ds.PGSimpleDataSource # org.postgresql.ds.PGSimpleDataSource, com.microsoft.sqlserver.jdbc.SQLServerDataSource
#####################################################
##### Embedded Bluesam datasource configuration #####
#####################################################
bluesamDs :
driver-class-name : org.postgresql.Driver
url : jdbc:postgresql://localhost/bluesam
username : bluesam
password : bluesam
type : org.postgresql.ds.PGSimpleDataSource
##########################################
##### Embedded Bluesam configuration #####
##########################################
bluesam :
cache : ehcache
persistence : pgsql
ehcache:
resource-pool:
size: 4GB
write-behind:
enabled: true
pgsql :
dataSource : bluesamDs
#########################
##### Jics settings #####
#########################
rabbitmq.host: localhost
jics:
cache: false #redis
resource-definitions.store-type: jpa # default value: jpa, other possible value: redis
jics.disableSyncpoint : false
#jics.initList:
#jics.parameters.datform: DDMMYY
#jics.parameters.applid: VELOCITY
#jics.parameters.sysid: CICS
#jics.parameters.eibtrmid: TERM
#jics.parameters.userid: MYUSERID
#jics.parameters.username: MYUSERNAME
#jics.parameters.opid: XXX
#jics.parameters.cwa.length: 0
#jics.parameters.netname: MYNETNAME
#jics.parameters.jobname: MJOBNAME
#jics.parameters.sysname: SYSNAME
##############################################
##### Jics RunUnitLauncher pool settings #####
##############################################
#jics.runUnitLauncherPool.enable: false
#jics.runUnitLauncherPool.size: 20
#jics.runUnitLauncherPool.validationInterval: 1000
#########################
##### Jhdb settings #####
#########################
#jhdb.lterm: LTERMVAL
#jhdb.identificationCardData: SomeIDData
###################################
##### DateHelper configuration ####
###################################
#forcedDate: "2013-08-26T12:59:58+01:57"
#############################
##### Sort configuration ####
#############################
#externalSort.threshold: 256MB
###################################
##### Server timeout (10 min) ####
###################################
spring.mvc.async.request-timeout: 600000
###############################
##### DATABASE STATISTICS ####
###############################
databaseStatistics : false
######################
##### CALLS GRAPH ####
######################
callGraph : false
####################################
##### SSL configuration #####
####################################
gapwalk.ssl.enabled : true
gapwalk.ssl.trustStore : "./config/clientkey.jks"
gapwalk.ssl.trustStorePassword : mysslcertifpassword
##################################
##### MQ settings #####
##################################
mq.queues: jmsmq
mq.queues.jmsMQQueueManagers[0].jmsMQQueueManager: QM1
mq.queues.jmsMQQueueManagers[0].jmsMQAppName: Gapwalk
mq.queues.jmsMQQueueManagers[0].jmsMQChannel: DEV.APP.SVRCONN
mq.queues.jmsMQQueueManagers[0].jmsMQHost: localhost
mq.queues.jmsMQQueueManagers[0].jmsMQPort: 1415
mq.queues.jmsMQQueueManagers[0].jmsMQUserid: app
mq.queues.jmsMQQueueManagers[0].jmsMQSSLCipher: "*TLS12ORHIGHER"
mq.queues.jmsMQQueueManagers[1].jmsMQQueueManager: QM2
mq.queues.jmsMQQueueManagers[1].jmsMQAppName: Gapwalk
mq.queues.jmsMQQueueManagers[1].jmsMQChannel: DEV.APP.SVRCONN
mq.queues.jmsMQQueueManagers[1].jmsMQHost: localhost
mq.queues.jmsMQQueueManagers[1].jmsMQPort: 1415
mq.queues.jmsMQQueueManagers[1].jmsMQUserid: app
#########################################################
##### Configuration properties for JMS MQ connection ####
#########################################################
mq.queues.jms.connectionfactory.borrow-connection-timeout: 31 # Timeout, in seconds, for borrowing connections from the pool.
mq.queues.jms.connectionfactory.ignore-session-transacted-flag: true # Whether or not to ignore the transacted flag when creating a session.
mq.queues.jms.connectionfactory.local-transaction-mode: false # Whether or not to include local transactions.
mq.queues.jms.connectionfactory.maintenance-interval: 62 # The time, in seconds, between runs of the pool's maintenance thread.
mq.queues.jms.connectionfactory.max-idle-time: 63 # The time, in seconds, after which connections are cleaned up from the pool.
mq.queues.jms.connectionfactory.max-lifetime: 0 # The time, in seconds, that a connection can be pooled for before being destroyed. 0 denotes no limit.
mq.queues.jms.connectionfactory.max-pool-size: 1 # The maximum size of the pool. This property will be overwritten by mq.queues.jmsMQQueueManagers[N].jmsMQMaxPoolSize property (if provided).
mq.queues.jms.connectionfactory.min-pool-size: 1 # The minimum size of the pool.
mq.queues.jms.connectionfactory.reap-timeout: 0 # The reap timeout, in seconds, for borrowed connections. 0 denotes no limit.
###############################
##### SQL SHIFT CODE POINT ####
###############################
# Code point 384 match unicode character \u0180
sqlCodePointShift : 384
###############################
##### LOCK TIMEOUT RECORD ####
###############################
# Blu4IV record lock timeout
lockTimeout : 100
##############################
##### REPORTS OUTPUT PATH ####
##############################
reportOutputPath: reports
##############################
##### TASK EXECUTOR ####
##############################
taskExecutor:
corePoolSize: 5
maxPoolSize: 10
queueCapacity: 50
allowCoreThreadTimeOut: false
##############################
##### PROGRAM NOT FOUND ####
##############################
stopExecutionWhenProgNotFound: false
######################################################
##### DISP DEFAULT VALUE (to be removed one day) ####
######################################################
defaultKeepExistingFiles: true
######################################################
##### BLOCKSIZE DEFAULT VALUE ####
######################################################
#blockSizeDefault: 32760
#####################################
##### JOBQUEUE CONFIGURATION ####
#####################################
jobqueue:
api.enabled: false
impl: none # possible values: quartz, none
schedulers: # list of schedulers
-
name: queue1
threadCount: 5
-
name: queue2
threadCount: 5
################################################################################
##### QUERY BUILDING ##
# useConcatCondition : false by default
# if true, in the query, the where condition is build with key concatenation ##
################################################################################
# query.useConcatCondition: true
########################################
##### JCL Batch Restart Mechanism ####
########################################
jcl:
checkpoint:
enabled: false
#expireTimeout: -1
#expireTimeoutUnit: SECONDS # Supported values: java.util.concurrent.TimeUnit
#provider: redis
##############################
##### System parameters ####
##############################
system.date.format:MDY
system.date.separator: "/"
#############################################################
##### Database metadata schema inclusion configuration ####
#############################################################
gapwalk:
database:
metadata:
schema-inclusion:
enabled: false
schemas:
global:
- "SCHEMA1"
- "SCHEMA2"
##############################
##### URL configuration ####
##############################
gapwalk.post.script.mediatype.json: false
########################################
##### CBLQDA parameters ####
########################################
gapwalk.cobol.cblqda.enabled: false
----
```
+ Use variable length files with LISTCAT commands
```
[**/*.*]
encoding=IBM930
reencoding=false
[global]
listcat.variablelengthpreprocessor.enabled=true
listcat.variablelengthpreprocessor.type=rdw
# use "rdw" if your .listcat file contains a set of records (RDW)
# use "bdw" if your .listcat file contains a set of blocks (bdw)
```
+ Provide Null Byte Indicator Value in LOAD/UNLOAD utility
```
# Unload properties
# For date/time: if use database configuration is enabled, formats are ignored
# For nbi; use hexadecimal syntax to specify the byte value
# - When the value is null in database : the value dumped to the file is filled by low value characters and the NBI is
# equal to the byte 6F (the ? character)
# - When the value is not null in database and the column is nullable: the NBI is equal to the byte 00 (low value) and NOT
# equal to the byte 40 (space)
unload:
sqlCodePointShift: 0
nbi:
whenNull: "6F"
whenNotNull: "00"
useDatabaseConfiguration: false
format:
date: MM/dd/yyyy
time: HH.mm.ss
timestamp: yyyy-MM-dd-HH.mm.ss.SSSSSS
```
## Available properties for the main application
This table provides an exhaustive view of key/values parameters.
**Note**
If you are migrating to version 5.1.0 or later and using bluesam with default openWarmUp behavior:
The default value of `bluesam.openWarmUp` has changed from `true` to `false`
To maintain existing behavior, you must explicitly set `bluesam.openWarmUp=true`
| Key | Type | Default value | Description | Release version |
| --- | --- | --- | --- | --- |
| `system.date.format` | string | MDY | The system date format DATFMT. | --- |
| `system.date.separator` | string | / | The system date separator DATSEP. Possible values are slash (`/`), dash (`–`), period (`.`), comma (`,`) or blank (` `). Value needs to be specified in double quotes `""`. | 5.17.0 |
| `logging.config` | Path | classpath:logback-main.xml | Standard key for the reference to the logback configuration file. Other standard logging keys are available too. | |
| `spring.jta.enabled` | boolean | false | Standard key. If the datasource support mode is not static-xa, spring JTA transactions autoconfiguration must be disabled. | |
| `datasource.jicsDs` \$1 -`driver-class-name` \$1 -`url` \$1 -`username` \$1 -`password` \$1 -`type` | Standard spring datasource with subkeys | | Contains the connection information for the Jics database. Alternately, use of AWS secrets is strongly encouraged, as explained in [JICS database](ba-runtime-config-app-secrets.md#jics-database). | |
| `jildb.datasource` \$1 -`driver-class-name` \$1 -`url` \$1 -`username` \$1 -`password` | Standard spring datasource with subkeys | | Contains the connection information for the Jics database. | |
| `jildb.backend` | string | | Specifies the database type used in the Jildb backend, for example, Oracle. | |
| `jildb.record-hold-timeout` | int | 10000 | Specifies the wait timeout period, in milliseconds, for the record holding mechanism in Jildb. | |
| `datasource.bluesamDs` \$1 -`driver-class-name` \$1 -`url` \$1 -`username` \$1 -`password` \$1 -`type` | Standard spring datasource with subkeys | | Contains the connection information for the Blusam database. Alternately, use of AWS secrets is strongly encouraged, as explained in [Blusam database](ba-runtime-config-app-secrets.md#blusam-database). | |
| `blu4iv.userspace.pageSize` | int | 4096 | Specifies the page size which is used to allocate storage for user spaces. The size of the user space at any given time is always a multiple of this number specified. | 4.10.0 |
| `blu4iv.userspace.store-type` | string | memory | Specifies the store type that is used for user space registry. Supported values are memory and redis. If no store type is provided, memory is used by default. | 4.10.0 |
| `blu4iv.userspace.redis.*` | Supported Redis properties | | Specifies configuration properties for the user spaces redis store, see [Available Redis cache properties in AWS Transform for mainframe Runtime](ba-runtime-redis-configuration.md). | 4.10.0 |
| `blu4iv.userspace.batchThreshold` | int | 1 | Specifies the number of update or set operations on a userspace after which the userspace is persisted in an external data repository. | 5.75.0 |
| `blu4iv.dataaccess.useOldDaoDesign` | boolean | false | A global flag that determines if the application is to use the old DAO architecture or the new. This is dependent on whether the DAO's were generated using old or new design. | |
| `bluesam.disabled` | boolean | false | Whether to disable Blusam entirely. | |
| `bluesam.cache` | string | | If not set, the Blusam cache will not be used. Possible values (cache implementations) are ehcache and redis ([Redis cache properties](ba-runtime-redis-configuration.md#ba-runtime-redis-caches-properties)). | |
| `bluesam.openWarmUp` | boolean | false | Specifies whether to cache any bluesam datasets during open. **Warning: Breaking Change in version 5.1.0** **- Default value changed from `true` to `false`.** | 5.1.0 |
| `bluesam.fileList` | string[] | | Specifies the list of bluesam dataset to be cached during open. **Note:****- This parameter is only effective when `bluesam.openWarmUp` is set to `false`.** | 5.1.0 |
| `bluesam.maxBluesamDisablingThreadpoolSize` | number | 10 | Specifies maximum threadpool size used to disable bluesam datasets for batch processing. | 4.5.0 |
| `bluesam.bluesamStatusPollingInterval` | number | 1000 | Specifies time (in millisecond) to wait between each iteration when polling bluesam status to check online activities. | 4.5.0 |
| `bluesam.maxBluesamStatusPollingRetry` | number | 3 | Specifies maximum number of retries when polling bluesam status is failing. | 4.5.0 |
| `bluesam.checkBluesamStatus` | boolean | false | Specifies whether or not to check bluesam dataset status before accessing it. | 4.5.0 |
| `bluesam.prefetchWindowSize` | int | 1000 | Specifies the number of records to prefetch and cache in memory for Redis cache optimization. This property is only effective when using Redis cache. | |
| `bluesam.prefetchWindowMultiples` | int | 5 | Specifies the multiplier for prefetch window size to determine maximum prefetch window capacity. The maximum capacity is calculated as `prefetchWindowSize × prefetchWindowMultiples`. This property is only effective when using Redis cache. | |
| `bluesam.sizesCleanUpThreshold` | int | 1000 | Maximum number of entries retained in the internal offset-tracking map per data set for large data sets (LargeKSDS, LargeESDS) during concurrent multi-threaded writes. When the map exceeds this threshold, it is trimmed to the 10 most recent entries to prevent heap exhaustion while preserving enough entries to avoid NullPointerException from concurrent thread access. Reduce this value if heap pressure is observed during high-volume large dataset bulk loads. | |
| `spring.aws.client.bluesam.redis.secret` | string | null | Specifies the credential secret ARN for Bluesam Redis cache, see [AWS Transform for mainframe Runtime secrets](ba-runtime-config-app-secrets.md). | |
| `spring.aws.client.bluesam.locks.redis.secret` | string | null | Specifies the credential secret ARN for Bluesam locks Redis cache, see [AWS Transform for mainframe Runtime secrets](ba-runtime-config-app-secrets.md). | |
| `forcedDate` | string | | Forces the date to the date provided if there is one. | |
| `clcommand.rtvmbrd.hasHeader` | string | true | Specify if the files contain headers that should not be included when counting the rows. | |
| `frozenDate` | boolean | true | Specifies whether to freeze the date. Applies only if`forcedDate` is also set. | |
| `externalSort.threshold` | datasize (example: 12 MB) | | The sort threshold: determines when the system should switch from in-memory to external merge sorting using temporary files on the file system. If not specified (default=`null`), the threshold is set to half of the available memory at each new sort task. To estimate the available memory, a call to System.gc() is performed. | |
| `blockSizeDefault` | number | 32760 | The default block size to be used for BDW bytes. | |
| `jics.parameters.datform` | string | MMDDYY | The date form. | |
| `jics.initList` | string | | The initialize JICS list, separated by commas. If present, it defines comma-separated names of lists to activate at Apache Tomcat startup among CICS lists. Example value: `$UUU,DFH$IVPL,PEZ1`. This will cascade to groups contained in those lists and their underlying resource definitions, which will then be visible to the runtime. Empty by default. | |
| `jics.parameters.applid` | string | VELOCITY | The applied to identify application in JICS (at least 4 characters, no max length). | |
| `jics.parameters.sysid` | string | CICS | The system identification (SYSID). | |
| `jics.parameters.eibtrmid` | string | TERM | The terminal identifier (4 characters maximum, 1 minimum). | |
| `jics.parameters.userid` | string | | The user id (8 characters maximum, no minimum). When no value is provided (blank by default) the HTTP session id is used as the user id. | |
| `jics.parameters.username` | string | MYUSERNAME | The username (10 characters maximum, 1 minimum). | |
| `jics.parameters.netname` | string | MYNETNAME | The network name (8 characters maximum, 1 minimum). | |
| `jics.parameters.opid` | string | XXX | The 3-character operator identification. | |
| `jics.parameters.jobname` | string | MJOBNAME | The job name. | |
| `jics.parameters.sysname` | string | SYSNAME | The AS400 system name (sysname). | |
| `jics.parameters.cwa.length` | number | 0 | The length of the common work area (CWA). | |
| `jics.parameters.charset` | string | CP037 | JICS globally used character set. | |
| `jics.parameters.tsqimpl` | string | bluesam | JICS Temporary Storage Queue (TSQ) implementation (allowed values are`bluesam` /`memory` /`redis`) | |
| `jics.queues.ts.redis.*` | Supported Redis properties | | Specifies configuration properties for the JICS TS Queues Redis server, see [Supported Redis properties](ba-runtime-redis-configuration.md#ba-runtime-redis-supported-properties). | |
| `spring.aws.client.jics.queues.ts.redis.secret` | string | null | Specifies the credential secret ARN for JICS TS Queues Redis server, see [AWS Transform for mainframe Runtime secrets](ba-runtime-config-app-secrets.md). | |
| `lockTimeout` | number | 500 | The lock timeout, in milliseconds. | |
| `sqlCodePointShift` | number | | Optional. The sql code point shift. Shifts the codepoint for control characters that we might encounter when migrating legacy RDBMS data to a modern RDBMS. For example, you can specify`384` to match Unicode character`\u0180`. | |
| `sqlIntegerOverflowAllowed` | boolean | false | Specifies whether to allow the SQL integer overflow, meaning whether placing larger values in the host variable is allowed. | |
| `database.cursor.overflow.allowed` | boolean | true | Specifies whether to allow the cursor overflow. Set to`true` to perform a next call on the cursor whatever its position. Set to`false` to check whether the cursor is at the last position before performing a next call on cursor. Only enable if cursor is SCROLLABLE (SENSITIVE or INSENSITIVE). | |
| `reportOutputPath` | string | `/reports` | The report output path. | |
| `server.servlet.session.tracking-modes` | string | cookie | Specifies the session tracking modes to use. Possible values are `url`, `cookie`, `ssl`. Multiple values can be specified separated by commas. Note: When deploying on Tomcat, you need to set `cookies=false` in context.xml because Tomcat takes precedence for tracking mode configuration. | |
| `server.servlet.session.timeout` | string | 30m | Specifies the session timeout duration. Examples: `60s` (60 seconds), `4m` (4 minutes), `4h` (4 hours). | |
| `spring.session.store-type` | string | none | The session cache for high-availability environments. Possible values are`none` or`redis`. Default is`none`. | |
| `stopExecutionWhenProgNotFound` | boolean | true | Specifies whether to stop running if a program isn't found. If set to`true`, interrupts the run if a program is not found. | |
| `forceHR` | boolean | false | Specifies whether to use Human Readable SYSPRINT, either on console or file output. | |
| `rollbackOnRTE` | boolean | false | Specifies whether to rollback implicit run unit transaction on runtime exceptions. | |
| `sctThreadLimit` | long | 5 | The thread limit for triggering scripts. | |
| `dataSimplifier.onInvalidNumericData` | string | reject | How to react when decoding invalid numeric data. Allowed values are`reject` /`toleratespaces` /`toleratespaceslowvalues` /`toleratemost`. Default is`reject`. | |
| `dataSimplifier.numproc` | string | PFD | numproc compiler specification. Allowed values are `PFD`/`NOPFD`/`MIG`/. Default is `PFD`. | |
| `dataSimplifier.doubleFloatingType` | string | IEEE\$1754 | The double floating type is the format used to encode and decode a floating-point number. Allowed values are `IEEE_754` / `HFP`(for Hexadecimal Floating Point format). Default value is `IEEE_754`. | 4.7.0 |
| `filesDirectory` | string | | The directory for batches input/output files. | |
| `ims.messages.extendedSize` | boolean | false | Specifies whether to set the extended size on IMS messages. | |
| `defaultKeepExistingFiles` | boolean | false | Specifies whether to set the dataset default previous value. | |
| `jics.db.ddlScriptLocation` | string | | The Jics DDL script location. Allows you to initiate the Jics database schema using a .sql script. Blank by default. For example,`./jics/sql/jics.sql`. | |
| `jics.db.schemaTestQueryLocation` | string | | Location of the sql file that should contain a unique query that returns the number of objects in the jics schema (if any). | |
| `jics.db.dataScriptLocation` | string | | Defines the path to SQL scripts used for initializing the JICS database. Accepts a comma-separated list of files and directories, allowing for multiple scripts and folders to be specified. | |
| `jics.db.dataTestQueryLocation` | string | | Location of a sql script containing a single sql query that is expected to return a count of objects (for example: counting number of records in the jics program table). If the count equals 0, database will be loaded using the`jics.db.dataScriptLocation` script, otherwise database load will be skipped. | |
| `jics.data.dataJsonInitLocation` | string | | | |
| `jics.xa.agent.timeout` | number | | | |
| `query.useConcatCondition` | boolean | false | Specifies whether key condition is built by key concatenation or not. | |
| `system.qdecfmt` | string | | | |
| `disposition.checkexistence` | boolean | false | Specifies whether to release a check on file existence for Dataset with DISP SHR or OLD. | |
| `useControlMVariable` | boolean | false | Specifies whether to use control-M specification for variable replacement. | |
| `card.encoding` | string | CP1145 | Card encoding: to be used with`useControlMVariable`. | |
| `mapTransfo.prefixes` | string | &,@,%% | List of prefixes to be used when transforming controlM variables. Each one separated by comma. | |
| `checkinputfilesize` | boolean | false | Specifies whether to release a check if the file size is a multiple of record size. | |
| `stepFailWhenAbend` | boolean | true | Specifies whether to raise an abend if a step fails or completes execution. | |
| `returnHttp5xxResponseForFailedSyncJob` | boolean | false | Specifies whether to return HTTP response code of 500 series for unsuccessful synchronized job execution. | 4.10.0 |
| `bluesam.fileLoading.commitInterval` | number | 100000 | The bluesam commit interval. | |
| `uppercaseUserInput` | boolean | true | Specifies whether user input must be in uppercase. | |
| `jhdb.lterm` | string | | Allow you to force a common logical terminal ID in the case of an IMS emulation. If not set then sessionId is used. | |
| `jhdb.identificationCardData` | string | | Used to hard-code some "operator identification card data" to the MID field designated by the CARD parameter. Blank by default, no input restriction. | |
| `encoding` | string | ASCII | The encoding used in projects (not in groovy files). Expects a valid encoding`CP1047`,`IBM930`,`ASCII`,`UTF-8`... | |
| `cl.configuration.context.encoding` | string | CP297 | The encoding of CL files. Expects a valid encoding`CP1047`,`IBM930`,`ASCII`,`UTF-8`... Default value is`CP297` | |
| `cl.zonedMode` | string | EBCDIC\$1STRICT | The mode for encoding or decoding control language (CL) commands. Allowed values are`EBCDIC_STRICT` /`EBCDIC_MODIFIED` /`AS400`. | |
| `ims.programs` | string | | List of IMS programs to use. Separate each parameter with a semicolon (`;`) and each transaction with a comma (`,`). For example:`PCP008,PCT008;PCP054,PCT054;PCP066,PCT066;PCP068,PCT068;` | |
| `jhdb.configuration.context.encoding` | string | CP297 | The JHDB (Java Hierarchical Database) encoding. Expects a valid encoding string`CP1047`,`IBM930`,`ASCII`,`UTF-8`... | |
| `jhdb.metadata.extrapath` | string | file:./setup/ | A configuration parameter that specifies an extra, runtime-specific root folder for psbs and dbds folders. | |
| `jhdb.checkpointPersistence` | string | none | The checkpoint persistence mode. Allowed values are`none` /`add` /`end`. Use`add` to persist checkpoints when a new one is created and added to the registry. Use`end` too persist checkpoint at server shutdown. Any other values disable the persistence. Note that each time a new checkpoint is added to the registry, all the existing checkpoints will be serialized and the file will be erased. It is not an append to the existing data in the file. So depending on the number of checkpoints, it can have some effects on performances. | |
| `jhdb.checkpointPath` | string | file:./setup/ | If`jhdb.checkpointPersistence` is not`none` then this parameter allows you to setup the checkpoint persistence path (checkpoint.dat file storage location), all the checkpoints data contained in the registry are serialized and backed up in a file (checkpoint.dat) located in provided folder. Note that only checkpoint data (scriptId, stepId, database position and checkpoint area) are concerned by this backup. | |
| `jhdb.navigation.cachenexts` | number | 5000 | The cache duration (in milliseconds) used in hierarchical navigation for an RDBMS. | |
| `jhdb.use-db-prefix` | boolean | true | Specifies whether to enable a database prefix in hierarchical navigation for an RDBMS. | |
| `jhdb.query.limitJoinUsage` | boolean | true | Specifies whether to use the limit join usage parameter on RDBMS graphs. | |
| `taskExecutor.corePoolSize` | number | 5 | When a transaction in a terminal is initiated via a groovy script, a new thread is created. Use this parameter to setup the core pool size. | |
| `taskExecutor.maxPoolSize` | number | 10 | When a transaction in a terminal is initiated via a groovy script, a new thread is created. Use this parameter to setup the max pool size (max number of parallel threads). | |
| `taskExecutor.queueCapacity` | number | 50 | When a transaction in a terminal is initiated via a groovy script, a new thread is created. Use this parameter to setup the queue size. (= maximum number of pending transactions when`taskExecutor.maxPoolSize` is reached) | |
| `taskExecutor.allowCoreThreadTimeOut` | boolean | false | Specifies whether to allow core threads to time out in JCIS. This enables dynamic growing and shrinking even in combination with a non-zero queue (since the max pool size will only grow once the queue is full). | |
| `jics.runUnitLauncherPool.enable` | boolean | false | Specifies whether to activate the run unit launcher pool in JICS. | |
| `jics.runUnitLauncherPool.size` | number | 20 | The run unit launcher pool size in JICS. | |
| `jics.runUnitLauncherPool.validationInterval` | number | 1000 | The interval between each run of the task that adjusts the size of the pool. | |
| `jics.runUnitLauncherPool.parallelism` | number | 2 | The number of threads used to produce the missing instances in the queue when the adjustment task runs. | |
| `context.preconstruct.enable` | boolean | false | Specifies whether to activate pre construction of program context. | |
| `context.preconstruct.frequencyInMillis` | number | 100 | The interval between each run of the task that adjusts the size of the pool. | |
| `context.preconstruct.parallelism` | number | 5 | The number of threads used to produce the missing instances in the queue when the adjustment task runs. | |
| `context.preconstruct.minInstances` | number | 2 | The number of instances that will be created the first time a context is needed. | |
| `spring.aws.application.credentials` | string | null | Load the AWS credentials from the credential profiles file in JICS. | |
| `jics.queues.sqs.region` | string | eu-west-1 | The AWS Region for Amazon Simple Queue Service, used in JICS. | |
| `jics.jcl.rt.encoding` | string | CP037 | The encoding of the JCL scripts written in the dedicated JICS queue. | |
| `jics.jcl.rt.queue` | string | JICS | The name of the queue to which JCL scripts can be written line by line at runtime. | |
| `mq.queues.sqs.region` | string | eu-west-3 | The AWS Region for the AWS SQS MQ service. | |
| `quartz.scheduler.stand-by-if-error` | boolean | false | Specifies whether to trigger job execution if the job scheduler is in standby mode. If true, When enabled job execution is not triggered. | |
| `databaseStatistics` | boolean | false | Specifies whether to allow SQL builders to collect and display statistics information. | |
| `dbDateFormat` | string | yyyy-MM-dd | The db target date format. | |
| `dbTimeFormat` | string | HH:mm:ss | The db target time format. | |
| `dbTimestampFormat` | string | yyyy-MM-dd HH:mm:ss.SSSSSS | The db target timestamp format. | |
| `dateTimeFormat` | string | ISO | The dateTimeFormat describes how to spill database date time timestamp type into data simplifier entities. Allowed values are`ISO` /`EUR` /`EUR` /`USA` /`LOCAL` | |
| `localDateFormat` | string | | List of local date formats.Separate each format with`\`. | |
| `localTimeFormat` | string | | List of local time formats. Separate each format with`\` | |
| `localTimestampFormat` | string | | List of local timestamp formats. Separate each format with`\`. | |
| `pgmDateFormat` | string | yyyy-MM-dd | The date time format. | |
| `pgmTimeFormat` | string | HH.mm.ss | The time format used for pgm (programs) execution. | |
| `pgmTimestampFormat` | string | yyyy-MM-dd-HH.mm.ss.SSSSSS | The timestamp format. | |
| `cacheMetadata` | boolean | true | Specifies whether to cache database metadata. | |
| `forceDisableSQLTrimStringType` | boolean | false | Specifies whether to disable trim of all sql string parameters. | |
| `fetchSize` | number | | The fetchSize value for cursors. Use when fetching data using chunks by load/unload utils. | |
| `check-groovy-file` | boolean | true | Specifies whether to check groovy files content before registering. | |
| `qtemp.uuid.length` | number | 9 | The QTEMP unique id length. | |
| `qtemp.dblog` | boolean | false | Whether to enable QTEMP Database logging. | |
| `qtemp.cleanup.threshold.hours` | number | 0 | To specify when`qtemp.dblog` is enabled. The db partition lifetime (in hours). | |
| `invalidDataTolerence` | boolean | true | Specifies whether invalid data is tolerated for packed type. | |
| `program.timeout` | number | -1 | Specifies a timeout for any program/transaction execution in seconds. After this time, the system will try to interrupt the program. | |
| `gapwalk.line.separator` | string | null | Specifies line separator type in gapwalk. The allowed values are WIN (CRLF) / UNIX (LF) / LINUX (LF). Other values are ignored and System line.sepatator property is used. | |
| `enableActivePgmIdCache` | boolean | false | Specifies whether to enable active program ID local cache. Use carefully this feature because JICS resources can be shared amongst programs and users. Those resources can be changed externally by any administrators and the local cache put in place might be invalidated. | |
| `mq.queues.default.syncpoint` | boolean | false | Specifies the default behavior for MQ PUT commands when neither MQPMO\$1SYNCPOINT nor MQPMO\$1NO\$1SYNCPOINT are set. When set to true, it acts as `MQPMO_SYNCPOINT` and messages are NOT directly committed during the PUT command. When set to false, it acts as `MQPMO_NO_SYNCPOINT` and messages are directly committed during the PUT command. | |
| `dataSimplifier.byteRangeBoundsCheck` | boolean | false | When set to true, it ensures that no ByteRange is created with improper values. The default is false. | |
| `file.stdoutIntoLogger` | boolean | false | Specifies whether to enable writing to logger instead of the default system output stream in the default `SYSPRINT` and `SYSPUNCH` files. | |
| `tempFilesDirectory` | string | null | Specifies the name of the folder location of the temporary files that are generated. | |
| `cleanTempFilesDirectoryAtStartup` | boolean | true | Specifies whether to purge the contents of the temporary files folder at application startup. | |
| `tempFolderPattern` | string | null | Specifies a pattern that will be used to dynamically build the name of the temporary folder based on the following predefined and customizable information. HOST: the host name. JOBID: the ID of the job. HASHCODE: the hash code of the job context. TIMESTAMP: the pattern to use when getting the timestamp. Target name of the temporary folder is TMP\$1DIR\$1\$1tempFolderPattern\$1. For example, in the case of the following pattern, the name will start with the job ID and end with the “timestamp”: tempFolderPattern: JOBID,HOST=xxxxx,HASHCODE,TIMESTAMP=yyyymmddhhmmss. If the property `tempFolderPattern` is not added to the YAML file or is empty, the name of the temporary folder will be "TMP\$1DIR\$1" \$1 this.hashCode() (DefaultJobContext). | |
| `database.cursor.raise.already.opened.error` | boolean | false | Specifies whether to enable raising SQLCODE error 502 when an already opened cursor is opening. | |
| `jics.spool.smtp.hostname` | string | null | Specifies the SMTP server host. Example: `smtp.xxx.com` | |
| `jics.spool.smtp.port` | string | null | Specifies the SMTP server port. Example: 25 | |
| `jics.spool.smtp.password` | string | null | Specifies the login password of the SMTP server. | |
| `jics.spool.smtp.username` | string | null | Specifies the username of the SMTP server. | |
| `jics.spool.smtp.debug` | boolean | false | Specifies the debug mode for the SMTP server. | |
| `gapwalk-application.security` | string | `disabled` | Toggle global security configuration (XSS, CORS, CSRF, OAUTH authentication...). Allowed values are `disabled` and `enabled`. | |
| `gapwalk-application.security.identity` | string | null | Global authentication method. Recommended value is `oauth`. Allowed values are `json` and `oauth`. This option is required when `gapwalk-application.security` is `enabled`. | |
| `gapwalk-application.security.issuerUri` | string | null | The issuer URI of the identity provider (IdP). This option is required when `gapwalk-application.identity` is `oauth`. | |
| `gapwalk-application.security.allowedOrigins` | string[] | `null` | The list of origins to allow. This option requires `gapwalk-application.identity` to be set to `oauth`. | |
| `gdgDirectoryPath` | string | `output/gdg` | GDG directory path is the directory where the gdg files are stored. | 4.6.0 |
| `gapwalk-application.security.customAllowedHeaders` | string[] | null | The list of custom headers to allow. This option requires `gapwalk-application.identity` to be set to `oauth`. | 4.8.0 |
| `listOfMDCUrlParams` | string | `null` | The list of URL parameters to add to the MDC when executing Groovy batch script. | |
| `gapwalk-application.security.claimGroupName` | string | `cognito:groups` | The claim attribute that contains the list of all the groups a user belongs to. Use `cognito:groups` for Amazon Cognito, or any other string for a foreign IdP. | |
| `gapwalk-application.security.userAttributeName` | string | `username` | The claim attribute name used to identify a user request. Use `username` for Amazon Cognito, `preferred_username` for Keycloak, or any other string for a foreign IdP. | |
| `gapwalk-application.defaultSuperAdminUserName` | string | `sadmin` | When `gapwalk-application.security` is disabled, specifies the default local super user name. | |
| `gapwalk-application.defaultSuperAdminUserPwd` | string | `sadmin` | When `gapwalk-application.security` is disabled, specifies the default local super user password. | |
| `gapwalk-application.security.filterURIs` | string | `disabled` | Toggle filtering URIs configuration. Allowed values are `disabled` and `enabled`. | |
| `gapwalk-application.security.blockedURIs` | string[] | null | The list of URIs to block. This option is required when `gapwalk-application.security.filterURIs` is `enabled`. | |
| `jics.redis.*` | Supported Redis properties | | Specifies configuration properties for the JICS Redis server connection factory, see [Supported Redis properties](ba-runtime-redis-configuration.md#ba-runtime-redis-supported-properties). | |
| `spring.aws.client.jics.redis.secret` | string | null | Specifies the credential secret ARN for JICS Redis server connection factory, see [AWS Transform for mainframe Runtime secrets](ba-runtime-config-app-secrets.md). | |
| `jcl.checkpoint.enabled` | boolean | false | Specifies if JCL checkpoint mechanism is enabled to allow job restart. JCL checkpoints are created and saved to the in-memory registry at the start of each step or main program invocation. All the step level checkpoints are persisted at the end of the job, if persistence provider is defined. | |
| `jcl.checkpoint.expireTimeout` | number | -1 | Specifies time duration to retain JCL checkpoints in the persistence provider or in-memory registry. | |
| `jcl.checkpoint.expireTimeoutUnit` | string | SECONDS | Specifies time duration unit for the `jcl.checkpoint.expireTimeout` property. Supported enum constant values: java.util.concurrent.TimeUnit. | |
| `jcl.checkpoint.provider` | string | null | Specifies JCL checkpoint mechanism persistence provider. Allowed values are `redis`. | |
| `jcl.checkpoint.redis.*` | Supported Redis properties | | Specifies configuration properties for JCL checkpoint mechanism's REDIS persistence provider, see [Supported Redis properties](ba-runtime-redis-configuration.md#ba-runtime-redis-supported-properties). | |
| `jcl.nullJclEof` | boolean | true | Specifies how null JCL statements (//) are handled during job execution. When true, // terminates the job immediately (EOF mode). When false, // is treated as a null statement and execution continues (IGNORE mode). | |
| `job.default.encoding` | string | CP1047 | Specifies the default encoding which is used to initialize the job level storage. For example, switches in BLU4IV application uses this encoding to initialize to zeroes. | 4.9.0 |
| `spring.aws.client.jcl.checkpoint.redis.secret` | string | null | Specifies the credential secret ARN for JCL checkpoint mechanism's Redis persistence provider, see [AWS Transform for mainframe Runtime secrets](ba-runtime-config-app-secrets.md). | |
| `gapwalk.ssl.enabled` | boolean | false | Indicated to set the following `gapwalk.ssl.*` properties to the current JVM system properties if there are not already set at application start. | |
| `gapwalk.ssl.trustStore` | string | null | Set the value to the system property `javax.net.ssl.trustStore` if not already set at application start. | |
| `gapwalk.ssl.trustStorePassword` | string | null | Set the value to the system property `javax.net.ssl.trustStorePassword` if not already setup at application start. Alternately, use of AWS secrets is strongly encouraged, as explained in [Secret manager for SSL password settings](ba-runtime-config-app-secrets.md#ba-runtime-ssl-secrets-properties). | |
| `gapwalk.ssl.trustStoreType` | string | null | Set the value to the system property `javax.net.ssl.trustStoreType` if not already setup at application start. | |
| `gapwalk.ssl.keyStore` | string | null | Set the value to the system property `javax.net.ssl.keyStore` if not already setup at application start. | |
| `gapwalk.ssl.keyStorePassword` | string | null | Set the value to the system property `javax.net.ssl.keyStorePassword` if not already setup at application start. Alternately, use of AWS secrets is strongly encouraged, as explained in [Secret manager for SSL password settings](ba-runtime-config-app-secrets.md#ba-runtime-ssl-secrets-properties). | |
| `mq.queues` | string | `sqs` | Specifies which supported queue brocker to use among `sqs` using Amazon SQS, `rabbitmq` using on-prem Rabbit MQ or `jms` using on-prem IBMMQ. | |
| `mq.queues.jmsMQQueueManagers[N]` | | | When `mq.queues` is `jms`, enables to specify an IBM MQ connection list. `mq.queues.jmsMQQueueManagers[0]` for the first connection, `mq.queues.jmsMQQueueManagers[1]` for the second and so on. | |
| `mq.queues.jmsMQQueueManagers[N].jmsMQQueueManager` | string | null | The IBMMQ queue manager name. | |
| `mq.queues.jmsMQQueueManagers[N].jmsMQAppName` | string | null | The IBMMQ application name. | |
| `mq.queues.jmsMQQueueManagers[N].jmsMQChannel` | string | null | The IBMMQ channel name. | |
| `mq.queues.jmsMQQueueManagers[N].jmsMQHost` | string | null | The IBMMQ hostname. | |
| `mq.queues.jmsMQQueueManagers[N].jmsMQPort` | number | null | The IBMMQ port. | |
| `mq.queues.jmsMQQueueManagers[N].jmsMQUserid` | string | null | The IBMMQ user name. | |
| `mq.queues.jmsMQQueueManagers[N].jmsMQPassword` | string | null | The IBMMQ user password. Alternately, use of AWS secrets is strongly encouraged, as explained in [Secret manager for IBM MQ password settings](ba-runtime-config-app-secrets.md#ba-runtime-IBMMQ-secrets-properties). | |
| `mq.queues.jmsMQQueueManagers[N].jmsMQMaxPoolSize` | number | 0 | The IBMMQ maximum pool size . With 0, an infinite number of physical connections are enabled. | |
| `mq.queues.jmsMQQueueManagers[N].jmsMQSSLCipher` | string | null | The IBMMQ SSL cipher suite. An example could be `"*TLS12ORHIGHER"`. Refer to the official documentation [TLS CipherSpecs and CipherSuites in IBM MQ classes for JMS](https://www.ibm.com/docs/en/ibm-mq/9.2?topic=jms-tls-cipherspecs-ciphersuites-in-mq-classes) for more details. | |
| `mq.queues.non.jms.client` | boolean | false | Indicate whether target client for sending messages to is non-JMS. Native MQ format will be used for non-JMS client while RFH2 format will be used for JMS. | 4.5.0 |
| `mq.connection.pool.share` | boolean | false | Indicate whether to share or recreate the JMS connection pool with the same Queue Manager. | 4.9.0 |
| `mq.queues.rabbitMQHost` | string | null | The Rabbit MQ hostname. | |
| `mq.queues.rabbitMQVirtualHost` | string | null | The Rabbit MQ virtual hostname. | |
| `mq.queues.rabbitMQPort` | number | null | The Rabbit MQ port. | |
| `mq.queues.rabbitMQUsername` | string | null | The Rabbit MQ user. | |
| `mq.queues.rabbitMQPassword` | string | null | The Rabbit MQ password. | |
| `mf.runtime.switch.N` | boolean | true | Enables null insertion for MF nature line-sequential files. | 4.4.0 |
| `mf.runtime.switch.T` | boolean | false | Enables insertion of tab characters in MF nature line-sequential files. | 4.4.0 |
| `gapwalk.database.support.useSavePointToRestoreFail` | boolean | false | Enables transaction recovery in case of failure by using savepoints on insert queries. Enabling this property may impact database performance. You can override this setting for specific queries using the query-to-database mapping configuration. | 4.6.0 |
| `xmlGeneratorPrettyFormat` | boolean | true | Determines the formatting style of the generated XML output within the XmlGenerator class. When set to `true`, the XML output is formatted in a human-readable, indented structure (pretty-printed). When set to `false`, the output is in a compact, single-line format without additional whitespace. | 4.8.0 |
| `gapwalk.database.metadata.schema-inclusion.enabled` | boolean | false | Enables a memory optimization feature that control which database schemas are cached by a application. This configuration helps reduce memory footprint while maintaining system stability by intelligently managing schema metadata. It automatically includes some common database system schemas which maybe required for proper operation. | 4.9.0 |
| `gapwalk.database.metadata.schema-inclusion.schemas.global` | list | null | Defines a list of schemas that should be cached. | 4.9.0 |
| `sqlConnectionAutoCommitEnabled` | boolean | true | Enables automatic commit of current connection during connection reset operations. When enabled, automatically commits the current connection before switching to a new datasource connection in non-XA environments to prevent connection instability. When disabled, logs a warning message about potential connection issues during reset operations. | 4.10.0 |
| `gapwalk.post.script.mediatype.json` | boolean | false | Specifies whether the `Content-Type` header of the response from endpoint `/post/script/{scriptId:.+}` is set to `application/json`, depending on the value of a boolean variable. If set to false, the default is `text/plain; charset=utf-8`. | |
| `startDefaultJob` | string | `false` | Specify whether to initialize default job at first transaction. | |
| `gapwalk.cobol.cblqda.enabled` | boolean | false | Enables a CBLQDA feature that controls QSAM files' dynamic allocation during an OPEN statement. This configuration helps to dynamically allocate temporary files declared in the program, even if the files are not defined in the JCL script. | |
| `mq.queues.jms.connectionfactory.*` | Supported Atomikos connection factory properties | | Specifies configuration properties for the JMS MQ connection pool. | |
## Available properties for optional web applications
Depending on your modernized application, you might need to configure one or more optional web applications that represent support for dependencies such as z/OS, AS/400, or IMS/MFS. The following tables contain lists of the available key/value parameters for configuring each optional web application.
### gapwalk-utility-pgm.war
This optional web application contains support for Z/OS utility programs.
This table provides an exhaustive view of key/values parameters for this application.
| Key | Type | Default value | Description | Release version |
| --- | --- | --- | --- | --- |
| `logging.config` | Path | classpath:logback-utility.xml | Standard key for the reference to the logback configuration file. Other standard logging keys are available too. | |
| `spring.jta.enabled` | boolean | false | Standard key. If the datasource support mode is not static-xa, spring JTA transactions auto configuration must be disabled. | |
| `spring.datasource.primary.jndi-name` | string | jdbc/primary | The JNDI name (Java Naming And Directory Interface) for the primary datasource, if using JNDI. | |
| `primary.datasource` -`driver-class-name` -`url` -`username` -`password` | Standard spring datasource with subkeys | | Contains the connection information for the application database, if not using JNDI. Must have the same configuration as in the modernized application YAML file. Alternately, use of AWS secrets is strongly encouraged, as explained in [Client database](ba-runtime-config-app-secrets.md#client-database). | |
| `encoding` | string | ASCII | The encoding used in utility programs. Expects a valid encoding `CP1047`,`IBM930`,`ASCII`,`UTF-8`. | |
| `sysPunchEncoding` | string | ASCII | The syspunch encoding character set. Expects a valid encoding`CP1047`,`IBM930`,`ASCII`,`UTF-8`. | |
| `systin.encoding` | string | ASCII | The encoding character set of SYSTIN file dataset. Expects a valid encoding`CP1047`,`IBM930`,`ASCII`,`UTF-8`. | 4.5.0 |
| `zonedMode` | string | EBCDIC\$1STRICT | The mode for encoding or decoding zoned data types. Allowed values are`EBCDIC_STRICT` /`EBCDIC_MODIFIED` /`AS400`. | |
| `idcams.encoding.forced` | string | | The encoding used in IDCAMS utility program. Expects a valid encoding `CP1047`, `IBM930`, `ASCII`, `UTF-8`. | 4.4.0 |
| `unload.chunkSize` | number | 0 | Chunk size used for unload utility. | |
| `unload.computeRecordSizeIfNull` | boolean | false | Determines whether to compute the record size if not specified. If specified, the value remains unchanged. | |
| `unload.sqlCodePointShift` | number | 0 | The SQL code pointshift for unload utility. Runs the shifting characters process. Required when your target database from DB2 is Postgresql. | |
| `unload.columnFiller` | string | space | The unload utility column filler. | |
| `unload.varCharIsNull` | boolean | false | Use this parameter in INFTILB program, if set to`true` then all not nullable fields with blank (space) values returns an empty string. | |
| `unload.useDatabaseConfiguration` | boolean | false | Specifies whether to use the date or time configuration from application-main.yml in unload utility. | |
| `unload.format.date` | string | MM/dd/yyyy | If`unload.useDatabaseConfiguration` is enabled, the date format to use in the unload utility. | |
| `unload.format.time` | string | HH.mm.ss | If`unload.useDatabaseConfiguration` is enabled, the time format to use in the unload utility. | |
| `unload.format.timestamp` | string | yyyy-MM-dd-HH.mm.ss.SSSSSS | If`unload.useDatabaseConfiguration` is enabled, the timestamp format to use in the unload utility. | |
| `unload.nbi.whenNull` | hexadecimal | 6F | The Null Byte Indicator (NBI) value to add when value from database is null. | |
| `unload.nbi.whenNotNull` | hexadecimal | 00 | The Null Byte Indicator (NBI) value to add when value from database is not null. | |
| `unload.nbi.writeNullIndicator` | boolean | false | Specifies whether to write out the null indicator in the unload output file. | |
| `unload.bmc.useInto` | boolean | false | Specifies whether to handle INTO bmc control keyword for unload utility. | |
| `unload.fetchSize` | number | 0 | Allows you to tune the fetch size when handling cursors in the unload utility. | |
| `unload.noPad` | boolean | true | Indicates that variable-length character (VARCHAR) fields are to be unloaded without any padding to the maximum length. | 4.5.0 |
| `treatLargeNumberAsInteger` | boolean | false | Specifies whether to treat large numbers as`Integer`. They are treated as`BigDecimal` by default. | |
| `load.batchSize` | number | 0 | The load utility batch size. | |
| `load.format.localDate` | string | dd.MM.yyyy\$1dd/MM/yyyy\$1yyyy-MM-dd | The load utility local date format to use. | |
| `load.format.localTime` | string | HH:mm:ss\$1HH.mm.ss | The load utility local time format to use. | |
| `load.format.dbDate` | string | yyyy-MM-dd | The load utility database format to use. | |
| `load.format.dbTime` | string | HH:mm:ss | The load utility database time to use. | |
| `load.sqlCodePointShift` | number | 0s | The SQL code pointshift for load utility. Runs the shifting characters process. Required when your target database from DB2 is Postgresql. | |
| `load.applyRollback` | boolean | false | Set this parameter to `true` to indicate that you want the service to roll back table changes if it encounters an error while loading data into the database. | |
| `forcedDate` | string | | Forces the date to the date provided if there is one. | |
| `frozenDate` | boolean | true | Specifies whether to freeze the date. Applies only if`forcedDate` is also set. | |
| `jcl.type` | string | mvs | .jcl file type. Allowed values are`jcl` /`vse`. The IDCAMS utility PRINT/REPRO commands return 4 if the file is empty for non-vse jcl. | |
| `hasGraphic` | boolean | false | Whether the INFUTILB utility needs to handle GRAPHIC DB2 columns. | |
| `convertGraphicDataToFullWidth` | boolean | true | Specifies whether to convert graphic data to full-width format. | |
### gapwalk-cl-command.war
This optional web application contains support for AS/400 utility programs.
This table provides an exhaustive view of key/values parameters for this application.
| Key | Type | Default value | Description |
| --- | --- | --- | --- |
| `logging.config` | Path | classpath:logback-utility.xml | Standard key for the reference to the logback configuration file. Other standard logging keys are available too. |
| `spring.jta.enabled` | boolean | false | Standard key. If the datasource support mode is not static-xa, spring JTA transactions auto configuration must be disabled. |
| `spring.datasource.primary.jndi-name` | string | jdbc/primary | The JNDI name (Java Naming And Directory Interface) for the primary datasource, if using JNDI. |
| `primary.datasource` \$1 -`driver-class-name` \$1 -`url` \$1 -`username` \$1 -`password` | Standard spring datasource with subkeys | | Contains the connection information for the application database, if not using JNDI. Must have the same configuration as in the modernized application YAML file. Alternately, use of AWS secrets is strongly encouraged, as explained in [Client database](ba-runtime-config-app-secrets.md#client-database). |
| `encoding` | string | ASCII | The encoding used in utility programs. Expects a valid encoding`CP1047`,`IBM930`,`ASCII`,`UTF-8`... |
| `zonedMode` | string | EBCDIC\$1STRICT | The mode for encoding or decoding zoned data types. Allowed values are`EBCDIC_STRICT` /`EBCDIC_MODIFIED` /`AS400`. |
| `commands-off` | string | | List of commands to turn off, separated by comma. Allowed values are`PGM_BASIC`,`RCVMSG`,`SNDRCVF`,`CHGVAR`,`QCLRDTAQ`,`RTVJOBA`,`ADDLFM`,`ADDPFM`,`RCVF`,`OVRDBF`,`DLTOVR`,`CPYF`,`SNDDTAQ`. Useful when you want to disable or overwrite an existing program. `PGM_BASIC` is a specific AWS Transform for mainframe Runtime program designed for debugging purposes. |
| `forcedDate` | string | | Forces the date to the date provided if there is one. |
### gapwalk-hierarchical-support.war
This optional web application contains IMS/MFS transaction support.
This table provides an exhaustive view of key/values parameters for this application.
| Key | Type | Default value | Description |
| --- | --- | --- | --- |
| `logging.config` | Path | classpath:logback-utility.xml | Standard key for the reference to the logback configuration file. Other standard logging keys are available too. |
| `spring.jta.enabled` | boolean | false | Standard key. If the datasource support mode is not static-xa, spring JTA transactions auto configuration must be disabled. |
| `jhdb.configuration.context.encoding` | string | | The JHDB (Java Hierarchical Database) encoding. Expects a valid encoding string`CP1047`,`IBM930`,`ASCII`,`UTF-8`... |
| `jhdb.checkpointPersistence` | string | none | The checkpoint persistence mode. Allowed values are`none` /`add` /`end`. Use`add` to persist checkpoints when a new one is created and added to the registry. Use`end` too persist checkpoint at server shutdown. Any other values disable the persistence. Note that each time a new checkpoint is added to the registry, all the existing checkpoints will be serialized and the file will be erased. It is not an append to the existing data in the file. So depending on the number of checkpoints, it can have some effects on performances. |
| `jhdb.keepParent` | boolean | false | Whether to keep \$1parent and \$1logicalparent during IMS insertion. When set to true the IMS ISRT call will insert \$1parent and \$1logicalparent into database columns. |
| `jhdb.query.timeout` | int | -1 | Specifies a timeout for any jhdb transaction execution in seconds. After this time, the system will try to interrupt the program. No timeout is set if the value is -1 (default). |
| `jhdb.backend` | string | | Jhdb backend type. Expected value is `rdbms` |
| `jhdb.transaction.scope.programs` | string | | list of programs to be declared as a whole transaction. Separate each program with a comma (`,`). For example:`PCP008,PCT008` |
| `metadata.datasource` \$1 -`driver-class-name` \$1 -`url` \$1 -`username` \$1 -`password` \$1 -`type` | string | Standard spring datasource with subkeys | Contains the metadata information for the jhdb database, including psbs, dbds, connections. Alternately, use of AWS secrets is strongly encouraged. |
## Available properties for the client application
Your modernized application may require specific property configurations for the client Spring application. These properties initialize beans from classes packaged in runtime JAR files. The `application-profile.yaml` file, where the profile value is set during application generation, allows you to configure these properties. The following table lists the key/value parameters available for configuring the client web application that uses beans from classes packaged in the Gapwalk runtime
| Key | Type | Default value | Description | Release version |
| --- | --- | --- | --- | --- |
| `blu4iv.dtaara.library.disable` | boolean | false | Controls the usage of library in the context of data area operations. If set to true, library usage is disabled for data area operations, but this does not affect the usage of QTemp. If set to false, library is considered when performing CRUD operations for data area. | 4.5.0 |
| `blu4iv.dao.data.max` | number | 10 | The size of the internal cache for input DAO operations. This cache exists at the program level (single instance). | 4.9.0 |
| `blu4iv.dao.sort.function` | string | | The sort function name for the blu4iv database. | 4.9.0 |
| `blu4iv.dao.support` | string | JPA | Specifies the data access implementation to use (JPA or JDBC). | 4.9.0 |
| `blu4iv.dao.cache.enabled` | boolean | false | Enable the In-memory cache. | 4.8.0 |
| `blu4iv.dao.cache.enabledHits` | boolean | false | Add the tracking of number of requests to the cache. | 4.8.0 |
| `blu4iv.dao.cache.initMaxResults` | number | 10000 | The size of the cache. | 4.8.0 |
| `blu4iv.dao.cache.entries.fileIds` | string | | The list of database tables to be cached. | 4.8.0 |
| `blu4iv.dao.cache.entries.programIds` | string | | The program's identifiers where the cache should be activated for the specified tables. The cache is available for all sub-programs in the execution stacks. | 4.8.0 |
| `blu4iv.librarylist.enabled` | boolean | false | Enable the use of the library list to resolve a file library. | 4.10.0 |
| `blu4iv.librarylist.libraries` | string | | The initial list of libraries ordered from left to right. | 4.10.0 |
### Configure the In-Memory cache for AS400 applications
The in-memory cache feature enables users to cache read-only data within memory, significantly improving performance for data-intensive programs. The cache system optimizes performance in three ways: loading data only on first access, creating data access maps on demand, and storing cached data efficiently near program memory. This design minimizes memory overhead while maximizing speed improvements.
```
###################################################################
# Cache configuration for read operations called from DAO classes #
###################################################################
blu4iv:
dao:
cache:
enabled: true
enabledHits: true
initMaxResults: 100000
entries:
-
fileIds: [${TABLEA}]
programIds: [${PROGRAM1}]
-
fileIds: [${TABLEB},${TABLEC}]
programIds: [${PROGRAM2}]
librarylist:
enabled: true
libraries: ["LIBA","LIBC","LIBE"]
```
## Configure API access logging
The API access logging feature records detailed information about API requests to BAC, JAC, and Gapwalk applications, helping meet security requirements by tracking who accessed what and when.
| Key | Type | Default value | Description | Release version |
| --- | --- | --- | --- | --- |
| `api.logging.enabled` | boolean | false | Enables API access logging for BAC, JAC, and Gapwalk applications. When enabled, logs all API requests with details. | 5.0.0 |
When enabled, user can provide logback file configuration to log API access logs in chosen place using the logger name `api.access`. The logs can include the following MDC fields:
| MDC Field | Description |
| --- | --- |
| `api-date` | The date and time when the API request was made |
| `api-duration` | How long it took to process the API request (milliseconds) |
| `api-host` | The source address that the API request came from |
| `api-context` | Where the API is hosted |
| `api-user` | The username or identifier of the person making the API request |
| `api-sessionid` | A unique identifier for the user's current login session |
| `api-scheme` | The transfer protocol used, for example, HTTP or HTTPS. |
| `api-name` | The endpoint/URI that was accessed |
| `api-retcode` | The status code returned after the API request completed |
| `api-secure` | The security method used to protect the API call (e.g., OAuth2, Token, Anonymous) |
| `api-method` | The type of HTTP request made (e.g., GET, POST, DELETE, ...) |
To configure a dedicated log file for API access logs, add the following to your logback configuration:
```
logs/main/main-api-access.log
true
%date %X{api-scheme} %X{api-host} %X{api-method} %X{api-name} - Return code: %X{api-retcode} - Start date: %X{api-date} - Duration: %X{api-duration} ms - User: %X{api-user} - SessionId: %X{api-sessionid} - SecureMethod: %X{api-secure} %n
```
Sample log output:
```
2025-06-13 22:24:36,174 http 127.0.0.1 GET /bac/api/services/rest/bluesamservice/listDataSet - Return code: 200 - Start date: 06-13-2025 22:24:35.863+0200 - Duration: 308 ms - User: velocity_admin - SessionId:
1X1X1X1X1X1X1X1X1X1X1X1X1X1X1X1X- SecureMethod: Oauth2
```
# Available Redis cache properties in AWS Transform for mainframe Runtime
You can use this document to learn about the Redis caches in AWS Transform for mainframe Runtime, along with Gapwalk configuration, supported Redis properties and how `application-main.yml` file can reference secret ARN for Redis caches.
## Redis caches in AWS Transform for mainframe Runtime
Redis servers can be used as caches for various features in the AWS Transform for mainframe Gapwalk application, such as:
****
| AWS Transform for mainframe Runtime features that use Redis caching | Description |
| --- | --- |
| Blusam cache | A Redis Blusam cache for reading records efficiently, using a write-behind strategy, to optimize write-intensive workloads encountered on batch payloads. |
| Blusam locks | A cache for distributed locks for datasets and records. |
| Dataset catalog | The catalog dataset cache. |
| Session cache | A Redis cache for HttpSession. The cache stores the username, the state of the dialogue with the Angular frontend, and specific 'dialect' (BMS, MFS, AS400) information. |
| Session tracker | A cache of active sessions with associated username and session-creation-time information. |
| JICS cache | A cache for JICS resource definitions. |
| TS queues | Storage for TS queues. |
| JCL checkpoint | JCL checkpoint cache. |
| Gapwalk file locks | A cache for distributed file locks by job. |
| Blu4iv locks | Storage for Blu4iv record locks. |
## Redis Gapwalk configuration
The global Redis configuration is used if `redis` is specified as the caching mechanism and no Redis configuration is provided for the specific feature. This configuration makes it possible for you to use the same configuration for multiple Redis caches simultaneously.
In the following example the Blusam datasets cache and JICS cache use the `gapwalk.redis` (`redis.server1`) configuration because their cache type is set to `redis`, and no implicit Redis properties are specified under [JICS resource definitions](#ba-runtime-redis-jics-cache) and [JICS resource definitions](#ba-runtime-redis-jics-cache). However, the Blusam locks cache will use a different Redis configuration (`redis.server2`) because its Redis properties are explicitly defined.
```
...
gapwalk:
redis:
hostName: redis.server1
port: 6379
...
bluesam:
# Redis bluesam cache
cache: redis
# Redis locks cache
locks:
cache: redis
hostName: redis.server2
port: 6379
...
# Redis jics cache
jics:
resource-definitions:
store-type: redis
...
```
To enable the global Redis configuration, add the following configuration in `main-application.yml`.
```
gapwalk:
redis:
hostName: localhost
port: 6379
mode: standalone # Optional
username: # Optional
password: "" # Optional
useSsl: false # Optional
database: 0 # Optional
maxTotal: 128 # Optional
maxIdle: 128 # Optional
minIdle: 16 # Optional
testOnBorrow: true # Optional
testOnReturn: true # Optional
testWhileIdle: true # Optional
testOnCreate: true # Optional
minEvictableIdleTimeMillis: 60000 # Optional
timeBetweenEvictionRunsMillis: 30000 # Optional
numTestsPerEvictionRun: -1 # Optional
blockWhenExhausted: true # Optional
nettyThreads: 32 # Optional
subscriptionsPerConnection: 10 # Optional
subscriptionConnectionPoolSize: 100 # Optional
pageSizeInBytes: 8192 # Optional
readTimeout: 2000 # Optional
```
## Supported Redis properties
The following table shows the Redis properties that are supported for global and specific Redis caches on AWS Transform for mainframe Runtime.
****
| Property name | Required? | Description | Values | Default |
| --- | --- | --- | --- | --- |
| mode | No | The Redis running mode. | standalone \$1 cluster | standalone |
| hostname | Yes | The hostname or IP address of the Redis server. | string | null |
| port | Yes | The port number on which the Redis server is listening for connections. | int | null |
| username | No | The username for authentication. | string | null |
| password | No | The password for authentication. | string | empty string |
| useSsl | No | Specifies whether to enable SSL/TLS encryption for the Redis connection. | boolean | false |
| database | No | The Redis database number to use. Redis supports multiple logical databases, and this property specifies which one to use. | int | 0 |
| maxTotal | No | The maximum number of connections allowed in the Redis connection pool. | int | 128 |
| maxIdle | No | The maximum number of idle connections allowed in the Redis connection pool. | int | 128 |
| minIdle | No | The minimum number of idle connections to maintain in the Redis connection pool. | int | 16 |
| testOnBorrow | No | A boolean value indicating whether to validate connections before borrowing them from the pool. | boolean | true |
| testOnReturn | No | A boolean value indicating whether to validate connections before returning them to the pool. | boolean | true |
| testWhileIdle | No | A boolean value indicating whether to validate idle connections in the pool periodically. | boolean | true |
| testOnCreate | No | A boolean value indicating whether to validate connections when they are created. | boolean | true |
| minEvictableIdleTimeMillis | No | The minimum amount of time (in milliseconds) that an idle connection must remain in the pool before it can be evicted. | long | 60000L |
| timeBetweenEvictionRunsMillis | No | The time (in milliseconds) between successive runs of the idle connection evictor thread. | long | 30000L |
| numTestsPerEvictionRun | No | The maximum number of connections to test during each run of the idle connection evictor thread. | int | -1 |
| blockWhenExhausted | No | A boolean value indicating whether to block and wait for a connection to become available when the pool is exhausted. | boolean | true |
| nettyThreads | No | The number of Netty threads to use for handling Redis connections. | int | 32 |
| subscriptionsPerConnection | No | The maximum number of subscriptions allowed per Redis connection. | int | 10 |
| subscriptionConnectionPoolSize | No | The maximum number of connections allowed in the Redis subscription connection pool. | int | 100 |
| pageSizeInBytes | No | The default page size in bytes for Redis operations. | long | 262144000 |
| readTimeout | No | The read timeout in milliseconds for Redis operations. | long | 2000 |
| timeToLiveMillis | No | The duration (in Milliseconds) for which a cache entry remains in the cache before being considered expired and removed. If this property is not specified, cache entries will not automatically expire by default. | long | -1 |
| useAsyncBatch | No | Enables asynchronous execution for Redis bulk write operations to improve performance. When set to false, falls back to synchronous execution mode. | boolean | true |
| useBatchInMemoryAtomic | No | Enables In-memory-atomic mode for Redis batch read operations. When set to false, falls back to default In-memory batch mode. | boolean | false |
| connectionPoolSize | No | The size of the connection pool used for Redisson client connections to Redis server. | int | 64 |
| connectionMinimumIdleSize | No | The minimum number of idle connections that Redisson will maintain in its connection pool. | int | 24 |
| idleConnectionTimeout | No | The timeout in milliseconds after which an idle connection in the pool will be closed. | int | 10000 |
| connectTimeout | No | The timeout in milliseconds for establishing a connection to Redis server. | int | 10000 |
## Redis cache properties
### Redis Blusam cache
```
bluesam:
cache: redis
# If the following redis properties are not specified gapwalk.redis configuration will be used for this cache
redis:
hostName: localhost
port: 6379
mode: standalone # Optional
username: # Optional
password: "" # Optional
useSsl: false # Optional
database: 0 # Optional
maxTotal: 128 # Optional
maxIdle: 128 # Optional
minIdle: 16 # Optional
testOnBorrow: true # Optional
testOnReturn: true # Optional
testWhileIdle: true # Optional
testOnCreate: true # Optional
minEvictableIdleTimeMillis: 60000 # Optional
timeBetweenEvictionRunsMillis: 30000 # Optional
numTestsPerEvictionRun: -1 # Optional
blockWhenExhausted: true # Optional
nettyThreads: 32 # Optional
subscriptionsPerConnection: 10 # Optional
subscriptionConnectionPoolSize: 100 # Optional
pageSizeInBytes: 8192 # Optional
readTimeout: 2000 # Optional
timeToLiveMillis: 60000 # Optional
connectionPoolSize: 64 # Optional
connectionMinimumIdleSize: 24 # Optional
idleConnectionTimeout: 10000 # Optional
connectTimeout: 10000 # Optional
```
### Redis Blusam cache
```
bluesam:
locks:
cache: redis
# If the following redis properties are not specified gapwalk.redis configuration will be used for this cache
hostName: localhost
port: 6379
mode: standalone # Optional
username: # Optional
password: "" # Optional
useSsl: false # Optional
database: 0 # Optional
maxTotal: 128 # Optional
maxIdle: 128 # Optional
minIdle: 16 # Optional
testOnBorrow: true # Optional
testOnReturn: true # Optional
testWhileIdle: true # Optional
testOnCreate: true # Optional
minEvictableIdleTimeMillis: 60000 # Optional
timeBetweenEvictionRunsMillis: 30000 # Optional
numTestsPerEvictionRun: -1 # Optional
blockWhenExhausted: true # Optional
nettyThreads: 32 # Optional
subscriptionsPerConnection: 10 # Optional
subscriptionConnectionPoolSize: 100 # Optional
pageSizeInBytes: 8192 # Optional
readTimeout: 2000 # Optional
```
### Session cache
```
spring:
session:
store-type: redis
# If the following redis properties are not specified gapwalk.redis configuration will be used for this cache
jics:
redis:
hostName: localhost
port: 6379
mode: standalone # Optional
username: # Optional
password: "" # Optional
useSsl: false # Optional
database: 0 # Optional
maxTotal: 128 # Optional
maxIdle: 128 # Optional
minIdle: 16 # Optional
testOnBorrow: true # Optional
testOnReturn: true # Optional
testWhileIdle: true # Optional
testOnCreate: true # Optional
minEvictableIdleTimeMillis: 60000 # Optional
timeBetweenEvictionRunsMillis: 30000 # Optional
numTestsPerEvictionRun: -1 # Optional
blockWhenExhausted: true # Optional
nettyThreads: 32 # Optional
subscriptionsPerConnection: 10 # Optional
subscriptionConnectionPoolSize: 100 # Optional
pageSizeInBytes: 8192 # Optional
readTimeout: 2000 # Optional
```
### JICS resource definitions
```
jics:
resource-definitions:
store-type: redis
# If the following redis properties are not specified gapwalk.redis configuration will be used for this cache
redis:
hostName: localhost
port: 6379
mode: standalone # Optional
username: # Optional
password: "" # Optional
useSsl: false # Optional
database: 0 # Optional
maxTotal: 128 # Optional
maxIdle: 128 # Optional
minIdle: 16 # Optional
testOnBorrow: true # Optional
testOnReturn: true # Optional
testWhileIdle: true # Optional
testOnCreate: true # Optional
minEvictableIdleTimeMillis: 60000 # Optional
timeBetweenEvictionRunsMillis: 30000 # Optional
numTestsPerEvictionRun: -1 # Optional
blockWhenExhausted: true # Optional
nettyThreads: 32 # Optional
subscriptionsPerConnection: 10 # Optional
subscriptionConnectionPoolSize: 100 # Optional
pageSizeInBytes: 8192 # Optional
readTimeout: 2000 # Optional
```
### JICS TS queues
```
jics:
parameters:
tsqimpl: redis
# If the following redis properties are not specified gapwalk.redis configuration will be used for this cache
queues:
ts:
redis:
hostName: localhost
port: 6379
mode: standalone # Optional
username: # Optional
password: "" # Optional
useSsl: false # Optional
database: 0 # Optional
maxTotal: 128 # Optional
maxIdle: 128 # Optional
minIdle: 16 # Optional
testOnBorrow: true # Optional
testOnReturn: true # Optional
testWhileIdle: true # Optional
testOnCreate: true # Optional
minEvictableIdleTimeMillis: 60000 # Optional
timeBetweenEvictionRunsMillis: 30000 # Optional
numTestsPerEvictionRun: -1 # Optional
blockWhenExhausted: true # Optional
nettyThreads: 32 # Optional
subscriptionsPerConnection: 10 # Optional
subscriptionConnectionPoolSize: 100 # Optional
pageSizeInBytes: 8192 # Optional
readTimeout: 2000 # Optional
```
### Session tracker
```
session-tracker:
store-type: redis
# If the following redis properties are not specified gapwalk.redis configuration will be used for this cache
redis:
hostName: localhost
port: 6379
mode: standalone # Optional
username: # Optional
password: "" # Optional
useSsl: false # Optional
database: 0 # Optional
maxTotal: 128 # Optional
maxIdle: 128 # Optional
minIdle: 16 # Optional
testOnBorrow: true # Optional
testOnReturn: true # Optional
testWhileIdle: true # Optional
testOnCreate: true # Optional
minEvictableIdleTimeMillis: 60000 # Optional
timeBetweenEvictionRunsMillis: 30000 # Optional
numTestsPerEvictionRun: -1 # Optional
blockWhenExhausted: true # Optional
nettyThreads: 32 # Optional
subscriptionsPerConnection: 10 # Optional
subscriptionConnectionPoolSize: 100 # Optional
pageSizeInBytes: 8192 # Optional
readTimeout: 2000 # Optional
```
### JCL checkpoint
```
jcl:
checkpoint:
provider: redis
# If the following redis properties are not specified gapwalk.redis configuration will be used for this cache
redis:
hostname: localhost
port: 6379
mode: standalone # Optional
username: # Optional
password: "" # Optional
useSsl: false # Optional
database: 0 # Optional
maxTotal: 128 # Optional
maxIdle: 128 # Optional
minIdle: 16 # Optional
testOnBorrow: true # Optional
testOnReturn: true # Optional
testWhileIdle: true # Optional
testOnCreate: true # Optional
minEvictableIdleTimeMillis: 60000 # Optional
timeBetweenEvictionRunsMillis: 30000 # Optional
numTestsPerEvictionRun: -1 # Optional
blockWhenExhausted: true # Optional
nettyThreads: 32 # Optional
subscriptionsPerConnection: 10 # Optional
subscriptionConnectionPoolSize: 100 # Optional
pageSizeInBytes: 8192 # Optional
readTimeout: 2000 # Optional
```
### Gapwalk file locks
```
filesLocks:
enabled: true
retryTime: 1000
MaxRetry: 5
provider: redis
# If the following redis properties are not specified gapwalk.redis configuration will be used for this cache
redis:
hostName: localhost
port: 6379
mode: standalone # Optional
username: # Optional
password: "" # Optional
useSsl: false # Optional
database: 0 # Optional
pool:
maxTotal: 128 # Optional
maxIdle: 128 # Optional
minIdle: 16 # Optional
testOnBorrow: true # Optional
testOnReturn: true # Optional
testWhileIdle: true # Optional
testOnCreate: true # Optional
minEvictableIdleTimeMillis: 60000 # Optional
timeBetweenEvictionRunsMillis: 30000 # Optional
numTestsPerEvictionRun: -1 # Optional
blockWhenExhausted: true # Optional
nettyThreads: 32 # Optional
subscriptionsPerConnection: 10 # Optional
subscriptionConnectionPoolSize: 100 # Optional
pageSizeInBytes: 8192 # Optional
readTimeout: 2000 # Optional
```
### Blu4iv locks
```
blu4iv.lock: redis
blu4iv.lock.timeout: 10 #(in millisecondes)
# If the following redis properties are not specified gapwalk.redis configuration will be used for this cache
blu4iv.lock.redis:
hostName: localhost
port: 6379
mode: standalone # Optional
username: # Optional
password: "" # Optional
useSsl: false # Optional
database: 0 # Optional
maxTotal: 128 # Optional
maxIdle: 128 # Optional
minIdle: 16 # Optional
testOnBorrow: true # Optional
testOnReturn: true # Optional
testWhileIdle: true # Optional
testOnCreate: true # Optional
minEvictableIdleTimeMillis: 60000 # Optional
timeBetweenEvictionRunsMillis: 30000 # Optional
numTestsPerEvictionRun: -1 # Optional
blockWhenExhausted: true # Optional
nettyThreads: 32 # Optional
subscriptionsPerConnection: 10 # Optional
subscriptionConnectionPoolSize: 100 # Optional
pageSizeInBytes: 8192 # Optional
readTimeout: 2000 # Optional
```
### Dataset catalog
```
datasimplifier:
catalogImplementation: redis
# If the following redis properties are not specified gapwalk.redis configuration will be used for this cache
redis:
hostName: localhost
port: 6379
mode: standalone # Optional
username: # Optional
password: "" # Optional
useSsl: false # Optional
database: 0 # Optional
maxTotal: 128 # Optional
maxIdle: 128 # Optional
minIdle: 16 # Optional
testOnBorrow: true # Optional
testOnReturn: true # Optional
testWhileIdle: true # Optional
testOnCreate: true # Optional
minEvictableIdleTimeMillis: 60000 # Optional
timeBetweenEvictionRunsMillis: 30000 # Optional
numTestsPerEvictionRun: -1 # Optional
blockWhenExhausted: true # Optional
nettyThreads: 32 # Optional
subscriptionsPerConnection: 10 # Optional
subscriptionConnectionPoolSize: 100 # Optional
pageSizeInBytes: 8192 # Optional
readTimeout: 2000 # Optional
```
## Secret manager for Redis caches
The `application-main.yaml` file can reference the secret ARN for Redis caches. For information about how to integrate AWS Secrets Manager to securely retrieve Redis connection details at runtime, see [AWS Transform for mainframe Runtime secrets](ba-runtime-config-app-secrets.md).
# Configure security for Gapwalk applications
The following topics describe how to secure Gapwalk applications.
It is your responsibility to provide the right configuration to ensure that the use of the AWS Transform for mainframe framework is secure.
All security-related features are disabled by default. To enable authentication (and CSRF,XSS,CSP, and so on), set `gapwalk-application.security` to `enabled` and `gapwalk-application.security.identity` to `oauth`.
**Topics**
+ [Configure URI accessibility for Gapwalk applications](ba-runtime-filteringURIs.md)
+ [Configure authentication for Gapwalk applications](ba-runtime-auth.md)
+ [Configure rate limiting for AWS Transform for mainframe Runtime](ba-runtime-rate-limiting.md)
# Configure URI accessibility for Gapwalk applications
This topic describes how to configure the filtering of URIs for Gapwalk applications. This feature does not require an identity provider (IdP).
To block a list of URIs, add the following two lines to the `application-main.yml` of your modernized application, replacing *URI-1*, *URI-2*, and so on, with the URIs that you want to block.
```
gapwalk-application.security.filterURIs: enabled
gapwalk-application.security.blockedURIs: URI-1, URI-2, URI-3
```
# Configure authentication for Gapwalk applications
To configure OAuth2 authentication for your Gapwalk application, you need to set up an identity provider (IdP) and integrate it with your application. This guide covers the steps for using Amazon Cognito or Keycloak as your IdP. With Amazon Cognito, you can update your application's configuration file with the Cognito user pool details. With Keycloak, you can control access to your application's APIs and resources based on the user's assigned roles.
**Topics**
+ [Configure Gapwalk OAuth2 authentication with Amazon Cognito](ba-runtime-auth-cognito.md)
+ [Configure Gapwalk OAuth2 authentication with Keycloak](ba-runtime-auth-keycloak.md)
# Configure Gapwalk OAuth2 authentication with Amazon Cognito
This topic describes how to configure OAuth2 authentication for Gapwalk applications using Amazon Cognito as an identity provider (IdP).
## Prerequisites
In this tutorial we will use Amazon Cognito as the IdP and PlanetDemo as the modernized project.
You can use any other external identity provider. The ClientRegistration information must be obtained from your IdP and is required for Gapwalk authentication. For more information, see the [Amazon Cognito Developer Guide](https://docs.aws.amazon.com/cognito/latest/developerguide/).
**The ClientRegistration information:**
client-id
The ID of the ClientRegistration. In our example it will be PlanetsDemo.
client-secret
Your client secret.
authorization endpoint
The authorization endpoint URI for the authorization server.
token endpoint
The token endpoint URI for the authorization server.
jwks endpoint
The URI used to get the JSON Web Key (JWK) that contains the keys for validating the JSON web signature issued by the authorization server.
redirect URI
The URI to which the authorization server redirects the end-user if access is granted.
## Amazon Cognito setup
First we will create and configure a Amazon Cognito user pool and user that we will use with our deployed Gapwalk application for testing purpose.
**Note**
If you are using another IdP, you can skip this step.
**Create user pool**
1. Go to Amazon Cognito in the AWS Management Console and authenticate using your AWS credentials.
1. Choose **User Pools**.
1. Choose **Create a user pool**.
1. In **Configure sign-in experience**, keep the **Cognito user pool** default provider type. You can choose one or multiple **Cognito user pool sign-in options**; for now, choose **User name**, then choose **Next**.
![\[alt_text\]](http://docs.aws.amazon.com/m2/latest/userguide/images/cog-auth-provider.png)
1. In **Configure security requirements**, keep the defaults and disable **Multi-factor authentication** by choosing **No MFA**, and then choose **Next**.
![\[alt_text\]](http://docs.aws.amazon.com/m2/latest/userguide/images/cog-sec-requirements.png)
1. As a security measure, disable **Enable self-registration**, and then choose **Next**.
![\[alt_text\]](http://docs.aws.amazon.com/m2/latest/userguide/images/cog-config-sign-up.png)
1. Choose **Send email with Cognito**, and then choose **Next**.
![\[alt_text\]](http://docs.aws.amazon.com/m2/latest/userguide/images/cog-email.png)
1. In **Integrate your app**, specify a name for your user pool. In **Hosted authentication pages**, choose **Use the Cognito Hosted UI**.
![\[alt_text\]](http://docs.aws.amazon.com/m2/latest/userguide/images/cog-domain.png)
1. For simplicity, in **Domain**, choose **Use a Cognito domain** and enter a domain prefix; for example, `https://planetsdemo`. The demo app must be added as a client.
1. In **Initial app client**, choose **Confidential client**. Enter an app client name, such as **planetsdemo**, and then choose **Generate a client secret**.
1. In **Allowed callback URL** enter the URL to redirect the user to after authentication. The URL must end with `/login/oauth2/code/cognito`. For example, for our application and backend Gapwalk and BAC applications:
```
http://localhost:8080/bac
http://localhost:8080/bac/login/oauth2/code/cognito
http://localhost:8080/gapwalk-application
http://localhost:8080/gapwalk-application/login/oauth2/code/cognito
http://localhost:8080/planetsdemo
http://localhost:8080/planetsdemo/login/oauth2/code/cognito
```
You can edit the URL later.
![\[alt_text\]](http://docs.aws.amazon.com/m2/latest/userguide/images/cog-urls.png)
1. In **Allowed sign-out URLs** enter the URL of the sign-out page that you want Amazon Cognito to redirect to when your application signs users out. For example, for backend Gapwalk and BAC applications:
```
http://localhost:8080/bac/logout
http://localhost:8080/gapwalk-application/logout
http://localhost:8080/planetsdemo/logout
```
You can edit the URL later.
1. Keep the default values in the **Advanced app client settings** and **Attribute read and write permissions** sections.
1. Choose **Next**.
1. In **Review and create**, verify your choices, and then choose **Create user pool**.
For more information, see [Create user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-create-user-pool.html).
**User creation**
Because self-registration is disabled, create a Amazon Cognito user. Navigate to Amazon Cognito in the AWS Management Console. Choose the user pool you created, and then in **Users** choose **Create user**.
In **User information**, choose **Send an email invitation**, enter a user name and an email address, and choose **Generate a password**. Choose **Create user**.
**Role creation**
In the **Groups** tab, create 3 groups (SUPER\$1ADMIN, ADMIN, and USER), and associate your user to one or more of these groups. These roles are later mapped to ROLE\$1SUPER\$1ADMIN, ROLE\$1ADMIN and ROLE\$1USER by the Gapwalk application to make it possible to access some restricted API REST calls.
The application implements hierarchical scope-to-role mapping that works with multiple OAuth2 identity providers. When JWT tokens issued by Cognito are used for resource server authorization, scopes defined in the token are automatically mapped to corresponding roles.
## Integrate Amazon Cognito into the Gapwalk application
Now that your Amazon Cognito user pool and users are ready, go the `application-main.yml` file of your modernized application and add the following code:
```
gapwalk-application.security: enabled
gapwalk-application.security.identity: oauth
gapwalk-application.security.issuerUri: https://cognito-idp..amazonaws.com/
gapwalk-application.security.domainName:
spring:
security:
oauth2:
client:
registration:
cognito:
client-id:
client-name:
client-secret:
provider: cognito
authorization-grant-type: authorization_code
scope: openid
redirect-uri: ""
provider:
cognito:
issuer-uri: ${gapwalk-application.security.issuerUri}
authorization-uri: ${gapwalk-application.security.domainName}/oauth2/authorize
jwk-set-uri: ${gapwalk-application.security.issuerUri}/.well-known/jwks.json
token-uri: ${gapwalk-application.security.domainName}/oauth2/token
user-name-attribute: username
resourceserver:
jwt:
jwk-set-uri: ${gapwalk-application.security.issuerUri}/.well-known/jwks.json
```
Replace the following placeholders as described:
1. Go to Amazon Cognito in the AWS Management Console and authenticate using your AWS credentials.
1. Choose **User Pools** and choose the user pool that you created. You can find your *pool-id* in **User pool ID**.
1. Choose **App integration** where you can find your *your-cognito-domain*, and then go to **App clients and analytics** and choose your app.
1. In **App client: yourApp** you can find the *client-name* , *client-id*, and *client-secret* (**Show client secret**).
1. *region-id* corresponds to the AWS Region ID where you created your Amazon Cognito user and user pool. Example: `eu-west-3`.
1. For *redirect-uri* enter the URI that you specified for **Allowed callback URL**. In our example it is `http://localhost:8080/planetsdemo/login/oauth2/code/cognito`.
You can now deploy your Gapwalk application and use the user created previously to sign in to your app.
# Configure Gapwalk OAuth2 authentication with Keycloak
This topic describes how to configure OAuth2 authentication for Gapwalk applications using Keycloak as an identity provider (IdP). In this tutorial we use Keycloak 24.0.0.
## Prerequisites
+ [Keycloak](https://www.keycloak.org/)
+ Gapwalk application
## Keycloak setup
1. Go to your Keycloak dashboard in your web browser. The default credentials are admin/admin. Go to the top left navigation bar, and create a realm with the name **demo**, as shown in the following image.
![\[alt_text\]](http://docs.aws.amazon.com/m2/latest/userguide/images/ba-runtime-auth-keycloak_2.png)
1. Create a client with the name **app-demo**.
![\[User interface for creating a new client in an authentication management system.\]](http://docs.aws.amazon.com/m2/latest/userguide/images/ba-runtime-auth-keycloak_3.jpg)
Replace `localhost:8080` with the address of your Gapwalk application
![\[alt_text\]](http://docs.aws.amazon.com/m2/latest/userguide/images/ba-runtime-auth-keycloak_4.png)
![\[alt_text\]](http://docs.aws.amazon.com/m2/latest/userguide/images/ba-runtime-auth-keycloak_5.png)
1. To get your client secret, choose **Clients**, then **app-demo**, then **Credentials**.
![\[alt_text\]](http://docs.aws.amazon.com/m2/latest/userguide/images/ba-runtime-auth-keycloak_6.jpg)
1. Choose **Clients**, then **Client scopes**, then **Add predefined mapper**. Choose **realm roles**.
![\[alt_text\]](http://docs.aws.amazon.com/m2/latest/userguide/images/ba-runtime-auth-keycloak_7.jpg)
1. Edit your realm role with the configuration shown in the following image.
![\[alt_text\]](http://docs.aws.amazon.com/m2/latest/userguide/images/ba-runtime-auth-keycloak_8.jpg)
1. Remember the defined **Token Claim Name**. You’ll need this value in the Gapwalk settings definition for the `gapwalk-application.security.claimGroupName` property.
![\[alt_text\]](http://docs.aws.amazon.com/m2/latest/userguide/images/ba-runtime-auth-keycloak_9.jpg)
1. Choose **Realms roles**, and create 3 roles: **SUPER\$1ADMIN**, **ADMIN**, and **USER**. These roles are later mapped to `ROLE_SUPER_ADMIN`, `ROLE_ADMIN`, and `ROLE_USER` by the Gapwalk application to be able to access some restricted API REST calls.
![\[alt_text\]](http://docs.aws.amazon.com/m2/latest/userguide/images/ba-runtime-auth-keycloak_10.jpg)
## Integrate Keycloak into the Gapwalk application
Edit your `application-main.yml` as follows:
```
gapwalk-application.security: enabled
gapwalk-application.security.identity: oauth
gapwalk-application.security.issuerUri: http:///realms/
gapwalk-application.security.claimGroupName: "keycloak:groups"
gapwalk-application.security.userAttributeName: "preferred_username"
# Use "username" for cognito,
# "preferred_username" for keycloak
# or any other string
spring:
security:
oauth2:
client:
registration:
demo:
client-id:
client-name: Demo App
client-secret:
provider: keycloak
authorization-grant-type: authorization_code
scope: openid
redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"
provider:
keycloak:
issuer-uri: ${gapwalk-application.security.issuerUri}
authorization-uri: ${gapwalk-application.security.issuerUri}/protocol/openid-connect/auth
jwk-set-uri: ${gapwalk-application.security.issuerUri}/protocol/openid-connect/certs
token-uri: ${gapwalk-application.security.issuerUri}/protocol/openid-connect/token
user-name-attribute: ${gapwalk-application.security.userAttributeName}
resourceserver:
jwt:
jwk-set-uri: ${gapwalk-application.security.issuerUri}/protocol/openid-connect/certs
```
Replace **, **, **, and ** with your Keycloak server hostname, your realm name, your client ID, and your client secret.
# Configure rate limiting for AWS Transform for mainframe Runtime
AWS Transform for mainframe Runtime includes built-in rate limiting functionality to protect gapwalk application from excessive requests and potential abuse. The rate limiting system uses the Token Bucket algorithm to provide both burst capacity and sustained rate limiting.
**Topics**
+ [Rate limiting overview](#ba-runtime-rate-limiting-overview)
+ [Configuration properties](#ba-runtime-rate-limiting-config)
+ [Enable rate limiting](#ba-runtime-rate-limiting-enable)
+ [Client identification](#ba-runtime-rate-limiting-client-id)
+ [Rate limit headers](#ba-runtime-rate-limiting-headers)
+ [Memory management](#ba-runtime-rate-limiting-memory)
## Rate limiting overview
The rate limiting system provides the following features:
**Token Bucket Algorithm**
+ Allows burst traffic up to the configured burst capacity
+ Refills tokens at a steady rate based on requests per minute
+ Provides smooth rate limiting without blocking legitimate traffic spikes
**Client Identification**
+ Identifies clients by IP address with proxy support
+ Supports X-Forwarded-For and X-Real-IP headers
+ Handles load balancer and reverse proxy scenarios
**Automatic Memory Management**
+ Automatically cleans up expired rate limit buckets
+ Configurable cleanup intervals and expiry times
+ Prevents memory leaks in long-running applications
**HTTP Integration**
+ Returns HTTP 429 (Too Many Requests) when limits exceeded
+ Includes standard rate limit headers in responses
+ Provides retry-after information for clients
## Configuration properties
Configure rate limiting in your `application-main.yaml` file:
```
gapwalk:
ratelimiting:
enabled: true # Enable/disable rate limiting
requestsPerMinute: 1000 # Sustained rate limit per minute
burstCapacity: 1500 # Maximum burst requests allowed
includeHeaders: true # Include X-RateLimit-* headers
cleanupIntervalMinutes: 5 # Cleanup interval for expired buckets
bucketExpiryHours: 1 # Hours after which unused buckets expire
errorMessage: "Too many requests. Try again later." # Custom error message
whitelistIps: "" # Comma-separated IPs to bypass limiting
perEndpointLimiting: false # Apply limits per endpoint (not implemented)
```
### Property descriptions
**enabled**
Master switch to enable or disable rate limiting functionality. Default: `false`
**requestsPerMinute**
Number of requests allowed per minute for sustained rate limiting. This represents the token refill rate. Default: `1000`
**burstCapacity**
Maximum number of requests allowed in a burst before rate limiting applies. Should be higher than `requestsPerMinute` to allow traffic spikes. Default: `1500`
**includeHeaders**
Whether to include standard rate limit headers (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`) in HTTP responses. Default: `true`
**cleanupIntervalMinutes**
Interval in minutes between automatic cleanup of expired rate limit buckets. Helps prevent memory leaks. Default: `5`
**bucketExpiryHours**
Time in hours after which unused rate limit buckets are considered expired and eligible for cleanup. Default: `1`
**errorMessage**
Custom error message returned in the JSON response when rate limit is exceeded. Default: `"Too many requests. Try again later."`
**whitelistIps**
Comma-separated list of IP addresses that bypass rate limiting entirely. Useful for health checks or trusted systems. Default: `empty`
**perEndpointLimiting**
Whether to apply separate rate limits per endpoint instead of per client only. Currently not implemented. Default: `false`
## Enable rate limiting
To enable rate limiting with default settings:
```
gapwalk:
ratelimiting:
enabled: true
```
## Client identification
The rate limiting system identifies clients using the following priority order:
1. **X-Forwarded-For header** (first IP if comma-separated)
1. **X-Real-IP header**
1. **Remote address** from the HTTP request
This ensures proper client identification when the application is behind:
+ Load balancers
+ Reverse proxies
+ CDNs
+ API gateways
### Example client identification
```
# Direct connection
Client IP: 192.168.1.100
# Behind load balancer with X-Forwarded-For
X-Forwarded-For: 203.0.113.45, 192.168.1.100
Client IP: 203.0.113.45 (first IP used)
# Behind reverse proxy with X-Real-IP
X-Real-IP: 203.0.113.45
Client IP: 203.0.113.45
```
## Rate limit headers
When `includeHeaders` is enabled, the following headers are added to HTTP responses:
**X-RateLimit-Limit**
The rate limit ceiling for the client (requests per minute)
**X-RateLimit-Remaining**
The number of requests remaining in the current rate limit window
**X-RateLimit-Reset**
The time at which the rate limit window resets (Unix timestamp)
### Example response headers
```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1640995200
```
### Rate limit exceeded response
When rate limit is exceeded, the system returns:
**HTTP Status**
429 Too Many Requests
**Content-Type**
application/json
**Retry-After**
Number of seconds to wait before retrying
```
{
"error": "Rate limit exceeded",
"message": "Too many requests. Try again later.",
"retryAfter": 60,
"timestamp": 1640995140000
}
```
## Memory management
The rate limiting system automatically manages memory to prevent leaks in long-running applications:
**Automatic Cleanup**
+ Runs every `cleanupIntervalMinutes` minutes
+ Removes buckets unused for `bucketExpiryHours` hours
+ Logs cleanup activity for monitoring
**Memory Efficiency**
+ Uses concurrent data structures for thread safety
+ Lazy bucket creation (only when needed)
+ Efficient token bucket implementation
### Monitoring cleanup activity
Check logs for cleanup messages:
```
INFO RateLimitingService - Cleaned up 15 expired rate limiting buckets
```