BASE24-eps - UIS Developers Guide

Title Page
UIS developers guide

BASE24-eps™
© 2008 by ACI Worldwide, Inc. All rights reserved.
All information contained in this documentation, as well as the software described in it, is
confidential and proprietary to ACI Worldwide, Inc., or one of its subsidiaries, is subject to a
license agreement, and may be used or copied only in accordance with the terms of such license.
Except as permitted by such license, no part of this documentation may be reproduced, stored in
a retrieval system, or transmitted in any form or by electronic, mechanical, recording, or any other
means, without the prior written permission of ACI Worldwide, Inc., or one of its subsidiaries.
ACI, ACI Worldwide, and the ACI product names used in this documentation are trademarks or
registered trademarks of ACI Worldwide, Inc., or one of its subsidiaries.
Other companies’ trademarks, service marks, or registered trademarks and service marks are
trademarks, service marks, or registered trademarks and service marks of their respective
companies.
2
TABLE OF CONTENTS
1. DOCUMENT PREFACE.............................................................................. 6
1.1 Document Control .................................................................................... 6

1.2 Overview .................................................................................................. 6
1.3 Reference Documents.............................................................................. 6
2. BASE24-eps UIS Startup/Runtime Configuration........................................ 7
2.1 Auditing Properties ................................................................................... 7

2.1.1 cleanup.userauditlog.retention.days ................................................... 7
2.1.2 cleanup.userauditlog.cleanup.starttime .............................................. 7
2.1.3 cleanup.userauditlog.timeperiod.hours............................................... 7
2.1.4 timertask.function.#.classname .......................................................... 7
2.1.5 timertask.manager.processid ............................................................. 8
2.2 Database Startup Properties .................................................................... 9
2.2.1 db.connection.wait.time ...................................................................... 9
2.2.2 db.datasource..................................................................................... 9
2.2.3 db.driver ............................................................................................. 9
2.2.4 db.max.connections.......................................................................... 10
2.2.5 db.static.connections ........................................................................ 10
2.2.6 db.type.............................................................................................. 10
2.2.7 db.user.id.......................................................................................... 10
2.2.8 db.user.password ............................................................................. 11
2.3 Event/Trace Logging Properties ............................................................. 12
2.3.1 event.config ...................................................................................... 12
2.3.2 trace.config....................................................................................... 12
2.4 Initialization Properties ........................................................................... 13
2.4.1 initialization.function.#.classname .................................................... 14
2.5 BASE24-eps Properties.......................................................................... 15
2.5.1 config.home ...................................................................................... 15
2.6 APPLCNFG Properties........................................................................... 16
2.6.1 Database Properties......................................................................... 16
2.6.2 Event/Trace Logging Properties ....................................................... 18
2.6.3 BASE24-eps Properties.................................................................... 19
2.7 System Properties .................................................................................. 22
2.7.1 config.filename ................................................................................. 22
2.7.2 jdal.trace........................................................................................... 22
2.7.3 jdal.trace.method .............................................................................. 22
2.7.4 process.id ......................................................................................... 23
3
TABLE OF CONTENTS
2.7.5 root.config......................................................................................... 23
2.7.6 SCH.................................................................................................. 23
2.7.7 Contingency Properties .................................................................... 23
3. BASE24-eps UIS Code/Configuration ....................................................... 24
3.1 XML Configuration Files ......................................................................... 24

3.1.1 < Transaction Map>.xml ................................................................... 25
3.1.2 <Data Source>Gen.xml .................................................................... 32
4. BASE24-eps UIS XML Schemas............................................................... 50
4.1 Request/Response Message Definitions................................................ 50

4.1.1 Data Type Schema Definitions ......................................................... 51
4.1.2 Element/Group Schema Definitions.................................................. 57
4.1.3 Message Schema Definitions ........................................................... 61
4.2 Data Validations ..................................................................................... 67
5. Formatter/Command Configuration ........................................................... 68
5.1 Formatter................................................................................................ 68
5.1.1 es.server.formatter.xml.ESXMLFormatter ........................................ 68
5.1.2 com.aciworldwide.common.formatter.NullFormatter......................... 71
5.2 Command............................................................................................... 72
5.2.1 Single Data Source Action................................................................ 73
5.2.2 Multi-Data Source Action (related) ................................................... 74
5.2.3 Multi-Data Source Action (unrelated)................................................ 74
5.2.4 Data Source Action with Continue Conditionals ............................... 75
5.3 Command-Level Filtering ....................................................................... 76
6. Components/Services ............................................................................... 77
6.1 Generators ............................................................................................. 78

6.1.1 ServiceGenerator ............................................................................. 78
6.1.2 ComponentGenerator....................................................................... 79
6.2 PassthruComponent Usage ................................................................... 81
6.2.1 Extending es.server.component.PassthruComponent...................... 84
6.3 Database-Level Filtering......................................................................... 87
7. How-To Guides ......................................................................................... 88
7.1 Create a New Request/Response Message........................................... 88

7.2 Alter an Existing Request/Response Message....................................... 90
4
TABLE OF CONTENTS
7.3 Create a New Data Source..................................................................... 92
7.4 Modify an Existing Data Source ............................................................. 93
7.5 Create/Modify Data Validations .............................................................. 94
7.6 Create a Custom Data Component ........................................................ 95
7.7 Create a Custom Data Source Service .................................................. 96
7.8 Implement Different Input Protocols/Message Formats.......................... 97
7.8.1 New Protocol Support....................................................................... 97
7.8.2 New Message Format Support ......................................................... 97
7.9 Implement Pass-Thru Processing .......................................................... 99
7.9.1 Straight Pass-Thru............................................................................ 99
7.9.2 Straight Pass-Thru w/ USEC Support..............................................101
7.9.3 Integrated Workflow.........................................................................103
7.10 Solve Various Development Issues ....................................................105
7.10.1 Code/Configuration Check List .....................................................105
7.10.2 Task ID/Function ID Specification.................................................106
7.10.3 Data Type Conversion between DALCI/SIS and UISs .................107
7.10.4 Customizing Data Components/Services w/ Copy Files...............108
7.10.5 Customizing Request/Response Data Handling...........................109
7.10.6 Maximum Number of Data Rows Retrieval...................................111
7.10.7 Updating of Primary Key Fields ....................................................112
7.10.8 Implementing Filtering Support.....................................................114
7.10.9 Implementing Dynamic SQL Table Access Support .....................115
7.10.10 Start/End Key Data Retrieval Support .......................................116
8. Appendix ..................................................................................................117
8.1 XML Simple Types and Restriction Hierarchy .......................................117

8.2 UIS Error Handling ................................................................................119
8.3 UIS DataObject Mapping.......................................................................120
8.3.1 Auditing Context ..............................................................................120
8.3.2 Data Source Context .......................................................................121
8.3.3 Error Context ...................................................................................122
8.3.4 Filtering Context ..............................................................................123
8.3.5 Message Context ............................................................................124
8.3.6 Miscellaneous Context ....................................................................126
8.3.7 Security Context ..............................................................................130
5
1. DOCUMENT PREFACE
1.1 Document Control
Version: Author: Date Distributed:

8.2 J. Hurlbut April 2008
MAJOR CHANGES: Initial release for 8.2.
1.2 Overview
The primary focus of this document is to discuss how to configure and code the
BASE24-eps UIServer (here-in referred to as UIS) environment and build additional
processing components with the architecture. Areas covered include:
XML Usage
o Usage and rules for message processing
o Usage and rules for data validations
Formatter/Command configuration
Data access components/services
How-to Guidelines
1.3 Reference Documents
The following reference documents should be used to support UIS development efforts:
Version : Document:
1.0 ACI Java Framework Development Guide
6
2. BASE24-eps UIS Startup/Runtime Configuration
The following subsections will discuss startup and runtime properties in the
config.properties file and APPLCNFG database table that have a direct impact on the
UIS implementation. This includes existing JSF properties as well as UIS properties.
2.1 Auditing Properties
The JSF provides auditing services to the UIS environment. To manage the user audit
log file contents, several settings are required. These settings are discussed in the
following subsections.
2.1.1 cleanup.userauditlog.retention.days
[Required - APPLCNFG] This property is used by the audit cleanup task. It defines the
number of days to leave records in the audit log.
Default setting is for 30 days.
2.1.2 cleanup.userauditlog.cleanup.starttime
[Required - APPLCNFG] This property defines the time of day to start the audit
cleanup task.
Default setting is for 23:59 (midnight).
2.1.3 cleanup.userauditlog.timeperiod.hours
[Required - APPLCNFG] This property defines the time period (in hours) between audit
cleanup processing. If the cleanup process should be run more frequently, this value
should be set lower.
Default setting is for 24 hours.
2.1.4 timertask.function.#.classname
[Required – config.properties] This property contains the class name of the Java
component that performs the audit log cleanup. If additional timer task-based classes
are implemented, the numeric value must be incremented from 0 by 1. For BASE24-eps
audit cleanup, a property will be set as follows:
timertask.function.0.classname=
com.aciworldwide.common.timertask.UserAuditLogCleanup
For BASE24-eps UIS contingency support, a property will be added as follows:

timertask.function.1.classname=
es.server.timertask.ContingencySAFProcess
7
Note: If additional product or CSM processes are required to execute based on timer
functionality, they can be added under additional entries of this property, however, those
classes must implement the JSF interface class of:
com.aciworldwide.framework.TimerTaskInterface
2.1.5 timertask.manager.processid
[Required – config.properties] This property contains the process ID of the process

that will run the audit cleanup tasks.
8
2.2 Database Startup Properties
The JSF provides DBService and CacheManager processes that work in tandem to
provide high-performance data access. To support configuration of these 2 services, an
array of db.* properties are supported that cover configuration of the following areas:
Auditing
Database access
JDBC driver details
2.2.1 db.connection.wait.time
[Required - config.properties] This property defines the amount of time, in

milliseconds, to wait for another thread to free a database connection in the
DBConnectionManager. This is used when the maximum number of connections has
been reached as specified in the db.max.connections property.
Example property entry:
db.connection.wait.time=1000
2.2.2 db.datasource
[Required – config.properties] This property provides the data source URI

specification that allows the JDBC driver to access the correct database. Configuration
requirements will typically be found in the JDBC driver’s vendor documentation.
db.datasource=jdbc:JDAL:-MDBV=CSV:-AI=ES:-STRT=/G/system/nw01data
2.2.3 db.driver
[Required – config.properties] This property specifies the class name of the JDBC
driver to use for all database connections. The whole package name, as it is found in
the jar containing the driver, should be specified. Refer to specific vendor
documentation for supporting information.
db.driver=com.aciworldwide.jdbcdriver.jdal.JDALDriver
Note: For a BASE24-eps DALCI controlled database, the db.driver and db.datasource
specifications will be made using the ACI JDAL database driver.
9
2.2.4 db.max.connections
[Required – config.properties] This property indicates the maximum number of

database connections to be opened up by the JSF DBConnectionManager.
db.max.connections=10
2.2.5 db.static.connections
[Required – config.properties] This property defines the number of connections to

acquire to the database when the JVM starts. These connections will stay active
through the life of the executing JVM. The JSF DBConnectionManager is responsible
for acquiring the connections.
db.static.connections=2
2.2.6 db.type
[Required – config.properties] This property indicates the type of database being

used in the current executing environment. Valid values are:
DB2
JDAL
JDAL2
MSSQL
ORACLE
SQLMX
db.type=JDAL
2.2.7 db.user.id
[Required – config.properties] This property indicates the user ID that should be used
to securely access the underlying database. A Database or a Security Administrator will
typically establish the user ID.
db.user.id=myuser
10
2.2.8 db.user.password
[Required – config.properties] This property indicates the user password that should
be used to securely access the underlying database. A Database or a Security
Administrator will typically establish the user password with the user ID.
db.user.password=c67834a7b2e28c4e
Note: If database passwords are stored in the config.properties file they must be
encrypted. The encryption process requires both the user ID and the password values
to generate the encrypted password. The utility to perform the encryption is available via
the JSF. The user password value can also be left blank for access that does not
require a user ID and/or password.
11
2.3 Event/Trace Logging Properties
The JSF provides 2 logging mechanisms:
Event Logging
Trace Logging
Both of these mechanisms are further described in the ACI Java Framework
Development Guide. The config.properties entries that will require configuration in all
UIS installations follow.
2.3.1 event.config
[Required – config.properties] This property identifies the fully qualified URI location
of where the EventConfig.xml configuration file resides. The EventConfig.xml
configuration file provides further configuration details to the JSF EventManager
service.
event.config=file:///C:/ESWeb/ESConfig/EventConfig.xml (Windows)
or
event.config=file:///user/ESWeb/ESConfig/EventConfig.xml (UNIX)
2.3.2 trace.config
[Required – config.properties] This property identifies the fully qualified URI location
of where the TraceConfig.xml configuration file resides. The TraceConfig.xml
configuration file provides further configuration details to the JSF TraceManager
service.
trace.config=file:///C:/ESWeb/ESConfig/TraceConfig.xml (Windows)
or
trace.config=file:///user/ESWeb/ESConfig/TraceConfig.xml (UNIX)
12
2.4 Initialization Properties
The UIS implementation of the JSF currently supports services that can be started at
initialization by the JSF InitializationManager. The InitializationManager will retrieve 0
or more entry sets of initialization properties that identify the Java class to be started and
its initialization entry method.
Currently, the UIS implementation supports services that can be started by the JSF
InitializationManager. These services are:
es.server.common.DataTypeValidationManager (must be started before

DataValidatorManager)
es.server.common.DataValidatorManager
es.server.formatter.xml.MessageSchemaManager
es.server.framework.TransactionMapManager
com.aciworldwide.framework.TransactionMapManager
usec.common.USECManager
es.server.common.OLTPAssignManager
com.aciworldwide.framework.pools.SAX2ParserManager
com.aciworldwide.application.audit.formatter.jaxb.JAXBContextManager
com.aciworldwide.common.MessageRouterService
Current UIS property entries in APPLCNFG includes:
initialization.function.0.classname=
es.server.common.DataTypeValidationManager
com.aciworldwide.framework.TransactionMapManager
es.server.common.DataValidatorManager
es.server.formatter.xml.MessageSchemaManager
com.aciworldwide.application.security.USECManager
es.server.common.OLTPAssignManager
com.aciworldwide.framework.pools.SAX2ParserManager
com.aciworldwide.application.audit.formatter.jaxb.JAXBContextManager
com.aciworldwide.application.pci.masking.formatter.jaxb.JAXBContext
Manager
13
com.aciworldwide.common.MessageRouterService
2.4.1 initialization.function.#.classname
[Optional - APPLCNFG] This property identifies the fully qualified Java package and
class name to be started. Each class name entry must set the # to a number starting at
0 and incrementing by 1.
14
2.5 BASE24-eps Properties
The UIS implementation of the JSF currently supports additional configuration

properties. At this time, these properties are primarily associated with BASE24-eps,
and fall under the following category:
Miscellaneous
config.home
Note: File locations in the UIS implementation are handled as direct file specifications.
However, throughout the config.properties and APPLCNFG entries that are being
discussed and throughout the XML Schema support discussed in Section 4, all file
specifications are handled as relative URIs. To resolve the relative URIs to file
specifications, all UIS-based applications will append the config.home property, found
in the config.properties file and discussed in Section 2.5.1, to each relative URI. This
2
was done so that configuration files could be more easily managed and configured from
a central location.
2.5.1 config.home
[Required – config.properties] This property identifies the home location of the

configuration files used in the UIS implementation. The value of this property will be
used by components and services to expand relative URIs to file specifications.
Note: The value established for this field must follow one of the example entries listed
below and must end in a forward slash /.
config.home=C:/ESWeb/ES044/ESConfig/
(Windows)
or
config.home=/user/mydir/ESWeb/ESConfig/
(UNIX)
15
2.6 APPLCNFG Properties
Additional UIS configuration properties exist in the APPLCNFG database table. The
JSF ConfigManager looks in both the config.properties (first) and the APPLCNFG
(second) to locate requested property settings. An attempt to retrieve a property is first
made based on the current system process ID (i.e. BASE24-EPSUI). If the property is
not found, a second attempt is made to locate the property based on a default process
ID (*).
The properties and values listed in this sub-section reflect those that will be managed
under the APPLCNFG table for BASE24-eps.
2.6.1 Database Properties
The JSF provides DBService and CacheManager that work in tandem to provide high-
performance data access. To support configuration of these 2 services, an array of db.*
properties are supported in the config.properties file that cover configuration of the
following areas:
Auditing
Database access
JDBC driver details
2.6.1.1 db.audited
[Required] This property identifies if database actions performed by a user is to be

audited. Database actions that are audited include:
Delete
Insert
Update
View
Valid values are true and false.
This setting is initially loaded into the APPLCNFG data source from the load file
scripts/ESAPPLCD load script.
16
2.6.1.2 db.audited.[service name]
[Optional] This property identifies the level of auditing to be performed against a data
source. The lowercase <service name> should be set to an actual data source service
name and there can be multiple occurrences of this property, 1 for each data source
service requiring auditing support. Valid values are:
full - report on times, users, activity and details (default)

medium - report on times, users, and activity, no details
none - no auditing is to be performed
The current list of supported 8.2 UIS services is covered in the <get manual name>.
2.6.1.3 db.cached.[service name]
[Optional] This property indicates that database access performed on the specified
service is to utilize the database service caching mechanism (CacheManager). All SQL
queries, except the fetchbyDataObject method, will first search the database services
cache for data. If the data is not found, it will update the cache with the data source
information retrieved. This functionality should be used for tables that are updated
infrequently, or read frequently and contain a small number of rows. The lowercase
<service name> should be set to an actual data source service name and there can be
multiple occurrences of this property, 1 for each data source service requiring caching
support.
Valid values are true and false (default).
The current list of supported 8.2 UIS services is covered in the <get manual name>.
17
2.6.2 Event/Trace Logging Properties
The JSF provides 2 logging mechanisms:
Event Logging
Trace Logging
Both of these mechanisms are further described in the ACI Java Framework
Development Guide. The APPLCNFG entries that will require configuration in all UIS
installations follow.
2.6.2.1 trace.enabled
[Required] This property identifies whether trace messages are enabled for
components/services executing with the JSF. Tracing of messages is configured within
the TraceConfig.xml file that is used by the JSF TraceManager service.
Note: Only set this property to true during development, debugging, or to uncover
production problems; do not run production environments with trace unless necessary.
2.6.2.2 trace.dataobject.enabled
[Optional] This property identifies whether trace messages are enabled for data object
output from the JSF. Tracing of messages is configured within the TraceConfig.xml file
that is used by the JSF TraceManager service. When set to true, the UIS
MessageSchema class will dump traces of the contents of the primary data object
during request message processing and response message building.
Note: Only set this property to true during development, debugging, or to uncover
production problems; do not run production environments with trace unless necessary.
18
2.6.3 BASE24-eps Properties
The UIS implementation of the JSF supports additional configuration properties. At this
time, these properties are primarily associated with BASE24-eps, and fall under the
following categories:
Application Management
amptc.connectionID
Data Support
db.upshiftdata
Filtering Support
filter.field.[task].#
Miscellaneous
process.id
ptc.connectionID
ptcf.connectionID
report.userauditlog.loc
Note: File locations in the UIS implementation can be handled as direct file
specifications. However, throughout the APPLCNFG entries that will be discussed in
the following sub-sections and throughout the XML Schema support discussed in
Section 4, all file specifications are handled as relative URIs. To resolve the relative
URIs to file specifications, all UIS applications will append the config.home property,
found in the config.properties file and discussed in Section 2.5.1, to each relative URI.
2
This was done so that configuration files could be more easily managed and configured
from a central location.
2.6.3.1 amptc.connectionID
[Optional] This property is optional, but required if Application Management support is

being performed. The value of this property identifies the default, non-formatting
Application Management connection ID row to use, with UIS PassthruComponent
processing, from the EXTRCNCT table. There are no restrictions on what the value can
be set to.
The pre-loaded default property value is:
amptc.connectionID=APPLICATION-MGMT
2.6.3.2 db.upshiftdata
[Required] This property indicates if application level support of upshifting string data
should be performed. Upshifting of data needs to be handled at the app level when
working with Enscribe or VSAM data. Otherwise, a respective SQL database may
handle upshifting requirements in which case this property could be set to false.
19
This setting is initially loaded into the APPLCNFG data source from the
2.6.3.3 filter.field.[task].#
[Optional] This property indicates field filter support for specific task Ids ([task]). If field
level filtering is being performed on behalf of a specific task, then 1 or more property
settings will be established for that task ID and its filtered field(s) with multiple entries
being identified with incrementally numeric (#) values starting at 0. This property guides
the UIS implementation to map incoming data values from logical elements to a field ID
understood by the filtering implementation from USEC. Values are depicted as 3 parts
(semi-colon separated):
1. Identifier of: F – filter only; M – USEC maintenance only; and B – both filter and
maintain.
2. The field ID known to USEC for filtering
3. The logical element in the message that contains the data.
A valid example entry for this property is:
filter.field.InstitutionConfiguration.0=F;InstitutionID;instdInstitution
ID
Filtering support also requires transmap filter class specification. Refer to Section 3.1.1
for further transmap filtering discussion.
2.6.3.4 ptc.connectionID
[Optional] This property is optional, but required if pass-thru processing is being

performed. The value of this property identifies the default, non-formatting connection ID
row to use, with UIS PassthruComponent processing, from the EXTRCNCT table.
There are no restrictions on what the value can be set to.
ptc.connectionID=BASE24-eps/C++XMLServer
scripts/ESAPPLCD load script. Additional product or CSM settings could be loaded in
from other similar files.
Note: This property can be extended to provide additional external connection

identifiers. These properties would then be used with extended PassthruComponent
processing. Property naming conventions should follow a [name].connectionID
standard.
20
2.6.3.5 ptcf.connectionID
[Optional] This property is optional, but required if pass-thru processing is being

performed. The value of this property identifies the default, with formatting connection
ID row to use, with UIS PassthruComponent processing, from the EXTRCNCT table.
There are no restrictions on what the value can be set to.
ptcf.connectionID=BASE24-eps/C++XMLServer Formatted
This setting is initially loaded into the APPLCNFG data source from scripts/ESAPPLCD
load script. Additional product or CSM settings could be loaded in from other similar
files.
Note: This property can be extended to provide additional external connection

identifiers. These properties would then be used with extended PassthruComponent
processing. Property naming conventions should follow a [name]f.connectionID
standard.
2.6.3.6 report.userauditlog.loc
[Optional] This property indicates the directory location where requested User Audit
Log reports will be placed. The directory must already exist; the UIS will not create the
directory.
Note: When setting the value for this property, use of “\” for NT environments versus “/”
for Unix environments must be observed.
21
2.7 System Properties
The system properties identified in this section are configured at the Web Server level as
additional JVM arguments.
The following system properties are required to execute the Web Server environment for
the UISs:
2.7.1 config.filename
[Required] This property identifies to the UIS environment where the primary
config.properties file is located. Most configuration properties are maintained in the
JSF APPLCNFG table; however, core properties necessary for system startup are
maintained in the physical properties file. Hence, the location of that file must be
specified with this system property.
The config.properties file can be located under the default directory for the user’s
machine (i.e. C:\Document and Settings\User 1) or it can be located elsewhere and
specified to the framework environment at startup via the following system property:
-Dconfig.filename=<file location & name>
The config.properties file contains a handful of key/value pairs that are used
throughout various framework services. Components and services request property
value information from the JSF ConfigManager service.
2.7.2 jdal.trace
[Optional] This property identifies if jdal level tracing is turned on or off. When set to
true, additional trace messages will be echoed to the standard out file for each database
function performed that goes through jdal. To turn this tracing off, set the property to
false.
NOTE: This property should not be set to true for production environments and should
only be used in extreme error evaluation situations.
2.7.3 jdal.trace.method
[Optional] This property identifies if jdal method level tracing is turned on or off. When
set to true, additional trace messages will be echoed to the standard out file for each
jdal method access. To turn this tracing off, set the property to false.
NOTE: This property should not be set to true for production environments and should
only be used in extreme error evaluation situations.
22
2.7.4 process.id
[Required] This property identifies the key value into many JSF tables containing
configuration information (i.e. APPLCNFG). Use of this system property allows multiple
configurations/Web Servers to share the same JSF database implementation while
maintaining unique processing requirements.
2.7.5 root.config
[Required] This property identifies the root location of where the Modules.lst,
Global.cfg, and the GlobalPrefs.cfg files reside. These files are used by specific UIF
components that are shared from the UIS.
2.7.6 SCH
[Required] This property identifies if the UIS implementation is running in Channel

Header support mode. Valid values are true and false. When set to true, inbound
request messages and responses to those requests will be processed with or without
Channel Header support from the client. Channel Header support is a feature of the
UIF. If this value is set to false, Channel Header support will be turned off.
Note: Support of this feature from the ES desktop client requires the configuration file of
../ES/desktop/DesktopLauncher.lax to include the system property setting of –
DSCH=true.
2.7.7 Contingency Properties
The following properties, when added, will implement the UIS contingency support.
2.7.7.1 cjsaf.enabled
[Optional] This property turns the contingency support on or off. To turn contingency
support on, set the value to true. To disable contingency support, set the value to false
or remove the property.
2.7.7.2 cjsaf.sleep
[Optional] This property identifies, in seconds, the amount of time for the
ContingencySAFProcess to wait between processing runs. When the process begins,
it will continue until all SAF records have been processed before returning to the
wait/sleep state.
2.7.7.3 cjsaf.retry
[Optional] This property identifies the number of times a SAF record will be retried for
processing before being deleted from the SAF. If a send failure does occur,
informational and record details will be written to the critical event log.
23
3. BASE24-eps UIS Code/Configuration
3.1 XML Configuration Files
With the exception of the config.properties configuration file, all other configuration files
used within UIS are managed via XML files. Configuration files provided by the UIS
implementation include:
<transmap>.xml
<XML message schema>.xml
<Data Source>Gen.xml
These configuration files will be discussed in the following sub-sections.
Additionally, there are two other XML-based configuration files, used within the
environment, that are provided by the JSF. Those files:
EventConfig.xml
TraceConfig.xml
The use and configuration of these files is discussed in the ACI Java Framework
Development Guide.
Note: All XML usage within the UIS environment follows the current W3C 2001 XML
Schema standards and guidelines found at http://www.w3.org/XML/Schema.
24
3.1.1 < Transaction Map>.xml
The <Transaction Map>.xml configuration files identify processing requirements, via

the following items, for each type of request message supported:
Associated task and function Ids
The filter to be used to handle filter-processing requirements.
The formatter to be used to handle the message specifics (request/response)
The location of the XML message schema to use for processing the message
The command(s) component(s) that will be utilized
The data component(s), and required method, that will be accessed to process the request
The continue and stop conditionals associated with multiple commands and/or multiple
transactions
During initialization, the TransactionMapManager component reads configuration data

from transmap files. The TransactionMapManager preloads all information contained
in these configuration files into individual TransactionMapField objects, each object
representing an <entry> from the configuration file. Transmap files are located and
loaded either from a runtime jar, typically named *-transmaps.jar, or from the
ESConfig/transmaps directory location.
BASE24-eps Note: Naming of these files should match the naming of the *.cfg file
located on the UI side.
25
3.1.1.1 XML Syntax
The XML syntax for the <Transaction Map>.xml file is as follows:
<transactions>
[Required] One <transactions> tag entry allowed.
<entry>
[Required] Multiple <entry> tags are allowed.
<tag>
[Required] Must contain the request identifier that will be
found in the root tag of the XML request message. One <tag>
tag entry allowed per <entry> group.
</tag>
<task>
[Optional] Must contain an associated UI task ID value. The
<task> and <function> values will be used to verify a user’s
security permissions to perform the configured actions.
This is specific to the ES UI environment. One <task> tag
entry allowed per <entry> group. For BASE24-eps, this
value will also serve as the file name of the transaction
map file.
</task>
<function isAdd = “true | false (default)”>

[Optional] Must contain an associated UI function ID value.
The <task> and <function> values will be used to verify a
user’s security permissions to perform the configured
actions. This is specific to the ES UI environment. One
<function> tag entry allowed per <entry> group.
The isAdd attribute should be used to identify function Ids

that result in add processing. This is primarily in the
case where BASE24-eps utilizes a generic Save function that
can imply either add or update processing. To ensure proper
filtering support with the UIS implementation, Save
functionality that is true add processing must be known
ahead of time.
</function>
<filter>
[Optional] One <formatter> tag entry allowed per <entry>
group.
<class>
[Required] Must contain the fully qualified Java filter
component name. The filter class is responsible for
providing database layer list filtering. One <class>
tag entry allowed per <filter> group.
</class>
</filter>
26
<formatter>
[Required] One <formatter> tag entry allowed per <entry>
group.
<class>
[Required] Must contain the fully qualified Java
formatter component name. The formatter class is
responsible for directing other components to break
request messages down into internal DataObject values
and for building response messages from internal
DataObject values. One <class> tag entry allowed per
<formatter> group.
</class>
</formatter>
<command>
[Required] Multiple <command> tag entries are allowed.
<contconditions>
[Optional] One <contconditions> tag entry allowed
per <command> group.
<code reset = “<new code>”>

[Required] Continue code settings here provide
flexibility for controlling command flow through
multiple transactions. They can be used to
identify specific error codes that may be
allowable for processing to continue. Codes
defined here and encountered during processing
will result in the internal error code to be
reset to null or the specified reset attribute
value and processing of the next command set
will be performed. Multiple <code> tag entries
allowed per <contconditions> group. If no
<contconditions> are defined, any error encountered
will cause processing to halt.
The reset attribute value can be used to define a

replacement error code or a successful code of
DBS_FILE_OK or DBS_FILE_EXHAUSTED. If not present,
the error code will be set to null.
</code>
</contconditions>
<class>
[Required] Must contain the fully qualified Java command
component name. The command class is responsible for
directing access to data or business components to that
will perform the required work. One <class> tag entry
allowed per <command> group.
</class>
27
<transaction>
[Required] Multiple <transaction> tag entries are
allowed.
<contconditions>
[Optional] One <contconditions> tag entry
allowed per <transaction> group.
<code reset = “<new code>”>

[Required] Continue code settings here
provide flexibility for controlling
transaction flow through multiple
transactions. They can be used to identify
specific error codes that may be allowable
for processing to continue. Codes defined
here and encountered during processing will
result in the internal error code to be
reset to null or the specified reset
attribute value and processing of the next
transaction set will be performed. Multiple
<code> tag entries allowed per <contconditions>
group. If no <contconditions> are defined, any
error encountered will cause processing to halt.
The reset attribute value can be used to define a

replacement error code or a successful code of
DBS_FILE_OK or DBS_FILE_EXHAUSTED. If not
present, the error code will be set to null.
</code>
</contconditions>
<component>
[Required] Must contain the fully qualified Java
data/business component name. Component classes can
be responsible for directing access to underlying
data sources, directing access to other non-Java
components, and for providing complex business
logic. One <component> tag entry allowed per
<transaction> group.
</component>
<method appData = “true | false (default)”

maxRows = “#”
whereset = “{set name}”>
[Required] Must identify the specific, public method
in the component class (identified in <component>)
to be invoked. One <method> tag entry allowed per
<transaction> group.
The appData attribute should be used when performing

2 or more getAll or getBy functions within a common
transaction set and there is a need to append data
in multiple rows in the primary data object because
of specific data commonalities between the data
sources. The components processed in this case must
be in the desired sequential order.
28
The maxRows attribute should be used when the number
of data rows retrieved by DBService and returned in
the response message must be restricted (i.e.
because of message size, performance, etc.). This
attribute is only valid for getBy methods; it will
not be applicable to get or getAll methods. If this
attribute is not present, all data rows that meet
selection criteria will be retrieved. If this
attribute is present with a valid numeric value,
only that number of rows will be retrieved and
returned. In this latter case, the response code
that will be returned to the client will depend on
the presence of more rows. Those codes are:
File_OK - more data rows exist
File_Exhausted - all data rows returned
The whereset attribute should be used when accessing

a getBy method that was architected to support
multiple wheresets. The whereset extension name
that should be utilized with the configured method
would be configured under this attribute.
</method>
</transaction>
</command>
</entry>
</transactions>
29
3.1.1.2 Example Configuration
The following is an example transaction map configuration file

(ContextConfiguration.xml):
<?xml version="1.0" encoding="UTF-8"?>

<transactions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<entry>
<tag>ContextConfigDeleteRq</tag>
<task>ContextConfiguration</task>
<function>Delete</function>
<formatter>
<class>es.server.formatter.xml.ESXMLFormatter</class>
</formatter>
<command>
<class>es.server.command.ESTransCommand</class>
<transaction>
<component>es.server.datasource.ContextCfgComponent
</component>
<method>delete</method>
</transaction>
</command>
</entry>
<entry>
<tag>ContextConfigInsertRq</tag>
<function>Save</function>
<formatter>
</formatter>
<command>
<transaction>
</component>
<method>add</method>
</transaction>
</command>
</entry>
<entry>
<tag>ContextConfigListRq</tag>
<function>View</function>
<formatter>
</formatter>
<command>
<class>es.server.command.ESSimpleCommand</class>
<transaction>
</component>
<method>getAll</method>
</transaction>
</command>
</entry>
<entry>
<tag>ContextConfigUpdateRq</tag>
30
<formatter>
</formatter>
<command>
<transaction>
</component>
<method>update</method>
</transaction>
</command>
</entry>
<entry>
<tag>ContextConfigViewRq</tag>
<function>View</function>
<formatter>
</formatter>
<command>
<transaction>
</component>
<method>get</method>
</transaction>
</command>
</entry>
</transactions>
31
3.1.2 <Data Source>Gen.xml
The purpose of a <Data Source>Gen.xml configuration file is to identify the following:
Configuration of data source tables/files including column/field names, data types (internal
and external), overriding constraints, and primary and alternate keys
Configuration of common processing actions (add, delete, update, etc.) and extended
processing actions (alternate fetches and deletes) that will be created in the generated
component or service code
Configuration of custom code that can be included in the generated component or service
code
These configuration files are used as input into the following generators:
ServiceGenerator
The ServiceGenerator is used to create the data source specific access code that buffers
application components from data access handling. Service components typically have a
one-to-one relationship with the underlying data source.
ComponentGenerator
The ComponentGenerator is used to create the data component source that is used to
access functionality from the generated service components. Data components also provide
ancillary support such as data validation handling and field requirement checking.
Custom Code Support
The ComponentGenerator and ServiceGenerator support custom code additions

within the *Gen.xml files. As will be seen in the next sub-section, there are various
ways to include additional import statements and global variables as well as a
standardized way for supporting custom validations. However, custom code involving
new methods has been standardized with the following directory structure guidelines:
ESConfig/
This directory contains a master SetCommon.bat file for establishing classpath

and other environment settings used during code generation.
32
ESConfig/datasource
This directory contains a master batch file for calling all individual data source
creation batch files from lower level directories.
ESConfig/datasource/gens/<data source>
The <data source> directories under ESConfig/datasource/gens are separated

by individual data sources. Within each directory will be the *Gen.xml file for that
data source, a batch control generation file that can be executed individually or as
part of the master batch file listed above, and any copy code specific to the data
source represented in <method name>.jcf files.
Although not enforced with the code generation, it is highly recommended that
each method written as copy code be represented in its own Java Copy File (jcf).
Hence, the <method name> would be set to the actual method name with the file
extension being jcf. The jcf file should contain the JavaDoc header information,
the method declaration, and all supporting code. A jcf file can also be created to
contain just import statements (set <method name> to something like import),
just additional global variables (set <method name> to something like
globalVariables) or a combination of global variables and a method – a jcf should
never contain import statements combined with anything else as the import
statements are placed outside of the component class definition.
Additional jcf files, which can be referenced by 2 or more data source code
generations, may also exist under ESConfig/datasource/gens/common
Templates for 3 common component code gen methods (genCstmDBObject,

genCstmRespObject, and genCstmRespMultiObject) can be found under the
templates directory at ESConfig/datasource/gens/templates. It is important to
note that although there can be many different custom methods created and
supported in the generated code, there can only be 1 customized method of each
of the above genCstm* methods.
33
3.1.2.1 XML Syntax
The XML syntax for a <Data Source>Gen.xml files is as follows:

<definition xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
[Required] One <definition> tag entry allowed.
Unless otherwise noted, all elements listed below are required.
<table>
One <table> entry allowed per configuration file.
<name>
Contains the name of table or file in data source. For
BASE24-eps, this is the assign name equivalent of the data
source as implemented under DALCI/SIS (i.e. Context
Configuration (ctxcd) would be CONTEXT_CONFIGURATION).
</name>
<columns>
One <columns> entry allowed per <definition> configuration
file.
<column>
Multiple <column> entries allowed, 1 per each column.
The <column> tag also supports the following attributes:
noUpshift = "true (default) | false”
The noUpshift attribute identifies if data should be

upshifted prior to being modified in a data source
and prior to sending data back in a response. This
attribute controls upshifting at the column level,
but is controlled globally by the config.properties
setting of db.upshiftdata. It also only applies to
columns with a <javatype> of string.
maintTS = "true | false (default)”
The maintTS attribute identifies a column as a last

maintenance timestamp column. This only applies to
a column with a <javatype> of timestamp. There can
only be 1 maintTS column per data source generation
file.
noUpdate = "true | false (default)”
The noUpdate attribute identifies a column to NOT be

processed in the generated SQL UPDATE statement.
This handles scenarios where a UIS implementation
for a data source must recognize all columns, but
yet not update all of them as some columns may only
specifically be modified by other batch and/or
online applications. In those cases, the columns
should be indicated in the appropriate data source
generation file with this attribute specified and
34
set to true. This specification should NOT be put
on primary key columns as they are not updateable by
default. Doing so will disable usage of
<sqldefault> settings for primary key columns.
pad = "true | false (default)”
The pad attribute identifies a column to be padded

with trailing spaces when formatting return data.
The ComponentGenerator uses this attribute for
generating the data component. If this attribute is
set to true, the <sqltypesize> tag must be supplied
for the column with a value. This attribute also
only applies to String data.
<colnumber>
Contains the numeric column or field identifier.
Must start at 0 and increment by 1 for each
subsequent <column> entry.
</colnumber>
<logicalname>
Internal data name applied to this column or field.
BASE24-eps Note: Naming conventions for this column

should follow <data source short name – lower case>
followed by mixed Java case of the <physical name>
excluding special characters (i.e. _, ., etc.) and
opting for readable terms as space allows – when
being space conservative, follow BASE24 abbreviation
guidelines.
</logicalname>
<physicalname>
Identifies actual table/file column/field name.
</physicalname>
<javatype>
Identifies internal Java data type of this column or
field. Valid types are (lower-case required):
boolean
byte[]
double
float
int
long
short
string
string_no_trim
timestamp
</javatype>
35
<sqltypesize>
[Optional] Used by the ComponentGenerator. Required
if the pad attribute was specified for the column
and set to true. If <javatype> is defined as String
or a type that requires a size value (i.e. (32)),
the numeric size should be indicated with this
element.
</sqltypesize>
<sqldefault>
[Optional] Used by the ComponentGenerator to
establish data validation checks. Contains default
value of this column or field as used by the data
source. Valid values are:
NULL
NOT NULL (default if this element is not
supplied)
Or specific value (i.e. 1234; encasing quotes
should NOT be supplied)
</sqldefault>
</column>
</columns>
<prikey>
One <prikey> entry allowed per configuration file.
<colnumber>
Contains column number, from <columns> group, included
in primary key. Multiple entries are allowed but they
must be in desired key order.
</colnumber>
</prikey>
</table>
<abbreviation>
Contains an abbreviation for the table or file. One
<abbreviation> entry allowed per configuration file. For
BASE24-eps, this value should be set to the short DDL name of
the data source (i.e. for Context Configuration this would be
ctxcd). This is used to name element map and message elements
files under ESConfig/elmtmaps and ESConfig/schemas/lib
respectively. This value should also match the gens directory
name and the prefix portion of the *Gen.xml file name.
</abbreviation>
<constants>
One <constants> group allowed per configuration file.
<file>
Contains the package location of a constant file (i.e.
com.aciworldwide.CommonConstants) to be included in the
generated code. Multiple <file> entries are allowed and
will be included as import statements in both Component and
Service generated code.
</file>
</constants>
<service>
36
One <service> group allowed per configuration file.
<name>
Contains the name of the data source service to be
generated.
</name>
<package>
Contains the Java qualified package location where the
generated data source service code will be placed (i.e.
es.server.datasource.database).
</package>
<type>
Contains the type of service to be generated. Valid values
are:
static [default; requires <table><name> tags and value to

be present; SQL statements will focus on single data
source]
dynamic [ignores any <table><name> setting; SQL
statements will process according to supplied data source
name (provided during instantiation of database service)]
both [requires <table><name> tags and value to be present
for static processing; SQL statements will process
according to supplied data source name (provided during
instantiation of database service with supplied name) or
according to default table name (if database service is
instantiated with no supplied data source name)]
</type>
<suffix>
[Optional] If present, identifies a standard suffix value
that will be appended to the standard INSERT, DELETE,
SELECT, and UPDATE statements generated. Only one <suffix>
entry allowed.
</suffix>
</service>
<component>
One <component> group allowed per configuration file.
<name>
Contains the name of the data source component to be
generated.
</name>
<package>
Contains the Java qualified package location where the
generated data source service code will be placed (i.e.
es.server.datasource).
</package>
</component>
<commonfunctions>
[Optional] One <commonfunctions> group allowed per
configuration file. If not specified, no add, delete, or
update methods will be generated.
<add suffix = “true | false (default)”>
37
[Optional] Set to true to indicate add functionality should
be provided in component and service.
If suffix attribute is specified and set to true, then the

supplied <suffix> value from the <service> group will be
appended to the standard generated INSERT statement.
</add>
<addmulti>
[Optional] Set to true to indicate multi-add functionality
should be provided in component and service.
</addmulti>
<delete suffix = “true | false (default)”>

[Optional] Set to true to indicate delete functionality

appended to the standard generated DELETE statement.
</delete>
<deletemulti>
[Optional] Set to true to indicate multi-delete
functionality should be provided in component and service.
</deletemulti>
<getcolinfo>
[Optional] Set to true to indicate getcolinfo functionality
</getcolinfo>
<readnext>
[Optional] Set to true to indicate that a full primary key
read next capability should be provided in component and
service. This should only be used if the primary key has
more than 1 key field AND progressive read nexts are
required (i.e. x number of rows at a time with last key data
sent in subsequent requests).
</readnext>
<update suffix = “true | false (default)”>

[Optional] Set to true to indicate update functionality

appended to the standard generated UPDATE statement.
</update>
<updatemulti>
[Optional] Set to true to indicate multi-update
functionality should be provided in component and service.
</updatemulti>
</commonfunctions>
<deleteby>
[Optional] One <deleteby> group allowed per configuration file.
38
<entry>
Multiple <entry> groups are allowed for <deleteby>.
<name>
Contains the name that will be appended to the generated
method name:
deleteBy<name> for generated component code

deleteBy<name> for generated service code
</name>
<multi>
[Optional] Set to true to indicate multi-delete
functionality should be provided in component and
service for this deleteBy entry.
<multi>
<wherecolumns>
One <wherecolumns> group allowed per <entry>.
<colnumber <attribute> = “<value>”>

Contains the column number, from table <columns>
group, to include in this specific delete instance.
Multiple <colnumber> entries are allowed and will be
used in param list and SQL query construction.
Refer to the WHERE clause discussion in the sub-

section following this sub-section.
</colnumber>
</wherecolumns>
<suffix>
[Optional] Contains additional SQL requirements that
will be appended to the SQL query generated. One
<suffix> group allowed per <entry>.
</suffix>
</entry>
</deleteby>
<fetchby>
[Optional] One <fetchby> group allowed per configuration file.
<entry>
Multiple <entry> groups are allowed for <fetchby>.
<name>
Name to be appended to the generated method name:
getBy<name> for generated component code

fetchBy<name> for generated service code
</name>
<timestampcolumn>
[Optional] Indicates the Timestamp column number, from
<columns> group, to use for ‘>=’ and ‘<’ time checks in
WHERE clause.
39
If <wheresets> are being configured, the value provided
by this tag will be applied to ALL <wheresets>
configured.
</timestampcolumn>
<orderbycolumns>
[Optional] One <orderbycolumns> group allowed per
<entry>.
<colnumber>
Contains the column number, from <columns> group, to
include in this specific fetch by instance.
used in an ORDER BY clause that will be appended to
the generated SQL statement.
</colnumber>
</orderbycolumns>
<retrievecolumns>
[Optional] One <retrievecolumns> group allowed per
<entry>.
<colnumber distinct = “true | false (default)”>

used to identify the column retrieval list for the
generated SQL SELECT statement. If a
<retrievecolumns> group is not provided for an
<entry>, all columns will be included in the
retrieval list.
The distinct attribute is used to identify if this

specific column should have the SQL DISTINCT
identifier applied to it.
</colnumber>
</retrievecolumns>
<wherecolumns>
[Optional] One <wherecolumns> group allowed per <entry>.
Not allowed if <wheresets> is present.

used in the WHERE clause of the generated SQL
statement.

</colnumber>
</wherecolumns>
<wheresets>
[Optional] One <wheresets> group allowed per <entry>.
Not allowed if <wherecolumns> is present.
<entry>
40
Multiple <entry> groups are allowed for <fetchby>.
<name>
Extension name of <wheresets> entry.
</name>
<orderbycolumns>
[Optional] see <orderbycolumns> definition above.
<colnumber>
...
</colnumber>
</orderbycolumns>
<retrievecolumns>
[Optional] see <retrievecolumns> definition
above.
<colnumber distinct = “true | false (default)”>

...
</colnumber>
</retrievecolumns>
<wherecolumns>
[Optional] see <wherecolumns> definition above.

...
</colnumber>
</wherecolumns>
<suffix>
[Optional] see <suffix> definition below.
</suffix>
</entry>
</wheresets>
<suffix>
will be appended to the SQL query generated (i.e. GROUP
BY fld1). One <suffix> group allowed per <entry>.
</suffix>
</entry>
<grouping>
Multiple <grouping> groups are allowed for <fetchby>.
<name>
getBy<name> for generated component code

</name>
<method1>
Name of first fetchBy method to use in logic processing.
Do not specify fetchBy as part of name; only specify
<name> value from specific fetchBy entry configured.
</method1>
<method2>
41
Name of second fetchBy method to use in logic
processing. Do not specify fetchBy as part of name;
only specify <name> value from specific fetchBy entry
configured.
</method2>
<colnumber>
Contains the column number, from table <columns> group,
to include in this specific grouping. Multiple
<colnumber> entries are allowed and will be used in the
conditional list generated.
</colnumber>
</grouping>
</fetchby>
<updateby>
[Optional] One <updateby> group allowed per configuration file.
<entry>
Multiple <entry> groups are allowed for <updateby>.
<name>
updateBy<name> for generated component code

updateBy<name> for generated service code
</name>
<multi>
[Optional] Set to true to indicate multi-update
functionality should be provided in component and
service for this updateBy entry.
<multi>
<setcolumns>
[Required] One <setcolumns> group allowed per <entry>.
<colnumber>
include in this specific order by set instance.
used to identify the column set list for the
generated SQL UPDATE statement.
By default, the use of <updateby> will not impact or

use maintenance timestamps in the SET or WHERE
clauses of the generated SQL statement. If
maintenance timestamp(s) are to be updated, you must
provide the appropriate setting of the field in
question in an extended formatter class and you must
include that maintenance timestamp field in the
<setcolumns> list.
</colnumber>
</setcolumns>
<wherecolumns>
[Optional] One <wherecolumns> group allowed per <entry>.
42
include in this specific update by instance.
used in the WHERE clause of the generated SQL
statement.

</colnumber>
</wherecolumns>
<suffix>
will be appended to the SQL query generated. One
<suffix> group allowed per <entry>.
</suffix>
</entry>
</fetchby>
<compcodeblock>
[Optional] Used by ComponentGenerator to generate component
code. One <compcodeblock> group allowed per configuration
file.
<import>
[Optional] One <import> group allowed per <compcodeblock>.
<value>
Multiple <value> entries are allowed per <import> group.
Each entry identifies a Java import statement to include
in generated service code. For example:
import java.sql.Timestamp;
</value>
<include>
Multiple <include> entries are allowed per <import>
group. Import statements can be be placed in a jcf file
and included in the code generation. The <include>
should specify the relative file/directory location that
will be appended to the config.home property from the
config.properties file.
</include>
</import>
<static>
[Optional] One <static> group allowed per <compcodeblock>.
<include>
Multiple <include> entries are allowed per <static>
group. Private static global variables should be placed
in a jcf file and included in the code generation. The
<include> should specify the relative file/directory
location that will be appended to the config.home
property from the config.properties file.
</include>
</static>
<code>
[Optional] One <code> group allowed per <compcodeblock>.
43
<include>
Multiple <include> entries are allowed per <code> group.
Each entry identifies code to be included in the
generated service; the code should exist in a jcf file.
Each custom method provided should reside in its own jcf
file and should include the physical source code to be
added including comments, blank lines, and code. The
</include>
</code>
<gendbcode>
[Optional] One <gendbcode> group allowed per
<compcodeblock>.
<include>
One <include> entry is allowed per <gendbcode> entry.
The entry identifies code to be included in the
generated service; the code should exist in a
genCstmDBObject.jcf file. The custom gen method
provided should include the physical source code to be
property from the config.properties file. A skelton
genCstmDBObject.jcf file is provided in the templates
directory as indicated earlier.
</include>
</gendbcode>
<genrespcode>
[Optional] One <genrespcode> group allowed per
<compcodeblock>.
<include>
One <include> entry is allowed per <genrespcode> entry.
The entry identifies code to be included in the
genCstmRespObject.jcf file. The custom gen method
genCstmRespObject.jcf file is provided in the templates
directory as indicated earlier.
</include>
</genrespcode>
<genrespmulticode>
[Optional] One <genrespmulticode> group allowed per
<compcodeblock>.
<include>
One <include> entry is allowed per <genrespmulticode>
entry. The entry identifies code to be included in the
44
genCstmRespMultiObject.jcf file. The custom gen method
genCstmRespMultiObject.jcf file is provided in the
templates directory as indicated earlier.
</include>
</genrespmulticode>
</compcodeblock>
<svccodeblock>
[Optional] Used by ServiceGenerator to generate service code.
One <svccodeblock> group allowed per configuration file.]
<import>
[Optional] One <import> group allowed per <svccodeblock>.
<value>
Multiple <value> entries are allowed per <import> group.
Each entry identifies a Java import statement to include
in generated service code. For example:
import java.sql.Timestamp;
</value>
<include>
Multiple <include> entries are allowed per <import>
group. Import statements can be be placed in a jcf file
and included in the code generation. The <include>
should specify the relative file/directory location that
will be appended to the config.home property from the
config.properties file.
</include>
</import>
<static>
[Optional] One <static> group allowed per <svccodeblock>.
<include>
Multiple <include> entries are allowed per <static>
group. Private static global variables should be placed
in a jcf file and included in the code generation. The
</include>
</static>
<code>
[Optional] One <code> group allowed per <svccodeblock>.
<include>
Multiple <include> entries are allowed per <code> group.
Each entry identifies code to be included in the
generated service; the code should exist in a jcf file.
Each custom method provided should reside in its own jcf
45
file and should include the physical source code to be
</include>
</code>
</svccodeblock>
</definition>
46
3.1.2.2 <wheresets> Usage
To reduce the amount of generated code when numerous, similar <fetchby> entries
are configured in a *Gen.xml file, support for a <wheresets> tag group has been
provided.
A <wheresets> is a candidate for usage if multiple fetch by statements are configured

where the <retrievecolumns> data is the same across the statements. Rather than
generate a unique set of methods for each fetch by set, <wheresets> can be
configured to provide a single fetch by method that will handle all variations of the SQL
processing dynamically. After configuration of the *Gen.xml file is complete and the
component and service have been generated and deployed for testing, the only
additional requirement is that the transmap entries that will reference the dynamic
method be updated to provide the additional method attribute of whereset=….
3.1.2.3 WHERE Clause Attributes
Standard WHERE clauses primarily consist of equals (=) checks and ‘AND’
processing. Custom WHERE clauses can be generated by using any of the following
<attribute>s = “<value>” options:
Parenthesis
lp = # [generates # number of left parens '(']
rp = # [generates # number of right parens ')']
Equalities
eq = true [default; provides ‘=’ check]
gt = true [provides ‘>’ check]
gte = true [provides ‘>=’ check]
lt = true [provides ‘<’ check]
lte = true [provides ‘<=’ check]
ne = true [provides ‘!=’ check]
like = true [provides SQL LIKE clause; provides wild-card search

capability (SQL wild-card rules must be followed)]
Conditionals
and = true [default; provides SQL AND clause]
or = true [provides SQL OR clause]
Note: Only 1 'eq', 'gt', 'gte', 'lt', 'lte', ‘ne’, or 'like' can be used for each <colnumber>
entry.
Note: Both lp and rp can be used in the same <colnumber> entry.
Note: Only 1 'and' or 'or' can be used for each <colnumber> entry.
47
Example Usage
The desired WHERE clause of an SQL SELECT that looks like this:
SELECT *
FROM tableA
WHERE ( ( fieldA > ? ) OR
( fieldB <= ? ) )
would be configured in the <wherecolumns> as:

<wherecolumns>
<colnumber lp = “2” rp = “1” gt = “true”
or = “true”>0</colnumber>
<colnumber lp = “1” rp = “2”
lte = “true”>1</colnumber>
</wherecolumns>
Note: For data sources managed under DALCI/SIS/MetaMan, the use of ‘lp’, ‘rp’,
‘like’, and ‘or’ are not supported as DALCI/SIS does not support processing for “or”,
parens, and “like” at this time. For true SQL-based data sources, these options can be
used.
3.1.2.4 DALCI Restrictions
DALCI has the following restrictions in place that must be observed when creating
*Gen.xml files for data sources that can/will be managed by DALCI/SIS:
No support of parenthesis (lp and rp options)

No support for “like” option
No support for “or” option
No support for join logic
No support for table views; representation must be for actual physical tables
Support requirements for any of the above restrictions must be provided for in custom
code (*.jcf methods, additional business components, etc.) at this time.
3.1.2.5 Example Configuration
The following is an example <Data Source>Gen.xml for a data source:

<definition xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<table>
<name>ctxcd</name>
<columns>
<column>
<colnumber>0</colnumber>
<logicalname>ctxcdProfile</logicalname>
<physicalname>ctx_prfl</physicalname>
<javatype>string</javatype>
<sqltypesize>16</sqltypesize>
<constraint>ProfileType</constraint>
</column>
<column>
48
<logicalname>ctxcdServerContext</logicalname>
<physicalname>LastUpdtTm</physicalname>
<javatype>timestamp</javatype>
<constraint>ServerContextType</constraint>
</column>
<column>
<logicalname>ctxcdDataSourceAssign</logicalname>
<physicalname>ctx_asgn_nam</physicalname>
<sqldefault>NULL</sqldefault>
<constraint>DataSrcAsgnType</constraint>
</column>
<column>
<logicalname>ctxcdComments</logicalname>
<physicalname>descr</physicalname>
<constraint>CommentsType</constraint>
</column>
</columns>
<prikey>
</prikey>
</table>
<abbreviation>ContextCfg</abbreviation>
<constants>
<file>es.server.ESConstants</file>
</constants>
<datavalidation>true</datavalidation>
<service>
<name>ContextCfgService</name>
<package>es.server.datasource.database</package>
</service>
<component>
<name>ContextCfgComponent</name>
<package>es.server.datasource</package>
</component>
<commonfunctions>
<add>true</add>
<addmulti>false</addmulti>
<delete>true</delete>
<deletemulti>false</deletemulti>
<update>true</update>
<updatemulti>false</updatemulti>
</commonfunctions>
</definition>
49
4. BASE24-eps UIS XML Schemas
XML schemas are prevalent throughout UIS for providing the following items:
Request/Response Message Definitions

Data Validations
Each of these areas will be discussed in the following sub-sections.
4.1 Request/Response Message Definitions
Message processing in the BASE24-eps UI environment is supported by XML

messages. UIS has gone to great extents to improve upon the use of XML Message
Schemas as a processing mechanism rather than just a source of documentation. This
has allowed the environment to be architected in a generic fashion with the ability to
configure and process request/response messages with practically little to no extra
coding.
To accomplish the improved use of XML schemas in this environment, however, has
meant that a more rigid hierarchy of rules and relationships be put into place. This was
necessary to help ensure the integrity of XML usage and to help maintain the generic
ability of the processing components.
The hierarchy of XML Schema Definitions that has been put into place is as follows:
Data Type Schema Definitions

Element/Group Schema Definitions
Message Schema Definitions
The layers of definitions, beginning with the low level Data Type Definitions and working
up through the high level Message Schema Definitions, are intended to be building
blocks of each other and to enable better extensibility for custom work.
These definition areas will be discussed in the following sub-sections.
50
4.1.1 Data Type Schema Definitions
The lowest level of the XML Schema Definitions consists of Data Type Schema
Definitions. Data type schema definitions define data items, their type, and any
restrictions to apply to them such as lengths, ranges, or enumerations to name a few.
4.1.1.1 Rules
The following rules and guidelines must be adhered to when creating data type
definitions:
1. Every data type definition must be an <xsd:simpleType>.
2. Every message element defined in request/response message formats must be an

extension of a lower level data type definition.
3. Every XML simple type specified must closely match the underlying data source data
type if the element is to be stored in a database.
4. Every data type definition must be a restriction of any type found in Section 8.1 or an
extension of any other previously defined data type definition.
5. When extending existing data types, restriction facets cannot be looser than they
have been defined in the base data type. For example, if the base data type has
defined a restriction facet for maxLength of say 16 characters, then data types that
extend this type cannot set the same restriction facet greater than 16 characters;
they can only restrict the facet further (i.e. go less than 16). The maximum depth of
data type extension supported is 5 levels.
6. Data type definitions in one file can extend data types found in another file, but
require the inclusion of
7. Naming conventions must be adhered to as follows:
[Product].[Std/CSM].[Data type].[Name/generalization].[Name]
where:
[Product] is set to one of the current products supported:
ES – for ESXMLDataTypes.xsd entries

ATMF – for ATMXMLDataTypes.xsd entries
[Std/CSM] is set to either Std (for product data types contained in

ESXMLDataTypes.xsd or ATMXMLDataTypes.xsd files) or CSM (for
customized data types contained in a CSMXMLDataTypes.xsd file).
[Data type] is set to the appropriate XML data type represented such as
Integer, Long, Short, or String.
51
[Name/generalization] is set to either a final data type name, if it is unique, or
a generalization if dealing with any of the following examples:
Enum
Range
Size
[Name] is set to a final data type name if a generalization identified above is

used.
With the exception of the final [Name] part, all other parts of a data type name are
required.
8. Best Practices:
For data defined as no leading or embedded spaces, use a pattern of:
<xsd:pattern value="[^\s]+"/>
Avoid defining data to element mappings in Gen.xml files or message schema

files that simply map to a Generic. Every data validation performed should at a
minimum include size (for string values) or range checks (for numeric values).
52
4.1.1.2 XML Syntax
The XML syntax for data type definition entries is as follows:
<xsd:schema id=[] xmlns:xsd=http://www.w3.org/2001/XMLSchema>

[Required] One <xsd:schema> tag entry allowed per data type
definition file.
The id=[] attribute is optional, but highly recommended and should

specify a unique name ([]) for the schema file. This will help
resolve conflicts in the element/group definition file where a data
type may be defined in more than 1 data type schema definition file.
The xmlns:xsd attribute is required and must specify the year

version of the XML Schema namespace to be applied to this schema.
The value listed above is the current supported level, 2001, by the
UIS implementation.
<xsd:include schemaLocation = “<name>”/>

[Optional] This identifies the relative URI file location of
the data type schema definition file to be applied to this data
type schema definition file. Multiple schema location entries
are allowed, but if a data type definition appears in more than
1 of these files, then the desired XML could become invalid.
The value of the config.properties file entry of config.home
will be used to resolve the relative URI. This item is
required if any of the data types in the current file extend
other data types that exist in separate data type schema
definition files.
<xsd:simpleType name = “<name>”>
[Required] This identifies a data type entry and gives it a
name in the name attribute. See Rule 7 above regarding naming
of an <xsd:simpleType>. Multiple <xsd:simpleType> entries are
allowed per schema definition library file.
<xsd:restriction base = “xsd:<XML Simple Type >”>

[Required] This identifies the XML Simple Type associated
with the <xsd:simpleType> entry. The type of data is
specified in the base attribute. Valid XML Simple Types are
located in Section 8.1. One <xsd:restriction> tag entry is
allowed for each <xsd:simpleType> group.
<xsd:[restriction]>
[Required] Must contain a type of restriction to apply
to this simple type. Multiple restrictions can be
applied to a simple type. The valid [restriction]
values, and the types they can be assigned to, are
indicated in the table in Section 8.1. The overall list
of XML restrictions supported includes:
53
enumeration minExclusive
fractionDigits maxInclusive
length minInclusive
maxLength pattern
minLength totalDigits
maxExclusive whiteSpace
</xsd:restriction>
</xsd:simpleType>
</xsd:schema>
54
4.1.1.3 XML Examples
The following is an example of a data type schema definition file:

<xsd:schema xmlns:xsd=http://www.w3.org/2001/XMLSchema>

<xsd:simpleType name="ES.Std.Integer.Generic">
<xsd:restriction base="xsd:integer"/>
</xsd:simpleType>
<xsd:simpleType name="ES.Std.Integer.Range.0To999">
<xsd:restriction base="ES.Std.Integer.Generic">
<xsd:minInclusive value="0"/>
<xsd:maxInclusive value="999"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="ES.Std.Long.Generic">
<xsd:restriction base="xsd:long"/>
</xsd:simpleType>
<xsd:simpleType name="ES.Std.Short.Generic">
<xsd:restriction base="xsd:short"/>
</xsd:simpleType>
<xsd:simpleType name="ES.Std.Short.Range.0To1">
<xsd:restriction base="ES.Std.Short.Generic">
<xsd:minInclusive value="0"/>
<xsd:maxInclusive value="1"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="ES.Std.String.Enum.0To1">
<xsd:restriction base="ES.Std.String.Generic">
<xsd:enumeration value="0"/>
<xsd:enumeration value="1"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="ES.Std.String.Generic">
<xsd:restriction base="xsd:string"/>
</xsd:simpleType>
<xsd:simpleType name="ES.Std.String.HexType">
<xsd:pattern value="[0-9A-Fa-f]+"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="ES.Std.String.Size.0To1">
<xsd:minLength value="0"/>
<xsd:maxLength value="1"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="ES.Std.String.Size.0To1NoES">
55
<xsd:restriction base="ES.Std.String.Size.0To1">
<xsd:pattern value="[^\s]+"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:schema>
56
4.1.2 Element/Group Schema Definitions
The next level of the XML Schema Definitions consists of Element/Group Schema
Definitions. These definitions build upon the data type schema definitions by defining
usable element and group names.
4.1.2.1 Rules
The following rules and guidelines must be adhered to when creating element and group
definitions:
1. Every definition must be an <xsd:element> or an <xsd:group>.
2. Every <xsd:element> definition must be of a type that is defined in a data type

schema definition file.
3. There are no additional rules for naming element/group entries other than to follow
Java conventions and ACI guidelines.
4. An <xsd:group> serves as a library reference within the context of the schema; a

logical grouping of elements and/or other groups. To obtain a true grouping with an
XML message, with group-like tags, define an <xsd:element> as a complexType
with sub-definitions for other elements, groups, choices, and/or sequences.
5. Element groups MUST appear in the XML messages received and sent by the
system.
6. When naming <xsd:group> entries, please attach a suffix of Group to the end of
the name.
7. Configurations for complex <xsd:element> definitions can consist of the following

ordering types:
<xsd:choice> : Multiple <xsd:element> entries can be configured under a
choice directive, but only the first <xsd:element> entry found will be processed.
The entries must be specified in the order of greatest importance to least
importance.
<xsd:sequence> : All contained <xsd:element> entries must be in the desired
sequence order.
The current environment does NOT support <xsd:all>.
57
8. The following XML tag setting:
<xsd:annotation>
<xsd:appInfo>appName</xsd:appInfo>
</xsd:annotation>
where appName is:
[Optional] This setting should be specified for those instances where element
names are not unique within a message and reside under 2 or more groups. If
this value is present, the message formatter will append the group name to all
immediate element names and place the associated value in the internal data
object. The message formatter will also look for this combined name internally in
order to properly build response messages. This setting only applies 1 level
deep (to the immediate group’s elements and must be reflected on
request/response message sets faced with multiple common element names.
Additionally, the combined group/element name must be reflected in the
appropriate <Data Source>Gen.xml file, but does NOT need to be reflected in
any XML elements definition file; only the distinct group name and distinct
element names must appear in an XML elements file.
Note: These rules apply to element/group definitions placed either in a specific

elements/group XSD files under ESConfig/schemas/lib or in a message schema
definition files under ESConfig/schemas/message (Section 4.1.3).
BASE24-eps Note: The ComponentGenerator will create data source specific

element files under ESConfig/schemas/lib during code generation. The format of these
elements files will adhere to the guidelines outlined in this sub-section. The files will
contain element entries whereby the name attribute is set according to the
<logicalname> tag value and the type attribute is set according to the <constraint> tag
value. The files will be named as <Data Source (caps)>Elements.xsd. References to
these files should then be made as xsd:include statements within the relative message
schema definition files.
58
4.1.2.2 XML Syntax
The core XML syntax for the element/group definition file is as follows:
[Required] One <xsd:schema> tag entry allowed per element/group
definition file. The xmlns:xsd attribute is also required and must
specify the year version of the XML Schema namespace to be applied
to this schema. The value listed above is the current supported
level, 2001, by the UIS implementation.

[Required] This identifies the relative URI file location of
the data type schema definition file to be applied to this
element/group definition file. Multiple schema location
entries are allowed, but if a data type definition appears in
more than 1 of these files, then the desired XML could become
invalid. The value of the config.properties file entry of
config.home will be used to resolve the relative URI.
</xsd:schema>
The XML syntax for element definition entries is as follows:
<xsd:element name = “<name>” type = “<type>”/>

[Required] This identifies a usable XML element and gives it a
name in the name attribute and an associated data type in the
type attribute. Element names must be unique within an
element/group schema definition file.
The XML syntax for group definition entries is as follows:
<xsd:group name = “<name>”>

[Required] This identifies a group entry and gives it a name in
the name attribute. Group names must be unique within an
element/group schema definition file.
<xsd:choice> or
<xsd:sequence>
[Required] The group must be defined as an xsd:choice or an
xsd:sequence entry. See applicable rules listed prior in
Section 4.1.2.1. One primary type of identification is
allowed per <xsd:group>, but there can be further embedded
<xsd:choice> or <xsd:sequence> entries below the primary.
</xsd:choice> or
</xsd:sequence>
<xsd:element name = {“<name>” or ref = “<ref>”}>

[Required] This identifies the XML element to be used as
part of this group definition. The XML element referenced
(ref) must be defined in the current file with an
<xsd:element> entry. When naming (name) a new
<xsd:element>, a reference attribute (ref) is not required.
</xsd:element>
</xsd:group>
59
The following is an example of the ESXMLCommonElements.xsd schema definition

file:
<xsd:include schemaLocation = "ESXMLDataTypes.xsd"/>

<xsd:element name = "AuthorizationID"

type = "AuthorizationIDType"/>
<xsd:element name = "ErrCode" type = "ErrCodeType"/>
<xsd:element name = "ErrIndex" type = "ErrIndexType"/>
<xsd:element name = "FieldID" type = "FieldIDType"/>
<xsd:element name = "SessionNumber" type = "SessionNumberType"/>
<xsd:element name = "TerminalID" type = "TerminalIDType"/>
<xsd:element name = "UserID" type = "UserIDType"/>

<xsd:group name = "ErrorGroup">

<xsd:sequence>
<xsd:element name = "Error">
<xsd:annotation>
<xsd:appInfo>appName</xsd:appInfo>
</xsd:annotation
<xsd:complexType>
<xsd:sequence>
<xsd:element ref = "ErrCode"/>
<xsd:element ref = "ErrDescr"/>
<xsd:element ref = "ErrIndex"/>
<xsd:element ref = "FieldID"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:group>
<xsd:group name = "TicketGroup">

<xsd:sequence>
<xsd:element name = "Ticket">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref = "UserID"/>
<xsd:element ref = "SessionNumber"/>
<xsd:element ref = "TerminalID"/>
<xsd:element ref = "AuthorizationID"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:group>
</xsd:schema>
60
4.1.3 Message Schema Definitions
The top level of the XML Schema Definitions consists of Message Schema Definitions.
These definitions build upon the element/group schema definitions by defining usable
request/response message elements.
4.1.3.1 Rules
The following rules and guidelines must be adhered to when creating message
definitions:
1. Elements used must exist in either the message schema file itself or in
element/group schema definition file(s) under ESConfig/schemas/lib.
2. All rules from Section 4.1.2 apply to element/group definitions placed in a message
3. XML message layouts can consist of element and groups. All elements and group
elements are handled as single level elements; except for multi-occur elements and
multi-occur groups that are handled as multi-row element sets.
4. The XML tag <xsd:element> can specify an optional default attribute and value to
use when the actual element is not found in the request or response information.
Example default configuration:
<xsd:element ref = "Comments" default = “No comments provided.”/>
5. Any element or group encountered in an inbound request message that is not

defined in the message element definition will be ignored.
6. All last update timestamp information within the BASE24-eps environment will be
returned in a ServerContext-like XML element. This element will be returned in
response messages typically resulting from fetch, insert, and update actions. For
delete and update requests, the requesting UI must typically pass last update
timestamp information to the UIS implementation in a ServerContext-like element
containing the previously received timestamp information. Failure to do this could
result in denied actions because of timestamp mismatches. The naming of the
actual element is recommended that the data source name (i.e. ctxcd, csecd, etc.)
be pre-appended to the element name (i.e. ctxcdServerContext) so that multiple data
source UIs do not encounter issues with multiple, same name ServerContext fields.
7. All BASE24-eps response messages will contain a RespStat attribute in the root tag
that identifies the success or failure of the requested action(s). Supported values are
discussed in Section 8.2.
61
8. Data validation and field requirement errors encountered in the UIS implementation
will be returned to the requesting UI with specific error group tagging as discussed in
the next sub-section. In these cases, the RespStat attribute should contain the
overall processing error and specific field errors will be included under the error
group information.
9. All request element definitions must end in the suffix Rq. All response element
definitions must end in the suffix Rs. The allowed combination is therefore Rq/Rs.
XML tags of <xsd:choice>, <xsd:sequence>, <xsd:element>, and <xsd:group>
can all use minOccurs and maxOccurs as follows:
minOccurs
[Optional] This setting identifies the minimum number of occurrences that will be
supported for the respective XML tag. Valid values start from 0. The value of
unbounded for this setting is not supported. If this setting is not specified, a default
value of 0 is assumed; this makes the XML tag entry optional. For <xsd:choice>, this
will control the suppression of warning messages on response message generation
when no data elements were found in the message and this option is set to 0.
Additionally, it will only apply to top-level <xsd:choice> tags; if an <xsd:choice> is any
descendent of an <xsd:group>, the minOccurs setting will not apply.
maxOccurs
[Optional] This setting identifies the maximum number of occurrences that will be
supported for the respective XML tag. Valid values start from 1. The value of
unbounded is supported for this setting. If this setting is not specified, a default value of
1 is assumed. Currently, this does not apply to <xsd:choice>.
Example minOccurs and maxOccurs configuration:
<xsd:group ref = "ErrorGroup" minOccurs = "0"

maxOccurs = "unbounded"/>
62
4.1.3.2 XML Syntax
The core XML syntax for a message schema definition file is as follows:
[Required] One <xsd:schema> tag entry allowed per message schema
definition file. The xmlns:xsd attribute is also required and must
specify the year version of the XML Schema namespace to be applied
to this schema. The value listed above is the current supported
level, 2001, by the UIS implementation.

[Required] This identifies the relative URI file location of
the element/group schema definition file to be applied to this
message schema definition file. Multiple schema location
entries are allowed, but if an element or group definition
appears in more than 1 of these files, then the desired XML
could become invalid. The value of the config.properties file
entry of config.home will be used to resolve the relative URI.
</xsd:schema>
The XML syntax for element definition entries is as follows:
<xsd:element name = “<name>”>

[Required] This identifies a usable XML element and gives it a
name in the name attribute and an associated data type in the
type attribute. Element names must be unique within a message
<xsd:complexType>
[Required] One <xsd:complexType> tag allowed per
<xsd:element>.
The remainder configuration for a message element can

consist of various combinations of the following XML tags:
<xsd:choice>
<xsd:sequence>
Rules governing these 2 tags are discussed in
Section 4.1.2.1. Ending tags of </xsd:choice> or
</xsd:sequence> must be supplied as required. Use
of min and max occurs is previously discussed under
rules in Section 4.1.3.1.
<xsd:element ref = “name”/>

<xsd:group ref = “name” />
These tags identify low-level element and group
references. The references are established with the
ref attribute providing a name value that exists in
an element/group schema definition file. Use of
defaults and min and max occurs is previously
discussed under rules in Section 4.1.3.1.
<xsd:attribute ref = “name”/ >

The use of this XML tag is currently only for
documentation purposes. All BASE24-eps UI response
63
messages will have a RespStat attribute returned
that identifies the success or failure of the
processed request. Refer to Section 8.2 for valid
response values.
</xsd:complexType>
</xsd:element>
Whenever data validations or field requirement checks fail in the UIS implementation,
error group information will be returned to the requesting UI. Guidelines for error group
XML syntax are as follows:
<xsd:choice>
<xsd:group ref = "ErrorGroup"/>
</xsd:choice>
There can be additional XML tags contained within the bounds of the start and end
<xsd:choice> tags, however, for response message identification, this example
configuration should be the first entry in the response message definition. See the
following sub-section for further examples of this.
64
The following is an example of a message schema definition file:

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:include schemaLocation = "../lib/CTXCDElements.xsd"/>
<xsd:include schemaLocation = "../lib/ESXMLCommonElements.xsd"/>

<xsd:element name = "ContextConfigDeleteRq">
<xsd:complexType>
<xsd:sequence>
<xsd:group ref = "TicketGroup"/>
<xsd:element ref = "ctxcdProfile"/>
<xsd:element ref = "ctxcdServerContext"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name = "ContextConfigDeleteRs">
<xsd:complexType>
<xsd:choice>
</xsd:choice>
<xsd:attribute ref = "RespStat"/>
</xsd:complexType>
</xsd:element>
<xsd:element name = "ContextConfigInsertRq">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref = "ctxcdDataSourceAssign"/>
<xsd:element ref = "ctxcdComments"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name = "ContextConfigInsertRs">
<xsd:complexType>
<xsd:choice>
</xsd:choice>
</xsd:complexType>
</xsd:element>
<xsd:element name = "ContextConfigListRq">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref = "StartKey" minOccurs = "0"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name = "ContextConfigListRs">
<xsd:complexType>
<xsd:choice>
<xsd:element ref = "ctxcdProfile" minOccurs = "0"
maxOccurs = "unbounded"/>
65
</xsd:choice>
</xsd:complexType>
</xsd:element>
<xsd:element name = "ContextConfigUpdateRq">
<xsd:complexType>
<xsd:sequence>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name = "ContextConfigUpdateRs">
<xsd:complexType>
<xsd:choice>
</xsd:choice>
</xsd:complexType>
</xsd:element>
<xsd:element name = "ContextConfigViewRq">
<xsd:complexType>
<xsd:sequence>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name = "ContextConfigViewRs">
<xsd:complexType>
<xsd:choice>
<xsd:sequence>
</xsd:sequence>
</xsd:choice>
</xsd:complexType>
</xsd:element>

<xsd:element name = "Profiles" type = "ProfileType"/>
<xsd:element name = "StartKey" type = "ProfileType"/>
</xsd:schema>
66
4.2 Data Validations
Runtime data validation mechanisms are provided within generated data component
code (refer to Section 3.1.2). Configuration of actual data validations is supported via
the data type schema definition file(s) as discussed previously in Section 4.1.1.
The DataTypeValidatorManager service within UIS provides data type validation

support for the data components and other components requiring validations. The
manager retrieves element-to-constraint mapping information, from element maps found
under ESConfig/elmtmaps or from the *-elmtmaps.jar files, at startup and loads that
information into memory to use during validation processing. This allows the manager to
manage the mappings versus external applications and to provide greater flexibility in
customization requirements without having to modify Gen.xml files and regenerating
data components.
Data validations in the UIS environment are NOT specifically tied to XML message
handling. When the need arises to handle other external message formats (i.e. ISO or
ANSI or other), data validations can still be performed using the same data type schema
definition files. The intent of server-side data validations is to provide a consistent
mechanism for ensuring validations are performed in a common manner across varied
components to ensure proper handling of data elements in the underlying data source.
Through global data type schema definition files, a user has the ability to alter the type or
size or other facet of an existing data type and have the take effect within the
environment.
Customization of the data validations is achieved through the use of the element maps.
During component generation, all constraint mapping information in relation to logical
name elements is written out to element map properties files located under
ESConfig/elmtmaps/<Data Source>Map.properties. If customization of a data type is
required, the user can create a new data type file that extends the existing
ESXMLDataTypes file (if desired), create the new data type, and then create a new,
csmMap.properties file and provide the new element-to-constraint mapping.
67
5. Formatter/Command Configuration
The UIS implementation utilizes a generic formatter/command infrastructure. Both

aspects of this infrastructure will be discussed in the following sub-sections.
5.1 Formatter
The basic principle of the formatter layer is to translate external message data into
internal data objects and then back again.
The UIS implementation provides 2 types of formatters; an ESXMLFormatter (from the

UIS implementation), and a NullFormatter (from the JSF). Use of each will be
discussed in the following sub-sections.
5.1.1 es.server.formatter.xml.ESXMLFormatter
The UIS implementation utilizes a generic XML formatter infrastructure. All request and
response messages are required to be in XML format following the guidelines outlined in
Section 4.
The generic aspect exists in that the primary BASE24-eps XML format handler,
ESXMLFormatter, in conjunction with the UIS MessageSchemaManager service
(using the MessageSchema class) can break down any XML request message into
internal DataObject elements (see Section 8.3), and can format any XML response
message from internal DataObject elements.
By following the configuration guidelines outlined in Section 4, a developer can create

message requirements through message schema definition files. It is recommended
that some order be applied to creating and naming message schema definition files. For
example, guidelines could be such that message schema definition files are created
along UI boundaries, each file containing request/response message formats necessary
for a specific UI to function in this environment. Another guideline could follow other
patterns, but should be consistent with the environment in which the files are being
managed.
BASE24-eps Note: Message schema definition files should be named according to the
<task> values contained within the files that represent individual UIs.
Developing the message layouts and generating the message schema definition files
(and any supporting element/group or data type definition files) is just the first aspect of
the formatter environment.
The next part of the formatter environment involves flow configuration such that the UIS
components can properly access the correct message schema definition file during
processing and be directed to the correct formatter handler (the ESXMLFormatter is the
current default BASE24-eps XML formatter supported, however, other formatters for
other types of message handling could be developed in the future).
68
The specific configuration to assist the formatter processing is maintained in the
<Transaction Map>.xml files; see Section 3.1.1. Within the <Transaction Map>.xml
configuration files, every request message tag that is supported must be configured in
this file to help direct the environment through both formatting and command processing.
In the BASE24-eps environment, when the appropriate adapter receives an incoming

request message, it calls upon the ESFormatterController class to provide formatting
support. The ESFormatterController calls the TransactionMapManager to retrieve a
TransactionMapField object that matches the root request tag of the message
received. If one is not found, an error response will be returned to the caller. Otherwise,
if a TransactionMapField object is found, it will be attached to the internal DataObject
(see Section 8.3) and then used to direct the ESFormatterController to call upon the
correct format handler (as specified by the <Transaction Map>.xml entry of
<formatter><class>class name</class> for the request type); the default being
ESXMLFormatter.
Once the appropriate formatter is called, that formatter will then utilize the UIS
MessageSchemaManager to perform the actual break down of the request message
into values that are placed in the primary DataObject. The rules and actions governing
this break down process were previously discussed in Section 4.1.3.1.
The MessageSchemaManager pre-loads all message schema definition files at

initialization. Each file is broken down and a MessageSchema object is created and
assigned to every internal message element.
Once the command level processing has been performed, the ESFormatterController
and the ESXMLFormatter are again called upon to generically format an XML response
message from data values contained in the primary data object. The
MessageSchemaManager is used to call upon the correct MessageSchema object
(accessed by taking the root request message name and switching the ending Rq to Rs)
that will then attempt to format the response message.
69
5.1.1.1 Message Customization w/ es.server.formatter.xml.ESXMLFormatter
In some instances, it may be necessary to massage incoming data such that it can more
accurately reflect how the underlying data source components or other internal business
components require the data to look. This could include, for example, combining 3
incoming elements into 1 logical element or perhaps generating a length element based
on the size of 1 or more incoming elements.
One ability to provide this support could be at the generated data source component via
the *Gen.xml files. The consideration of this, however, should be limited as messaging
issues could impact the flexibility of the generated component.
The preferred ability to provide support for this data massaging should be with extending
the default formatter and providing customized data handling as necessary.
The ESXMLFormatter class is an extendable class that provides 4 custom exits for
writing data massaging code. Those custom exits and their use are:
cstmBuildRequest
This method should be overridden in the extended class when implementing pass-thru
support whereby the UIS implementation will be formatting and sending requests to an
external entity and the data represented in the primary data object does not reflect all of the
messaging requirements (i.e. additional element names, 1-to-1 mapping of elements, etc.).
Data massaging provided with this method should be done to data contained in the primary
data object and will be done prior to any actual request message building.
cstmBuildResponse
This method should be overridden in the extended class when the UIS implementation will be
formatting and sending response messages to the originating client where the data
represented in the primary data object does not reflect all of the messaging requirements (i.e.
additional element names, 1-to-1 mapping of elements, etc.). Data massaging provided with
this method should be done to data contained in the primary data object and will be done
prior to any actual response message building.
cstmParseRequest
receiving request messages from a client and the data represented in the primary data object
does not reflect all of the internal processing requirements (i.e. additional element names, 1-
to-1 mapping of elements, etc.). Data massaging provided with this method should be done
to data contained in the primary data object and will be done after the original request
message has been parsed.
70
cstmParseResponse
receiving response messages from an external entity and the data represented in the primary
data object does not reflect all of the internal processing requirements (i.e. additional element
names, 1-to-1 mapping of elements, etc.). Data massaging provided with this method should
be done to data contained in the primary data object and will be done after the original
response message has been parsed.
Each of the overridden methods must return a true/false indicator that identifies the
success or failure of the custom processing.
When working with the custom exits, the developer should also be aware that the
custom formatter may process for more than 1 request/response root tag and must take
that into consideration when writing the custom code handling.
The UIS implementation requires that developers adhere to the following conventions:
When extending the ESXMLFormatter class, the new class should simply be called
XMLFormatter.
Placement of the XMLFormatter class created should be under a directory of

es.server.formatter.xml.<directory> where <directory> should be set to the same name
matching the ESConfig/transmaps/<Transaction Map>.xml file name for messages
originating from a specific UI application.
Appropriate changes should then be made to the necessary entries in the

ESConfig/transmaps/<Transaction Map>.xml file to ensure proper message processing.
5.1.2 com.aciworldwide.common.formatter.NullFormatter
The JSF provides a generic NullFormatter. The intent of using the NullFormatter class
should be in cases where straight pass-thru support is required of incoming requests. In
these cases, incoming request messages will not be parsed since the UIS
implementation will not be included in directly processing any of the data. However,
because of the flow of processing through the UIS implementation, a formatter class is
required. Hence, the NullFormatter can be used as the <formatter><class>
specification in the <Transaction Map>.xml request configuration entry.
71
5.2 Command
The UIS implementation provides a generic command infrastructure with multi-level

simple and/or transactional command support. This support is provided at varying levels
as discussed below.
At the first layer of command processing the ability exists to do single command actions
or multi-command actions. The CommandController component is the primary director
of command processing at this level. The CommandController also provides primary
data validation support of data received from any request.
At the next layer, request processing in this environment can be done with simple
commands or transactional commands. The implementation provides 3 support classes,
ESSimpleCommand, ESTransCommand, and ESPassthruCommand. Each of the
command classes should be used as follows:
ESSimpleCommand
This command class should be used for simple component processing that does not require
transactional support (i.e. insurances of data integrity). This would typically be evident of
simple data retrieval actions (i.e. reads or list retrievals). This class should be used only
when the UIS implementation is participating in the workflow. USEC and audit processing
are also supported with this command class.
ESTransCommand
This command class should be used if data integrity is important. This would be the case if
multiple related inserts, deletes, and or updates are being performed; if one action fails, the
entire action set will fail and the data source is returned to its original start state. This class
should be used only when the UIS implementation is participating in the workflow. USEC
and audit processing are also supported with this command class.
ESPassthruCommand
This command class should be used if requests/response processing is to be performed with

an external entity (not the originating client). USEC and audit processing are NOT supported
with this command class. This class will typically be used in conjunction with the
es.server.component.PassthruComponent class. Typical transmap configuration would
consist of a separate <command> set with the specified <class> being set to
es.server.command.ESPassthruCommand. The next <transaction><component> would
then be set to the class of es.server.component.PassthruComponent.
Configuration for command processing is handled in the <Transaction Map>.xml file.

Specifically, command configuration is contained within the start and end <command>
tags. For detailed information regarding configuration options and guidelines, refer to
Section 3.1.1.
Different command configuration scenarios follow.
72
5.2.1 Single Data Source Action
Single data source actions are those where a single action is being performed against a
certain data or business component. The <Transaction Map>.xml configuration file
supports this at the <command> tag level. If a single component is to be acted upon,
then an example tag configuration might be:
<command>
<transaction>
<component>es.server.datasource.ContextCfgComponent</component>
</transaction>
</command>
In the above example, a simple-based command (ESSimpleCommand) will control

command processing. The data component to be acted upon will be the
ContextCfgComponent and the method contained within the data component to be
called will be the add method. Once the action has been performed successfully, the
results will be committed to the data source and the response returned.
The command environment supports multiple, un-related commands by simply

configuring multiple <command> tag sets. Example:
<command>
<transaction>
<method>addMulti</method>
</transaction>
</command>
<command>
<transaction>
</transaction>
</command>
Note: When performing multiple command sets, the command environment will perform
the commands in the order they are represented in the configuration file.
Additionally, the configuration for request processing can include a mix of single data
source processing and multiple data source processing through the configuration of
multiple <command> tag sets. See examples of this in the following topics.
73
5.2.2 Multi-Data Source Action (related)
Multi-data source actions are those where multiple actions are being performed against
1 or more data or business components. The <Transaction Map>.xml configuration file
supports this at the <command> and at the <transaction> tag level. If multiple
components are to be acted upon, then an example tag configuration might be:
<command>
<transaction>
</transaction>
<transaction>
<component>es.server.datasource.PrefixCfgComponent</component>
</transaction>
</command>
In the above example, a transaction-based command (ESTransCommand) will control

all command processing. The data components to be acted upon will be the
ContextCfgComponent (and the add method) and the PrefixCfgComponent (and the
add method). When doing multiple <transaction> tags, the configured class,
ESTransCommand or ESSImpleCommand will control processing flow, performing
each <transaction> tag set in the sequence indicated in the configuration file. So in the
above example, the ESTransCommand will first perform the add method on the
ContextCfgComponent and then, if no errors occur, will perform the add method on the
PrefixCfgComponent. If both actions succeed, a positive response will be returned. If
either action fails in this configuration, then any actions taken will be backed out and a
negative response returned.
5.2.3 Multi-Data Source Action (unrelated)
In the prior example code, for related multi-data source actions, the actions performed
are considered related as far as data integrity is concerned. If the actions to be
performed were not considered related, then the configuration could be depicted as
follows:
<command>
<transaction>
</transaction>
</command>
<command>
<transaction>
</transaction>
</command>
74
In this case, both actions are unique and separate. The CommandController would
manage the processing flow, in this example.
5.2.4 Data Source Action with Continue Conditionals
The ability to help control conditional flow through multiple <command> and/or multiple
<transaction> sets in a <Transaction Map>.xml configuration file is controlled with the
use of <contconditions><code> as previously outlined in Section 3.1.1.
The primary function of the CommandController (for <command>) and

ESTransProcessor (for <transaction>) is to halt processing whenever an error
condition is encountered. There may be occasion, however, when the occurrence of
one or more error conditions within one leg of processing may be acceptable and should
not halt processing. In these cases, it may be desirable to continue processing into the
next set and to reset the error code to null or some chosen value. To do this, continue
conditions can be added to each command or transaction segment to identify what
acceptable conditions may be encountered. So for example, lets say that a data not
found condition in one transaction set may be acceptable and processing should
continue. The transaction map configuration may appear something like:
<command>
<transaction>
<contconditions>
<code reset = “DBS_FILE_OK”>DBS_NOT_FOUND</code>
</contconditions>
</transaction>
<transaction>
</transaction>
</command>
In the above example, a continue conditional was placed on the get processing of the
ContextCfgComponent such that if that action returns a DBS_NOT_FOUND error
condition, the result would be that the error code would be reset to null, a positive
response of DBS_FILE_OK would be placed in a RESP_STAT key/value in the primary
data object, and processing would then continue into the PrefixCfgComponent’s get
method.
Note: It is important to remember that when a continue condition is specified, the error
code will always be reset to either null or the reset attribute code specified (unless the
reset code is an approval code of DBS_FILE_OK or DBS_FILE_EXHAUSTED in which
case the error code is set to null and a RESP_STAT key/value in the primary data object
is used to indicate the approval code).
Note: The code and reset values that are specified must be internal JSF codes, not
BASE24-eps return codes.
75
5.3 Command-Level Filtering
Field-level filtering is supported in the UIS implementation at two distinct levels:

command and database service (discussed in the next section).
The following actions may cause command-level filtering to occur:
¾ Delete
¾ Save (update)
¾ View
When the CommandController, via callback request from ESTransCommand and

ESSimpleCommand, calls upon USEC to verify security authentication and
authorization, the USECIF will identify if field-level filtering is implemented for the current
task. This is identified with APPLCNFG properties for filter.field.<taskid>.#. The
presence of one or more of these properties will provide the information necessary for
the USECIF to extract the field value information from the primary data object and verify
it against filtering data retrieved from the USEC environment. Values that fail filtering
restrictions will result in the request being denied with a Not_Authorized_Filter
response.
This processing will be performed against delete, save (update), and view processing.
At this time, filter processing is not performed on add processing. All add requests from
a UI will be allowed to be performed, however, if the user has no further rights to view,
delete, or update that information they will not be permitted access to the new data.
After all command and transaction processing has been satisfied for the designated
workflow, the CommandController will perform a callback to USEC, via the USECIF,
when the processing involved was an add or a delete and filterable fields were present.
The USEC table of FieldValues (FldVals) maintains field value information that can be
applied to any filter. The addition and removal of field data to this table is initiated during
this final phase of filter processing.
Note: Data that is added to the FldVals table is not immediately implemented within
any new or existing filter. The process of associating the value(s) to a filter requires
manual intervention from a system or security administrator.
76
6. Components/Services
In the UIS implementation, lower-level components and services are responsible for
performing the data related work. Components can consist of business or data
components. Services are primarily data access services that act upon the data in the
underlying data sources. Comparisons between the components and services can be
made as follows:
Data Components and Services are typically one-to-one relationships. Both are created to
access a single, underlying data source. The service takes care of shielding direct access
requirements from the components while the data component takes care of validations and
requirement checks.
Business Components are typically unrelated to data components or services. Business

components may be additional Java components written to help access multiple data
components and/or services; perhaps in those instances where flow configuration cannot be
accomplished adequately with the <Transaction Map>.xml configuration. Business
components may also be Java components written to access external components (i.e. C++)
or external systems. The UIS implementation supports a PassthruComponent that can be
used in processing requests/response messages with external (non-originating) entities. See
Section 6.2.
For Data Components and Services, the UIS implementation utilizes code generators to
create usable Java code. At this time, business components must be manually
developed.
Aspects of the code generation infrastructure will be discussed in the following sub-
sections.
Data access in the UIS environment is currently being performed through the use of
Java JDBC. Customer’s can provide their own selection of many available JDBC drivers
for respective databases transparently from our environment.
All generators discussed in the following sub-sections exist under the

es.server.generator package. Example batch files used to execute the respective
generator programs are found under ESConfig/scripts.
77
6.1 Generators
6.1.1 ServiceGenerator
A ServiceGenerator utility is provided by the UIS implementation that utilizes a

configuration file (see Section 3.1.2) to create a Java data service class. The
ServiceGenerator is an extended class of the BaseGenerator that uses XML
configuration input files to help drive code generation.
The service classes generated help shield the data components, business components,
and other classes from lower-level data access issues. Every data source directly
accessed by the environment must have an applicable service class.
As was discussed in Section 3.1.2, configurations for services are very flexible. Users
can establish common function support as well as customized support in the form of
various, flexible retrieval functions. Additionally, custom Java code can also be included
in the gen files that the generator will place into the service class.
Note: When adding custom code into a gen file to be placed into a service class, any
methods that will be identified for direct access within the TransMap.xml flow must use
a single internal data object as the only parameter. Passing of any processing details
between classes requires those details be appended to the primary data object rather
than passing individual arguments.
All generation files will typically exist under the ESConfig/datasource/gens directory.
Generated code will be named as indicated in the gen file and will be placed in the
package location also identified in the gen file. Once a service class is generated, it can
then be compiled and tested. It is recommended that data service classes be placed
under the following structure:
es/server/datasource/database/<service>
Note: Java service classes that are generated by the ServiceGenerator should NOT
be modified directly. If modifications are made to the existing code, regeneration of that
code will result in the loss of your changes. Modifications to the functionality needed in
the service classes should be handled by altering the gen configuration file and
regenerating the service class code, or by enhancing the ServiceGenerator to provide
new service functionality and then regenerating the service class code.
Note: Customer-based modifications to existing product service classes should be

avoided. If customer requirements dictate different service support, new gen files should
be created for the data source and then a custom service generated and placed in a
different package location. Configuration changes in the TransMap.xml file would then
be made to reflect use of the different service and the environment’s classpath updated
to ensure the newly generated service can be found appropriately.
78
6.1.2 ComponentGenerator
A ComponentGenerator utility is provided by the UIS implementation that utilizes a

configuration file (see Section 3.1.2) to create a Java data component class. The
ComponentGenerator is an extended class of the BaseGenerator that uses XML
configuration input files to help drive code generation.
The data component classes generated help provide access to lower-level data
services. Every data source directly accessed by the environment must have an
applicable service class.
As was discussed in Section 3.1.2, configurations for data components are very flexible.
Users can establish common function support as well as customized support in the form
of various, flexible retrieval functions. Additionally, custom Java code can also be
included in the gen files that the generator will place into the data component class.
Note: When adding custom code into a gen file to be placed into a data component
class, any methods that will be identified for direct access within the TransMap.xml flow
must use just a single internal data object as the only parameter. Passing of any
processing details between classes requires those details be appended to the primary
data object rather than passing individual arguments.
All generation files will typically exist under the ESConfig/datasource/gens directory.
Generated code will be named as indicated in the gen file and will be placed in the
package location also identified in the gen file. Once a data component is generated, it
can then be compiled and tested. It is recommended that data components be placed
under the following structure:
es/server/datasource/<data component>
Execution of this generator will also result in the creation of the element maps under:
ESConfig/elmtmaps/<Data Source>Map.properties
These files will contain the constraint mapping information for the logical name elements
in order for data validations to successfully function.
Note: Java data component classes that are generated by the ComponentGenerator
should NOT be modified directly. If modifications are made to the existing code,
regeneration of that code will result in the loss of your changes. Modifications to the
functionality needed in the data component classes should be handled by altering the
gen configuration file and regenerating the data component class code, or by enhancing
the ComponentGenerator to provide new functionality and then regenerating the data
component class code.
79
Note: Customer-based modifications to existing product data component classes
should be avoided. If customer requirements dictate different data component support,
new gen files should be created for the data source and then a custom data component
generated and placed in a different package location. Configuration changes in the
TransMap.xml file would then be made to reflect use of the different data component
and the environment’s classpath updated to ensure the newly generated data
component can be found appropriately.
80
6.2 PassthruComponent Usage
The UIS implementation provides an extendable PassthruComponent. When properly

configured, the es.server.component.PassthruComponent class can be used to
exchange XML-based message requests and responses with an external entity (not the
originating client). PassthruComponent takes advantage of the UIS framework as well
as the JSF to accomplish this.
Note: At this time, the current PassthruComponent will only function in a synchronous
mode; it does not support asynchronous processing.
To configure PassthruComponent support, the following steps are required:
Process Identifier - setup a unique Process Identifier for your application.
o You may have one-to-many Process IDs per installation.

o Process IDs can be specified as system properties on the Java run-line (or in
the config.properties file). Use the -Dprocess.id=<unique Process ID>
Java run-line syntax where <unique Process ID> is a string value up to 50
characters in length - per JSF definition.
o BASE24-EPSUI is the standard process ID (i.e. -Dprocess.id=BASE24-
EPSUI).
o For test installs, cluster implementations, or to specify a unique environment,
a Process ID can be anything that makes sense.
External Connection - Create an External Connection Table (i.e., EXTRCNCT) row

entry for each Process ID specified in the previous step.
o An external connection entry represents an end-point. An EXTRCNCT row

describes the details associated with communicating with the end-point.
Numerous standard JSF options exist.
o The primary index is External Connection ID (i.e., ExtrCnctID) and Process ID

(i.e., PrcsID).
o External Connection IDs used to access existing BASE24-eps C++ XML

Server applications can be specified in the config.properties file, key
"ptc.connectionID ". The default value if not specified in the
config.properties file is "BASE24-eps/C++XMLServer".
o DscrTx - Description can be any descriptive string text.
o MssgFrmtClasTx - Message Formatter Class should be set to

com.aciworldwide.common.formatter.NullFormatter for straight pass-thru
(no XML parsing) or es.server.formatter.xml.ESXMLFormatter (or
extended formatter class) for parsing and potentially other processing. Note
this formatter is used for outbound requests to the end-point (e.g., BASE24-
eps C++ XML Server) and inbound responses from the end-point.
81
o PrtcCd - Protocol Code indicates the protocol used to communicate with this
end-point. Many options exist:
TCPIP
TCPIP-CLIENT
TCPIP-SERVER
HTTP
NONE
CLIENTAUTH
JMS-ASYNC
JMS-SYNC
EJB
SMTP
etc.
and the remaining columns are specific to the protocol chosen. For our test
purposes, TCPIP (or TCPIP-CLIENT) represents TCP/IP, acting as a client
requesting a connection. The remaining fields will be defined as they relate to
the TCP/IP protocol. Keep in mind many other options exist.
PrtcOptnList - Protocol Options List defines how TCP/IP data streams are tied
to messages. HDR2 indicates the TCP/IP stream is prefaced with a 2-byte
binary message length - an XPNET/BASE24-eps C++ Server requirement.
PrtcDfnd1Tx - Protocol Defined Field 1 defines the end-point's IP address.
PrtcDfnd2Tx - Protocol Defined Field 2 defines the end-point's well-known port.
PrtcDfnd3Tx - Protocol Defined Field 3 is not used.
TimeOutNum - Time Out Number defines the amount of time to wait for a reply
on the socket. Values are specified in seconds.
RtryAtmpNum - Retry Attempt Number defines the maximum number of retry

attempts.
InitConnNum - Initial Connection Number defines the initial number of sockets to

create for the connection pool.
82
MaxConnNum - Maximum Connection Number defines the maximum number of
sockets that this connection pool is allowed.
LastUpdtTim - Last Update Time defines the timestamp of the last update to this
entry.
A BASE24-eps desktop UI will be created in the future to help maintain this file.
Refer to screen prints below for examples of data configuration in the EXTRCNCT
table.
Example External Connection Table information:
83
External Connection Table Column Definitions:
Install the jms.jar under the lib directory of the Web project. The JSF requires
additional APIs from this jar.
6.2.1 Extending es.server.component.PassthruComponent
In some instances, it may be necessary to massage outgoing data such that it can more
accurately reflect how the external entity requires the data to look. This could include,
for example, combining 3 data elements into 1 element or perhaps generating a length
element based on the size of 1 or more data elements. The same could occur when
receiving a response from an external entity and needing to massage data in the primary
data object for internal UIS processing.
The preferred ability to provide support for this data massaging should be with extending
the PassthruComponent class and providing customized data handling as necessary.
Packaging of the extended components can follow any defined convention; a convention
has not yet been established for BASE24-eps implementations, as no requirements for
customization yet exist.
By customizing the component to handle specific massaging requirements, the user

would then configure the use of the extended PassthruComponent (with the default
execute method) in the appropriate transaction map file as shown by example in the
prior sub-section.
84
The PassthruComponent class is an extendable class that provides 4 custom exits for
writing data massaging code and response handling code. Those custom exits and their
use are:
cstmBuildRequest
This method should be overridden in the extended class when implementing pass-thru
support with formatting and sending requests to an external entity and the data represented
in the primary data object does not reflect all of the messaging requirements (i.e. additional
element names, 1-to-1 mapping of elements, etc.). Data massaging provided with this
method should be done to data contained in the primary data object and will be done prior to
any actual request message building. This method should return true or false based on the
success or failure of the data massaging.
cstmParseResponse
This method should be overridden in the extended class when receiving response messages
from an external entity and the data represented in the primary data object does not reflect all
of the internal processing requirements (i.e. additional element names, 1-to-1 mapping of
elements, etc.). Data massaging provided with this method should be done to data contained
in the primary data object and will be done after the original response message has been
parsed. This method should return true or false based on the success or failure of the data
massaging.
cstmPreProcess
This method should be overridden in the extended class when there is a need to pre-
determine if passthru processing should even be performed. The method is called before
any additional passthru configuration is retrieved or message service instantiation is
established. Return true if passthru processing should continue, false if it should not.
evaluateResponse
This method should be overridden in the extended class when receiving response messages
from an external entity and the data represented in the primary data object does not reflect all
of the internal processing requirements (i.e. additional element names, 1-to-1 mapping of
elements, etc.). Data massaging provided with this method should be done to data contained
in the primary data object and will be done after the original response message has been
parsed. This method should return true or false based on the success or failure of the data
massaging.
getExternalConnectionID
This method retrieves the default connection ID key entry from the config.properties file. This
value of the property obtained is used to key into the EXTRCNCT table during end-point
processing. The EXTRCNCT table can have multiple connections defined, hence if the user
requires different connection configuration for additional end-points, the PassthruComponent
class can be extended and this method overridden to provide hard-coding or other
config.properties data retrieval in order to identify the table key to use. The default
config.properties entry used for this class and this method is:
ptc.connectionID
If overridden, this method must still return a String-based key value.
85
getUniqueMessageID
This method retrieves or generates a unique message ID. It should be overridden in the
extended class if the default method of generating a unique message ID must be different for
the end-point processing the request. The default implementation generates this String-
based value by using the JSF class/method of:
UUID.create()
If overridden, this method must still return a String-based value.
When working with the custom exits, the developer should also be aware that the
custom component may process for more than 1 request/response root tag and must
take that into consideration when writing the custom code handling.
The UIS implementation requires that developers adhere to the following convention:
Appropriate changes should be made to the necessary entries in the

ESConfig/transmaps/<Transaction Map>.xml file to ensure proper message processing.
86
6.3 Database-Level Filtering
Field-level filtering is supported in the UIS implementation at two distinct levels:

command (discussed previously in Section 5.2) and database service.
The following actions may cause database-level filtering to occur:
¾ List All
¾ Get By
When the respective database service performs one of the above requests, it will
determine if filtering is to be applied to the data before it is returned. The determining
factors will be the presence of the following items in the primary data object:
¾ FILTER_FIELD_MAP
¾ USEC_PERMISSION_DATA
These 2 items are placed in the primary data object by the USECIF during the
authentication and authorization step. Additionally, for a database service to provide
filtering support requires that an appropriate filter class be specified in the respective
transmap configuration data via the <filter><class> tags. If no filter class is specified in
the transmap configuration for the current type of request being processed, then filtering
will not be performed.
The current filter class specification for BASE24-eps is es.server.filter.ESFilter. This

filter class is based on the filtering support provided by the USEC environment.
Additional filter classes that are based on other mechanisms can be provided so long as
they extend the es.server.filter.FilterBase abstract class.
For a data row to be successfully filtered requires that all of its filter-related values pass
all assigned filter constraints. If a data row has multiple columns that are being filtered
upon and 1 or more of the column values fail filtering constraints, the data row will not be
returned. The database services also support filtering in conjunction with MAX_ROWS
support such that repeated database retrievals will be performed until all rows have been
exhausted or the service has reached the MAX_ROWS value for returnable data rows.
87
7. How-To Guides
This section provides UIS development scenarios with how-to steps for configuring and
building a functional server-side component environment.
7.1 Create a New Request/Response Message
To create support for a new request/response message in the UIS environment, the
following assumptions must be made:
The intended data source to be accessed must already have an available data
component and service to use. If this is not true, please include the steps under
Section 7.3 to create a new data component and service during this process.
If the intended data source already has a data component and service, but does not
have available an appropriate method to process the action(s) necessary, please
include the steps under Section 7.4 to modify the existing data component and
service during this process.
The message formatting being supported is XML based. If this is not true, please
include the steps under Section 7.8 to create a new message formatter during this
process.
If the message processing must include a non-data component or service, then a

new Java component may be required. Please identify the new functionality of the
new business component and include its development during this process.
To create support for a new request/response message in the UIS environment, use the
following steps as the guideline:
1. Identify any data source(s) that will be accessed. If external components or external
systems are to be accessed, identify the mechanism to be used to access them (i.e.
JNI, RMI, TCP/IP, etc.).
2. If data source(s) are to be accessed, identify if respective data component(s) and

service(s) already exist. If not, include Section 7.3 with this step.
3. If data source(s) are to be accessed, identify if existing data component(s) and

service(s) provide the required functionality. If not, include Section 7.4 with this
step.
4. Identify if the request/response messages will be XML based. If not, include Section
7.8 with this step. Otherwise, identify the XML message requirements between the
client and the server implementation. All request/response message elements used
must be defined in an element/group schema definition file. Refer to Section 4 for
further information on messaging requirements/rules. This step should result in a
new message schema definition file being created under
ESConfig/schemas/message/<file name>.xml and perhaps modifications to
existing, or creation of a new, element/group schema definition file and to a data type
88
schema definition file. All message schema related files exist under
ESConfig/schemas/message.
5. Create a new <Transaction Map>.xml file to include the new flow processing for the
new request/response messages. Refer to Section 3.1.1 for configuration
requirements and rules pertaining to this file and to Section 5 for examples and
other information. Primarily, every request message identified in the new message
schema definition file must have a flow entry set created in an appropriate
<Transaction Map>.xml file. Ensure that proper simple or transactional command
support has been identified when configuring the flow. This step should result in a
new transmap definition file being created under ESConfig/transmaps/<file
name>.xml
6. Deploy the new/updated configuration files to your work area along with any new or
updated components and services.
7. Test all functionality ensuring valid security processing and auditing functionality in
addition to request/response message handling.
89
7.2 Alter an Existing Request/Response Message
To modify support of an existing request/response message in the UIS environment, the

following assumptions must be made:
The intended data source to be accessed must already have an available data
component and service to use. If this is not true, please include the steps under
Section 7.3 to create a new data component and service during this process.
If the intended data source already has a data component and service, but does not
have available an appropriate method to process the action(s) necessary, please
include the steps under Section 7.4 to modify the existing data component and
service during this process.
The message formatting being supported is XML based. If this is not true, please
include the steps under Section 7.8 to create a new message formatter during this
process.
If the message processing must include a non-data component or service, then a

new Java component may be required. Please identify the new functionality of the
new business component and include its development during this process.
Modifications to existing request/response messages may typically be made for the

following reasons:
Data type changes.

Addition of new fields (could also be related to changes to be made to existing data
components, business components, and services).
Removal of existing fields.
Addition of new functional messages (could also be related to changes to be made
to existing data components, business components, and services).
Removal of functional messages.
To modify support of an existing request/response message in the UIS environment, use

the following steps as the guideline:
1. Identify any data source(s) that will be accessed. If external components or external
systems are to be accessed, identify the mechanism to be used to access them (i.e.
JNI, RMI, TCP/IP, etc.).
2. If new data source(s) are to be accessed, identify if respective data component(s)

and service(s) already exist. If not, include Section 7.3 with this step.
3. If existing data source(s) are to be accessed differently, identify if existing data

component(s) and service(s) provide the required functionality. If not, include
Section 7.4 with this step.
4. All request/response message elements used must be defined in an element/group

schema definition file. Refer to Section 4 for further information on messaging
90
requirements/rules. This step should result in modification of an existing message
schema definition file from ESConfig/schemas/message/<file name>.xml and
perhaps modifications to existing, or creation of a new, element/group schema
definition file and to a data type schema definition file. All message schema related
files exist under ESConfig/schemas/message.
5. Verify the processing flow configuration in the ESConfig/transmaps/<Transaction

Map>.xml file is still valid and make adjustments where necessary. Refer to
Section 3.1.1 for configuration requirements and rules pertaining to this file and to
Section 5 for examples and other information.
6. Deploy the new/updated configuration files to your work area along with any new or
updated components and services.
7. Test all functionality ensuring valid security processing and auditing functionality in
addition to request/response message handling.
91
7.3 Create a New Data Source
Creating a new data source requires the following items be addressed:
1. Creation of a new <table>Gen.xml file; placement of file should be according to

whether this is a product data source or a custom data source. It is recommended
that the Gen files be appropriately placed under the ESConfig/datasource/gens
directory. Allowable configuration items are discussed in Section 3.1.2.
2. Verify and create, if necessary, appropriate data type schema definitions for
validation support as well as appropriate element/group definitions. Refer to Section
7.5 for data type creation/modification and to Section 4 for further configuration
information on schema definitions.
3. Creation of the data component and data source service generated code from the
Gen file. Refer to Sections 7.6 & 7.7 for information on creating data components
and data source services.
4. Open an existing or create a new <Transaction Map>.xml file and make the
appropriate configuration changes or additions to utilize the newly generated custom
data components and methods for the new data source.
92
7.4 Modify an Existing Data Source
Modifying an existing data source requires the following items be addressed:
1. Open the existing <table>Gen.xml file or, for custom work, copy the existing file to a
custom directory; placement of file should be according to whether this is a product
data source or a custom data source. It is recommended that the Gen files be
appropriately placed under the ESConfig/datasource/gens directory. Allowable
configuration items are discussed in Section 3.1.2.
2. Make the appropriate configuration changes to the Gen file. Changes could include
column size modifications, data validation changes, internal/external data type
support, primary/alternate key changes, and more.
3. Update of the actual data source or migration to an updated data source. Once the
new table is created, appropriate database tools can be used to transfer data
between the two tables; data type changes may require special handling. If changes
are being made directly to a data source, then use the appropriate database tool to
perform the change(s) manually. Please note that limitations may exist on what
exactly can be changed to existing database tables and flat file data sources may
have even greater restrictions.
4. Modify, if necessary, any appropriate data type schema definitions for validation
support as well as appropriate element/group definitions. Refer to Section 7.5 for
data type creation/modification and to Section 4 for further configuration information
on schema definitions.
5. Re-generate the data component and data source service code from the Gen file.
Refer to Sections 7.6 & 7.7 for information on creating data components and data
source services. If working with custom code, ensure the generated classes are
placed under a custom package.
6. Open an existing or create a new <Transaction Map>.xml file and make the
appropriate configuration changes or additions to utilize the newly generated custom
data components and methods for the new data source.
93
7.5 Create/Modify Data Validations
Establishing custom data validations is fairly straightforward. All data validation

requirements are currently defined in ESConfig/datatypes/ESXMLDataTypes.xsd. To
redefine a validation for an existing data type, do the following steps:
1. Create a new XMLDataTypes.xsd file and place it under a new, custom directory. It
is highly recommended that unless a data validation change is being made for
product reasons, that all changes be placed in customized files in custom directories
under ESConfig/schemas/. Refer to Section 4.1.1 for data type support
information.
2. If a data validation for an existing message element is being redefined, simply copy
the existing data validation from the above file and place it in the customized file.
Modify the data validation as required. If a new data type is being created for an
existing data element (as defined in the element or message definition files or the
ESXMLCommonElements.xsd), then customization will also be required to the
elements definition file AND related message schema files. Whenever possible, just
copy the existing data type and leave the name intact.
3. For the customized data validation to be implemented, 2 options exist. First, if a new
data type was created the existing data component code must be regenerated from
an updated <table>Gen.xml file. Again, unless the modification is being made for
product reasons, it is recommended that a copy of the appropriate <table>Gen.xml
file be placed in a custom directory and then modified. Second, the associated
elmtmaps file for the data source will need to be modified or a custom map file
established for the element-to-constraint combination.
4. If choosing to modify an existing Gen file, re-generate the data component code with
an appropriate batch file. If the intended target is the existing class file location, then
it is recommended that a backup of the existing product classes be made.
Otherwise, specify a new package location in the Gen file for the data component
class and then re-generate the code.
5. If choosing to update or create a new data source or CSM elmtmaps file, just
provide the element-to-constraint key/value pair and then stop/restart the
environment for the DataValidatorManager to reload the information into memory.
6. If a custom data component class was generated, open the associated

<Transaction Map>.xml file containing the appropriate configuration items, and
update it to utilize the newly generated custom data component and methods versus
the product data component.
94
7.6 Create a Custom Data Component
Creating custom data components will typically be done in cases where the underlying
data sources have been modified in a customer environment or perhaps where data
validations are being modified or custom code is needed in the data component. As a
general rule, custom components (data or service), should require that copies of existing
Gen files be made to a custom directory and then custom classes generated to custom
package locations.
The steps to create custom data components are:
1. Copy the related <table>Gen.xml file to a custom directory. It is recommended that

the custom directory be created under the ESConfig/datasource/gens/ directory.
2. Open the Gen file and make the appropriate changes. Refer to Section 3.1.2 for
Gen file guidelines. Typically, modifications will be made to include custom fetch
retrievals, but could also include custom code blocks. Changes must also be made
to the package location for the data component to place it under a custom directory,
not the product package/directory.
3. Create an appropriate batch file to help generate the new data component.
4. Execute the batch file.
5. Compile the generated data component. Please note that when creating custom
fetch retrievals, an appropriate custom data service will also need to be generated
and compiled prior to compiling the new data component. Refer to Section 7.7 for
information on creating a custom data service.
6. Modify an existing or create a new <Transaction Map>.xml file containing the

appropriate configuration items to utilize the newly generated custom data
component and methods.
95
7.7 Create a Custom Data Source Service
Creating custom data services will typically be done in cases where the underlying data
sources have been modified in a customer environment or perhaps where custom code
is needed in the data source service. As a general rule, custom components (data or
service), should require that copies of existing Gen files be made to a custom directory
and then custom classes generated to custom package locations.
The steps to create custom data source services are:
1. Copy the related <table>Gen.xml file to a custom directory. It is recommended that

the custom directory be created under the ESConfig/datasource/gens/ directory.
2. Open the Gen file and make the appropriate changes. Refer to Section 3.1.2 for
Gen file guidelines. Typically, modifications will be made to include custom fetch
retrievals, but could also include custom code blocks. Changes must also be made
to the package location for the data source service to place it under a custom
directory, not the product package/directory.
3. Create an appropriate batch file to help generate the new data source service.
4. Execute the batch file.
5. Compile the generated data source service.
96
7.8 Implement Different Input Protocols/Message Formats
The JSF provides support for many different protocols including:
TCP/IP, Sockets
HTTP
SOAP
JMS
EJB
The current UIS environment has provided implementations for the following protocols:
HTTP
JMS (in progress)
The UIS environment by default supports XML-based messaging formats, as has been
discussed throughout this developer’s guide. However, it may become necessary in the
future to support additional protocols or additional message formats.
7.8.1 New Protocol Support
If the addition or replacement of protocol support is required to UIS, the engineer should
seek reference implementations from other user’s of the JSF. The adapter layer of the
JSF provides the protocol support. The UIS implementation for HTTP support utilizes
the es.server.ESHTTPServlet class. Other protocols will require a full component
replacement of the servlet class. The functionality provided by all adapter classes
should be fairly consistent in that they:
Handle the protocol semantics for which they are being created.
Handle the receipt and sending of message data with the client.
And direct the flow of processing as follows:
1. Accept incoming request message.

2. Call upon the ESFormatterController to process the request message.
3. Call upon the CommandController to perform the data handling.
4. Call upon the ESFormatterController to build the response message.
5. Return the response message to the client.
7.8.2 New Message Format Support
If the addition or replacement of message formats is required for UIS the engineer
should seek reference implementations from other user’s of the JSF. The formatter
implementation for UIS currently provides all XML handling. For XML handling, the
ESFormatterController is configured, via the transmap XML files, to call upon the
ESXMLFormatter class to direct XML message processing. The ESXMLFormatter
class utilizes the MessageSchemaManager class to process XML request/response
data.
97
Message format addition or replacement enhancements may require modifications to
existing adapters (i.e. ESHTTPServlet) as well as the ESFormatterController. Beyond
that, a new formatter (i.e. similar to ESXMLFormatter) would need to be created in
addition to any other special message handling mechanisms (i.e. similar to
MessageSchemaManager). Data mapping requirements have already been outlined in
this document and must be adhered to by all formatters. The data type and
element/group schema definitions discussed in Section 4 drives internal data element
names. Data names for incoming request and outgoing response messages could be
defined differently, however, the responsibility of mapping requirements from external to
internal values falls on the respective formatter and any of its supporting components.
Additionally, if any new message handling support classes are generated (similar to
MessageSchemaManager), it is recommended that the primary class implement the
JSF InitializationInterface, that it provide an init() method, and that it be configured to
start at process initialization. This also requires additional entries be placed in the
config.properties file (see Section 2.4).
98
7.9 Implement Pass-Thru Processing
The current UIS environment provides a pass-thru implementation that allows requests
to be passed on to other end points for processing. These requests can be straight
pass-thru or they can be part of an integrated workflow involving other UIS processing.
There are various combinations and considerations for establishing pass-thru and/or
integrated support and the sub-sections that follow will detail the steps necessary to
implement this processing.
7.9.1 Straight Pass-Thru
Straight pass-thru processing should be implemented when the following conditions

exist:
A request is to be received by the UIS implementation and forwarded on to another end-

point.
The UIS implementation is not to be involved with any of the workflow processing.
USEC/UAUD processing is not required.
To implement this processing, follow these steps:
Establish the EXTRCNCT configuration and runtime parameters as previously

outlined in Section 6.2. This includes PassthruComponent configuration to handle
outbound request/response handling as well as the use of the NullFormatter to
allow use of the original XML request message received.
Define all pass-thru messages.
o Pass-thru messages must contain a unique XML message root tag.
o XML message root tags and the corresponding details must be configured in an
ESConfig/transmaps/*.xml file(s).
o Transaction Map entries for pass-thru messages define important processing

characteristics regarding the pass-thru message (e.g., command, formatter,
schema, task, and function).
o Use the es.server.command.ESPassthruCommand command.
o Use the com.aciworldwide.common.formatter.NullFormatter formatter.
o Do not define task or function configuration in the transaction map.
o Refer to the example transaction map below.
99
Example Process Control transaction map file:

<transactions xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance">
<entry>
<tag>ProcessControlRq</tag>
<formatter>
<class>com.aciworldwide.common.formatter.NullFormatter
</class>
</formatter>
<command>
<class>es.server.command.ESPassthruCommand</class>
<transaction>
<component>es.server.component.PassthruComponent
</component>
<method>execute</method>
</transaction>
</command>
</entry>
100
7.9.2 Straight Pass-Thru w/ USEC Support
Straight pass-thru processing with USEC support should be implemented when the
following conditions exist:

point.
The UIS implementation is not to be involved with any of the workflow processing aside from
USEC.
USEC processing is required.
UAUD processing is not required.
To implement this processing, follow these steps:

outbound request/response handling as well as the use of the NullFormatter to

o Use the es.server.command.ESSimpleCommand command.
o Use the es.server.formatter.xml.ESXMLFormatter formatter (or any

customized extended version thereof).
o Define the task and function configuration in the transaction map.
101

instance">
<entry>
<task>ProcessControl</task>
<function>Send</function>
<formatter>
<class>es.server.formatter.xml.ESXMLFormatter
</class>
</formatter>
<command>
<transaction>
</component>
</transaction>
</command>
</entry>
Variations of this pass-thru processing with USEC support could include:
Customized inbound message parsing/outbound response building via an extended

ESXMLFormatter (see Section 5.1.1.1).
Customized outbound message building/inbound response parsing via an extended

PassthruComponent (see Section 6.2.1).
102
7.9.3 Integrated Workflow
Pass-thru processing with USEC/UAUD support and integrated UIS workflow processing
should be implemented when the following conditions exist:

point.
The UIS implementation will be involved with part of the workflow processing. This would
include accessing data source information managed by the implementation.
USEC processing is required.
UAUD processing is required (only UIS implementation processing will be audited; auditing
requirements of external end-points must be fulfilled by those end-points).
To implement this processing, simply follow these steps:

outbound request/response handling as well as the use of the ESXMLFormatter to

o Use the es.server.command.ESSimpleCommand command or the

es.server.command.ESTransCommand command.
o Use the es.server.formatter.xml.ESXMLFormatter formatter (or any

customized extended version thereof).
o Define the task and function configuration in the transaction map.
103

instance">
<entry>
<task>ProcessControl</task>
<function>Send</function>
<formatter>
<class>es.server.formatter.xml.ESXMLFormatter
</class>
</formatter>
<command>
<transaction>
<component>es.server.datasource.TableComponent
</component>
</transaction>
<transaction>
</component>
</transaction>
</command>
</entry>
Variations of this integrated workflow processing could include:
Customized inbound message parsing/outbound response building via an extended

ESXMLFormatter (see Section 5.1.1.1).
Customized outbound message building/inbound response parsing via an extended

PassthruComponent (see Section 6.2.1).
104
7.10 Solve Various Development Issues
The sub-sections that follow are a conglomeration of various development challenges

that have been faced through various UIS projects and how they were resolved.
7.10.1 Code/Configuration Check List
When doing any custom work previously discussed in this section or in the sub-
sections that follow, it is important to understand the relationships of all configuration
and class files involved and where they typically reside.
The following check list should serve as a guideline for ensuring changes/additions are
properly identified and managed with the cataloged UIS code so that code changes are
not lost.
ESConfig/schemas/lib
Ensure any data type additions/changes have retrofitted into the

ESXMLDataTypes.xsd file or customer extended version of this file. Be careful
not to lose existing changes and also be careful when modifying or removing
existing entries – ensure other message schemas are not using them. Keep
entries in alphabetical order.
Ensure you have generated your <Data Source>Elements.xsd file and that your
message schema file (under ESConfig/schemas/message) properly includes this
file or files.
Ensure all elements files generated and modified data types schema file have been
validated by an XML tool such as IBM Websphere App Developer’s XML validator
or some other XML validator.
ESConfig/schemas/message
Ensure you have created/updated a new/existing message schema file for your
data source. Message identification (by request/response) should be in
alphabetical order in the file. Naming convention requires a file name that matches
the associated task ID (value that would have been set for the <task> tags in the
message schema file).
Ensure the message schema file has been validated by an XML tool; such as IBM
Websphere App Developer’s XML validator or some other XML validator.
105
ESConfig/transmaps
Ensure you have created/updated a new transaction map file for your UI/client,
broken down by task ID. Your transaction map should only contain entry sets for
your request handling, they should be in alphabetical order, and the file name
should be set to the same value as the <task> tag in the transaction map file.
ESConfig/datasource/gens/<data source>
Ensure you have created/modified your <data source>Gen.xml file. Verify all
naming conventions for <logicalname> entries have been adhered to.
Ensure you have included all copy files (.jcf) created for your data source code
generation. These files will exist under your data source directory or under the
ESConfig/datasource/gens/common directory.
es/server/formatter/xml/<UI/Client Message Set >
Ensure you have provided a new directory, named after the UI message set, and
included the extended XMLFormatter class if customization was provided at the
message-handling layer. Ensure any changes have also been reflected in the
appropriate ESConfig/transmaps file.
7.10.2 Task ID/Function ID Specification
When specifying the task ID and function ID for a request, in the transmap
configuration file (via the <task> and <function> tags), the ID values must be
configured in the USEC environment. Failure to do so will result in Not_Authorized
responses being return for the request(s).
106
7.10.3 Data Type Conversion between DALCI/SIS and UISs
When establishing *Gen.xml configuration for a data source (new or existing) that is
created under DALCI/SIS, it is important to properly set the <javatype> tag value for
each column. The <javatype> represents how the UIS implementation will internally
handle the data.
The following table depicts the UIS supported mapping between JDBC (SQL) types
and Java types (please follow the depicted case closely) and what the equivalent
DALCI/SIS data types are (please note that string can also be set to string_no_trim):
DALCI/SIS DB Type JDBC Type Java Type

bt_char CHAR string
bt_stringf CHAR string
bt_stringv VARCHAR string
bt_stringv LONGVARCHAR string
bt_flag BIT * boolean
bt_binaryf BINARY byte[]
bt_binaryv VARBINARY byte[]
bt_binaryl LONGVARBINARY byte[]
bt_int16s SMALLINT short
DOUBLE double
bt_float64 FLOAT double
bt_float32 REAL float
bt_int32s INTEGER int
bt_int64s BIGINT (decimal) long
bt_int64s TIMESTAMP timestamp
* For DB2 implementations, the underlying data source must have the physical type set
as a CHAR(1).
107
7.10.4 Customizing Data Components/Services w/ Copy Files
There may be instances where custom data processing is required at the data
component or database service layer. This could be to help support customized data
validations (i.e. cross-field validations or other external validations), data integrity
support with other data sources, external processing of other components or external
systems, and more.
Where these things cannot be appropriately handled with custom XML formatters or
transmap configuration flow, custom code can be added to data components and
database service class via the use of copy files.
The primary guidelines that are recommended include:
¾ One *.jcf file should be created per method. That *.jcf file may include additional
global attributes although it is recommended that they be established in their own
*.jcf file to be included separately with the code generation. The primary name of the
*.jcf file should represent the method name.
¾ If a custom method is added to a generated data component and is intended to be a

public method that can be referenced from transmap configuration, the only
argument that should be accepted by that method is the tranObj argument.
¾ As was previously mentioned in Section 6, code additions to generated data

components and database services should NOT be done directly to the components
and services themselves as these changes would be lost during future code
generation of those classes. It has been customary, however, for engineers to
modify existing data component and database service classes during development
and to test those changes; upon completion the changes are then reflected in the
updated *Gen.xml file and in new/updated *.jcf files.
Please refer back to Section 6 on data component and database service code
generation support as well as Section 3.1.2 for *Gen.xml configuration support.
108
7.10.5 Customizing Request/Response Data Handling
Special handling requirements of request data may be required to ensure proper data
source processing. Likewise, special handling of data source information may be
required to ensure proper response handling to a UI/client. To accomplish this, the
desired mechanism to employ is an extended XMLFormatter class (previously
discussed in Section 5.1.1.1).
The es.server.formatter.xml.ESXMLFormatter class can be extended to provide

custom data handling under some of the following scenarios:
¾ Request data coming in does not reflect internal logical names of data source
columns that will be involved in processing the request.
¾ Response data being returned to the UI/client does not correspond to internal logical
names of data elements retrieved from a data source.
To handle data massaging of request data, the cstmParseRequest method should be

overloaded in the extended XMLFormatter. This method is called AFTER the initial
message parsing has been performed. The intent of this method is to then allow
multiple data elements to be combined, additional validations to be performed, new
elements to be created, and more and to then have that new data placed into the
tranObj object as new key/value pairs.
On the response side, logical named data elements from a data source may need to be
broken down into individual elements or new elements (based on new criteria) created
and placed in the tranObj object. To do this, the cstmBuildResponse method should
be overloaded in the extended XMLFormatter. This method is called BEFORE any
response message build occurs.
Things to consider during this level of custom work include:
¾ New request elements, placed into the tranObj object, must be named appropriately
to map to the required logical name of a data source column or other logical name
required for other component processing.
¾ New response elements, placed into the tranObj object, must be named
appropriately named for the MessageSchema class to use when building the
response message. The names must map to an element name found in the
response message schema definition.
¾ When placing new key/value pairs into the tranObj object, care must be taken to use
the appropriate “put” method of the JSF DataObject class. The “put” method can
be used in all numeric and timestamp instances and in string instances where space
character preservation (at the beginning and end of the value) is not important. If
working with string data and the preservation of space characters at the front and/or
end of the value is important, then the “putNoTrim” method should be used.
109
¾ When establishing processing in the extended XMLFormatter class, it is important
to remember that these overloaded methods will always be called. To ensure that
the extended XMLFormatter class is only used in specific instances, the transmap
configuration should only identify the extended formatter class for those requests
that require some level of custom message/data handling. All other transmap
request configurations should default to the standard class of
es.server.formatter.xml.ESXMLFormatter.
¾ To further the above bullet item, it is possible then that one of the overloaded
methods could be called on say delete and add processing, if so configured, but
each may require their own custom data handling. In these cases, the overloaded
methods may need to perform conditional checking based on the request identifier
as specified in tranObj with the key of XML_INBND_RQ_TRAN_TYPE. A code
example follows:
String msgType = tranObj.getString( XML_INBND_RQ_TRAN_TYPE );
if ( msgType.equals( "ActiveScriptListRq" ) )
{
...
}
In this example, the conditional processing would only occur if the current request
were for ActiveScriptListRq.
110
7.10.6 Maximum Number of Data Rows Retrieval
There may be an instance where a UI/client can only accept so much data to be
returned in a response message. The UIS implementation works such that on listAll
processing, all data rows (or all filtered data rows) for a data source is returned in a
response message and for getBy processing, all data rows (or all filtered data rows)
satisfying set constraints are returned. In some instances, it may be necessary to
restrict the number of rows returned.
To do this, the respective transmap configuration for the request should be established
such that the maxRows = “#” attribute (via the <method> tag) is supplied with the
appropriate getBy type method specification (some data retrieval methods may not have
getBy type names, but this setting only applies to data retrieval functions); refer to
Section 3.1.1.1. This setting will then restrict the lower-level database services to only
return the specified number of data rows in a response message.
Special consideration, however, must be given to a UI/client that makes follow-up

requests to UIS to retrieve the next set of rows. UIS requires that the key information
from the last row retrieved be provided in the request so that the next set greater than
those values can be retrieved. For listAll processing initially, this would mean a follow-
up call to a specific getBy method that utilizes that key positioning information. If
another listAll call were to be made, the same data rows retrieved initially would be
returned again in the response, as the listAll processing does not involve key
positioning. Likewise, care must be taken in crafting the getBy SQL processing (via the
*Gen.xml file) to ensure that appropriate key positioning clauses (with >, >=, <, <=, etc.)
are accounted for to allow continuous data retrievals to work.
111
7.10.7 Updating of Primary Key Fields
There have been a few instances in work with BASE24-eps files where a requesting
UI/client must perform an update of 1 or more data rows and the data being updated
includes primary key fields. Typically, a database does not allow updates to primary key
fields. To resolve this with the UIS implementation, a workflow combined with various
elements allows update-like actions to occur through delete and insert functionality. This
is performed with the following coding steps:
1. Since a direct update is not typically allowed, delete and insert actions must be
configured in a transmap flow for the specific update request. An example of how
this was done for one request is:
<entry>
<tag>JTS_UpdateRq</tag>
<task>JournalTDESuppression</task>
<formatter>
<class>es.server.formatter.xml.JTS_Config.XMLFormatter</class>
<schema>message/JTS_config.xsd</schema>
</formatter>
<command>
<transaction>
<component>es.server.datasource.
JournalTDESuppressionComponent</component>
<method>delete</method>
</transaction>
<transaction>
<component>es.server.datasource.
JournalTDESuppressionComponent</component>
</transaction>
</command>
</entry>
The important aspects of the above configuration include:
¾ Use of the es.server.command.ESTransCommand class

¾ Implementing multiple <transaction> sets with the first method action being a delete
and the second method action being an add
1. The next aspect of enabling this type of support is to provide a custom

XMLFormatter. Recall from Section 5.1.1.1 that the ESXMLFormatter can be
extended to provide customized support for data handling. In this case, the
cstmParseRequest method needs to be overloaded in an extended XMLFormatter
class. In this method, you need to have context of the before key values (for the
delete) and the after key values (for the update). If the request message does not
provide this information, it must be updated to do so (respective client changes may
be required). In the cstmParseRequest method, 3 key/value pairs will need to be
generated for the primary data object. They are:
112
¾ DELETE_BY_ORIG should be added to tranObj and set to a value of “true”.
¾ ORIG_DATA should be added to tranObj. The value of ORIG_DATA should be
another JSF DataObject and it should contain 1 or more rows of original key value
information to be used for delete processing.
¾ NEW_DATA should be added to tranObj. The value of NEW_DATA should be
another JSF DataObject and it should contain 1 or more rows of new key information
to be used for add processing.
The BASE24-eps implementation for JTS_config provides a full example of this type
of implementation.
113
7.10.8 Implementing Filtering Support
To implement filtering support within UIS processing for a UI/client, the following
configuration steps must be taken:
1. Provide APPLCNFG entries for the filter.field.<tasked> property values, one for
each field that must be filtered from the UI/client. Refer to Section 2.6.3.3 for further
property information. The entries can be manually added to the APPLCNFG
database table or added to the DALCI ESConfig/scripts/ESFILTLD script file.
2. If database level filtering is required for getAll or getBy actions, then the impacted
transmap request configuration(s) must be updated to include a <filter><class>
specification as previously discussed in Section 3.1.1.1. The designated class for
BASE24-eps is the es.server.filter.ESFilter class.
3. Appropriate permission/filtering support must be configured in the USEC

environment. Please refer to documentation for USEC to identify those configuration
requirements.
4. The UI/client should expect to possibly receive a Not_Authorized_Filter response

when filtering restrictions are violated on delete, update, and view processing. For
getAll or getBy processing, approval responses may still be returned containing only
those data rows that have passed filtering restrictions.
Refer to Sections 5.3 & 6.3 for filtering overview information.
114
7.10.9 Implementing Dynamic SQL Table Access Support
Dynamic SQL table access support refers to 2 or more database tables sharing the
exact same structure and form but having different names. In the BASE24-eps
implementation, an example of this might be the journal perusal files (multiple files
named differently, but each containing the exact same data format). Processing of these
database tables through a common database service is possible by performing the
following steps:
1. Modify the appropriate *Gen.xml file to provide a <type> setting for the <service> to
be of either both or dynamic. If there is 1 generic instance of the database table
and multiple additional copies of it, then use a <type> of both and set the
<table><name> value accordingly. If there are no generic instances of the database
table (only copies of it), then use a <type> of dynamic and do NOT set the
<table><name> value.
2. The use of the generated service will then require that the desired table name to be
processed against be supplied in the working data object via the
DYNAMIC_DS_NAME key with the value set accordingly. This will typically be done
in an extended XMLFormatter class where the dynamic table name or data source
assign is supplied in the request message in some pertinent field.
115
7.10.10 Start/End Key Data Retrieval Support
Start and end key data retrieval typically requires client input that contains the starting
and ending values. In a sense, this acts as a filter against the database to only retrieve
data rows that satisfy the range established by these values.
The UIS implementation supports this by requiring the following steps:
1. Establish an extended XMLFormatter class for the client and override the
cstmParseRequest method. In this method, the start and end values must be
extracted from the tranObj object and placed back into the tranObj object with the
corresponding logical column names as the key. Additionally, the start value and its
associated logical column key must be placed in row 0 of the tranObj object and the
ending value and its same associated logical column key must be placed in row 1 of
the tranObj object. This is because both keys would have the same name and
hence could not exist in the same data object row. The generated component and
service also expect to find this start/end specification in a row 0/row 1 combination.
2. Modify the appropriate *Gen.xml file to provide a <fetchBy> grouping for the
specialized start/end data retrieval to be done. An example is as follows:
<fetchby>
<entry>
<name>StartEndKey</name>
<retrievecolumns>
</retrievecolumns>
<wherecolumns>
<colnumber gte = "true">0</colnumber>
<colnumber lt = "true">0</colnumber>
</wherecolumns>
</entry>
</fetchby>
In the above example, column number 0 under the <wherecolumns> represents the
key column that will be working with start/end values. The use of the attributes gte
and lt, or comparable, is important to ensure whether the start/end values are
included or excluded from the evaluation of row retrieval. The <retrievecolumns>
can then be established to only return specific columns or left out to allow all
columns to be retrieved. For more information on <fetchBy> configuration, refer to
Section 3.1.2.
116
8. Appendix
8.1 XML Simple Types and Restriction Hierarchy
Data type definitions used for message processing and data validations are supported
through the use of Sun’s XML Data Type library (xsdlib.jar and relaxngDatatype.jar).
The chart listed on the next page identifies the following items:
The list of supported XML Simple Types
The list of supported restrictions for each Simple Type AND the processing priority order the
XML Data Type library applies to each Simple Type.
117
118
8.2 UIS Error Handling
The UIS implementation supports the following error responses that are returnable in the
respStat attribute of the root tag of an XML response message.
UI Message Responses What does it mean? Internal JSF Response Code

OK 1. List Request - More data DBS_FILE_OK
available.
2. Delete Request – If data not
found, OK is returned.
3. All other request messages -
successful response.
System_Error Too many to list. Could be related SYSTEM_ERROR
to XML data, system configuration,
or other. Look through server logs
for details, but enjoy researching the
problem.
Data_Not_Found Requested records were not found. DBS_NOT_FOUND
Duplicate_Data Possible on inserts and updates. DBS_DUP_FOUND
Field_Validate_Error Didn’t like one or more of the items in DBS_DATA_FORMAT_ERROR
the request. Primary respStat will
Field-level errors are: indicate the Field_Validate_Error,
where as error data will indicate DV_INVALID_VALUE
InvldValue specific fields and their underlying DV_INVALID_LENGTH
Length errors. DV_OUT_OF_RANGE
OutofRange DV_OVER_MAX_LENGTH
Overflow DV_REQUIRED
Required DV_UNDER_MIN_LENGTH
Undermin
File_Exhausted End of list, empty list, or EOF. DBS_FILE_EXHAUSTED

Need_To_Reread Last Update Timestamps do not DBS_TIMESTAMP_MISMATCH
match.
Not_Authorized Indicates that USEC validation N/A
failed.
Not_Authorized_Filter Indicates the USEC validation failed N/A
concerning filtering restrictions.
XML_Format_Invalid Format errors in XML data. N/A
Rules
1. The UIS environment will return File_Exhausted to indicate an empty list.

2. When working with response codes internally, command layer and below, the
represented codes are in JSF format. When working with response codes in the
formatter layer and above, they are represented in BASE24-eps UI format.
119
8.3 UIS DataObject Mapping
The UIS implementation supports the DataObject concept of the JSF. Processing
values and other objects are placed in a primary data object that is passed between
classes. This primary object is referenced throughout various UIS classes as tranObj.
The various object and processing values that are placed in the primary data object fall
under the following categories:
¾ Auditing Context
¾ Data Source Context
¾ Error Context
¾ Filtering Context
¾ Message Context
¾ Miscellaneous Context
¾ Security Context
Each of the categories and their associated objects and processing values are listed in
the sub-sections that follow.
8.3.1 Auditing Context
8.3.1.1 AUDIT_DATA
The value associated with this key specifies an audit data object (JSF class
com.aciworldwide.common.datasource.AuditData) that contains audit information from
actions performed against data source data during processing. For AuditService
requests received from UAUD, the UIS converts audit data from the
cef.shared.auditing.AuditData object format to that of the JSF class used.
All insert, delete, and update actions can be audited as well as specific get actions.
Some data list retrieval functions may not be audited.
120
8.3.2 Data Source Context
All data for a data source will be represented in the primary data object as key/value
pairs with the key(s) being the logical name(s) from the data source. The data will be
representative of either request or response data as follows:
Request
All of the respective data elements retrieved from incoming requests are stored as a key
/ string value pairs in the primary data object. Special rules include:
¾ When processing XML request messages containing group elements, the group is flattened
out and only the sub-elements are added to the data object. This places the requirement that
all XML elements contained in a request message must be unique across the entire
message.
¾ When processing XML request messages containing elements or groups that can have
multiple rows (maxOccurs is greater than 1), each row of information will be placed in an
additional row contained in the data object (starting at row 0 (default row) and going to either
the maxOccurs limit or the maximum number of rows found, whichever is less). The first rule
above also applies (flattening of group data).
Response
All of the respective data elements retrieved from data sources or specific field error
information are stored as a String value, under this data object, and is accessed by its
key element name (except in the case of field error processing). The data values will be
used to generate response messages.
Special creation rules include:
¾ When processing multiple rows of retrieved data (maxOccurs is greater than 1), each row of
information will be placed in an additional row contained in the data object (starting at row 0
(default row) and going to either the maxOccurs limit or the maximum number of rows found,
whichever is less).
¾ If there are 1 or more fields that are in error because of requirement and/or data validation
checks, error information specific to each field will be contained in the data object per the
guidelines under the Error Context sub-section that follows.
121
8.3.3 Error Context
If there are 1 or more fields that are in error because of requirement and/or data
validation checks, error information specific to each field will be contained in the data
object as follows:
Each field in error will be represented in a separate row starting at row 0.

The associated field ID will be indicated with a key of ErrorFieldID.
The associated row index will be indicated with a key of ErrorErrIndex.
The associated error code will be indicated with a key of ErrorErrCode.
The associated error description will be indicated with a key of ErrorErrDescr.
122
8.3.4 Filtering Context
8.3.4.1 FILTER_FIELD_MAP
The value associated with this key identifies those fields (and their logical name
mappings) that are being filtered for the current task involved. This information is used
to extract information from request messages as well as provide filtering support on data
retrieval at the database layer.
8.3.4.2 FILTER_MAINT_MAP
The value associated with this key identifies those fields (and their logical name
mappings) that are being filter maintained for the current task involved. This information
is used to add/remove filter value information to/from the USEC database..
123
8.3.5 Message Context
8.3.5.1 EXTERNAL_CONNECTION_ID_STR
The value associated with this key indicates the External Connection associated with a
message.
8.3.5.2 EXTERNAL_REQUEST_BYTE
The value associated with this key specifies a byte array (byte[]) containing the original
XML request message or the request message to be sent to an external entity.
8.3.5.3 EXTERNAL_RESPONSE_BYTE
The value associated with this key specifies a byte array (byte[]) containing the
formatted XML response message or the incoming response from an external entity.
8.3.5.4 MESSAGE_UNIQUE_ID_STR
The value associated with this key provides a key to message context stored, retrieved,
and deleted for outstanding messages in the Message Services.
8.3.5.5 XML_INBND_RQ_TRAN_TYPE
The value associated with this key specifies the transaction key value identifying what
the incoming request tag was (keyed by the root tag of the XML request message).
8.3.5.6 XML_INBND_RS_TRAN_TYPE
the response tag will be for replying to the inbound request (keyed by the root tag of the
XML request message).
8.3.5.7 XML_OUTBND_RQ_TRAN_TYPE
the request tag will be for sending an outbound request.
8.3.5.8 XML_OUTBND_RS_TRAN_TYPE
the response tag will be for receiving a response to an outbound request.
8.3.5.9 XML_RESP_ROOT
The value associated with this key stores the XML response message as an XML
document with the beginning root Element.
124
8.3.5.10 XML_RQST_ROOT
The value associated with this key stores the XML request message as an XML
document with the beginning root Element.
125
8.3.6 Miscellaneous Context
8.3.6.1 APP_ROW
The value associated with this key indicates the next row in the primary data object to
append data to. This is only utilized on getAll and getBy functions AND only on
subsequent calls to similar functions. Data appending should only be performed when
retrieving data from multiple data sources containing the exact same pertinent data as
an immediate prior processed data source.
Setting of this key/value comes from the <method> tag of the respective transmap
configuration file entry for the request being processed.
8.3.6.2 BYPASS_UPDATE_LAST_FM
The value associated with this key indicates the update processing for a data source will
NOT include last maintenance timestamp handling. This is primarily supported for
processing of contingency SAF requests on a secondary Web Server.
8.3.6.3 CHANNEL_DATA
The value associated with this key stores the original UIF channel data information
received from the request message.
8.3.6.4 CMND_IDX
The value associated with this key specifies the current <command> set being
processed from the associated transmap configuration file entry.
This is an internal value used by UIS that should not be modified by a user.
8.3.6.5 DATA_VALIDATED
The value associated with this key indicates to the CommandController class (and the
sub-classes it uses) that the data validation step for the current request has been
performed. This helps avoid repeated data validations from occurring.
8.3.6.6 DELETE_BY_ORIG
When present, the value associated with this key specifies a setting of true to indicate
that UIS is performing special delete handling. This is typically used in cases where an
update request has been issued, part of the update includes primary key fields which are
typically not allowed to be updated, and the implementation must perform one or more
deletes followed by one or more inserts to achieve the desired results.
The data component layer expects the NEW_DATA and ORIG_DATA key/values to
also be present when processing this key.
126
8.3.6.7 DYNAMIC_DS_NAME
When present, the value associated with this key specifies the actual data source to be
processed during database actions. This is to be used in cases where multiple tables
sharing the same structure can be accessed from a common database service, provided
the database service is given the name of the data source to access. The value for this
key will typically come from a client, supplied in a request message, and will be loaded
into this key by an extended XMLFormatter class.
8.3.6.8 FIELD_MAINT_MAP
When present, identifies the current field element names for those elements that have
filter requirements in the USEC database. If this map is present near the end of request
processing, additional filter processing will be performed with the USEC environment.
8.3.6.9 FILTER_MAINT_MAP
When present, identifies the current element mapping for those elements that have filter
requirements in the USEC database. If this map is present near the end of request
processing, additional filter processing will be performed with the USEC environment.
8.3.6.10 IN_TRANSACTION
When present, identifies if the current data component processing is being done within
the context of a database transaction. If not present, then standard, non-transactional
support is being performed.
8.3.6.11 MAX_ROWS
The value associated with this key specifies the maximum number of rows that the
database layer will retrieve and return on getAll and getBy processing.
Setting of this key/value comes from the <method> tag of the respective transmap
configuration file entry for the request being processed.
8.3.6.12 MSG_IND
The value associated with this key identifies the type of message processing currently
being (i.e. inbound/outbound request/response). Used to provide proper message
handling in the message layer.
127
8.3.6.13 MSG_TYPE
When present, the value associated with this key identifies the type of message
processing that must be performed for outbound request messages. It is used as a
helper value in instances where the outbound message may be in a different format
other than XML. Currently, we only support XML for all inbound and outbound
messaging.
8.3.6.14 MULTI_ROWS
When present, the value associated with this key specifies a setting of true to indicate
that UIS is performing special original delete row handling.
8.3.6.15 NEW_DATA
The value associated with this key specifies the appropriate named logical data
elements, for the data source, with the new set of values that will be used for INSERT
processing.
This key must be present in conjunction with the DELETE_BY_ORIG and ORIG_DATA
key/values.
8.3.6.16 NUM_RESP_ROWS
The value associated with this key specifies the number of data object rows that actually
contain valid response data. This information is provided by the data source
components and utilized by the MessageSchema class during response building.
8.3.6.17 ORIG_DATA
The value associated with this key specifies the appropriate named logical data
elements, for the data source, with the old set of values that will be used for DELETE
processing.
This key must be present in conjunction with the DELETE_BY_ORIG and NEW_DATA
key/values.
8.3.6.18 RESP_STAT
When present, the value associated with this key specifies the internal approval
response code when the data object’s error code is null. Currently, the only values this
could contain are DBS_FILE_OK (response message value set to FILE_OK on
outbound responses) and DBS_FILE_EXHAUSTED (response message value set to
FILE_EXHAUSTED on outbound responses).
128
8.3.6.19 ROW_ID_MAP
The value associated with this key indicates any received RowID settings received from
a request message. When multiple data rows are received in a request, this map helps
coordinate error data setting and other processing necessary to keep the server and
client display in sync.
8.3.6.20 TRAN_IDX
The value associated with this key specifies the current <transaction> set being
processed from the associated transmap configuration file entry.
8.3.6.21 TRANSACTION_MAP_ENTRY_STR
The value associated with this key specifies a TransactionMapField object that
contains a single <entry> set of information from a trans map XML script file. The object
is used throughout formatter and command processing to guide request processing.
8.3.6.22 TRANSACTION_MAP_KEY_STR
The value associated with this key specifies the transaction key value (root tag of the
XML request message) used to access the proper configuration map entry in the trans
map files.
129
8.3.7 Security Context
8.3.7.1 SECURITY_VERIFIED
The value associated with this key specifies a true or false value to indicate if the
CommandController class has already performed USEC related authentication and
authorization functions. This processing is performed one time during processing when
the ESTransCommand or ESSimpleCommand classes are invoked.
8.3.7.2 USEC_PERMISSION_DATA
The value associated with this key is a USEC Permissions data object that provides task
permission and filtering information for a user that is used to provide authorization
support within the UIS environment. This information is used to provide task/function
verification as well as filtering support at both the top level command processing layer
and at the database layer.
8.3.7.3 USER_SUBJECT
The value associated with this key specifies the USEC user subject data object
containing security data for the current request. This information is used when
performing various security related tasks.
130

BASE24-eps - UIS Developers Guide

Uploaded by

Copyright:

Available Formats

BASE24-eps - UIS Developers Guide

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

BASE24-eps - UIS Developers Guide

Uploaded by

Copyright:

Available Formats

Title Page

UIS developers guide

1.1 Document Control .................................................................................... 6

2. BASE24-eps UIS Startup/Runtime Configuration........................................ 7

2.1 Auditing Properties ................................................................................... 7

3. BASE24-eps UIS Code/Configuration ....................................................... 24

3.1 XML Configuration Files ......................................................................... 24

4. BASE24-eps UIS XML Schemas............................................................... 50

4.1 Request/Response Message Definitions................................................ 50

5. Formatter/Command Configuration ........................................................... 68

6.1 Generators ............................................................................................. 78

7. How-To Guides ......................................................................................... 88

7.1 Create a New Request/Response Message........................................... 88

8.1 XML Simple Types and Restriction Hierarchy .......................................117

1.1 Document Control

Version: Author: Date Distributed:

MAJOR CHANGES: Initial release for 8.2.

1.3 Reference Documents

2.1 Auditing Properties

Default setting is for 30 days.

Default setting is for 23:59 (midnight).

Default setting is for 24 hours.

For BASE24-eps UIS contingency support, a property will be added as follows:

[Required – config.properties] This property contains the process ID of the process

[Required - config.properties] This property defines the amount of time, in

Example property entry:

[Required – config.properties] This property provides the data source URI

Example property entry:

Example property entry:

[Required – config.properties] This property indicates the maximum number of

Example property entry:

[Required – config.properties] This property defines the number of connections to

Example property entry:

[Required – config.properties] This property indicates the type of database being

Example property entry:

Example property entry:

Example property entry:

The JSF provides 2 logging mechanisms:

Example property entry:

Example property entry:

 es.server.common.DataTypeValidationManager (must be started before

Current UIS property entries in APPLCNFG includes:

Example property entry:

The UIS implementation of the JSF currently supports additional configuration

[Required – config.properties] This property identifies the home location of the

Example property entry:

2.6.1 Database Properties

[Required] This property identifies if database actions performed by a user is to be

Valid values are true and false.

 full - report on times, users, activity and details (default)

2.6.1.3 db.cached.[service name]

Valid values are true and false (default).

The JSF provides 2 logging mechanisms:

Valid values are true and false.

Valid values are true and false.

[Optional] This property is optional, but required if Application Management support is

The pre-loaded default property value is:

A valid example entry for this property is:

[Optional] This property is optional, but required if pass-thru processing is being

es.server.common.DataTypeValidationManager (must be started before

full - report on times, users, activity and details (default)

getBy<name> for generated component code

getBy<name> for generated component code

updateBy<name> for generated component code