Installation and Configuration Guide - OATSystemssupport.oatsystems.com/training/oat80_docs/Installation_Config.pdf · Installation and Configuration Guide Version 8.0 OATSystems,

Installation and Configuration Guide

Version 8.0 OATSystems, Inc.August 2012 Document Number: OAT_OFS_ICG_8.0

Copyright © 2012 OATSystem s Inc. All Rights Reserved.

This docum ent contains proprietary inform ation that is owned by OATSystem s. Copying or reproduc-tion of any m aterial from this site to any other location for further reproduction or redistribution is expressly prohibited. Any reproduction or redistribution of the files not in accordance with the term s of the License Statem ent is a violation of copyright law.

OAT and Senseware are registered tradem arks of OATSystem s, Inc.

Java and all Java-based m arks are tradem arks or registered tradem arks of O racle Corporation in the United States and other countries. OATSystem s is independent of O racle Corporation.

O racle is a registered tradem ark of O racle Corporation and/or its affiliates.

IBM is a registered tradem ark of International Business M achines Corporation.

M icroStrategy 8, M icroStrategy Intelligence Server, M icroStrategy W eb Universal, and M icroStrategy Desktop are registered tradem arks or tradem arks of M icroStrategy Incorporated.

M icrosoft and W indows are either registered tradem arks or tradem arks of M icrosoft Corporation in the United States and/or other countries.

All other trade nam es and tradem arks are the property of their respective owners.

OATSystem s m akes no warranties, express or im plied, with regards to its products in this docum ent.

Support Inform ation

You can contact the OAT Support Center (O SC) for technical support at:OATSystem s, Inc.200 W est StreetW altham , M A 02451USA

Phone: 877-OAT-SUPPO RT or 781-907-6081Fax: 781-907-6098Em ail: info@oatsystem s.comW eb site: https://support.oatsystem s.com

CONTENTS

CHAPTER 1 Introduction................................................................................................2Overview ..........................................................................................................................2The OAT Foundation Suite Architecture.....................................................................3

CHAPTER 2 First Steps in Installation.........................................................................6Overview ..........................................................................................................................6Basic Installation Requirements ....................................................................................7OFS Deployments ...........................................................................................................8Hardware Requirements................................................................................................9Software Requirements ................................................................................................12Hardware Requirements for Database Servers .......................................................13Software Requirements for Database Servers...........................................................15

CHAPTER 3 Installing OAT Enterprise Data Manager (Windows) .....................24Before You Begin ...........................................................................................................24Installing OAT Enterprise Data Manager..................................................................26

CHAPTER 4 Installing OAT Enterprise Data Manager (Linux) ............................48Before You Begin ...........................................................................................................48Installing OAT Enterprise Data Manager..................................................................50

CHAPTER 5 Installing OAT Enterprise Administrator (Windows) .....................78Before You Begin ...........................................................................................................78Installing OAT Enterprise Administrator..................................................................79

CHAPTER 6 Installing OAT Enterprise Administrator (Linux) ..........................104Before You Begin .........................................................................................................104

OAT Foundation Suite i

Installing OAT Enterprise Administrator on Linux...............................................106

CHAPTER 7 Installing OATxpress Server (Windows)..........................................132Before You Begin .........................................................................................................132Installing OATxpress Server......................................................................................134Configuring OPC Server ............................................................................................153

CHAPTER 8 Installing OATxpress Server (Linux) ................................................156Before You Begin .........................................................................................................156Installing OATxpress Server......................................................................................158Configuring OPC Server with OATxpress ..............................................................184

CHAPTER 9 Installing OATxpress Server (Ubuntu).............................................186Installing OATxpress on Ubuntu..............................................................................186

CHAPTER 10 Non‐default Database and Web Server Options...........................188Creating a DB2 Database............................................................................................188Installation with a DB2 Database..............................................................................190Installation with an Oracle Database .......................................................................193WebSphere Application Server (WAS) Installation Options on Windows ........195

CHAPTER 11 Acquiring & Installing a License Key .............................................216Requesting a License Key...........................................................................................217Installing the License Key ..........................................................................................222

CHAPTER 12 OAT Enterprise Data Manager Post‐Installation Procedures.....226Starting the OAT Enterprise Data Manager............................................................226Verifying Startup of the OAT Enterprise Data Manager ......................................228Stopping the OAT Enterprise Data Manager..........................................................229

CHAPTER 13 OAT Enterprise Administrator Post‐Installation Procedures.....230Starting the OAT Enterprise Administrator............................................................231

ii Installation and Configuration Guide

Verifying Startup of the OAT Enterprise Administrator ......................................232Logging in to OAT Enterprise Administrator ........................................................233Stopping the OAT Enterprise Administrator..........................................................234

CHAPTER 14 OATxpress Server Post‐Installation Procedures ...........................236Starting the OATxpress Server..................................................................................237Verifying startup of Tomcat and OATxpress Server .............................................238Logging in to the Web Application ..........................................................................239Stopping the OATxpress Server................................................................................240

CHAPTER 15 Configuring OAT EDM & OAT Enterprise Administrator.........244Configuring OAT Enterprise Data Manager...........................................................244Configuring OAT Enterprise Administrator ..........................................................255Configuring OAT EDM after OAT EA Installation................................................255

CHAPTER 16 Migrating from standalone to Enterprise ‐ managed OATxpress258Introduction ................................................................................................................258Prerequisites.................................................................................................................259Migrating to Enterprise ‐ managed OATxpress .....................................................259

CHAPTER 17 Uninstalling the OAT Enterprise Data Manager ..........................268Uninstalling OAT Enterprise Data Manager on Windows...................................269Uninstalling OAT Enterprise Data Manager on Linux..........................................272

CHAPTER 18 Uninstalling the OAT Enterprise Administrator ..........................274Uninstalling OAT Enterprise Administrator on Windows...................................274Uninstalling OAT Enterprise Administrator on Linux .........................................278

CHAPTER 19 Uninstalling the OATxpress Server.................................................280Uninstalling OATxpress on Windows.....................................................................280Uninstalling OATxpress on Linux............................................................................284

OAT Foundation Suite iii

Uninstalling OATxpress on Ubuntu ........................................................................284

APPENDIX A Installation Knowledge Base .................................................................288

Introduction .................................................................................................................288Log files to be checked................................................................................................288Service Names..............................................................................................................289WebSphere ClassLoader ............................................................................................290

APPENDIX B OAT Foundation Suite Security ............................................................292

WebApp Security ........................................................................................................292Database Security ........................................................................................................298RMI Security ................................................................................................................298JMS Security .................................................................................................................299Web Service Security ..................................................................................................299Keystore Management for SSL..................................................................................307Ports...............................................................................................................................309

APPENDIX C Configuring Files for Products ..............................................................318

Using the XML files ....................................................................................................318

APPENDIX D Ubuntu Setup Properties File ................................................................326

Sample of the Ubuntu Setup Properties File ..........................................................326

APPENDIX E Configuring WebSphere AppServer and MQ for SOA....................330

Configure WebSphere MQ ........................................................................................330Configure WebSphere AppServer JNDI Resource.................................................332

APPENDIX F Kettle ETL Setup.......................................................................................334

Install OFS OAT Enterprise Data Manager Server.................................................334

iv Installation and Configuration Guide

Importing Kettle Metadata Repository ....................................................................335

APPENDIX G MicroStrategy Configuration.................................................................338

Install and Configure OAT Enterprise Data Manager...........................................339Install and Configure MicroStrategy........................................................................339Run and Configure the oatentreports Web Application .......................................364Load the Data...............................................................................................................368View the Reports .........................................................................................................368Configure an MSTR Server Behind a Firewall........................................................368Enable Retailer and Supplier Portal Reports...........................................................368

APPENDIX H Configuring OFS for WAS Data Source ..............................................372

Overview ......................................................................................................................372Configure Connection Pool in WebSphere..............................................................373Configuring OFS to Use WAS Data Source.............................................................387

APPENDIX I Install OFS in a Federated Environment...............................................388

Overview ......................................................................................................................388OFS Installation ...........................................................................................................388OFS Application Server Settings...............................................................................390Creating JDBC Provider .............................................................................................391Creating Connection Pool ..........................................................................................392Database update ..........................................................................................................393Running the Deployer ................................................................................................394

APPENDIX J Customizing Reports................................................................................396

Introduction .................................................................................................................396Sample Configuration.................................................................................................397Customizing Configuration.......................................................................................399

OAT Foundation Suite v

Available Custom Search Criteria ............................................................................400

vi Installation and Configuration Guide

SECTION 1

Introduction & Requirements

CHAPTER 1 Introduction

In this chapter This chapter describes the architecture of the OAT Foundation Suite (OFS) and the role of various OAT Foundation Suite components in a typical enterprise‐wide RFID infrastructure rollout.

OverviewThe OAT Foundation Suite consists of four integrated software components that can be installed and configured separately.

OATxpress performs real‐time operations in an RFID deployment, such as device management, business process execution and data capture. It provides RFID middleware for data capture and aggregation, device management and monitoring, EPC number and product management, and integration with business systems. Its core component is the scenario engine, an event‐driven workflow engine, which executes RFID/Auto‐ID centric business processes (such as pallet building, shipping, receiving) and allows business context data (such as orders, ASNs) to be associated with RFID data.

OAT Foundation Suite 2

Introduction

OATxpress servers can migrate their collected data to the OAT Enterprise Data Manager for analysis. They can manage the RFID infrastructure in one or more sites. Several OATxpress servers can be installed in an enterprise to manage all its sites.

OAT Enterprise Data Manager serves as the consolidation point and repository for RFID data from all OATxpress servers in the enterprise. It serves as a single point to collect contextualized EPC data from OATxpress servers. This aggregated data can be used for integrating with other business systems, or for reporting, dashboards, or analytics. It provides both a consistency engine to manage the data, as well as analytic capabilities to obtain value from the data. Examples of applications built using the analytics capabilities of the OAT Enterprise Data Manager are Real‐time Promotions Execution package and the Out‐of‐Stock Predication package.

The OAT Enterprise Administrator manages all OATxpress servers in an enterprise. It stores and distributes master data (such as locations, products and EPC number ranges) to the managed OATxpress servers, and, if configured, the OAT Enterprise Data Manager. It provides a single point to configure devices and scenarios at a server, and manages users and roles needed to access any server in the system. It also provides a dashboard to monitor events.

Lower‐level boxes indicate readers (antennae) that read or scan RFID tags, or other input devices such as barcode scanners or printers. Printers print RFID tags and convey print status data through the OATxpress servers.

The OAT Foundation Suite Architecture Figure 1 shows the deployment architecture of an enterprise‐wide installation of OAT Foundation Suite components.

3 Installation and Configuration Guide

FIGURE 1. The OAT Foundation Suite Architecture


Introduction


CHAPTER 2 First Steps in Installation

OverviewThis chapter describes the hardware and software requirements and basic knowledge prerequisites for installing the following:

• OAT Enterprise Administrator• OAT Enterprise Data Manager• OATxpress Server


First Steps in Installation

Basic Installation RequirementsFollowing is a list of requirements and basic information that you need to install the OAT Foundation Suite:

• The single OATenterprise installer offers three server options, enabling you to install each of the following products:• OAT Enterprise Administrator• OAT Enterprise Data Manager• OATxpress Server

• You can install only one of these products during a single installer run. To install multiple products, re‐run the installer after installing one product.

• OAT does not recommend or support the installation of OATxpress server along with the OAT Enterprise Data Manager or the OAT Enterprise Admin‐istrator on the same machine. OAT Enterprise Administrator and OAT Enterprise Data Manager can be installed on the same machine in limited pilot deployments with low performance requirements.

• If you install multiple products on the same host, they must reside in differ‐ent installation folders, and listen on different ports (if you choose to use Tomcat) or be distinct server instances (if you choose to use WebSphere Application Server). The Tomcat server port and connector port are both required to be distinct for multiple products installed on the same host.

• The OATxpress server and OAT Enterprise Administrator products need connection and authentication details of the database server to create or con‐nect to the database for that product.

• The OAT Enterprise Data Manager installation requires connection and authentication details for the following databases:• An Enterprise Data Manager (EDM) database

The EDM database is created during the OAT Enterprise Data Manager installation, but its schema is similar to the OATxpress database schema.

• An Enterprise Administrator (EA) databaseThe Enterprise Administrator database connection and authentication details are required to be supplied, but the database itself is not created during the OAT Enterprise Data Manager installation ‐ this happens dur‐ing OAT Enterprise Administrator installation. The OAT Enterprise Data Manager uses the OAT Enterprise Administrator database for informa‐tion on scheduled batch processes, permissions, etc.


• An Enterprise Data Manager Star (EDM Star) databaseThe EDM Star database is created during the OAT Enterprise Data Man‐ager installation. This database is used for reporting.

The three products have distinct configuration files, hibernate mapping files, and database creation scripts, but share the rest of the installation package, including JDK, Tomcat, OFS libraries, configurations and command line tools.

The Client browser supported for all products is:

• Internet Explorer 7• Internet Explorer 8• Firefox

The minimum supported screen resolution for all the products is: 1024 x 768 pixels.

OFS DeploymentsThe OAT Foundation Suite supports three deployment architectures described below:

• A standalone OATxpress serverThis configuration is only suitable for limited deployments of RFID infra‐structure, such as pilots and limited rollouts. A standalone OATxpress server cannot be managed by an OAT Enterprise Administrator and cannot send gathered information to an OAT Enterprise Data Manager. In a stand‐alone OATxpress installation, you can directly configure locations, products, devices and scenarios through the OATxpress Web application.

• One or more OATxpress server(s) and OAT Enterprise AdministratorIn this configuration, the OAT Enterprise Administrator can be used to cen‐trally configure shared master information, such as locations and products, devices and scenarios. The Enterprise Administrator also provides access to the OATxpress servers to configure devices and scenarios through the OATxpress Web application. Devices and scenarios can also be configured locally on each OATxpress server. It is strongly recommended that you perform all the configuration



tasks through the OATenterprise Web application, to have an overall central administration feel.This configuration is useful when an enterprise‐wide rollout is planned, but there is no imminent requirement to collect the data centrally. An OAT Enterprise Data Manager can be installed later to upgrade this configuration to the next one mentioned below. The OATxpress servers and the OAT Enterprise Administrator must be installed on separate server hardware.

• One or more OATxpress server(s), OAT Enterprise Administrator and OAT Enterprise Data ManagerThis configuration corresponds to the deployment architecture in Figure 1. Apart from central management using the OAT Enterprise Administrator, this configuration allows OATxpress servers to migrate the collected data to OAT Enterprise Data Manager for enterprise‐wide analysis. The OATxpress servers must be installed on separate server hardware.

Hardware Requirements

OAT Enterprise Data Manager & OAT Enterprise Administrator

TABLE 1.

Hardware Minimum Recommended

Processor Intel Pentium M or Xeon Intel Pentium Xeon or Dual‐Core

Number of processors 1 2

Core speed 2.0 GHz 3.0 GHz or more

Front‐side bus speed 400 MHz 800 MHz or more

L2 cache 1 MB 4 MB or more


OATxpress Server

Memory2 GB memory for each (4 GB if both are running on the same machine)

4 GB or more

Total HDD capacity 80 GB 160 GB or more. RAID 1/5 preferred

Spindle speed 5400 RPM 10000 RPM or more

Hard drive bus speed 66 Mbps (ATA) 150 Mbps or more (SATA or SAS)

Ethernet controller and LAN connectivity to data‐base server

100 Mbps 1 Gbps or more

TABLE 2.







Memory 2 GB RAM 4 GB or more


TABLE 1.






Ethernet controller and LAN connectivity to data‐base server

10 Mbps 100 Mbps or more

TABLE 2.



Software Requirements

Supported Software Configurations

The OAT Foundation Suite runs with the combinations of operating systems, database software, and Web servers given in the table below.

How to read the table The Operating Systems shown in column 1 support the Database Software in column 2 and Application servers in column 3. For example, in row 1, Microsoft Windows Server 2008 SP1/SP2 supports the database software listed in column 2 (of the same row), and the Apache Tomcat 6.0.26 Application server.

TABLE 3.

Operating System Database Software Application Server

Microsoft Windows Server 2008, SP1/SP2

• Microsoft SQL Server 2008• Oracle 11g

(Enterprise Edition 11.1.0.6)

Apache Tomcat 6.0.26

Microsoft Windows Server 2008, SP1/SP2

• DB2 Universal Database 9.1.2 • Oracle 11g

(Enterprise Edition 11.1.0.6)

IBM WebSphere 6.1

Microsoft Windows 7 Microsoft SQL Server 2008Express Edition


Microsoft Windows Server 2008 Oracle 11g(Enterprise Edition 11.1.0.6)


RedHat Enterprise Linux ES/AS 4 (Update 4)

Oracle 11g (Enterprise Edition 11.1.0.6)


Ubuntu 10.04 LTS Oracle Database 10g Express Edition (Oracle XE)




OAT recommends having a separate database server system, rather than a database server on the same machine on which you install OAT components. However, if your enterprise installation crosses one of the threshold values mentioned in the table below, you should run your database server on a separate machine dedicated for that purpose, failing which overall system performance will be adversely impacted.

Hardware Requirements for Database Servers

TABLE 4.

Configuration Threshold beyond which database software must be installed on a separate server

OATxpress Server with high throughput

100 + EPCs processed every minute

Standalone Enterprise Administrator

10 + managed sites

Standalone Enterprise Data Manager

100 + EPCs processed every minute, or more than 1 million EPCs in database

TABLE 5.








Memory 1 GB 2 GB or more




Ethernet controller 10 Mbps 100 Mbps or more

TABLE 5.




Software Requirements for Database Servers

DB2

OAT Foundation Suite supports DB2 Workgroup Server Edition 9.1.2. While creating databases for use with OFS, observe the following:

• Use any name of your choice for each database.• Create two table spaces that are associated with each database: one of the

regular type, and one of the system temporary type. When creating the table spaces:• Define a container for each table space.• Create a buffer pool with a page size of 16 K for each table space.• Use defaults for all other settings.

• For each database use the DB2 Control Center to make the following changes:• Associate a DB2 user with the database. (In the object tree, expand

Instances ‐‐> DB2 ‐‐> Databases ‐‐> actual_database_name ‐‐> User and Group Objects. Right‐click on DB Users, select Add, and enter a DB2 username.)

• Associate the same DB2 user with the regular type — not the system temporary type — table space. (In the object tree, under actual_database_name, expand Table Spaces, right‐click the regular table space created earlier, select Privileges, and add the DB2 user to the list.)

• If the DB2 database and the OATxpress server are located on different machines, you must:• Install a DB2 client on the OATxpress server machine.• Catalog the DB2 instance (for example, DB2).

Note: You may change the database password, after installation if required. You can deploy (deploy ‐‐dbPassword =<newpassword> ) to change the password in the respective server. This is applicable for both Windows and Linux environment.

Refer to Chapter 10: Non‐default Database and Web Server Options for more information on creating a DB2 database.


Oracle®

If you use Oracle for OFS databases, the following conditions must be met for compatibility with OAT Enterprise Data Manager, OAT Enterprise Administrator and OATxpress:

• The servers must have Oracle Instant Client installed. In Linux environ‐ments, the directory where the client libraries are installed should be added to the LD_LIBRARY_PATH environment variable. In Windows environ‐ments, the Oracle installation directory is picked up from the registry.

• The database user account(s) to be used by the OFS installation must exist prior to installing the servers. You must specify the database username and when requested by the OFS installer. You can use the dbca graphical tool provided by Oracle, or any other tool, to create the database.

• You may change the database password, after installation if required. You can deploy (deploy ‐‐dbPassword =<newpassword> ) to change the pass‐word in the respective server. This is applicable for both Windows and Linux environment.Note the following restrictions while assigning a new password:

• Dollar $, under‐score_, and hash # are the only special characters that can be used.

• Use all the special characters within the double quotes. • Dollar $ and exclamation symbol ! cannot be used, if the installation is

through Linux. • The database user account(s) must have the following system roles and priv‐

ileges assigned by the SYS user:• CONNECT• RESOURCE• SELECT_CATALOG_ROLE• CREATE ANY MATERIALIZED VIEW• CREATE MATERIALIZED VIEW • ALTER MATERIALIZED VIEW • DROP MATERIALIZED VIEW • GLOBAL QUERY REWRITE• CREATE DATABASE LINK• CREATE SESSION



• CREATE TABLE• UNLIMITED TABLESPACE

To create and grant permissions to users, use the ʹsqlplusʹ command line tool. Follow the steps listed below:

1. Connect to Oracle using the command sqlplus / as sysdba.2. In the sqlplus prompt, type the following command to create a user:

SQL> create user <username> identified by <password>;

3. At the sqlplus prompt, type the following command to grant permissions to the user. The commands differ for different databases:• OATxpress/OAT Enterprise Administrator database:

SQL> grant CREATE SESSION, CREATE TABLE, CONNECT, RESOURCE, UNLIMITED TABLESPACE, DBA to <username>;

• OAT Enterprise Data Manager database:

SQL> grant CONNECT, RESOURCE, SELECT_CATALOG_ROLE, CREATE ANY MATERIALIZED VIEW, GLOBAL QUERY REWRITE, CREATE DATA-BASE LINK to <username>;

• OAT Enterprise Data Manager Star database:

SQL> grant DBA, CONNECT, RESOURCE, SELECT_CATALOG_ROLE, CREATE DATABASE LINK to <username>;

SQL Server 2008

If you are using Microsoft SQL Server 2008 for OFS databases, the following conditions must be met for compatibility:

• The Named Pipes network protocol must be disabled. (You can use the Cli‐ent Network Utility provided with SQL Server to disable the protocol.) and the TCP/IP network protocol must be enabled.

• Security for SQL Server must include SQL Server authentication.• Minimum of 64 concurrent user connections allowed.• All transaction logs must be set to auto‐grow.


• A user login must exist that has SQL Server authentication, database cre‐ation privileges, and access to the master database. Because there is no default database user in SQL Server, you must specify an existing database username and password when requested by the installer.

• If required you may change the above password by deploying (deploy ‐‐dbPassword =<newpassword> ) in the respective server. This is applicable for both Windows and Linux environment.More than one dollar $, cap symbol ^ and double quote ʺ in db password are not supported while giving new password.

The SQL Server database user that you specify for the OAT Enterprise Data Manager Star database must have read (SELECT) permission for the OAT Enterprise Data Manager database. This is required for ETL operation.

You can set these properties with the Microsoft SQL Server Management Studio as follows:

• Under Security in the SQL Server Properties dialog, select SQL Server and Windows Authentication.

• Under Connections in the SQL Server Properties dialog, set Maximum con‐current user connections to 65 or higher (or 0 for unlimited).

• In the SQL Server Login Properties dialog for a new or existing user account, perform the following steps:a. On the General tab:

1. If creating a new user account, enter the username. 2. Select SQL Server Authentication.

3. Specify a password.

b. On the Server Roles tab, check the Database Creators checkbox.

c. On the Database Access tab, check the Master Database checkbox.

d. Click OK.



Supported Web Servers

IBM WebSphere Application Server (WAS)

IBM WebSphere Application Server (WAS)

To increase timeouts for the deploy process in WebSphere Server, follow these steps:

1. Stop the WebSphere Server.2. Modify <WAS_INSTALL_DIR>/AppServer/profiles/<AppServerProfile>/

properties/soap.client.props file and change the SOAP request timeout to 30 minutes:

com.ibm.SOAP.requestTimeout=1800

3. Restart the WebSphere App Server.

WebSphere MQ IBM WebSphere MQ 6.0.2 must be installed, according to the directions in Appendix E: Configuring WebSphere AppServer and MQ for SOA.

Additional Software

The OATenterprise installer installs the following third‐party components with the OATxpress software:

• Apache Tomcat server 6.0.26 (when Tomcat is chosen)• Sun JDK 1.6

The installer installs Tomcat unless WebSphere is the chosen Web server. The OATenterprise installer installs these components in your installation directory (for example, C:\OATxpress\jakarta‐tomcat‐6.0.26).

Active Directory

Active Directory (AD) is needed if you use external user authentication. AD is recommended to be on a different host. OAT strongly recommends that you do not host AD on the same system on which you install OFS components.


JVM heap size settings

The OATenterprise installer sets the following values for the Java Virtual Machine (JVM) heap size for all three servers (OAT Enterprise Administrator, OAT Enterprise Data Manager and OATxpress server):

• Minimum size: 1024 Megabytes• Maximum size: 1024 Megabytes

The size restrictions apply whether OATxpress is installed as a Windows service or not.




SECTION II

Installation



CHAPTER 3 Installing OAT Enterprise Data Manager (Windows)

Introduction This chapter explains the steps for installing the OAT Enterprise Data Manager on the Windows platform.

Before You BeginBefore you start installing the OAT Enterprise Data Manager, you must have the following information about the server on which you want to install OAT Enterprise Data Manager:

• The server’s host name or IP address.• Database parameters such as the host name or IP address of the database

server (if, as is recommended, your database server is a different host from the one on which you are installing OAT Enterprise Data Manager); the port number on which the database server is accessible; and the database names for each of the following three databases:• OAT Enterprise Data Manager database• OAT Enterprise Data Manager Star database• OAT Enterprise Administrator database

• User credentials for each of these three databases: the user account (login name) and password.


Installing OAT Enterprise Data Manager (Windows)

• Web server information:• The port on which this system will accept HTTP connections. This port

should not be used by any other running programs, and should have any firewall running on the system configured to accept connections on that port.

• JMS configuration details:• JNDI Provider URL• JNDI Factory Class• JMS Connection Factory• JMS Destination• JMS User/Password if your JMS provider’s security is enabled • JMS Notification Queue Name for configuring JMS for SOA• JMS Import Queue Name for configuring JMS for SOA

Note the following:

• OAT does not recommend or support the installation of OAT Enterprise Data Manager and OATxpress Server on the same machine.

• Re‐installing OAT Enterprise Data Manager results in the loss of all data accumulated on the enterprise server since the previous installation.

• You must ensure that the database software (installed locally or remotely) is running during this installation procedure. You need to have observed the constraints mentioned in the section on your particular database software, under Supported Database Software in Chapter 2: First Steps in Installation, while creating the user accounts and databases which you will use with OFS applications.

• The steps below assume the default choice for Web server, which is Apache Tomcat. For instructions regarding IBM WebSphere Application Server, please refer to Chapter 10: Non‐default Database and Web Server Options.


Installing OAT Enterprise Data Manager1. Invoke:

setup.exe

The OAT Enterprise Data Manager installation screen appears. The OATenterprise installer, after extracting all components, displays the Introduction screen.

FIGURE 1. The Introduction Screen

2. Click Next. The License Agreement appears.Type a valid license key (license.txt file) to run OAT Enterprise Data Manager. Obtain this key and install it after you complete the installation of OAT Enterprise Data Manager. Chapter 11: Acquiring & Installing a License Key has instructions to guide you through obtaining and installing the license key.



FIGURE 2. The License Agreement Screen

3. Click the corresponding radio button to accept the license agreement. Click Next to display the Configure Server Mode screen. Select the type of server you are installing


.

FIGURE 3. The Configure Server Mode Screen

4. Select the OAT Enterprise Data Manager option from the list. Click Next.The Choose Install Folder screen appears.



FIGURE 4. The Choose Install Folder Screen

5. Click Choose... to specify the directory in which to install OAT Enterprise Data Manager, or click Restore Default Folder to install OAT Enterprise Data Manager in the default directory. The default location is C:\OATedm.

Note: If you assign an alternate path and folder, ensure that there are no spaces or special characters included in the directory path you have mentioned.

Click Next to proceed to the next step. The OAT Enterprise Data Manager Database Selection screen appears.


FIGURE 5. The OAT Enterprise Data Manager Database Selection Screen

Note: Ensure that the database software, installed locally or remotely, is during this installation.

6. Select the option that reflects the database software you are using, and click Next. The OAT Enterprise Data Manager Database Location screen appears.

Note: Since you have chosen Microsoft SQL Server 2008 as the database option, Apache Tomcat is the default Web server selected. If you opt for Oracle or IBM DB2 database options, refer to Chapter 10: Non‐default Database and Web Server Options to proceed with the installation.

Note: .If you are using a Microsoft SQL Server 2008 database and your database instance name is not the default name, then you must specify the host name and the database instance name in the form:

hostname\dbinstancename

as in the following example:



acme\mydb_instance

where “acme” is the host name, and “mydb_instance” is the database instance name. This format is required for both local and remote data‐bases.

FIGURE 6. The OAT Enterprise Data Manager Database Location Screen

7. Enter the host name or the IP address for the OAT Enterprise Data Manager database.

• If the database software is installed on the same machine, then specify localhost as the host name.

• If the database software is installed on a separate machine, then spec‐ify the host name or the IP address of that remote machine.

Click Next. You will be taken to the OAT Enterprise Data Manager Database input screen.


FIGURE 7. The OAT Enterprise Data Manager Database Input Screen

8. Specify the following values when Microsoft SQL Server 2008 is chosen as the database software. For IBM DB2 or Oracle databases, the values are slightly different. Please see Chapter 10: Non‐default Database and Web Server Options for details.• Database Name: Enter a unique name for the database to be used by the

OAT Enterprise Data Manager. • Database Port: Enter the port number assigned to the database software.• Database User with Privileges: Enter the database user account to be

used by the OAT Enterprise Data Manager to Create, Read, Update, and Delete (CRUD) data in the named database instance.

• Database Password: Enter the password for the database user account.

Note: You may change the above EDM password by deploying (deploy ‐‐dbPassword =<newpassword> ) in the respective server. This is applicable for both Windows and Linux environment.

Click Next.



A warning message is displayed that warns you that any existing database with the name you have given will have all the tables in that database deleted before it is used for OAT Enterprise Data Manager:

FIGURE 8. The Warning Dialog Box

9. If you choose to continue with the installation, then the OATenterprise installer deletes the tables from an existing database ‐ which may have been created during a previous installation of OAT Enterprise Data Manager. Click:• Cancel to cancel the OAT Enterprise Data Manager installation and avoid

deleting any database tables.• Continue to proceed with installation. The OAT Enterprise Administrator Database Location screen appears.


FIGURE 9. The OAT Enterprise Administrator Database Location Screen

10. Enter the host name or the IP address for the OAT Enterprise Administrator database.

• If the database software is installed locally, then specify localhost.• If the database software is installed remotely, then specify the host

name or the IP address of the remote machine.Click Next to proceed with the installation.The OAT Enterprise Administrator Database input screen appears.



FIGURE 10. The OAT Enterprise Administrator Database Input Screen

11. Specify the following values when Microsoft SQL Server 2008 is chosen as the database. For IBM DB2 or Oracle databases, the values are slightly differ‐ent. See Chapter 10: Non‐default Database and Web Server Options for details.• Database Name: Enter a unique name for the database to be used by the

OAT Enterprise Administrator.• Database Port: Enter the port number assigned to the database software.• Database User with Privileges: Enter the name of a database user

account to be used by the OAT Enterprise Administrator to Create, Read, Update, and Delete (CRUD) data of the database contents.


Note: Change the above EA database password in EDM by deploying (deploy ‐‐eaDbPassword =<newpassword> ) in the respective server. This is applicable for both Windows and Linux environ‐ment.


Click Next. The OAT Enterprise Data Manager (EDM) Star Database Location screen appears.

FIGURE 11. The OAT Enterprise Data Manager (EDM) Star Database Location Screen

12. Enter the host name or the IP address of the OAT Enterprise Data Manager (EDM) Star database server.

• If the database software is installed locally, then specify localhost.• If the database software is installed remotely, then specify the host

name or IP address of that remote machine.Click Next to proceed to the OAT Enterprise Data Manager (EDM) Star Database input screen.



FIGURE 12. The OAT Enterprise Data Manager (EDM) Star Database Input Screen

13. Specify the following values when Microsoft SQL Server 2008 is chosen as the database. For IBM DB2 or Oracle databases, the values are slightly differ‐ent. See Chapter 10: Non‐default Database and Web Server Options for details.• Database Name: Enter the name for the OAT Enterprise Data Manager

Star database.• Database Port: Enter the port number of the database software.• Database User with Privileges: Enter the name of a database user

account with privileges to Create, Read, Update, and Delete (CRUD) the database contents.


Note: Change the above Star database password in EDM by deploying (deploy ‐‐starDbPassword =<newpassword> ) in the respective server. This is applicable for both Windows and Linux environ‐ment


Click Next. The Warning dialog appears:


14. If you continue with the installation and OAT Enterprise Data Manager (or any component of the OAT Foundation Suite) was previously installed on the machine, the database tables created by that earlier installation will be deleted. Click:• Cancel to abort the OAT Enterprise Data Manager installation and avoid

the possibility of deleting any database tables.• Continue to proceed with the installation, deleting any OAT Enterprise

Data Manager Star database tables that may be found. The MSTR Server screen appears.



FIGURE 14. The MSTR Server Screen

15. Enter the IP address or the host name of the MSTR server (the server on which MicroStrategy is installed, or will be installed after this installation) from where the oatentreports will be accessible.

Note: See Appendix G: MicroStrategy Configuration, for information on how to configure MicroStrategy and deploy oatentreports Web application for OAT Enterprise Data Manager.

Click Next, to proceed to the Configure Web Server screen.


FIGURE 15. The Configure Web Server Screen

16. Enter configuration details for the Web server as follows:• To enable secure connections between Web browser and the OAT

Enterprise Data Manager, check the Yes checkbox. • Enter the port to be used for secure browsing in the https port for

browsing server field.• Enter the host name or the IP address of the machine on which you are

installing the OAT Enterprise Data Manager in the Host Name field.Click Next. You will now configure the OAT Enterprise Data Manager.

Note: If HTTPS is configured for one server in the OFS deployment hierarchy it must be configured for all. It is not possible to mix HTTPS‐enabled with HTTP‐only servers.



FIGURE 16. The Configure OAT Enterprise Data Manager Screen

17. Specify the following values:• Unique ID: Enter an enterprise‐unique 4‐digit hexadecimal identifier for

this installation of OAT Enterprise Data Manager.• Name: Enter an enterprise‐unique name for the OAT Enterprise Data

Manager.• Port (Web server): Enter the port on which you will have the non‐HTTPS

OAT EDM Web server running. In this case, it is the Tomcat Web server.• Port (Enterprise Data Manager server): Enter the port on which you

want the OAT Enterprise Data Manager to run.

Note: If you have chosen to enable HTTPS for secure connections between Web browsers and OAT Enterprise Data Manager in the previous step, then you will not be asked to provide a value for this field.

• Heap size in MB (Min): Enter the Java minimum heap size for OAT Enterprise Data Manager.


• Heap size in MB (Max): Enter the Java maximum heap size for OAT Enterprise Data Manager.

Click Next to display the Configure Security screen.

FIGURE 17. The Configure Security Screen

18. Enable security for RMI, JMS and Webservice as required, by checking the respective checkboxes. Click Next to proceed to the JMS Configuration screen.For more details on security, see Appendix B: OAT Foundation Suite Security.



FIGURE 18. The JMS Configuration Screen

19. Select:• Yes to use JMS (Java Message Service) transport functionality with your

Web service. Click Next, to proceed to the Configure JMS screen.

• No to bypass JMS configuration and proceed directly to step 22, which deals with the Install as Window Service screen.

Note: If your system has failover backup operation installed, then the Cluster Configure screen will appear.

The OAT Enterprise Data Manager can operate either with SOAP or JMS for data migration. Therefore, it is not possible to configure some OATxpress servers in a single deployment for SOAP and others in the same deployment for JMS.

Note: The installerʹs default values in the JMS configuration screens are those for Apache ActiveMQ, which is bundled with the OAT Foundation Suite.


FIGURE 19. The Configure JMS Screen

20. Specify the following values:• JNDI Provider URL: Enter the URL of the JNDI service.• JNDI Factory Class: Enter the JNDI initial context factory class used to

create initial context. • JMS Connection Factory: Enter the JNDI look‐up name for the JMS

connection factory object. • JMS Destination: Enter the JNDI look‐up name for the JMS destination

object (queue or topic). • JMS User: Enter the username for accessing the JMS provider. Leave this

box empty if security is not enabled in your JMS provider.

• JMS Password: Enter the password of the user. Leave this box empty if security is not enabled in your JMS provider.

Click Next. The Configure JMS for SOA screen appears.



FIGURE 20. The Configure JMS for SOA Screen




object (queue or topic). • JMS Notification Queue Name: Enter the JNDI name to look up the JMS

Destination for EPCIS events notifications.• JMS Import Queue Name: Enter the JNDI name to look up the JMS

Destination for Master Data Import.• JMS User: Enter the username for accessing the JMS provider. Leave this

box empty if security is not enabled in your JMS provider.



Note: See Appendix E: Configuring WebSphere AppServer and MQ for SOA for instructions on how to install and configure IBM WebSphere MQ as the JMS provider for OAT Enterprise Data Manager.

Click Next. The Install as Windows Service screen appears.

FIGURE 21. The Install as Windows Service Screen

22. Select:• Yes to run OAT Enterprise Data Manager as a Windows service. The OAT

Enterprise Data Manager server software restarts automatically following a restart of the server machine.

• No not to run OAT Enterprise Data Manager as a Windows service. Manually start the OAT Enterprise Data Manager service when it is required. Click Next for a pre‐installation summary of your selections.



FIGURE 22. The Pre‐Installation Summary Screen

23. Review your OAT Enterprise Data Manager configuration selections before installing. • Click Previous to modify the installation options. • Click Install to install the OAT Enterprise Data Manager. The Installing OATenterprise screen appears, when OAT Enterprise Data Manager starts installing.

24. After finishing the install, you will see a message in the Done Installing screen. Check the View README File checkbox, and click Next to view the View Readme File screen.

25. Review the Readme file; to view the entire file, you’ll have to scroll through the viewing pane. Click Next to proceed to the Install Complete screen.

26. Click Done to complete the install.

See Appendix A: Installation Knowledge Base for information on verifying that your installation was successful.


CHAPTER 4 Installing OAT Enterprise Data Manager (Linux)

Introduction This chapter explains the steps to be followed for installing the OAT Enterprise Data Manager on the Linux platform in text‐based console mode.

Before You BeginBefore you start installing the OAT Enterprise Data Manager, have the following information a ready to enter them when required by the installer:

• The server’s host name or static IP address.• Database parameters such as the host name or IP address of the database

server (if, as is recommended, your database server is a different host from the one on which you are installing OAT Enterprise Data Manager); the port number on which the database server is accessible; and the database names for each of the following three databases:

• OAT Enterprise Data Manager database• OAT Enterprise Data Manager Star database• OAT Enterprise Administrator database

You also need the correct user credentials for each of these three databases: the user account (login name) and password.

• Web server information:• The ports on which this system will accept HTTP or HTTPS browser and

webservice connections. These ports should not be used by any other


Installing OAT Enterprise Data Manager (Linux)

programs, and should have any firewall that is running on the system configured to accept connections on these ports.

• JMS configuration details:• JNDI Provider URL• JNDI Factory Class• JMS Connection Factory• JMS Destination• JMS User/Password if your JMS provider’s security is enabled• JMS Notification Queue Name for configuring JMS for SOA• JMS Import Queue Name for configuring JMS for SOA

Please note the following:

• OAT does not recommend or support the installation of OAT Enterprise Data Manager, OATxpress and OAT Enterprise Administrator on the same machine.

• The OAT Enterprise Data Manager requires a valid license key to operate. Please see Chapter 11: Acquiring & Installing a License Key for instructions on how to acquire and install a license key.

• You must be logged on as root to run the OATenterprise installer to install the OAT Enterprise Data Manager.

• Re‐installing OAT Enterprise Data Manager results in the loss of all data accumulated with OAT Enterprise Data Manager since the previous installation.

• You must ensure that the database software (installed locally or remotely) is running during this installation procedure. You need to have observed the constraints mentioned in the section on your particular database software, under Supported Database Software in Chapter 2: First Steps in Installation, while creating the user accounts and databases which you will use with OFS applications.

• If you are reusing the OAT Enterprise Data Manager database instance, ensure that no connection exists between the database instance and a client, or the OAT Enterprise Data Manager server, before reinstalling OAT Enterprise Data Manager. Consider restarting the database server to break connections to all database instances.

• Ensure that the machine’s system clock registers the current date and time before installing OAT Enterprise Data Manager.


• Ensure that the environment variable LD_LIBRARY_PATH includes a reference to the directory with Oracle client libraries if the Oracle Instant Client is not installed using the Oracle installer. If the client is installed using the Oracle installer, do not set this environment variable.

• The steps below assume the default choice for the Web server, which is Apache Tomcat. For instructions regarding IBM WebSphere Application Server, please refer to Chapter 10: Non‐default Database and Web Server Options. While those instructions refer to the Windows installation screens, the flow and input values are the same for both Windows and Linux platforms.

Installing OAT Enterprise Data ManagerTo install OAT Enterprise Data Manager on Linux:

1. Invoke setup as follows:

./setup.bin

The installation screen appears. The OATenterprise installer displays an introduction.




2. Press Enter to advance to the License Agreement screen.


FIGURE 24. The License Agreement Screen (a)

3. Review the terms and conditions of the license agreement, press Enter till you get DO YOU ACCEPT THE TERMS OF THIS LICENSE AGREEMENT? message. This screen reminds you that you need a valid license key (license.txt file) to run OAT Enterprise Data Manager. You need to obtain this key and install it after you complete the installation of OAT Enterprise Data Manager. Chapter 11: Acquiring & Installing a License Key contains instructions to guide you through obtaining and installing the license key.



FIGURE 25. The License Agreement Screen (b)

4. Type Y to accept the terms and conditions of this license agreement, and press Enter. You will be asked to select the type of server you want to install in the next step.



5. Enter the number for your choice, and press Enter. Since you are installing the OAT Enterprise Data Manager, select 1 and press Enter to continue.


6. Specify the location for installing the OAT Enterprise Data Manager. Enter an absolute path and press Enter, or simply press Enter to accept the default location.

Note: If you mention an alternate path, ensure that there are no spaces or special characters included in the location path.

Note: In steps below, pressing Enter without entering a specific value will accept the installer default value for the step, and proceed to the next step. The installer default for the current step is shown as a string (for example, the Install Folder above) or as an arrow marking one of the choices in a menu (for example, the choice of type of server to install, below).



FIGURE 28. The OAT Enterprise Data Manager Database Selection Screen

7. Select the database software you will be using with the OAT Enterprise Data Manager by entering the number of your choice, and press Enter. In this case, we enter 1 to choose the Oracle database software option.

Note: If you choose the IBM DB2 database option, refer to Chapter 10: Non‐default Database and Web Server Options for database creation details, and for an explanation of the parameters requested. Note that the information is applicable to both Windows and Linux installations.

Note: The OAT Enterprise Data Manager server uses three database schemas. The OATenterprise installer requests database information for each schema, starting with the OAT Enterprise Data Manager database. Always assign different database names to the database instances.

FIGURE 29. The OAT Enterprise Data Manager Configure Database Screen

8. Enter the path in which the database client (or server, if the database server is running on the same system) has been installed, and press Enter to con‐


tinue. To use the default location, press Enter.This is required in order to find the location of the sqlplus binary utility.

FIGURE 30. The OAT Enterprise Data Manager Database Location Screen

9. Specify the IP address or the host name of the server running the database software you have chosen to use for OAT Enterprise Data Manager. • If the database software is installed on the same machine, then enter

localhost.• If, as OAT recommends, it is installed on a remote machine, then enter the

IP address or the host name of the remote machine where the database software is running.

FIGURE 31. The OAT Enterprise Data Manager Database SID Name Screen

10. Enter the SID (System ID) Name for the database. A message warns you that any existing database with the name you have given will have all tables in that database deleted before it is used for OAT Enterprise Data Manager.



FIGURE 32. The Warning Screen

11. Enter the number of your choice, and press Enter.If you choose to continue with the installation, then the OATenterprise installer will delete the tables from an existing database ‐ which may have been created during a previous installation of OAT Enterprise Data Manager. By canceling the installation, you avoid deleting any database tables, and abort the installation procedure.

FIGURE 33. The OAT Enterprise Data Manager Database Service Name Screen

12. Enter the Database Service Name (the database name), or accept the default.


FIGURE 34. The OAT Enterprise Data Manager Oracle Port Screen

13. Enter the Database Port number assigned to the database listener, and press Enter to continue. In this case, the default number provided is the correct port for the Oracle database listener.

FIGURE 35. The OAT Enterprise Data Manager Database User Screen

14. Enter the name of a database user account which has permission to execute Create, Read, Update and Delete (CRUD) operations on the specified data‐base.

FIGURE 36. The OAT Enterprise Data Manager Database Password Screen

15. Enter the password for the database user account you have just entered. The installer now proceeds to request similar information for the OAT Enterprise Administrator database.




16. Specify the IP address or the host name of the server hosting the database you will use for the OAT Enterprise Administrator. • If the database software is installed on the same machine, then enter

localhost.• If it is installed on a remote machine, then enter the IP address or the host

name of the remote machine.

FIGURE 38. The OAT Enterprise Administrator Database SID Name Screen

17. Enter the SID (System ID) Name for the database instance to be used by the OAT Enterprise Administrator.


FIGURE 39. The OAT Enterprise Administrator Database Service Name Screen

18. Enter the Database Service Name for the OAT Enterprise Administrator database.

FIGURE 40. The OAT Enterprise Administrator Oracle Port Screen

19. Enter the OAT Enterprise Administrator Database Port number assigned to the database listener. In this case, the default is the correct number for the Oracle database listener.

FIGURE 41. The OAT Enterprise Administrator Database User Screen

20. Enter the name of a database user account with permission to perform Cre‐ate, Read, Update, and Delete (CRUD) operations.



FIGURE 42. The OAT Enterprise Administrator Database Password Screen

21. Enter the password for the database user account you have just entered. The OATenterprise installer now proceeds to request configuration information for the OAT Enterprise Data Manager Star Database.

FIGURE 43. The Star Database Location Screen

22. Specify the IP address or the host name of the server hosting the database you will use for the OAT Enterprise Data Manager Star database. • If the database software is installed on the same machine, then enter


name of that remote machine.


FIGURE 44. The OAT Enterprise Data Manager (EDM) Star Database SID Name Screen

23. Enter the OAT Enterprise Data Manager SID (System ID) Name for the data‐base instance. The database instance must already exist.

FIGURE 45. The OAT Enterprise Data Manager (EDM) Star Database Service Name Screen

24. Enter the service name for the OAT Enterprise Data Manager Star Database. Press Enter to continue with the installation.A warning message appears.




25. Enter the number of your choice, and press Enter to continue.If you continue with the installation, the database tables in an existing database with the name you have provided will be deleted. By canceling the installation, you avoid the possibility of deleting any database tables.

FIGURE 47. The OAT Enterprise Data Manager (EDM) Star Oracle Port Screen

26. Enter the port number assigned to the database listener for the OAT Enter‐prise Data Manager Star Database, and press Enter to continue. In this case, the default port number is correct since it is an Oracle database listener.

FIGURE 48. The OAT Enterprise Data Manager (EDM) Star Database User Screen

27. Enter the name of a database user account that has permissions to perform Create, Read, Update, and Delete (CRUD) operations on the specified data‐base.


FIGURE 49. The OAT Enterprise Data Manager (EDM) Star Database Password Screen

28. Enter the password for the database user account you have specified.The OATenterprise installer now proceeds to request the domain name for the OAT Enterprise Data Manager Star Database server.

FIGURE 50. The Star Database Domain Name Screen

29. Enter the domain name for OAT Enterprise Data Manager Star database server. For example: oatsystems.com.

FIGURE 51. The MSTR Server Screen



30. Enter the IP address or the host name of the MicroStrategy (MSTR) Server (the server on which MicroStrategy is installed, or will be installed after this installation) from where the OAT Enterprise reports will be accessible.

FIGURE 52. The Web Server Option Screen

31. Specify the Web server you want to use with OAT Enterprise Data Manager, by entering the number for your choice.

FIGURE 53. The Configure Web Server Screen (a)

32. To enable secure HTTPS connections between the browser and OAT Enter‐prise Data Manager, choose Yes. Select your choice by entering the number for the appropriate option.

Note: If HTTPS is configured for one server in the OFS deployment hierarchy, it must be configured for all. It is not possible to mix HTTPS‐enabled with HTTP‐only servers.


FIGURE 54. The Configure Web Server Screen (b)

33. Enter the port number to be used for secure browsing.

FIGURE 55. The Configure Web Server Screen (c)

34. Enter the host name or IP address of the machine on which you are currently installing OAT Enterprise Data Manager. Press Enter to continue.

FIGURE 56. The Configure OAT Enterprise Data Manager Screen (a)



35. Enter a unique 4‐digit hexadecimal identifier for the OAT Enterprise Data Manager. This identifier should be unique across all the OATenterprise nodes in your organization.

FIGURE 57. The Configure OAT Enterprise Data Manager Screen (b)

36. Enter a unique name for this OAT Enterprise Data Manager. This name should be unique across all the OATenterprise server nodes.

Note: The installer will request you to enter an HTTP port only if you have not enabled secure connections (HTTPS) between the Web browser and the OAT Enterprise Data Manager. In our case, since we have enabled HTTPS, the installer does not ask for an HTTP port.

FIGURE 58. The Configure OAT Enterprise Data Manager Screen (c)

37. Enter the port number on which the Web server of your choice will be acces‐sible. (In this case, the chosen server is Tomcat.)


FIGURE 59. The Configure OAT Enterprise Data Manager Screen (d)

38. Enter the Webservice context.

FIGURE 60. The Configure OAT Enterprise Data Manager Screen (e)

39. Enter the Java minimum heap size.

FIGURE 61. The Configure OAT Enterprise Data Manager Screen (f)

40. Enter the Java maximum heap size.



FIGURE 62. The RMI Security Screen

41. To enable RMI security, choose Yes by entering 1, and press Enter to go to the next step.

FIGURE 63. The Webservice Security Screen

42. To enable webservice security, choose Yes by entering 1, and press Enter to proceed to the next step.



43. If you are using a JMS transport with your Web service, then choose Yes (1).Choose No if you do not use the JMS transport. If you have chosen Yes, then you will be prompted for JMS configuration details in the steps below. If you have chosen No, then the installer will bypass JMS configuration steps and proceed directly to step 54.

Note: The default values shown in the installer screen of the JMS configuration steps are the values configured for ActiveMQ that runs automatically for each OAT server. In our case, it is OAT Enterprise Data Manager.

FIGURE 65. The Configure JMS Screen (a)

44. Enter the URL of the JNDI service.

FIGURE 66. The Configure JMS Screen (b)

45. Enter the JNDI initial context factory class used to create initial context.



FIGURE 67. The Configure JMS Screen (c)

46. Enter the JNDI look‐up name for the JMS connection factory object.

FIGURE 68. The Configure JMS Screen (d)

47. Enter the JNDI name of the JMS destination object (queue or topic) that will be used by OAT Enterprise Data Manager.

FIGURE 69. The Configure JMS for SOA Screen (a)

48. Specify the URL of the JNDI service.


FIGURE 70. The Configure JMS for SOA Screen (b)


FIGURE 71. The Configure JMS For SOA Screen (c)

50. Enter the JNDI look‐up name for the JMS connection factory.

FIGURE 72. The Configure JMS for SOA Screen (d)

51. Enter the JNDI look‐up name for the JMS destination object (queue or topic).



FIGURE 73. The Configure JMS for SOA Screen (e)

52. Enter the JNDI name of the JMS Notification Queue name that OAT Enter‐prise Data Manager will use.

FIGURE 74. The Configure JMS for SOA Screen (f)

53. Enter the JNDI name of the JMS Import Queue name that OAT Enterprise Data Manager will use.

Note: See Appendix E: Configuring WebSphere AppServer and MQ for SOA for instructions on how to install and configure IBM WebSphere MQ as the JMS provider for OAT Enterprise Data Manager.


FIGURE 75. The Run OAT Enterprise Data Manager on Restart Screen

54. Enter:• Yes (1), to automatically restart OAT Enterprise Data Manager on every

boot.• No (2), if you do not want the OAT Enterprise Data Manager to start

automatically. In this case, you have to manually start the OAT Enterprise Data Manager. For procedural information on how to control the OAT Enterprise Data Manager service, see Chapter 12: OAT Enterprise Data Manager Post‐Installation Procedures.

Press Enter to proceed. The Pre‐Installation Summary is displayed.




55. Review all the configuration settings before installing.


• To change or modify any of these settings, type back and press Enter to go to the step where you need to change values. Repeat subsequent steps to return to this stage.

• To abort installation, press Ctrl+C. After you finish reviewing, press Enter to install OAT Enterprise Data Manager in the specified directory. After a few seconds, the OATenterprise installer will display the Installation Successful screen.

FIGURE 77. The Installation Successful Screen

56. At this stage, you may choose to view the README file.57. If you chose to review the README file, press Enter to page through it, till

you get to the IMPORTANT INFORMATION COMPLETE message. Press Enter to proceed to the Installation Complete screen.

58. Once you see the Installation Complete screen, you can press Enter to exit the OATenterprise installer.

Note: After installation, you should edit the file <OATedm_Install_Dir>\ofs\conf\jndi‐soa.properties file and modify the username and password properties here for the secure client login to



your JMS broker. If no password is needed, you can either leave them blank, or comment both lines with a ʹ#ʹ at the beginning of the line. Apply the same changes to jndi‐connection‐factory.properties as necessary. Please note that if you are accepting the defaults to use the ActiveMQ broker, you should set the username and password to blank.


OA

CHAPTER 5 Installing OAT Enterprise Administrator (Windows)

Introduction This chapter explains how to install OAT Enterprise Administrator on the Windows platform. See Chapter 2: First Steps in Installation for information on supported hardware, and software requirements.

Before You BeginBefore you start installing the OAT Enterprise Administrator, you must have the following information that you will need to supply to the installer:

• Server information:• Host name or static IP address• OAT Enterprise Administrator database parameters and user

account• Web server information:

• HTTP port • JMS configuration details:

• JNDI Provider URL• JNDI Factory Class• JMS Connection Factory• JMS Destination

T Foundation Suite 78

Installing OAT Enterprise Administrator (Windows)

• JMS User/Password if your JMS provider’s security is enabled• JMS Notification Queue Name for configuring JMS for SOA• JMS Import Queue Name for configuring JMS for SOA

Note the following guidelines:

• Re‐installing OAT Enterprise Administrator results in the loss of all data accumulated with OAT Enterprise Administrator since the previous installation.

• The OAT Enterprise Administrator requires a valid license key to operate. See Chapter 11: Acquiring & Installing a License Key for instructions on how to acquire and install a license key.

• OAT does not recommend or support the installation of OATxpress server along with the OAT Enterprise Data Manager or the OAT Enterprise Administrator on the same machine. OAT Enterprise Administrator and OAT Enterprise Data Manager can be installed on the same machine in limited pilot deployments with low performance requirements.

• You must ensure that the machine’s system clock registers the current date and time before installing OAT Enterprise Administrator.

• You must also ensure that the database software (whether installed locally or remotely) is running during this installation procedure.

• The steps below assume the default choice for Web server, which is Apache Tomcat. For instructions regarding IBM WebSphere Application Server, please refer to Chapter 10: Non‐default Database and Web Server Options.

Installing OAT Enterprise AdministratorTo install OAT Enterprise Administrator, perform the following steps:

1. Copy the OATenterprise setup.exe file to the system where you will be installing OAT Enterprise Administrator candidate.

2. In Windows Explorer, navigate to the folder where you have downloaded the setup.exe file, and double‐click it to start the installer.The OATenterprise installer, after extracting all of the components, displays an Introduction screen.



3. Click Next. The License Agreement appears.




4. To continue installing OAT Enterprise Administrator, accept the terms and conditions of the License Agreement by selecting the appropriate radio but‐ton. Click Next to display the Configure Server Mode screen.

Note: To obtain a valid license key, please follow the instructions in Chapter 11: Acquiring & Installing a License Key to guide you through obtaining and installing the license key.



5. Select the OAT Enterprise Administrator option, and click Next to proceed with the installation.




6. Specify the location for installing the OAT Enterprise Administrator:• To select the default installation folder, click Next. The default directory is

C:\OATea.• For a different installation folder, enter the folder’s path and name, or

click Choose..., select the folder, and click Next to proceed with the installation. To revert to the default installation folder after you have changed the folder, click the Restore Default Folder button.

Note: Do not include spaces or special characters in the location path.


FIGURE 82. The Configure OAT Enterprise Data Manager Details Screen

7. Enter the OAT Enterprise Data Manager‐related information to configure it for OAT Enterprise Administrator:• Check the OAT Enterprise Data Manager available checkbox to confirm

that the OAT Enterprise Data Manager has been installed or is going to be installed right after this installation. Uncheck it if you are configuring EDM later.

Note: You may configure the EDM even after EA installation. Refer to Chapter 15: Configuring OAT EDM & OAT Enterprise Administra‐tor for the steps involved.

• Enter the OAT Enterprise Data Manager Host.• Enter the OAT Enterprise Data Manager Port number.• Enter the Transport Packet Size (in KB). This is the maximum size of data

per block to be sent to the OAT Enterprise Data Manager.



• Enter the Data Migration Wait Time (in seconds). The Data Migration Wait Time is the amount of time to wait before synchronizing the next block of data to the OAT Enterprise Data Manager.

• Enter the Data Migration Scheduling Time (in Min). The Data Migration Scheduling Time is the time intervals at which data migration should run to migrate data to the OAT Enterprise Data Manager.

Click Next to move to the OAT Enterprise Administrator Database Selection step.

FIGURE 83. The OAT Enterprise Administrator Database Selection Screen

Note: As stated previously, the database software, whether installed locally or remotely, must be running during this installation.

8. Select the type of database software to be used with the OAT Enterprise Administrator.


Note: Since we have chosen Microsoft SQL Server 2008 as the database option, Apache Tomcat will be the default Web server selected. If you opt for Oracle or IBM DB2 database options, refer to Chapter 10: Non‐default Database and Web Server Options to proceed with the installation.

Click Next. The OAT Enterprise Administrator Database Location screen appears.


9. Specify the IP address or the host name of the server that hosts the database software used for OAT Enterprise Administrator. • If the database software is installed on the same machine, then enter


name of the remote machine.



Note: If you are using a Microsoft SQL Server 2008 database, and your database instance name is not the default name, then you must specify the hostname and the database instance name in the form hostname\dbin‐stancename. This is true for both local and remote databases. For example,

acme\myoatdb_instance

Here, “acme” is the hostname, and “myoatdb_instance” is the database instance name.

Click Next. You will be taken to the OAT Enterprise Administrator Database input screen.

FIGURE 85. The OAT Enterprise Administrator Database Input Screen

10. Specify the following values when Microsoft SQL Server 2008 is chosen as the database. For IBM DB2 or Oracle databases, the values are slightly differ‐ent. See Chapter 10: Non‐default Database and Web Server Options for details.


• Database Name: Enter a unique name for the database to be used by the OAT Enterprise Administrator.

• Database Port: Enter the port number assigned to the database software.• Database User with Privileges: Enter the name of the database user

account to be used by the OAT Enterprise Administrator to Create, Read, Update, and Delete (CRUD) the named database and its contents.

Note: When using the Microsoft SQL Server database software, the database user account must exist prior to installing OAT Enterprise Administrator.

• Database Password: Enter the password for the database user account.Click Next, to proceed. A message warns you that if the installer finds an existing database with the name you have entered, it will delete all tables in that database.


11. If you choose to continue with the installation, then the OATenterprise installer will delete tables from any existing database with the name you have entered. By canceling the installation, you can avoid deleting any data‐base tables, and abort the installation procedure.Click:• Cancel to cancel the OAT Enterprise Administrator installation.• Continue to proceed to the Configure Web Server screen.




12. Enter configuration details for the Web server. • To enable secure connections (HTTPS) between the browser and the OAT

Enterprise Administrator server, check the Yes checkbox. • Enter the https port for browsing server in the field provided.• Enter the host name or the IP address of the machine on which you are

installing OAT Enterprise Administrator in the Host Name field.Click Next. The Configure OAT Enterprise Administrator screen appears.



FIGURE 88. The Configure OAT Enterprise Administrator Screen

• Unique ID: Enter a 4‐digit hexadecimal identifier for this OAT Enterprise Administrator that is unique across all OATenterprise nodes that will interact with the OAT Enterprise Data Manager.

• Name: Enter a name for this OAT Enterprise Administrator node that is unique across all OATenterprise nodes and will interact with OAT Enterprise Data Manager.

Note: Do not specify a name that contains a space or special characters.

• Port (Web server): Enter the port on which you wish to have the Web server running. In this case, the Web server is Tomcat.

• Port (OAT Enterprise Administrator): Enter the port on which you want the OAT Enterprise Administrator to run.



Note: If the HTTPS transport is enabled between the Web browser and OAT Enterprise Administrator, then the OAT Enterprise Administrator port is not shown.

• Heap size (in MB) Min: Enter the minimum Java heap size for OAT Enterprise Administrator.

• Heap size (in MB) Max: Enter the maximum Java heap size for OAT Enterprise Administrator.

Click Next. The Configure Authentication screen appears.

FIGURE 89. The Configure Authentication Screen

13. Select:• Yes to configure OAT Enterprise Administrator to use LDAP for

authentication. When you click Next, the Configure External Authentication screen will appear. This is what is described in the steps immediately following this one.

• No to ignore LDAP authentication. When you click Next, you will proceed directly to step 19 displaying the Configure Security screen.


FIGURE 90. The Configure External Authentication Screen

14. Select the active directory to be used with the LDAP server. In this case, we have chosen Microsoft Active Directory.• Click Next. The Configure Microsoft Active Directory screen appears.



FIGURE 91. The Configure Microsoft Active Directory Screen

15. Specify the following values:• LDAP URL: The URL of LDAP server (clustered or primary) to which the

authentication request will be routed. To support failover, multiple LDAP server urls can be provided with comma (,) separation.The URL needs to be given in the following format:<protocol>://<hostname or IP address>:<port>• Protocol: Needs to be either ldap or ldaps (for secure connections)• Host name/IP address: Host name/IP address of ldap server. For

example; MSAD serverʹs IP address.• Port: Can be non‐secure/secure/global catalog. Default values are:

Non‐secure: 389Secure: 636Global catalog: 3268


• Base DN: Base Distinguished Name is used to search for domain users. If global catalog or multiple LDAP servers is used, then provide the common base DN for all. For example, if global catalogue is enabled and multiple sub‐domain users (india.oatsystems.com, us.oatsystems.com) are allowed to login, then provide the common base DN (oatsystems.com) for all to support sub‐tree level user or group access.

• OAT Admin Group Names: Supports the name of the LDAP group which gets Server Admin role in OFS, by default. The group name can include OU or parent group as part of DN. The names can be separated with; (semicolon).

• OAT User Group Names: Users who are a part of the Base DN get OFS access by default. You can restrict this by providing the user group names, so that only these group of users will get OFS access. Multiple group names can be entered with, (comma) separation. If the group name is duplicated in multiple OU, then group names along with OU names need to be given. You need to replace all the, (comma) s in the group name with; (semi colon).

Note: After the install, if LDAP is used for authentication of Websphere, append the complete <OATeaInstall>\ofs\conf\ldap_msad.conf file content to <WAS_PROFILE_BASE>\profiles\<ProfileName>\proper‐ties\wsjass.conf. Ensure that the same login module (JNDI) is not existing in <WAS_PROFILE_BASE>\profiles\<ProfileName>\proper‐ties\wsjass.conf.

Click Next, to proceed with the installation.



FIGURE 92. The Configure Microsoft Active Directory Login Format Screen

16. Select the login format from the dropdown list.Click Next.If you have selected Login ID as the Login Format, you will be taken to the Configure Login ID screen, step 17. If you have chosen CN as the Login Format you will be taken to step 18.


FIGURE 93. The Configure Login Format Screen

17. Enter the following details:OAT Administrator CN: Indicates the CN that will have administrative rights for the OAT Enterprise Administrator server.OAT Administrator Password: Indicates the password for the OAT Administrator login. After installation, you may change this password if required. You may use the deploy (deploy ‐‐ldapAdminPassword= <newpassword> ) to change the password.

Click Next to go to the Configure Caching screen.



FIGURE 94. The Configure Caching Screen

18. Check Enable Username and Password caching to decrease queries to the LDAP server and to improve authentication performance.Click Next. The Configure Security screen appears.



19. Enable security for RMI, JMS and Webservice as required, by checking the respective checkboxes. Click Next to proceed to the JMS Configuration screen.For more details on security, please see Appendix B: OAT Foundation Suite Security.

20. If you are using JMS transport functionality with your Web service, then choose Yes, and click Next to configure JMS details. Choose No to ignore JMS configuration and proceed directly to the Install as Windows Service screen, step 23.

Note: If you choose No, and your system has failover backup operation installed, then the Cluster Configure screen will appear.

Note: The installerʹs default values in the JMS configuration screens are those for Apache ActiveMQ, which is bundled with the OAT Foundation Suite.






connection factory object.• JMS Destination: Enter the JNDI look‐up name for the JMS destination

object (queue or topic). • JMS Username: Enter the username for accessing the JMS provider.

Leave this box empty if security is not enabled in your JMS provider.• JMS Password: Enter the password of the user. Leave this box empty if

security is not enabled in your JMS provider.Click Next. The Configure JMS for SOA screen appears.








Destination for Master Data Import.• JMS Username: Enter the username for accessing the JMS provider.

Leave this box empty if security is not enabled in your JMS provider.




Note: See Appendix E: Configuring WebSphere AppServer and MQ for SOA for instructions on how to install and configure IBM WebSphere MQ as the JMS provider.



23. Select:• Yes, to set the OAT Enterprise Administrator service to automatically

start every time the system boots. • No, if you do not want to run the OAT Enterprise Administrator

automatically. In this case, you have to manually start the OAT Enterprise Administrator when required.

Click Next. The Pre‐Installation Summary screen appears.



24. Review your selections before installing.• To modify the choices or entries, click Previous.• To install using the displayed parameters, click Install.The Installing OATenterprise screen appears.


26. Review the Readme file; to view the entire file, you’ll have to scroll through the viewing pane. Click Next to proceed to the Install Complete screen.


See Appendix A: Installation Knowledge Base, for details on verifying that your installation was successful.




CHAPTER 6 Installing OAT Enterprise Administrator (Linux)

Introduction This chapter describes steps for installing OAT Enterprise Administrator on Linux.

For information on basic software and hardware requirements, please see Chapter 2: First Steps in Installation.

Before You BeginBefore you start installing the OAT Enterprise Administrator, obtain the following:

• OATenterprise setup file (setup.bin) ‐ download to the OAT Enterprise Administrator installation candidate system.

• Server requirements:• Host name or static IP address• OAT Enterprise Administrator database parameters and user account

• Details of OAT Enterprise Data Manager (if installed):• Host name or IP address• Port

• Web server information:• HTTP or HTTPS port number (unused port, to be used for Enterprise

Administrator)


Installing OAT Enterprise Administrator (Linux)

• JMS configuration details:• JNDI Provider URL• JNDI Factory Class• JMS Connection Factory• JMS Destination• JMS User/Password if your JMS provider’s security is enabled

Note the following:

• You must be logged on as the root user during the OAT Enterprise Administrator installation.

• The OAT Enterprise Administrator requires a valid license key to operate. See Chapter 11: Acquiring & Installing a License Key to acquire and install a license key.

• Re‐installing OAT Enterprise Administrator results in the loss of data accumulated with OAT Enterprise Administrator since the previous installation.

• If reusing an OAT Enterprise Administrator database instance, ensure that no connection exists between the database instance and a client or the OAT Enterprise Administrator before installing OAT Enterprise Administrator. Consider restarting the database server to break all connections to all database instances.


• Ensure that the machine’s system clock registers the current date and time before installing OAT Enterprise Administrator.

• If using Oracle, before installing OAT Enterprise Administrator, you must have Oracle Instant Client installed, and add the directory where the client libraries are installed to the LD_LIBRARY_PATH environment variable. If the Oracle database server is on the same machine as OAT Enterprise Administrator, then the client is not required.


• The steps below assume the default choice for the Web server, Apache Tomcat. For instructions regarding IBM Web Sphere Application Server, refer to Chapter 10: Non‐default Database and Web Server Options. While these instructions refer to the Windows installation screen, the flow and input values are the same for both the Windows and Lynx platforms.

Installing OAT Enterprise Administrator on Linux1. Set the root directory as your current directory, and invoke the setup.bin file:

./setup.bin

The OAT enterprise installer, after extracting all of the components, displays the Introduction screen.


2. Press Enter to advance to the License Agreement screen.




3. Review the terms and conditions of the license agreement. Press Enter for the DO YOU ACCEPT THE TERMS OF THIS LICENSE AGREEMENT? message. This screen reminds you that you need a valid license key (license.txt file) to run OAT Enterprise Administrator. Obtain this key and install it after completing the installation of OAT Enterprise Administrator. Chapter 11: Acquiring & Installing a License Key has instructions on obtaining and installing the license key.



4. Type Y to accept the terms and conditions of this license agreement and press Enter. You will be asked to select the type of server you want to install in the next step.




5. Select the type of server you want to install and press Enter. Since you are installing OAT Enterprise Administrator, select 2 and press Enter to con‐tinue with the installation.


6. Specify the location for installing the OAT Enterprise Administrator. Enter an absolute path and press Enter, or press Enter to accept the default loca‐tion.

Note: If you assign an alternate path and folder, ensure that there are no spaces or special characters included in the location path.


Note: In the following steps, pressing Enter without entering a specific value will accept the installer default value for the step, and proceed to the next step. The installer default for the current step is shown as a string (for example, the Install Folder above) or as an arrow marking one of the choices in a menu (for example, the choice of type of server to install, above).


7. Enter:• Yes (1), to confirm that the OAT Enterprise Data Manager has been

installed prior to this installation, or will be installed immediately after this installation.

• No (2), if the OAT Enterprise Data Manager is not installed.Press Enter to continue with the installation. If you have chosen Yes, the installer will proceed to the Configure OAT Enterprise Data Manager step. If you have chosen No, the installer will direct you to the OAT Enterprise Administrator Database Selection screen (step 13).

Note: You can configure the EDM after the EA installation.



FIGURE 106. The Configure OAT Enterprise Data Manager

8. Enter the host name or IP address of the machine on which you have OAT Enterprise Data Manager installed. Press Enter to continue.

FIGURE 107. The Configure OAT Enterprise Data Manager

9. Enter the port on which the OAT Enterprise Data Manager is running, and press Enter to continue.

FIGURE 108. The WebService Context Detail


Enter the Webservice Context details.

FIGURE 109. The Configure OAT Enterprise Data Manager for OAT Enterprise Administrator Screen (a)

10. Enter the transport packet size for the OAT Enterprise Data Manager. This is the maximum size of data per block to be sent to the OAT Enterprise Data Manager. To accept the default value (100), press Enter and continue to the next step.

FIGURE 110. The Configure OAT Enterprise Data Manager for OAT Enterprise Administrator Screen (b)

11. Enter the data synchronization wait time. This is the amount of time to wait before synchronizing the next block of data to the OAT Enterprise Data Man‐ager. Press Enter to proceed.

FIGURE 111. The Configure OAT Enterprise Data Manager for OAT Enterprise Administrator Screen (c)



12. Enter the scheduling time interval for data synchronization. This is the time interval at which the data migration should run to migrate data to the OAT Enterprise Data Manager.

FIGURE 112. The OAT Enterprise Administrator Database Selection Screen

13. Select the database software you will be using with the OAT Enterprise Administrator by entering the number for your choice and press Enter. In this case, select 1 to choose the Oracle database software option.

Note: If you choose to use the IBM DB2 database option, then refer to Chapter 11: Acquiring & Installing a License Key for database creation details, and for an explanation of the parameters requested. Note that the information is applicable to both Windows and Linux installations.

FIGURE 113. The OAT Enterprise Administrator Configure Database Screen

14. Enter the directory of the database client or server installed directory loca‐tion and press Enter to continue.

Note: If you assign an alternate path and folder, ensure that there are no spaces or special characters in the location path.



15. Specify the IP address or the host name of the database software used for the OAT Enterprise Administrator. • If the database software is installed on the same machine, enter localhost.• If it is installed on a remote machine, enter the IP address or the host

name of the remote machine where the database software is running.Press Enter to continue with the installation.

FIGURE 115. The OAT Enterprise Administrator Database SID Name Screen

Enter the SID (System ID) Name for the database. Press Enter to continue. A warning message appears:




16. Select any one of the options, by entering the number of your choice and press Enter to continue.If you choose to continue with the installation then the installer deletes all database tables from the database with the name you have entered. By canceling the installation, you avoid the possibility of deleting any database tables.

FIGURE 117. The OAT Enterprise Administrator Database Service Name Screen

17. Enter the Database Service Name for the OAT Enterprise Administrator.

FIGURE 118. The OAT Enterprise Administrator Oracle port Screen


18. Enter the Database Port number assigned to the database listener and press Enter to continue.

FIGURE 119. The OAT Enterprise Administrator Database User Screen

19. Enter the Database User with Privileges. This is the username of a database user who has permission to perform Create, Read, Update, and Delete (CRUD) operations.

FIGURE 120. The OAT Enterprise Administrator Database Password Screen

20. Enter the password of the database user who has permission to perform Cre‐ate, Read, Update, and Delete (CRUD) operations.


21. Specify the Web server you want to use with the OAT Enterprise Adminis‐trator, by entering the number of your choice.



FIGURE 122. The Configure Web Server Screen (a)

22. Enter the configuration details for the Web server you have chosen in the earlier step. To enable a secure connection (HTTPS) between the Web browser and the OAT Enterprise Administrator, choose Yes by specifying 1.


FIGURE 123. The Configure Web Server Screen (b)

23. Enter the HTTPS port for secure browsing.

FIGURE 124. The Configure Web Server Screen (c)


24. Enter the host name or IP address of the machine on which you are currently installing the OAT Enterprise Administrator.

FIGURE 125. The Configure OAT Enterprise Administrator Screen (a)

25. Enter a unique 4‐digit hexadecimal identifier for the OAT Enterprise Admin‐istrator. This identifier should be unique across all OATenterprise nodes that interact with each other.

FIGURE 126. The Configure OAT Enterprise Administrator Screen (b)

26. Enter a unique name for this OAT Enterprise Administrator. The name should be unique across all OATenterprise nodes that interact with each other.

Note: The installer will request you to enter a HTTP port if you have not enabled a secure connection (HTTPS) between the Web browser and the OAT Enterprise Administrator. If you have chosen to enable HTTPS, then you will not be queried for a HTTP port (see step 22). In our case, we have enabled HTTPS, so the installer does not ask for a HTTP port.



FIGURE 127. The Configure OAT Enterprise Administrator Screen (c)

27. Enter the port number for the Web server, in this case Tomcat.

FIGURE 128. The WebService Context for OAT Enterprise Administrator Screen

28. Enter the WebService Context details.

FIGURE 129. The Configure OAT Enterprise Administrator Screen (d)

29. Enter the Java minimum heap size and press Enter to proceed.


FIGURE 130. The Configure OAT Enterprise Administrator Screen (e)

30. Enter the Java maximum heap size and press Enter to proceed.

FIGURE 131. The Configure LDAP Screen

31. Specify the number for your appropriate option to enable the LDAP authen‐tication. Choose:• Yes, to configure LDAP authentication to authorize administrative

operations. • No, to bypass LDAP Configuration and proceed directly to the RMI

security step.

FIGURE 132. The Configure Active Directory Screen



32. Select the type of LDAP directory being used, by entering the number of your choice. If you have chosen the Microsoft Active Directory option, then the Configure Microsoft Active Directory screen appears.If you have chosen the Other option, then the Configure Custom Active Directory screen appears.


33. Specify the LDAP server URL.


34. Enter the base DNs, based on your internal naming conventions.


35. Enter the OAT Admin Group Names, and press Enter to proceed.


FIGURE 136. The Configure Microsoft Active Directory Login Format Screen

36. Specify the login format by entering the number of your choice.


37. Specify the CN that will have administrative rights for the OAT Enterprise Administrator server.


38. Enter the password for the OAT Administrator login. After installation, you may change this password.Use the deploy (deploy ‐‐ldapAdminPassword= <newpassword> ) to change the password.



FIGURE 139. The Configure Caching Screen

39. Configure caching by entering the number of your choice. Select:• Yes, to enable username and password caching.• No, to disable username and password caching.If you enable caching, users will be able to log into the system even if the authoritative server (an external authentication system such as an LDAP server, or an OATenterprise server) is not reachable.


40. Enter the appropriate number for your choice:• Yes (1), to enable Remote Method Invocation security.• No (2), to disable RMI security.


FIGURE 141. The JMS Security Screen

41. Choose:• Yes (1), to enable JMS security.• No (2), to disable JMS security.


42. Enter the number for your choice. Choose:• Yes (1), to enable Webservice security.• No (2), to disable Webservice security.




43. If you are using a JMS transport with your Web service, then choose Yes and press Enter to configure JMS details. Choose No, if you do not use JMS trans‐port. If you have chosen Yes, then you will have to enter the JMS configuration details in the steps below. If you have chosen No, then you will be taken to step no. 54.

Note: The default values shown in the installer screen of the JMS configuration steps are the values configured for ActiveMQ that runs automatically for each OAT server. In our case, it is the OAT Enterprise Administrator.







46. Enter the JNDI name for the JMS connection factory object.


47. Enter the JNDI name for the JMS destination object (queue or topic) that will be used by the OAT Enterprise Administrator.




48. In this step, configure JMS for SOA; specify the URL of the JNDI service.



FIGURE 150. The Configure JMS for SOA Screen (c)

50. Enter the JNDI name for the JMS connection factory object.



51. Enter the JNDI name for the JMS destination object (queue or topic).


52. Enter the JNDI name of the JMS Notification Queue name that OAT Enter‐prise Administrator server will use.


53. Enter the JNDI name of the JMS Import Queue name that OAT Enterprise Administrator server will use.




FIGURE 154. The Run OAT Enterprise Administrator on Restart Screen

54. Specify the appropriate number for your choice. Select:• Yes, to run the OAT Enterprise Administrator to automatically restart

this system after every system restart. • No, if you do not want to run the OAT Enterprise Administrator

automatically.You have to manually restart the OAT Enterprise Administrator.



55. Review all the configuration settings before installing. • To change or modify any of these settings, navigate back to the

appropriate step and re‐enter the values. • To abort the installation, press Ctrl+C.



After you finish reviewing, press Enter to install the OAT Enterprise Administrator in the specified directory. After a few seconds, the installer will display the Installation Successful screen.


56. At this stage, you may choose to view the README file.57. If you chose to review the README file, press Enter to page through it, till

you get an IMPORTANT INFORMATION COMPLETE message. Press Enter to proceed to the Installation Complete screen.

58. Once you see the Installation Complete screen, press Enter to exit the installer.

Note: After installation, you should edit the <OATea_Install_Dir>\ofs\conf\jndi‐soa.properties file and modify the username and password properties for secure client login to your JMS broker. If no password is needed, you can either leave them blank or comment both lines with a ʹ#ʹ at the beginning of the line. Apply the same changes to jndi‐connection‐factory.properties as necessary. Note that if you accept the defaults to use the ActiveMQ broker, you should set the username and password to blank.


OA

CHAPTER 7 Installing OATxpress Server (Windows)

Introduction This chapter explains the procedure for installing the OATxpress server on the Windows platform. See Chapter 2: First Steps in Installation for information on hardware and software requirements for OATxpress server.

Before You BeginBefore you start installation, do the following:

• Download the OATenterprise setup file (setup.exe) to the OATx‐press server candidate.

• Obtain the following data:• The host name or static IP address of the server on which you

will install the OATxpress server.• OATxpress database parameters such as the host name or IP

address of the database server and the correct user credentials such as the user account (login name) and password.

• The IP address/hostname and port information of the OAT Enterprise Administrator, if it is installed in the deployment.

• Web server information:• HTTP port

• JMS configuration details:• JNDI Provider URL

T Foundation Suite 132

Installing OATxpress Server (Windows)

• JNDI Factory Class• JMS Connection Factory• JMS Destination• JMS User/Password if your JMS provider’s security is enabledJMS

Notification Queue Name for configuring JMS for SOA• JMS Import Queue Name for configuring JMS for SOA

Note the following:

• Re‐installing an OATxpress results in the loss of data accumulated in that OATxpress since the previous installation.

• The OATxpress server requires a valid license key to operate. See Chapter 11: Acquiring & Installing a License Key for instructions on how to acquire and install a license key.


• You must ensure that the machine’s system clock registers the current date and time before installing OATxpress.

• You must also ensure that the database software (installed locally or remotely) is running during installation.

• The steps below assume the default choice for Web server, which is Apache Tomcat. For instructions regarding IBM WebSphere Application Server, refer to Chapter 10: Non‐default Database and Web Server Options.


Installing OATxpress ServerTo install OATxpress, perform the following steps:

1. In a Windows Explorer window, double‐click the file:

setup.exe

The OATxpress installation screen appears. The OATenterprise installer, after extracting all components, displays the Introduction screen.


2. Click Next. The License Agreement appears.




3. To continue installing the OATxpress, accept the terms and conditions of the License Agreement by selecting the appropriate radio button. Click Next to display the Configure Server Mode screen. Select the type of server you want to install.

Note: Follow the instructions in Chapter 11: Acquiring & Installing a License Key for obtaining and installing the license key.



4. Select the OATxpress option and click Next to advance to the Choose Install Folder screen.




5. Specify the installation location for the OATxpress:• To select the default installation folder, click Next. The default installation

path is C:\OATxpress.• For a different installation folder, enter the folder’s path and name, or

click Choose..., select the folder, and click Next. To revert to the default installation folder after you have changed the folder, click the Restore Default Folder button.


The Configure OATxpress screen appears.


FIGURE 161. The Configure OATxpress Screen

6. Select:• Yes, if you have installed the OAT Enterprise Administrator prior to this

installation, or is going to be installed after this installation.Installing OAT Enterprise Administrator as part of your deployment enables you to configure and monitor all aspects of multiple OATxpress servers via a single OATenterprise Web interface, and migrate master and partner data to the OAT Enterprise Data Manager for processing ETL operations and report‐ing.

• No, if you are deploying a standalone OATxpress server, without an OAT Enterprise Administrator within your deployment. In this case, you will configure and monitor all the activities occurring in a standalone OATxpress server through the OATxpress Web application.Click Next to proceed to the OATxpress Database Selection screen.



Note: If you have chosen Yes, enter the OAT Enterprise Administrator details in the next step. If you have chosen No, then skip the OAT Enterprise Administrator configuration step, and proceed to database selection in step 9.

FIGURE 162. The Configure OAT Enterprise Administrator Details

7. In the Configure OAT Enterprise Administrator Details screen, do the fol‐lowing:• Enter a unique name, host and port number, assigned to the OAT

Enterprise Administrator at the time of installation.• Check the Synchronize OAT Enterprise Administrator... checkbox to

enable the OAT Enterprise Administrator to synchronize master data with OATxpresss on startup.

• Check the Enable username password cache checkbox, and click Next. The Configure OAT Enterprise Data Manager Details screen appears.


FIGURE 163. The Configure OAT Enterprise Data Manager Details Screen

8. In the Configure OAT Enterprise Data Manager Details screen, do the fol‐lowing:• Check the OAT Enterprise Data Manager available checkbox, if the OAT

Enterprise Data Manager has been installed or is going to be installed after this installation.

• Check the Enable Data Compression checkbox. Letting OATxpress compress data that is sent to the Enterprise Data Manager saves network bandwidth.

• Enter the hostname or IP address and port of the OAT Enterprise Data Manager in the respective fields provided.

• Select the mode of data migration by choosing the appropriate radio buttons:• Push data to OAT Enterprise Data Manager automatically• Wait for OAT Enterprise Data Manager request

Click Next to proceed with the installation.



FIGURE 164. The OATxpress Database Selection Screen

Note: As stated earlier, the database software, whether installed locally or remotely, must be running during this installation.

9. Select the type of database software to be used with the OATxpress server.Click Next, to proceed to the OATxpress Database Location screen.

Note: Since we have chosen the Microsoft SQL Server 2008 as the default database for our installation procedure, Apache Tomcat will be the default Web server selected. If you opt for Oracle or IBM DB2 database options, refer to Chapter 10: Non‐default Database and Web Server Options to proceed with the installation.


FIGURE 165. The OATxpress Database Location Screen

10. Specify the IP address or the host name of the system hosting the database software used for the OATxpress. • If the database software is installed on the same machine, then enter


name of the remote machine where the database software is running.Click Next to display the OATxpress Database input screen.

Note: If you are using a Microsoft SQL Server 2008 database and your database instance name is not the default name, then you must specify the hostname and the database instance name in the form hostname\dbin‐stancename as in the following example:

acme\myoatdb_instance

where “acme” is the hostname and “myoatdb_instance” is the database instance name. This is true for both the local and remote databases.



FIGURE 166. The OATxpress Database Input Screen

11. Specify the following values when Microsoft SQL Server 2008 is chosen as the database. For IBM DB2 or Oracle databases, the values are slightly differ‐ent. See Chapter 10: Non‐default Database and Web Server Options for details.• Database Name: Enter a unique name for the database to be used by the

OATxpress (do not attempt to re‐use the database used for any other OAT Foundation Suite component).


account to be used by the OATxpress to Create, Read, Update and Delete (CRUD) the named database and its contents.

Note: While using the Microsoft SQL Server database software, the database user account must exist prior to installing the OATxpress.

• Database Password: Enter the password for the database user account.Click Next. The Warning dialog appears:



12. If you choose to continue with the installation then the OATenterprise installer deletes all database tables from the database with the name you have entered. Such a database may have been created during a previous installation of the OATxpress server. By canceling the installation, you avoid deleting any database tables and terminate the installation procedure.Click:• Cancel to abort the OATxpress server installation.• Continue to proceed with the installation, deleting all tables in any

existing database with the name you have entered. The Configure Web Server screen appears.




13. Enter the configuration details for the Web server. • For a secure connection between the Web browser and the OATxpress,

check the Yes checkbox. • Enter the https port for browsing server in the field provided.• Enter the host name or the IP address of the machine on which

OATxpress is being installed in the Host Name field.Click Next. The Configure OATxpress screen appears.




14. Specify the following values:• Unique ID: Enter a 4‐digit hexadecimal identifier for this OATxpress

server that is unique across all OATenterprise nodes, which interact with the OAT Enterprise Data Manager.

• Name: Enter a name for this OATxpress server that is unique across all OATenterprise nodes that interact with OAT Enterprise Data Manager.

Note: Do not specify a name that contains a space or special characters.

• Port (Web server): Enter the port on which you want to run the Web server for OATxpress. In this case, the Web server is Tomcat.

• Port (OATxpress server): Enter the port on which you want the OATxpress server to run.

Note: You will not be prompted to enter an HTTP web server port number for OATxpress server if you have enabled HTTPS connection between the Web browser and the OATxpress server.



• Heap size (in MB) Min: Enter the Java minimum heap size for OATx‐press.

• Heap size (in MB) Max: Enter the Java maximum heap size for OATx‐press.

Click Next. The Configure Security screen appears.


15. Enable security for RMI, JMS and Webservice as required, by checking the respective checkboxes. Click Next to proceed to the JMS Configuration screen.For more details on security, see Appendix B: OAT Foundation Suite Security.



16. If you are using JMS transport functionality with your Web service, then choose Yes, and click Next to configure JMS details. Choose No to ignore this step and proceed directly to the Install as Windows Service screen, step 19.The Configure JMS screen appears.

Note: If you are installing OATxpress in a deployment with EDM, choose to either have all OATxpress servers in the deployment use SOAP for data migration, or all should use JMS for this; you cannot have a mix.

Note: The installerʹs default values in the JMS configuration screens are those for Apache ActiveMQ, bundled with the OAT Foundation Suite.




17. Specify the following values:• JNDI Provider URL: Enter the URL of the JNDI service.• JMS Connection Factory: Enter the JNDI look‐up name for the JMS


object (queue or topic). • JMS Username: Enter the username for accessing the JMS provider.

Leave this box empty if security is not enabled in your JMS provider.• JMS Password: Enter the password of the JMS user. Leave this box empty

if security is not enabled in your JMS provider.Click Next. The Configure JMS for SOA screen appears.




create initial context.• JMS Connection Factory: Enter the JNDI look‐up name for the JMS

connection factory object.• JMS Destination: Enter the JNDI look‐up name for the JMS destination



Destination for Master Data Import.• JMS Username: Enter the username for accessing the JMS provider.

Leave this box empty if security is not enabled in your JMS provider.



• JMS Password: Enter the password of the JMS user. Leave this box empty if security is not enabled in your JMS provider.

Note: See Appendix E: Configuring WebSphere AppServer and MQ for SOA for instructions on how to install and configure IBM WebSphere MQ as the JMS provider for the OATxpress.



19. Select:• Yes to run OATxpress as a Windows service. • No to not run OATxpress as a Windows service. Selecting this option

means that the OATxpress software does not restart automatically. You will therefore have to manually restart OATxpress as required.

Click Next. The Pre‐Installation Summary of your selections appears.



20. Review your OATxpress configuration selections before installing.• To modify the configuration selections, click Previous.• To install the selected configuration, click Install.The Installing OATenterprise screen appears, when OATxpress starts installing.


22. Review the Readme file; to view the entire file, you’ll have to scroll through the viewing pane. When you have finished reviewing it, click Next to pro‐ceed to the Install Complete screen.


See Appendix A: Installation Knowledge Base, for details on verifying that your installation was successful.



Configuring OPC ServerConfiguring the OPC server to connect to the OATxpress server involves:

• Setting up OPC with OATxpress• Adding Registers

The following software are required to setup OPC server with OATxpress:

• OPC servers like RSLinx, Kepware etc... • Netmodule JOPC‐Bridge (JNI bridge enabling OFS to communicate with

OPC server)

Setting up OPC with OATxpressOPC can be setup with OATxpress in any of the two scenarios:

• OPC and OATxpress running on the same Windows Machine• OPC and OATxpress running on different Windows Machine

OPC and OATxpress Running on Same Windows Machine

Perform the following steps, if OPC and OATxpress are running on the same Windows Machine:

1. Install OATxpress on a Windows Machine. 2. Obtain JOPC‐Bridge from Netmodule (Trial Version / Full License Version). 3. Expand the JOPC‐Bridge*.zip file to the local directory. Following is the

directory structure defined for the zip file:

JOPC-Bridge

|

|-Lib

|-Doc

|-Samples

|-Tools

4. Copy Lib/jopcbridge.jar to $OFS_INSTALL/jakarta‐tomcat‐5.5.28/webapps/axis/WEB‐INF/lib.


5. Copy Lib/jopcbridge.jar to $OFS_INSTALL/jakarta‐tomcat‐5.5.28/webapps/oatedge/WEB‐INF/lib.

6. Copy Dlls Lib/jopcbridge.dll and Lib/SglW32.dll to c:/WINDOWS/System32 directory.

7. Right click on the dlls, go to the Security tab and give Full Control Permis‐sions to everyone.

8. Run the command Tools/OPCRegistry.exe. A list of OPC servers on the machine appears. Note down the name/ProgId of the OPC server you want to connect with OATxpress.

9. Start OATxpress and add a location. 10. Go to Add Device; Select digital_io_device as category; Select OPC SERVER

as device type. 11. Go to the next page. Add the OPC server name noted down in step 8 in the

text field Server Name. 12. Enter the IP as 127.0.0.1. 13. Add the Input/Output registers you are interested in. 14. Click Save and Apply Config.

OPC and OATxpress Running on Different Windows Machine

Perform the following steps if OPC and OATxpress are running on different Windows Machines:

1. Perform the above steps on Windows Machine1. 2. Install the OPC server on Windows Machine2. (You need to install the OPC

server on both the Windows Machines). 3. Go to Windows Machine1 and run the command dcomcnfg.exe. 4. Go to Console Root ‐> Component Services ‐> Computers ‐> My Computer ‐

> DCOM Config. 5. Search for the component of the installed OPC server. Right click on the com‐

ponent and select Properties. 6. Go to Location tab. Uncheck the ʺRun application on this computerʺ check‐

box. Check the ʺRun application the following computerʺ checkbox. Browse and select Windows Machine 2. Give valid user names and passwords wher‐ever required. Press OK.

7. Login using the same domain user on both the Windows Machines and this user should have full permissions to access the OPC server on both the machines.



The following steps also need to be performed in addition to the above steps. This is applicable for both the scenarios:

1. Go to ControlPanel ‐>Administrative Tools ‐>Component Services‐> Ser‐vices(Local).

2. Search for OATxpress Tomcat. Right click and select Properties. 3. Go to Logon tab. Click the radio button ʹ This account ʹ. 4. Enter the domain user name and password which gives permissions to start

the OPC server on remote machine. Press OK.

Note: If OATxpress is running as ʹWindows Serviceʹ, then do not use the system account to start the (tomcat) Windows service to work with the OPC server. Else start the Windows (tomcat) service with the login (domain user) which has permission to start the OPC server on the remote server. If Kepware is the OPC server, then start Kepware as service.


CHAPTER 8 Installing OATxpress Server (Linux)

Introduction This chapter explains how to install OATxpress on Linux using the text‐based console mode.

Note: Log on as a root user to install OATxpress. OATxpress requires a local installation of the Oracle client to communicate with a remote Oracle database.

Before You BeginBefore you install the OATxpress server, download the setup file to the server candidate and obtain the following information:

• OATxpress requirements:• Host name or static IP address• Database parameters and user account

• Web server information:• HTTP or HTTPS port numbers that will be used for browser and

webservice connections. These ports should be unused by any other installed programs, and if there is any firewall running on the system, it should be configured to accept incoming connections on these ports.


Installing OATxpress Server (Linux)

• The following details of OAT Enterprise Administrator and OAT Enterprise Data Manager, if installed:• Host name or IP address• Port

• JMS configuration details, if the JMS transport will be used:• JNDI Provider URL• JNDI Factory Class• JMS Connection Factory• JMS Destination• JMS User/Password if your JMS provider’s security is enabled

• JMS Notification Queue Name for configuring JMS for SOA• JMS Import Queue Name for configuring JMS for SOA

Note the following:

• You must be logged on as a root user for the installation.• The OATxpress server requires a valid license key to operate. See Chapter

11: Acquiring & Installing a License Key to acquire and install the license key.

• Re‐installing OATxpress results in the loss of data accumulated with the previous installation of OATxpress.

• You must ensure that the database software (whether installed locally or remotely) is running during this installation procedure.

• If you are reusing an OATxpress database instance, ensure that no connection exists between the database instance and a client or the OATxpress before installing the OATxpress. Consider restarting the database server to break all connections to all database instances.


• Ensure that the machine’s system clock registers the current date and time before installing OATxpress.


• If using Oracle, before installing OAT Enterprise Administrator, you must have Oracle Instant Client installed. You must also add the directory where the client libraries are installed to the LD_LIBRARY_PATH environment variable. If the Oracle database server is on the same machine as the OAT Enterprise Administrator, then the client is not needed.

• If you are using Apache Tomcat as the server, increase the value of TOMCAT_STARTUP_TIME in ofs/conf/oat_startup.properties to avoid “failed to start” message which appears because of the delay in starting the server.

• The steps below assume the default choice for the Web server is Apache Tomcat. For instructions regarding IBM WebSphere Application Server, refer to Chapter 10: Non‐default Database and Web Server Options. While the instructions refer to the Windows installation screens, the flow and input values are the same for both Windows and Linux platforms.

Installing OATxpress ServerTo install OATxpress server on a Linux machine:

1. Invoke setup as follows:

./setup.bin




The OATxpress installation screen appears. The OATenterprise installer displays an Introduction. Press Enter to advance to the License Agreement.



2. Review the terms and conditions of the license agreement. Press Enter till you get DO YOU ACCEPT THE TERMS OF THIS LICENSE AGREEMENT? message.




3. Type Y to accept the terms and conditions of the license agreement and press Enter. You will be asked to select the type of server you want to install in the next step.



4. Select the type of server by entering the number of your choice and press Enter. Since you are installing the OATxpress, type 3 and press Enter to con‐tinue with the installation.

.


5. Specify the location for installing the OATxpress. Enter an absolute path and press Enter, or simply press Enter to accept the default path. If you assign an alternate path and folder, ensure that there are no spaces or special charac‐ters included in the location path.

Note: In most of the following steps, pressing Enter without entering a specific value will accept the installer default value for the step, and proceed to the next step. The installer default for the current step is shown as a string (for example, the Install Folder above) or as an arrow marking one of the choices in a menu (for example, the choice of type of server to install, above).




6. Specify whether you have installed, or will install an Enterprise Administra‐tor in your deployment. Choose:

• Yes, if you have installed, or will install OAT Enterprise Administrator. Installing OAT Enterprise Administrator as part of your deployment enables you to configure and monitor all aspects of multiple OATxpress servers via a single OATenterprise Web interface, and migrate master and partner data to the OAT Enterprise Data Manager for processing ETL operations and report‐ing.

• No, if you do not have an OAT Enterprise Administrator in your deploy‐ment. This means that you have a standalone OATxpress server, without any cen‐tral Enterprise Administrator. In this case, you will configure and monitor all the activities occurring in a standalone OATxpress server through the OATx‐press Web application.Press Enter to continue.

Note: If you have chosen Yes, then enter the OAT Enterprise Administrator details in the next steps. If you have chosen No, the installer skips the OAT Enterprise Administrator steps, and takes you to step no. 11.

FIGURE 182. The Configure OAT Enterprise Administrator Screen (a)

7. Supply the OAT Enterprise Administrator’s unique name.

FIGURE 183. The Configure OAT Enterprise Administrator Screen (b)


8. Enter the host name or IP address of the machine on which the OAT Enter‐prise Administrator has been installed, and press Enter to proceed.

FIGURE 184. The Configure OAT Enterprise Administrator Screen (c)

9. Enter the port on which OAT Enterprise Administrator is accepting webser‐vice connections.

FIGURE 185. The Webservice Context OAT Enterprise Administrator Screen

10. Enter the OAT EA webservice context.




11. Enter 1 if you have installed OAT Enterprise Data Manager prior to this installation, or will be installing it immediately after this installation. Enter 2 if you have not installed OAT Enterprise Data Manager.If you have chosen 1, the installer proceeds to the Configure OAT Enterprise Data Manager steps. If you have chosen 2, the installer skips the OAT Enterprise Data Manager’s configuring steps and proceeds to the Configure OAT Enterprise Administrator steps (see step 17).

FIGURE 187. The Configure OAT Enterprise Data Manager Screen (a)

12. Enter the host name/IP address of the machine that is hosting the OAT Enter‐prise Data Manager.

FIGURE 188. The Configure OAT Enterprise Data Manager Screen (b)

13. Enter the port number on which the OAT Enterprise Data Manager is accept‐ing webservice connections.


FIGURE 189. The Webservice Context of OAT Enterprise Data Manager Screen

14. Enter the OAT EDM webservice context.

FIGURE 190. The Configure OAT Enterprise Data Manager Details for OATxpress Screen (a)

15. Enter 1 if you want to enable data compression, and 2 if you do not want to do so. Enabling data compression will let the OATxpress server compress data that is sent to OAT Enterprise Data Manager, saving network band‐width.



FIGURE 191. The Configure OAT Enterprise Data Manager Details for OATxpress Screen (b)

16. Select the mode for migrating data to the OAT Enterprise Data Manager.


17. Choose whether OATxpress should request a synchronization of master data from the Enterprise Administrator every time OATxpress starts up:• Yes, to synchronize master data on startup.• No, if you do not want synchronization at startup.

In this case, you have to periodically synchronize the master data through the OATenterprise Web application on the Enterprise Adminis‐trator.



18. Enter the appropriate number of your choice, and press Enter. Specify:• 1, to enable username and password caching.• 2, to disable username and password caching.

FIGURE 194. The OATxpress Database Selection Screen

19. Select the database software you will be using with the OATxpress by enter‐ing the number for your choice and pressing Enter. In this case, we selected Oracle.

Note: If you choose to use the IBM DB2 database option, then refer to Chapter 10: Non‐default Database and Web Server Options for database creation details, and for an explanation of the parameters requested. Note that the information is applicable to both Windows and Linux installations.



FIGURE 195. The OATxpress Configure Database Screen

20. Enter the directory in which the database client or server software is installed, and press Enter to continue.



21. Specify the IP address or the host name of the database server. • If the database software is installed on the same machine, then enter

localhost.• If it is installed on a remote machine, enter the IP address or the host

name of that remote machine.


FIGURE 197. The OATxpress Database SID Name

22. Enter the SID (System ID) Name for the database. Press Enter to continue. A warning message appears.


23. Select any one of the options, by entering the number of your choice and press Enter to continue.If you choose to continue with the installation then the OATenterprise installer deletes all tables from the database you have specified. By canceling the installation, you avoid deleting any database tables.



FIGURE 199. The OATxpress Database Service Name Screen

24. Enter the Database Service Name for the database.

FIGURE 200. The OATxpress Oracle Port Screen

25. Enter the Database Port number assigned to the database listener.

FIGURE 201. The OATxpress Database User Screen

26. Enter the username of a database user who has permission to perform Cre‐ate, Read, Update, and Delete (CRUD) operations on the specified database.


FIGURE 202. The OATxpress Database Password Screen

27. Enter the password for the database user account you have specified.


28. Specify the Web server you want to use with the OATxpress.

FIGURE 204. The Configure Web Server Option

29. To enable secure (HTTPS) connections between the Web browser and the OATxpress, choose Yes (numeric option 1).




FIGURE 205. The Configure OATxpress Screen (a)

30. Enter a unique 4‐digit hexadecimal identifier for the OATxpress. This identi‐fier should be unique across all the OATenterprise nodes that communicate with each other.

FIGURE 206. The Configure OATxpress Screen (b)

31. Enter a unique name for this OATxpress. This name should be unique across all the nodes of OATenterprise.


FIGURE 207. The Configure OATxpress Screen (c)

32. Enter the port number on which OATxpress will listen for browser connec‐tions (HTTP). The default port is 8080.

Note: You will not be prompted to enter an HTTP web server port number for OATxpress server if you have enabled HTTPS connections (see step 29).

FIGURE 208. The Configure OATxpress Screen (d)

33. Enter the port number on which your Web server (Tomcat) must run.

FIGURE 209. The Webservice Context for OATxpress



34. Enter the web service context details.

FIGURE 210. The Configure OATxpress Screen (e)

35. Enter the minimum Java heap size.

FIGURE 211. The Configure OATxpress Screen (f)

36. Enter the maximum Java heap size.


37. Enter the appropriate number of your choice:


• Yes (1), to enable RMI security.• No (2), to disable RMI security.

FIGURE 213. The JMS Security Screen

38. Enter:• Yes (1), to enable JMS security.• No (2), to disable JMS security.


39. Choose:• Yes (1), to enable webservice security.• No (2), to disable webservice security.Press Enter to proceed to the JMS Configuration screen.




40. If you are using a JMS transport with your Web service, then choose Yes and press Enter.If you have chosen Yes, then you will have to enter the JMS configuration details in the following steps. If you have chosen No, then you will bypass the JMS configuration and proceed directly to step 51.

Note: The default values shown in the installer screen of the JMS configuration steps are the values configured for ActiveMQ that runs automatically for each OAT server. In our case, it is an OATxpress server.









44. Enter the JNDI look‐up name for the JMS destination object (queue or topic) that will be used by OATxpress.




45. Next, you will configure JMS for SOA by specifying the URL of the JNDI ser‐vice.



FIGURE 222. The Configure JMS for SOA Screen (c)




48. Enter the JNDI look‐up name for the JMS destination object (queue or topic).


49. Enter the JNDI name of the JMS Notification Queue name that OATxpress server will use.


50. Enter the JNDI name of the JMS Import Queue name that the OATxpress server will use. Press Enter to proceed.




Press Enter to proceed with the installation. The Run OATxpress on restart screen appears.

FIGURE 226. The Run OATxpress on Restart Screen

51. Select:• Yes, to set the OATxpress to automatically restart every time the system

restarts. • No, if you do not want to run the OATxpress automatically. In this case,

manually start the OATxpress. For procedures on how to start the OATxpress, see Chapter 14: OATxpress Server Post‐Installation Procedures.

Press Enter to proceed. The Pre‐Installation Summary displays.


FIGURE 227. The Pre‐Installation Screen

52. Review all your settings before you proceed. • To change or modify any of these settings, type back and press Enter to

go to the step you need to revise. • To abort installation, press Ctrl+C.



After you finish reviewing, press Enter to install the OATxpress server to the specified directory. After a few seconds, the OATenterprise installer will display the Installation Successful screen.


53. At this stage, you may choose to view or skip the README file.54. If you chose to review the README file, press Enter to page through the file,

till you see an IMPORTANT INFORMATION COMPLETE message. Press Enter to proceed to the Installation Complete screen.

55. Once you see the Installation Complete screen, press Enter to exit the OATenterprise installer.

Note: After installation, edit the <OATxpress_Install_dir>\ofs\conf\jndi‐soa.properties file and modify the username and password properties here for secure client login to your JMS broker. If no password is needed, leave properties blank or comment both lines with a ʹ#ʹ at the beginning of the line. Apply the same changes to jndi‐connection‐factory.properties as necessary. Note that if you are accepting the defaults to use the ActiveMQ broker, you should set the username and password to blanks.


Configuring OPC Server with OATxpressPerform the following steps to setup OPC with OATxpress on Linux:

1. Install OATxpress on a Linux machine. 2. Install OPC Server on a Windows machine. 3. Install OPC Rmi Service on the same Windows machine as described below:

a. Copy OAT_Installation_directory/ofs/conf/OPC/OPCService.zip from Linux machine to the Windows machine of OPC server and unzip it to any of the drives (say c:).

b. Copy the following jars from OAT_Installation_directory/jakarta‐tomcat‐5.5.28/webapps/axis/WEB‐INF/lib/ to c:\OPCRmiService\jars directory.• oatedge.jar• device‐opc‐engine.jar• log4j*.jar

c. Copy jopcbridge.jar(from JOPCBridge install folder) to c:\OPCRmiSer‐vice\jars directory.

d. Open the command window and go to c:\OPCRmiService directory. e. Run OPC Rmi Service ʺOPCRmiService.bat 1099ʺ where 1099 is the port

on which the service should run. f. Go to the Linux box on which OATxpress is installed and start OATx‐

press Server. g. Add the OPC Device and give the Windows machine IP and RMI Port for

text fields ʺIP Adresssʺ and ʺPortʺ respectively. 4. Edit savant.properties in OAT/ofs/conf directory of Linux box and set the

property rmi_hostname to the Linux box host IP. For eg. if host IP is 172.17.0.26, then add the entry below in savant.properties:• rmi_hostname = 172.17.0.26

5. Edit /etc/hosts file on the Linux box and add an entry for the IP address to host name mapping. For eg. if host name is oat_machine1 and IP is 172.17.0.26 then add 172.17.0.26 oat_machine1.




CHAPTER 9 Installing OATxpress Server (Ubuntu)

Introduction This chapter explains how to install OATxpress on Ubuntu using the silent mode of installation.

Installing OATxpress on UbuntuFollow the steps below to install OATxpress on Ubuntu:

• Ensure that Oracle Express is installed on the same system where you are installing OATxpress.

• Login as a non‐root user.• Download setup.properties and setup.bin to the same folder, for example

/tmp.• In setup.properties (see a sample in Appendix D: Ubuntu Setup

Properties File) ensure the following:• The database name should read as follows:

USER_INPUT_DBNAME=XEUSER_INPUT_SERVICENAME=XE

• The properties (USER_INPUT_OATEDGE_PORT,WEBSERVER_PORT) value should not be 8080 as Oracle XE uses this port. Provide an appropriate value for these properties. This value will be used for the port on which you run OATxpress.

• Run sudo ./ setup.bin from the folder in which setup.bin is present.


Installing OATxpress Server (Ubuntu)

• When prompted, enter the password of the root user.• The OATxpress Server is installed silently.• As part of the installation, the username “oat” with the password as

“secret” is created automatically. To work with OATxpress, login to the system using “oat” as the username” and “secret” as the password.

The procedure to install OATxpress server on Ubuntu using the console mode is similar to the installation of OATxpress on Linux. Refer to Chapter 8: Installing OATxpress Server (Linux) for details.


CHAPTER 10 Non‐default Database and Web Server Options

Introduction OFS installation sequences have been created keeping in mind typical deployment configurations. Default choices during installation have also been selected based on typical deployments. However, your installation may require you to select non‐default options. Such installations, with non‐default options, are described in this chapter. These include:

• Use of Oracle or IBM DB2 databases (rather than Microsoft SQL)• Use of IBM WebSphere as a Web server (rather than Tomcat)

Creating a DB2 DatabaseYou can create a database on DB2 using a wizard from the Control Center tool, and also by using a SQL script.

Note: Database creation using the wizard is not documented in this chapter. If you choose to use the wizard, ensure that relevant parameters like pagesize, extentsize, etc. are set as in the script below.

The following SQL script can be used on DB2 (running on Windows) to create each database. The parameters to be filled in for the script are:

• <dbname> ‐ Name of the database. For example, edmcoredb.• <drive> ‐ Drive on which to create the database. For example, D:.• <db directory> ‐ Directory in which to place the database files, including the

drive letter on Windows platforms. For example, D:\DB2.


Non-default Database and Web Server Options

• <buffer pool name> ‐ Name of the buffer pool to use.• <tablespace name> ‐ Name of the tablespace to use.• <temp tablespace name> ‐ Name of the temporary tablespace to use.• <user group> ‐ Userʹs group to which to grant specific permissions.• <username> ‐ Username of the database.

Note that the script creates a buffer pool, tablespace and temporary tablespace, and grants specific permissions to the specified group and user. You can leave these commands out if you wish to use the existing buffer pool, tablespace, etc. instead. However, ensure that the parameters are set correctly as mentioned below.

Also note that it is important to execute the ʹUPDATEʹ commands below:

!DB2STOP;

!DB2START;

DROP DATABASE <dbname>;

CONNECT RESET;

CREATE DATABASE <dbname> ON <drive> USING CODESET UTF-8 TERRITORY US COLLATE USING SYSTEM USER TABLESPACE MAN-AGED BY SYSTEM USING ('<db directory>\<dbname>') EXTENTSIZE 16 PREFETCHSIZE 32 OVERHEAD 10.50 TRANSFERRATE 0.14 CATA-LOG TABLESPACE MANAGED BY SYSTEM USING ('<db direc-tory>\<dbname>-catalog') EXTENTSIZE 8 PREFETCHSIZE 8 OVERHEAD 10.50 TRANSFERRATE 0.14;

CONNECT TO <dbname>;

CREATE Bufferpool <buffer pool name> IMMEDIATE SIZE 1000 PAGE-SIZE 16 K;

CREATE REGULAR TABLESPACE <tablespace name> PAGESIZE 16 K MANAGED BY SYSTEM USING ('<db directory>\<tablespace name>') EXTENTSIZE 16 OVERHEAD 12.67 PREFETCHSIZE 32 TRANSFERRATE 0.18 BUFFERPOOL "<buffer pool name>" DROPPED TABLE RECOVERY OFF;

COMMENT ON TABLESPACE <tablespace name> IS '';

CREATE SYSTEM TEMPORARY TABLESPACE <temp tablespace name> PAGESIZE 16 K MANAGED BY SYSTEM USING ('<db direc-tory>\<temp tablespace name>') EXTENTSIZE 8 OVERHEAD 12.67 PREFETCHSIZE 8 TRANSFERRATE 0.18 BUFFERPOOL <buffer pool name>;

COMMENT ON TABLESPACE <temp tablespace name> IS '';

GRANT DBADM,CREATETAB,BINDADD,CON-NECT,CREATE_NOT_FENCED_ROUTINE,IMPLICIT_SCHEMA,LOAD,CRE


ATE_EXTERNAL_ROUTINE,QUIESCE_CONNECT ON DATABASE TO GROUP <user group>;

GRANT DBADM,CREATETAB,BINDADD,CON-NECT,CREATE_NOT_FENCED_ROUTINE,IMPLICIT_SCHEMA,LOAD,CREATE_EXTERNAL_ROUTINE,QUIESCE_CONNECT ON DATABASE TO USER <username>;

GRANT USE OF TABLESPACE <tablespace name> TO USER <user-name> WITH GRANT OPTION;

UPDATE DBM CFG USING FEDERATED YES DEFERRED;

UPDATE DATABASE CONFIGURATION USING DBHEAP 160000 IMME-DIATE;

UPDATE DATABASE CONFIGURATION USING STMTHEAP 160000 IMMEDIATE;

UPDATE DATABASE CONFIGURATION USING STAT_HEAP_SZ 160000 DEFERRED;

UPDATE DATABASE CONFIGURATION USING APPLHEAPSZ 1024 DEFERRED;

CONNECT RESET;

After executing these commands, restart the database server:

!DB2STOP;

!DB2START;

Note: Changes while creating the database for Star Schema on EDM server:

• Create a buffer pool with 32K page size instead of the 16K for other databases.

• Create two table spaces with type LARGE and USER TEMPORARY using the above buffer pool (in addition to the REGULAR and SYSTEM TEMPORARY table spaces mentioned above) in order to host the large view v_tag_attr_dim, whose size is determined by the total number of asset attributes defined in the system.

• Assign privilege to <user name> to access these two table spaces.

Installation with a DB2 DatabaseOn choosing the IBM DB2 database option for the database selection step, the installer proceeds to this screen:




Note: The installer screen shown (above) is for installing OATxpress server. If you are installing an OAT Enterprise Data Manager or an OAT Enterprise Administrator server, the screen caption will reflect your installation. For example, if you are installing OAT Enterprise Administrator, the screen caption will read: OAT Enterprise Administrator Database Location.

1. Specify the IP address or the host name of the server that hosts the IBM DB2 database software for OATxpress.• If the database software is installed on the same machine, then enter


name of the remote machine. Click Next. You will now provide further inputs concerning the database.



2. Specify the following values:• Database Name: Enter the name of the database. This database should

already exist; the installer will not create this database. For instructions on creating and configuring databases, see Creating a DB2 Database.


account to Create, Read, Update, and Delete (CRUD) the named database instance and its contents. The user account must therefore have CRUD permissions.

• Database Password: Enter the password for the database user account.• Instance Name: Enter the instance name for the database. This is the

name given while creating a catalog entry in the installation host for the DB2 database on another host. To obtain the instance name, open the



Control Center application of DB2, and on the left‐side panel, open All Systems ‐‐> <DB2 host name> ‐‐> Instances. There is only one entry under Instances; this is the instance name. If the database is on the same host as the OAT server install, you will see DB2 as the instance name.

• Tablespace Name: Enter the name of the tablespace on which this database was created.

You can now continue with the standard installation sequence. Refer to Section II: ‐ Installation.

Installation with an Oracle DatabaseIf, during the standard installation sequence, you select Oracle as your database, the installer proceeds to this screen:



Note: The installer screen shown (above) is for installing the OATxpress server. If you are installing an OAT Enterprise Data Manager or an OAT Enterprise Administrator server, the screen caption will reflect your installation. For example, if you are installing OAT Enterprise Administrator, the screen caption will read: OAT Enterprise Administrator Database Location.

1. Specify the IP address or the host name of the server that hosts the Oracle database software for OATxpress.• If the database software is installed on the same machine, then enter


name of the remote machine. Click Next. You will now provide input for the database.


2. Specify the following values:• Database SID Name: Enter the System ID of the database. This database

should already exist; installer will not create this database. For



instructions on creating and configuring databases, refer to Chapter 2: First Steps in Installation.

• Oracle Service Name: Name of the Oracle service for this database. This is usually the same name as the SID.

• Database Port: Enter the port number assigned to the database software. For Oracle, the default is 1521.

• Database User with Privileges: Enter the name of the database user account to Create, Read, Update, and Delete (CRUD) the named database instance and its contents. The user account must therefore have CRUD permissions.

• Database Password: Enter the password for the database user account.You can now continue with the standard installation sequence. Refer to Section II: ‐ Installation.

WebSphere Application Server (WAS) Installation Options on Windows

This section describes installation of OAT servers using IBM WebSphere as the Web server, on the Windows platform. Note that configuration steps for OAT Enterprise Administrator and OATxpress are different.

Before You Begin Note the following:

• The server must have WebSphere installed on it.• The IBM WebSphere default application server must be started. The default

application server can be started either from the command prompt or from the Windows Service panel. The service name is IBMWAS61Service ‐ Premis‐esNode for OAT Enterprise Administrator.

OAT Enterprise Administrator

To install OAT EA using IBM WebSphere as the Web server:

We assume that you have supplied user credential values for the OAT EA database, and are now viewing the Configure WebSphere screen.


FIGURE 233. Configure WebSphere Screen

1. Select:• Yes, to create a new WebSphere Application Server to run OAT EA.

Click Next to proceed to the Configure Web Server screen.• No, if you want OAT EA to run on a default WebSphere Application

Server.Click Next, to proceed to Auto‐Detect HTTP Port screen.



FIGURE 234. Configure Web Server Screen

2. Enter the configuration details for the Web server you have just defined:• To enable secure http connections between Web browser and the OAT EA

server, check the Yes checkbox.• Enter the port to be used for secure browsing in the Https Port for

Browsing Server field.• Enter the host name or the IP address of the machine on which you are

installing the OAT EA, in the Host Name field.Click Next, to proceed to the Configure OAT EA screen.



FIGURE 235. Configure OAT Enterprise Administrator Screen

3. Specify the following values:• Unique ID: Enter a 4‐digit hexadecimal identifier unique across all

OATenterprise nodes which interact with the OAT Enterprise Data Manager.

• Name: Enter a name unique across all OATenterprise nodes that interacts with the OAT Enterprise Data Manager.

Note: Do not specify a name that has spaces or special characters.

• Port: Enter the port on which you want the OAT EA server to run on.

Note: If the HTTPS transport is enabled between the Web browser and OAT Enterprise Administrator, then the OAT Enterprise Administrator port is not shown.

• Heap size (in MB) Min: Enter the Java minimum heap size for OAT EA.• Heap size (in MB) Max: Enter the Java maximum heap size for OAT EA.



• Application Server Name: Enter the name for the WebSphere Application Server. The new Application Server will be created using the name entered during installation.

Click Next to move to the Configure Authentication screen.

FIGURE 236. Configure Authentication Screen

4. Click • Yes to use external authentication.

Click Next to move to the Configure External Authentication screen.• No to ignore external authentication.

Click Next to move to the Configure Security screen.


FIGURE 237. Configure External Authentication Screen

5. Select • Microsoft Active Directory to configure Microsoft Active Directory. Refer

to Chapter 5 Installing OAT Enterprise Administrator (Windows) for more details.Click Next to move to the Configure Microsoft Active Directory screen.

• Select WebSphere Application Security to move to configure the OAT Server Administrator.Click Next to move to the Configure OAT Server Administrator screen.

• Select Other to customize an active directory other than Microsoft Active and WebSphere.Click Next to move to the Configure Custom Active Directory screen.



FIGURE 238. Configure OAT Server Administrator Screen

6. Enter the following values.• OAT Admin Group Name: Enter the group name to which the user with

administrator privileges belongs. Multiple group names can be specified with pipe (|) separator. All the users belonging to the specified group(s) get Server Administrator role and the rest get Default User role in OFS.

• User Identity: Enter the user identity of the WebSphere administrator user who can start or stop the Application Server.

• User Password: Enter the user password for the above user.Note the following WebSphere Authentication and Authorization details:

• During installation, a challenge pop‐up appears to check server startup status. The WAS admin user or password has to be provided to proceed further on the installation. This pop‐up closes automati‐cally after a specified time (say 3 minutes).


• While installing WAS, an authentication pop‐up appears, if WAS App security is enabled.

• If the user belongs to the Server Administrator role in WAS, then the role in EA/Xpress will be of a Server Administrator, else it will be of a Default User.

• As the user logs‐in for the first time, a user with default roles is created in the OAT database. Later the Server Administrator can alter the user role assignments that exists in the OAT database. Next time when the user logs‐in, permissions based on the existing roles will be available.

• WAS application security needs to be enabled and WAS application server needs to be configured for SSO, to support SSO from EA to Xpress and vice‐versa.

Click Next to move to the Configuring Security screen. Refer to Chapter 5: Installing OAT Enterprise Administrator (Windows) for further installation procedures.

The screen below appears if you have chosen to use the default WebSphere Application Server for OATxpress server.

FIGURE 239. Auto Detect http Port Screen



7. Select:• Yes, if you want the installer to auto detect the HTTP port of the default

WebSphere Application Server.Click Next, to move to the Auto Detect http Port screen WebSphere Application Server.

• No, if you want to enter the HTTP port manually during the installation.Click Next, to configure the default WebSphere Application Server manu‐ally. The Configure Web Server screen appears.


Note: If you had chosen to specify WAS port instead of auto‐detect, specify this in the Configure Web Server screen.

8. Enter the configuration details for the Web server:• To enable secure connections between the Web browser and the

OATxpress server, check the Yes checkbox.


• Enter the port to be used for secure browsing in the Https Port for Browsing Server field.

• Enter the host name or the IP address of the machine on which you are installing OATxpress in the Host Name field.

Click Next.After configuring the Web server, the installer proceeds to the following screens:• Configure OAT EA• Configure Authentication• Configure External Authentication• Configure OAT Server Administrator• Configure SecurityRefer to Chapter 5: Installing OAT Enterprise Administrator (Windows) for further installation procedures.

OATxpress We assume that you have supplied user credential values for the OATxpress database, and are now viewing the Configure Web Server screen.

To install OATxpress using IBM WebSphere as the Web server:




1. Click on the IBM WebSphere option and click Next, to proceed.

Note: The above step is applicable only when Oracle is selected as the database software. When IBM DB2 is the database software, WebSphere is assumed to be the application server. Therefore, the Configure WebSphere screen appears immediately when you click Next, after entering the database values in the OATxpress Database input screen.


FIGURE 242. Configure WebSphere Screen

2. Select:• Yes, if you want to create a new WebSphere Application Server to run

OAT EA. Click Next, to proceed to the Configure Web Server screen.

• No, if you want OAT EA to run on a default WebSphere Application Server.Click Next, to proceed to Auto‐Detect HTTP Port screen.




3. Enter the configuration details for the Web server you have just defined in the earlier step:• To enable secure connections between the Web browser and the

OATxpress server, check the Yes checkbox.• Enter the port to be used for secure browsing in the https port for


installing OATxpress in the Host Name field.Click Next, to proceed to the Configure OATxpress screen.



FIGURE 244. Configure OATxpress Screen

4. Specify the following values:• Unique ID: Enter a 4‐digit hexadecimal identifier unique across all

OATenterprise nodes which interact with the OAT Enterprise Data Manager.

• Name: Enter a name unique across all OATenterprise nodes which interact with the OAT Enterprise Data Manager.

Note: Do not specify a name that has spaces or special characters.

• Port: Enter the port on which you want the OATxpress server to run on.

Note: You will not be prompted to enter an HTTP web server port num‐ber for OATxpress server, if you have enabled HTTPS connections between the Web browser and the OATxpress server.

• Heap size (in MB) Min: Enter the Java minimum heap size for OATxpress.



• Heap size (in MB) Max: Enter the Java maximum heap size for OATxpress.

• Application Server Name: Enter the name for the WebSphere Application Server. The new Application Server will be created by the name entered during installation.

Click Next to move to the Configure Authentication screen.

FIGURE 245. Configure Authentication Screen

5. Click • Yes to use WebSphere application security for authentication.• No, if you do not want to use authentication of WebSphere application

security.Click Next; to move to the Configure Security screen.

Note: Note the following WebSphere authentication details:

• For EA controlled Xpress, authentication happens in Xpress. The authorization and role assignment happens via EA.


• WAS application security needs to be enabled and WAS application server has to be configured for SSO. If WebSphere SSO is not configured, Xpress cannot be accessed via EA.

Refer to Chapter 7: Installing OATxpress Server (Windows) for further installation procedures.

FIGURE 246. Auto‐detect Http Port Screen

This screen appears if you have chosen to use the default WebSphere AppServer for the OATxpress server.

6. Select:• Yes, if you want the installer to auto detect the HTTP port of the default

WebSphere Application Server.Click Next, to configure the detected WebSphere AppServer.

• No, if you want to enter the HTTP port manually during the installation.Click Next, to configure the default WebSphere AppServer manually. The Configure Web Server screen appears.




Note: If you had chosen to specify the WAS port instead of auto‐detect it, specify this in the Configure Web Server screen.

7. Enter the configuration details for the Web server:• To enable secure connection between the Web browser and the

OATxpress server, check the Yes checkbox.• Enter the port to be used for secure browsing in the https port for


installing OATxpress in the Host Name field.Click Next. After configuring the Web server, the installer proceeds to the following screens:Configure OATxpress Configure AuthenticationConfigure Security JMS Configuration screen


8. After configuring the JMS transport feature, the installer proceeds to the Install as Windows Service screen. If you choose Yes, to set the OATxpress Windows service to automatically start every time the system boots.

9. Click Next to proceed to the Pre‐installation Summary screen.Refer to Chapter 7: Installing OATxpress Server (Windows) for further installation procedures.




SECTION III

License Keys & Post‐Installation



CHAPTER 11 Acquiring & Installing a License Key

Introduction This chapter explains the procedure to acquire and install a license key for the respective OAT server installation. As part of its licensing strategy, OATSystems, Inc. provides a license key through the OAT Support Center as a follow‐on transaction to the purchase and delivery of its software.

A license key is a text file that identifies the contact person, the authorized features, the license type and duration, and the server where the software will run. It also contains an encrypted key string that allows the authorized features to be used on the designated server.

The OAT Support Center issues license keys upon request. To request a license key, you must have an OAT Support Center account (you can request an account, if necessary). You must also provide the MAC address and the host name or IP address of the intended server. The license key enables the software to run only on that server.

Once you have the license key, you need to copy the license key file to the installation directory of the appropriate server and restart the server.

The process for acquiring a license key is identical for all (OAT Enterprise Data Manager, OAT Enterprise Administrator and OATxpress) servers.


Acquiring & Installing a License Key

Requesting a License KeyYou need an OAT Support Center account before you can request a license key.

Acquiring an account To acquire an OSC account:

1. In a browser window, enter:https://support.oatsystems.com

The Login page for the OAT Support Center opens.

FIGURE 248. The OAT Support Center Login Page

Click Need an account? The Account Request page opens.


FIGURE 249. The Account Request Page

2. Enter the required information and click Send. Depending on the time and day of your submission, you should receive confirmation of your new account within a day.

Before You Begin You should have the following information about the server:

• MAC address:• In Windows, the MAC address consists of a sequence of six double‐digit

hexadecimal numbers separated by hyphens (for example, 00‐0D‐60‐5D‐C7‐34). The ipconfig /all command displays the address in a command window.

• In Linux, the MAC address consists of a sequence of six double‐digit hexadecimal numbers separated by colons (for example, 00:0D:60:5D:C7:34). The ipconfig -a command displays the address in a shell.

• Host name or static IP address of the server.



To get the MAC address, host name and IP address in Windows, please follow these instructions:

Note: These steps should be performed on the system on which the OAT Enterprise Administrator is to be installed or on the system on which the OAT Enterprise Administrator is already installed.

h. Click Start ‐‐> Run.The Run dialog box appears.

i. Navigate to a command prompt as shown.

FIGURE 250. The Run Dialog Box

Click OK.The command prompt appears.

j. Type ipconfig /all command line and press Enter.The system will display the Windows IP Configuration and Ethernet Local Area Connection details.


FIGURE 251. The Command Prompt Window (a)

The Windows IP Configuration displays the Host Name. The Ethernet adapter Local Area Connection displays the Physical Address (MAC Address highlighted) and the IP Address.

To obtain the MAC address, IP address and the host name in Linux, follow the steps outlined below:

a. Type ipconfig -a in a terminal window. You will get this screen.



FIGURE 252. The Command Prompt Window (b)

The screen displays the MAC address (highlighted), and inet addr (the IP address).

b. Type hostname in the terminal window for the host name.

To request a license key:

1. In a browser window, enter:https://support.oatsystems.com

The Login page for the OAT Support Center opens.2. Enter your username and password and click Login. The OAT Support Cen‐

ter Home page opens.


FIGURE 253. The OAT Support Center Getting Started Page

3. Click Request a license key for your software. The License Key Request form opens, populated with your account information.

4. Enter the required information such as the IP address, hostname and the MAC address of the server where you want to install the product, and click Send.

You can expect an e‐mail response with an attached license key file from the OSC in less than a day. The license key will unlock all of your installation features.

Installing the License KeyWhen installing a license key, copy the file (license.txt) to the installation direc‐tory of the server and configure the savant.properties file, if necessary.



Installing a license key To install a license key:

1. Copy the license.txt file you received from the OAT Support Center to the associated server.

Note: To determine which server is associated with a license.txt file, open the file and check its MAC address and IP address or host name.

2. Copy the file to:

<OAT_Install_Dir>\ofs\conf

where OAT_Install_Dir is the OAT installation directory. This is the default location of the license.txt file. You can place the file in a different location (for example, <OAT_Install_Dir>ofs\local\conf, and specify the alternate location in the next step.

Note: Ensure that everyone has read privileges for the license.txt file.

3. Create the file:

<OAT_Install_Dir>\ofs\local\conf\savant.properties.m

if it does not exist, and enter the following property setting:

com.oatsystems.license.file=<path_to_file>\license.txt

You can make this change in the savant.properties file in the <OAT_Install_Dir>\ofs\conf folder, when you run the deploy batch/script, which is in the <OAT_Install_Dir>\ofs\bin folder. But the properties files in <OAT_Install_Dir>\ofs\conf and <OAT_Install_Dir>\ofs\webapps folders will be overwritten with settings from the property template files ‐ losing all the changes that may have been made. To make permanent changes (those that will survive running the deploy script), create .m merge files, whose names are based on the name of the property file you want to affect, in the <OAT_Install_Dir>\ofs\local folder. For example, in this step, specify a “permanent” property override for the license file path and name. The original setting is in the savant.properties file, so we create a file called savant.properties.m in <OAT_Install_Dir>\ofs\local\conf.

4. Open a command prompt, change the working directory to <OAT_Install_Dir>\ofs\bin, and run deploy ‐f. Running the deploy batch/script will overwrite any changes that were made in the files in the <OAT_Install_Dir>\ofs\conf or


<OAT_Install_Dir>\webapps folders ‐ but since we have created a merge configuration file in <OAT_Install_Dir>\ofs\local\conf, as explained earlier.

5. If the associated server is running, restart it for the license key to take effect.




CHAPTER 12 OAT Enterprise Data Manager Post‐Installation Procedures

Introduction This chapter explains the procedure to start, stop and verify the OAT Enterprise Data Manager, both for Windows and Linux. Topics include the following:

• Starting the OAT Enterprise Data Manager• Verifying Startup of the OAT Enterprise Data Manager• Stopping the OAT Enterprise Data Manager

Starting the OAT Enterprise Data ManagerBefore you start the OAT Enterprise Data Manager, install the license key. See Chapter 11: Acquiring & Installing a License Key for details. If you have installed the OAT Enterprise Data Manager as a Windows service, stop and restart the OAT Enterprise Data Manager and Tomcat services in the Windows Services.


OAT Enterprise Data Manager Post-Installation Procedures

Note: The OAT Enterprise Data Manager requires a companion service for the Web server on which it runs. Both services (the OAT Enterprise Data Manager service and the companion service) must be running for the OAT Enterprise Data Manager server to function. Note that the companion service must be running before you can start the OAT Enterprise Data Manager service. For deployments on a stack with the Tomcat Web Server, the companion service will be named OATTomcat; for deployments on a stack with IBMʹs Web‐Sphere AppServer, the companion service will be named IBM Web‐Sphere Application Server.

Starting the OAT Enterprise Data Manager

You can start the OAT Enterprise Data Manager as follows:

In Linux:

cd <OAT_Install_Dir>/ofs/conf

./oatedm start

Additionally, the following command is available when the OAT Enterprise Data Manager has been installed as a service:

service oatedm start

In Windows:

From the Start menu, navigate to All Programs ‐‐> OAT Enterprise Data Manager ‐‐> Start OAT Enterprise Data Manager

You can also use the following command at a command prompt, to view status messages during startup. These messages indicate the webserver startup status and the database connectivity status, among other information.

cd <OAT_Install_Dir>

oatedge start

where OAT_Install_Dir is the OAT Enterprise Data Manager installation directory (for example, C:\OATedm)


Verifying Startup of the OAT Enterprise Data ManagerChecking the status In Linux:


./oatedm status

In Windows (using a command prompt window):

<OAT_Install_Dir>\ofs\conf\oatedge status

where OAT_Install_Dir is the OAT installation directory (for example, C:\OATedm).

The status command provides the following feedback when everything is running in Windows:

Web Server is running OK.

OAT Enterprise Data Manager Server Status:

Service Manager: Running

Database Connectivity: OK

To verify that the OAT Enterprise Data Manager is running as expected, check the OAT Enterprise Data Manager log for errors. Enter:

cd <OAT_Install_Dir>\ofs\log

Then on either platform, enter:

tail -f oatedge_errors.log

You must have either Cygwin or the Microsoft Windows Server 2008 Resource Kit Tools installed to use the tail command in Windows.


OAT Enterprise Data Manager Post-Installation Procedures

Stopping the OAT Enterprise Data ManagerYou can stop the OAT Enterprise Data Manager as follows:

In Linux:


./oatedm stop

or, use the following command when the OAT Enterprise Data Manager has been installed as a service:

service oatedm stop

In Windows:

From the Start menu, navigate to All Programs ‐‐> OAT Enterprise Data Manager ‐‐> Stop OAT Enterprise Data Manager

or, you can also use the following command:


oatedge stop

where OAT_Install_Dir is the OAT installation directory (for example, C:\OATedm).


CHAPTER 13 OAT Enterprise Administrator Post‐Installation Procedures

Introduction This chapter explains how to start and stop the OAT Enterprise Administrator, log into the Web application and verify the OAT Enterprise Administrator startup on Linux and Windows. The topics included in this chapter are:

• Starting the OAT Enterprise Administrator• Verifying Startup of the OAT Enterprise Administrator• Logging in to OAT Enterprise Administrator• Stopping the OAT Enterprise Administrator


OAT Enterprise Administrator Post-Installation Procedures

Starting the OAT Enterprise AdministratorBefore you can start the OAT Enterprise Administrator, install the license key. See Chapter 11: Acquiring & Installing a License Key for details.

Note: The OAT Enterprise Administrator service requires a companion service for the Web server on which it runs. Both services (OAT Enterprise Administrator service and the companion service) must be running for the OAT Enterprise Administrator server to function. Note that the companion service must be running before you can start the OAT Enterprise Administrator service. For deployments on a stack with the Tomcat Web Server, the companion service will be named OATTomcat; for deployments on a stack with IBMʹs Web‐Sphere AppServer, the companion service will be named IBM Web‐Sphere Application Server.

Starting the OAT Enterprise Administrator

You can start the OAT Enterprise Administrator as follows:

In Linux:


./oatedge start

Additionally, the following command is available when the OAT Enterprise Administrator has been installed as a service:

service oatadmin start

In Windows:

Navigate from the Start menu to ‐‐> All Programs ‐‐> OAT Enterprise Administrator ‐‐> Start OAT Enterprise Administrator Server

You can also use the following command at a command prompt, to view status messages during startup. These messages indicate the webserver startup status andthe database connectivity status, among other information.


oatedge start

where OAT_Install_Dir is the OAT installation directory (for example, C:\OATea).


Verifying Startup of the OAT Enterprise AdministratorChecking the status In this section, you can verify startup by checking the status of the OAT

Enterprise Administrator.

In Linux:


./oatedge status


<OAT_Install_Dir>\ofs\conf\oatedge status

where OAT_Install_Dir is the OAT installation directory (for example, C:\OATea).

The status command provides the following feedback when everything is running:

Web Server is running Ok.

OAT Enterprise Administrator Server Status:



To verify that the OAT Enterprise Administrator is running as expected:

1. Open a Web browser window on the server machine, or on another machine with network access to the server machine. In this procedure, the hostname is the name of a remote server machine (for example, oat‐server) and 8080 is the default port number. If the server is configured to run on a different port, then use that port number instead.

2. To verify access to the OAT Enterprise Administrator Web application, enter:

http://localhost:8080/oatedge (for a local server)

or

http://hostname:8080/oatedge (for the remote server on hostname)



Where hostname is the name of a remote machine running the OAT Enterprise Administrator. If you entered a different port number while installing, use that port number instead of ʺ8080ʺ. If you chose to enable HTTPS secure connections, change the beginning of the URL to ʺhttps://ʺ instead of ʺhttp://ʺ. The OAT Enterprise Administrator login page displays.

3. Check the OAT Enterprise Administrator log for errors. Enter:

cd <OAT_Install_Dir>\ofs\log

Then enter:

tail -f oatedge_errors.log


Logging in to OAT Enterprise AdministratorIn Windows, you can open the OAT Enterprise Administrator login page from the Start menu by clicking All Programs ‐‐> OAT Enterprise Data Manager ‐‐> OFS OAT Enterprise Data Manager.

You can also open the OAT Enterprise Administrator login page, by entering one of the following URLs in a browser window:


or


If you supplied a different port number while installing, use that port number instead of ʺ8080ʺ. If you chose to enable HTTPS secure connections, change the beginning of the URL to ʺhttps://ʺ instead of ʺhttp://ʺ.


In Linux, from a browser use the URL:

http://<ipaddress>:<port>/oatedge

The initial login username and password are:

Username: oat_adminPassword: apollo

Note: The above password can be changed in LDAP/non‐LDAP configura‐tion. The password supports all special characters.

For more information, please see the OAT Foundation Suite OATxpress User Guide.

Stopping the OAT Enterprise AdministratorYou can stop the OAT Enterprise Administrator as follows:

In Linux:


./oatedge stop

You can also use the following command:

service oatadmin stop

In Windows:

Go to the Start menu ‐‐> All Programs ‐‐> OAT Enterprise Administrator ‐‐> Stop OAT Enterprise Administrator Server.

or, use the following command to see the database and Web server connectivity status:


oatedge stop

where <OAT_Install_Dir> is the OAT installation directory (for example, C:\OATea).




CHAPTER 14 OATxpress Server Post‐Installation Procedures

Introduction This chapter explains the procedure to start and stop the OATxpress server, verify startup, and log on to the OATxpress Web application. The topics included in this chapter are:

• Starting the OATxpress Server• Verifying startup of Tomcat and OATxpress Server• Logging in to the Web Application• Stopping the OATxpress Server


OATxpress Server Post-Installation Procedures

Starting the OATxpress ServerIf the OATxpress server was installed to run as a Windows service or to restart automatically with Linux, and if its host computer is running, then the OATxpress server should be running as well. If so, you should proceed to log into the Web application.

Note: The OATxpress service requires a companion service for the Web server on which it runs. Both services (the OATxpress service and the companion service) must be running for the OATxpress server to function. Also note that the companion service must be running before you can start the OATxpress service. For deployments on a stack with the Tomcat Web Server, the companion service will be named OATTomcat; for deployments on a stack with IBMʹs Web‐Sphere AppServer, the companion service will be named IBM Web‐Sphere Application Server.

Starting the OATxpress server

You can start OATxpress as follows:

In Linux:


./oatxpress start

Additionally, the following command is available when the OATxpress has been installed as a service:

service oatxpress start

In Windows:

Click Start ‐‐> Programs ‐‐> OATxpress ‐‐> Start OATxpress Server

You can also use the following command at a command prompt, to view status messages during startup. These messages indicate webserver startup status and database connectivity status, among other information.


oatedge start

where <OAT_Install_Dir> is the OATxpress installation directory (for example, C:\OATxpress).


Verifying startup of Tomcat and OATxpress ServerChecking the OATxpress status

To check the status of the OATxpress server, enter the following command in a command window:

In Linux:


./oatxpress status


<OAT_Install_Dir>\oatedge status


The status command provides the following feedback when everything is running:

Web Server is running OK.

OATxpress Server Status:



Verifying access To verify access to the OATxpress Web application, enter:


or


If you supplied a different port number while installing, use that port number instead of ʺ8080ʺ. If you chose to enable HTTPS secure connections, change the beginning of the URL to ʺhttps://ʺ instead of ʺhttp://ʺ. The OATxpress login page will display.



Checking logs for errors To check the OATxpress logs for errors:

In Linux:

cd <OAT_Install_Dir>/ofs/logtail -f oatedge_errors.log

In Windows:

cd <OAT_install_Dir>\ofs\log\tail -f oatedge_errors.log



Logging in to the Web ApplicationIn Windows, open the OATxpress login page from the Start menu by clicking All Programs ‐‐> OATxpress ‐‐> OATxpress Server Manager.

You can open the OATxpress login page both in Linux as well as Windows, by entering one of the following URLs in a browser window:



If you supplied a different port number while installing, use that port number instead of ʺ8080ʺ. If you chose to enable HTTPS secure connections, change the beginning of the URL to ʺhttps://ʺ instead of ʺhttp://ʺ.

In Linux, from a browser use the URL:

http://<ipaddress>:<port>/oatedge


The initial login username and password for the OATxpress Web application are:

• Username: oat_admin• Password: apollo

Note: The above password can be changed in LDAP/non‐LDAP configura‐tion. The password supports all special characters.

After logging in for the first time, you are required to change your password. You will then be able to create other accounts. See the OAT Foundation Suite User Guide for information on creating users and roles.

Stopping the OATxpress ServerYou can stop OATxpress as follows:

In Linux:


./oatxpress stop

or, use the following command when the OATxpress server has been installed as a service:

service oatxpress stop

Note: Follow the same procedure in Ubuntu.

In Windows:

Click Start ‐‐> Programs ‐‐> OATxpress ‐‐> Stop OATxpress Server

or, you can also use the following command:


oatedge stop

where <OAT_Install_Dir> is the OAT installation directory (for example, C:\OATxpress).




SECTION IV

Configuration



CHAPTER 15 Configuring OAT EDM & OAT Enterprise Administrator

Introduction This chapter describes the steps to be followed for configuring the OAT Enterprise Data Manager and the OAT Enterprise Administrator.

Configuring OAT Enterprise Data ManagerAfter installing the OAT Enterprise Data Manager:

1. Copy the license.txt to <OAT_Install_Dir>\ofs\confWhere <OAT_Install_Dir> is the installation directory for OAT Enterprise Data Manager. For example: E:\OATedm.For information on acquiring & installing a license key, see Chapter 11: Acquiring & Installing a License Key.

2. Configure MicroStrategy for OAT Enterprise Data Manager. See Appendix G: MicroStrategy Configuration for details.


Configuring OAT EDM & OAT Enterprise Administrator

Preparing an OATxpress Server for use with OAT Enterprise Data ManagerOFS allows an OATxpress server to send data to the Enterprise server based on a configurable schedule. Several new options are available with OFS for migrat‐ing data from the OATxpress server to the Enterprise Data Manager (EDM). These are:

• Automatic data push from OATxpress to EDM, after a certain number of database transactions

• Data compression• Additional transport option of JMS (in addition to SOAP)

The default options for data migration are:

• Automatic push from OATxpress server to EDM• Compressed format• SOAP transport

If this configuration needs to be changed, it can be done using the parameters in <OATxpress_Install_Dir>\ofs\conf\savant.properties.

The following sub‐sections cover additional options and configuration parame‐ters in greater detail. Note that all parameters are present in savant.properties.

Push data from OATxpress to OAT Enterprise Data ManagerIn earlier versions, data migration was done to a fixed schedule. Since the amount of data generated in an OATxpress server can vary widely across time, this made it hard to predict the amount of data that needed to be migrated in each cycle. While there were options to limit the amount of data on the network at any time, it was possible that a large amount of data got accumulated with‐out being sent, and then at the scheduled time this large data was sent in bursts.

To handle such situations the option to initiate data migration as and when data is generated was added. While this is the default, it can be disabled using a con‐figuration parameter:

dm.push_data_to_enterprise=no

Another parameter that controls how often to send data is:

dm.migrate_after_states=1


A state comprises of a configurable number of database transactions, by default 500. The above parameter in effect states that after 500 transactions data should be migrated. By setting the value to, say, 5, the number of transactions between migrations can be increased to 2500.

A related parameter that controls the number of transactions per state is:

max_connection_operations=500

This parameter may not be present in savant.properties; however, you may add it. Increasing or decreasing the default value of 500 gives you finer control over when data migration will occur.

Data CompressionData compression is enabled by default. This lets an OATxpress server reduce bandwidth usage. To disable data compression, set the following parameter:

dm.compress_data=false

It is possible for different OATxpress servers to have different compression set‐tings. EDM can handle both compressed and uncompressed data.

Note: Note that only data gets compressed. Responses and acknowledgement messages are still sent without compression.

JMS TransportPrevious versions supported only SOAP transport for data migration. OFS adds JMS as an additional transport option, although SOAP remains the default.

EDM can operate either with SOAP or JMS, but not both. Therefore, it is not possible to configure some OATxpress servers in a single deployment for SOAP and others in the same deployment for JMS.

Changes need to be made in configuration files to enable JMS and disable SOAP. The list of changes are:

1. In the OAT Enterprise Data Manager and the OATxpress server directories:

<OATedm_Install_Dir>\ofs\conf\savant.properties <OATxpress_Install_Dir>\ofs\conf\savant.properties



Set the following properties to true. These properties will be used by EDM to start transferring data using JMS:

• dm.transport_type.jms=true• jms.broker.embedded=true

2. The following properties are also used by JMS. You can change them if required. The properties are applicable to bothOAT Enterprise Data Man‐ager as well as OATxpress.• To change the IP address or hostname, or JMS port number of local

machine, use the jms.broker.uri setting.

Note: The jms.broker.uri setting is not straightforward if the embedded ActiveMQ is used as the JMS broker. In OFS, when the embedded JMS broker is used, the jms.broker.uri is set to xbean:activemq.xml and this XML configuration file holds the actual configuration for the ActiveMQ broker. The file is located in <OATxpress_install_dir>\ofs\conf\activemq.xml. The specific sec‐tion related to the transport URI is:<transportConnectors> <transportConnector name=ʺdefaultʺ uri=ʺtcp://localhost:61616ʺ discoveryUri=ʺmulticast://defaultʺ/></transportConnectors>

To change the hostname and port number for the JMS broker, mod‐ify the uri attribute for the <transportConnector> element.

• To change the JMS reply timeout period, change the dm.jms.reply_timeout.millis setting.

• To change remote peer id for JMS, change dm.jms.remote_peer_id


3. In the OAT Enterprise Data Manager directory:

<EDM_Install_Dir>\ofs\conf\edm-des-config.xml.template

• Under remote‐listeners, comment out GenericServerTransformer for SOAP, and uncomment SimpleServerTransformer for JMS.Your changes will look like this:







<listener remote-peer-id="hl-savant" desc="The JMS Server writes to this listener">

<transformer class-name="com.oatsystems.des.Sim-pleServerTransformer">

<args>topic=dm-export remote_peer_id=hl-savant</args>

</transformer>

</listener>



The above block defines the ʺlistenerʺ on the OAT Enterprise Data Man‐ager server; there is only one listener, which accepts data transform requests for data migration from multiple OATxpress servers. The remote_peer_id setting is used on OATxpress servers, to identify this specific listener on the OAT Enterprise Data Manager server. When receiving incoming messages, the OAT Enterprise Data Manager will use



the remote_peer_id in the message to determine the correct listener to process each message. All incoming messages from multiple OATxpress servers should, therefore, use the same remote_peer_id to identify this listener.

• Under remote‐services, comment out SoapClientTransformer for Soap and uncomment SimpleClientTransformer for JMS.Your changes will look like this:







<remote-service topic="dm-export" remote-peer-id="hl-savant" desc="Data migration export transformers for hl-savant over JMS">

<transformer class-name="com.oatsystems.des.SimpleCli-entTransformer">

<args>transport_type=jms envelope_data=<![CDATA["<jms-connection queue=\"ofs.ack.queue\" persistent=\"true\" transact=\"false\" cli-ent-ack=\"false\" host-name=\"<EDM_SERVER>\" port=\"61616\" priority=\"5\"></jms-connection>"]]>

</args>

</transformer>


</remote-service>

</remote-services>



4. In the OATxpress server directory:

<oatxpress_install_dir>\ofs\conf\site-des-config.xml.template

• This file needs to be changed at every OATxpress server location.• Under remote‐services node, comment out SoapClientTransformer for

SOAP and uncomment SimpleClientTransformer for JMS.After you make the change, your template file will look like this:







<remote-service topic="dm-export" remote-peer-id="hl-savant" desc="Data migration export transformers for hl-savant over JMS">

<transformer class-name="com.oatsystems.des.SimpleCli-entTransformer">

<args>transport_type=jms envelope_data=<![CDATA["<jms-connection queue=\"ofs.trans.queue\" persistent=\"true\" transact=\"false\" cli-ent-ack=\"false\" host-name=\"<EDM_SERVER>\" port=\"61616\" priority=\"5\"></jms-connection>"]]>

</args>

</transformer>

</remote-service>


The remote‐peer‐id should remain the same at both ends of the SOAP/JMS channel; for all OATxpress servers, it needs to be set to the same ʺhl‐savantʺ value. On the data sending side (the OATxpress server), we use topic + remote‐peer‐id to locate the specific remote service in the configuration, which is to be used to deliver the message.

On the data receiving side the (OAT Enterprise Data Manager server), we use the remote‐peer‐id to identify the specific listener to process the incoming message, and the topic is used to locate a local service to process the message. Since the remote‐peer‐id is not used to identify different OATxpress servers, they can all use the same remote‐peer‐id for data communication.

Improving Data Throughput

You can improve the throughput of data from multiple servers to an OAT Enterprise Data Manager by:

• Reducing the number of operations per state for an OATxpress server data‐base.

• Increasing the number of operations per state for an OAT Enterprise Data Manager database.

• Increasing the length of time before a server times out when transferring data.

• Scheduling a limited number of servers to transfer data to an OAT Enterprise Data Manager simultaneously. For more information, refer to the OAT Foun‐dation Suite OATxpress User Guide, Streamlining Deployment across your Organization.

Reducing/Increasing the number of operations per state

A server transfers data to an OAT Enterprise Data Manager via packets. Each packet can contain one or more states, depending on the configured data limit per packet. By reducing the number of operations per state (the default is 500), you reduce the amount of data per packet and thereby increase the transmission rate.

Increasing the number of operations saved in the OAT Enterprise Data Manager’s database state can reduce the time required to increment the state, which reduces the overall time required for data transfers from servers.



To change the number of operations per state:

1. On the server, edit:

<OAT_Install_Dir>\ofs\conf\savant.properties

where <OAT_Install_Dir> is an OAT installation directory.2. Reduce/Increase the value of the following property (you may need to

add the property to the file):

max_connection_operations=500

3. Save your changes.

Increasing the length of time before a time‐out

Increasing the time‐out period for an OATxpress server increases the probability of completing a data transfer before the server times out.

To increase the time‐out period for an OATxpress server:

1. On the OATxpress server, edit:

<OAT_Install_Dir>\ofs\conf\savant.properties

(OAT_Install_Dir is the OATxpress installation directory)2. Increase the value of the following property (you may need to add the

property to the file):

axis.client.timeout_millis=60000

3. Save your changes.

If you specify a value of 0 (no time‐out), the adapter waits until the server responds.

If you specify no value, the adapter uses the default value of 60,000 (which is equal to 60 seconds).

The recommended range of values when transferring large amounts of data is 300,000 (5 minutes) to 900,000 (15 minutes).


Configuring for Report Integration Data

Some OAT Enterprise Data Manager reports require order and shipment IDs to function properly. Normally, a shipment or order ID gets saved in the OBJECT_STATE table by a scenario running on an OATxpress Server. If the IDs are where the OAT Enterprise Data Manager expects to find them in the data migrated from OATxpress servers (that is, in certain column fields of the OBJECT_STATE table for case or pallet tag objects), then the reports function properly. Otherwise, you need to configure the OAT Enterprise Data Manager to use the correct values.

The object state type and object state column for shipment_id and order_id are configured in dw_etl_config.xml.

The default value for shipment_id is state_data_0 and that for sales_order_id is state_data_1.The default value for object state type for both are GENERIC_OBJECT_STATE.

In the event that different object_state_type or object state data is used for either shipment_id or sales_order_id, you must simply perform a search and replace in dw_etl_config.xml to make it consistent with the usage in the OATxpress scenario. The dw_etl_config.xml is located at .edm_install_dir\ofs\conf. For more information, refer to the OATxpress Scenario SDK Guide.

Changing the TCP/IP Port Number for RMI

During installation, the OAT Enterprise Data Manager installer sets the TCP/IP port number for Java Remote Method Invocation (RMI) to 7099. If another TCP/IP application already uses that port number, then you need to change the OAT Enterprise Data Manager RMI port number.

To check the TCP/IP port numbers of the applications running on the OAT Enterprise Data Manager server node, use the netstat ‐a command. To assign RMI to a different TCP/IP port number, edit the rmi_registry_port property value in the savant.properties file located in:

<edm_install_dir>\ofs\conf\

For example, C:\OATedm\ofs\conf\savant.properties.



Configuring OAT Enterprise AdministratorAfter installing the OAT Enterprise Administrator, you have to perform the following steps:

1. Copy the license.txt to <OAT_Install_Dir>\ofs\confwhere <OAT_Install_Dir> is the installation directory for the OAT Enterprise Administrator.For information on acquiring and installing license key, see Chapter 11: Acquiring & Installing a License Key.

2. If HTTPS is enabled then refer to the Secure Transport for Tomcat section in Appendix B: OAT Foundation Suite Security.

If LDAPS is enabled then refer to User Authentication, Default Authentication and External Authentication sections in Appendix B: OAT Foundation Suite Security.

Configuring OAT EDM after OAT EA InstallationIf the EDM server was not configured while installing EA, and you want to configure it later, perform the following steps:

1. Add new rows in the database for master data synchronization, and insert the following values:

insert into migration_host(remote_peer_id, last_state)

values ('ccs:edmserver', -1);

insert into scheduled_task(task_name, clsid, args, period_minutes, at_time_hrs, at_time_minutes, start_time, deleted )

values ('MasterDataTransfer_For_edmserver',

'com.oatsystems.ccs.des.CCSExportTask',

'dm_topic=ccs-export remote_peer_id=ccs db_conn_prefix=sense-ware dm_spec_file=@INSTALL_DIR@/ofs/conf/ccs-edm-dm-spec.xml senseware_name=edmserver dm_recvr_host=@EDM_HOST@ dm_recvr_port=@EDM_PORT@ dm_transfer_limit=@DM_TRANSPORT_SIZE@ dm_transfer_wait_time=@DM_WAIT_TIME@ is_edm=true',

@DM_SCHDULE_TIME@,


-1,

-1,

@DB_SPECIFIC_DATE@,

'F');

insert into scheduled_task(task_name, clsid, args, period_minutes, at_time_hrs, at_time_minutes, start_time, deleted )

values ('EDM_ETL',

'com.oatsystems.etlclient.InitiateETLTask',

'',

60,

-1,

-1,

@DB_SPECIFIC_DATE@,

'F');

Following are variables that need to be replaced before running the script:

@INSTALL_DIR@ - <Directory where EA is installed. For example, C:/OATea>

@EDM_HOST@ - <Host name of server where EDM is installed>

@EDM_PORT@ - <Port number where EDM is running>

@DM_TRANSPORT_SIZE@ - <Maximum size of data (in bytes) to be send from EA to EDM at a time. For example, 100000>

@DM_WAIT_TIME@ - <Waiting time (in seconds) before sending the next packet of data, when the data to be sent exceeds @DM_TRANSPORT_SIZE@. For example, 10>

@DM_SCHDULE_TIME@ - <Time interval (in minutes) between 2 scheduled data synchronizations from EA to EDM>

@DB_SPECIFIC_DATE@ - <SQLServer - getdate(); Oracle - sysdate; DB2 - CURRENT TIMESTAMP>

2. Edit ofs/configure.properties in EA installation to add the EDM host and port values as follows:

OATAXIOM_SERVER=<Host name of server where EDM is installed>

OATAXIOM_PORT=<Port number where EDM is running>



3. Run the deploy.bat with ofs/bin/deploy ‐f command.


CHAPTER 16 Migrating from standalone to Enterprise ‐ managed OATxpress

Introduction An OATxpress server can be installed as a standalone or as an EA‐managed server, as described in the ʺOFS Deploymentsʺ section. The standalone option is preferable for pilots and limited production systems because it reduces the overheads of installing and managing the OAT Enterprise Administrator. The EA‐managed option is better for wider rollouts because it enables centralized administration. This is also a pre‐requisite to gather and analyze OATxpress data centrally using the OAT Enterprise Data Manager.

When a pilot or limited production system based on a standalone OATxpress is expanded to a wider rollout, an administrator might wish to integrate a standalone OATxpress with the newly installed Enterprise Administrator. One option is to re‐create the standalone OATxpress configuration (like locations, products and devices) in a new EA‐managed OATxpress. However, the transactional data such as objects (EPCs) and object associations collected by the standalone OATxpress will be lost during this process.


Migrating from standalone to Enterprise - managed OATxpress

This chapter describes an alternate method to convert a standalone OATxpress server to an EA‐managed server, while preserving transactional data in OATxpress database. The limitations of this process are noted in respective steps.

For information on basic software and hardware requirements, see Chapter 2: First Steps in Installation.

PrerequisitesObserve the following prerequisites before migration:

• Login to the application when required.• All the running scenarios need to be stopped to avoid unexpected errors.

Migrating to Enterprise ‐ managed OATxpressPerform the following steps to migrate from a standalone OATxpress to Enterprise ‐ managed OATxpress server:

• Add a new OATxpress on EA • Change the OATxpress ID and name • Export master data from standalone OATXpress • Upload locations to EA • Upload products to EA • Save configuration • Change user management • Configure OATxpress with EA and EDM • Remove master data from OATXpress • Reload configuration and restart• EDM data migration


Add a New OATxpress on EA

To add a new OATxpress on EA:

1. Add a new OATxpress server on EA as explained in Chapter 4: Streamlining Deployment across your Organization of the OAT Enterprise User Guide. Refer to the section Adding Servers for more details.

Note the following details while adding a new server:

• The server name must be the same as the standalone OATxpress installation name.

• Obtain the server name from senseware.id property from ofs/conf/savant.properties.

• OFS does not support modification of an existing Enterprise‐managed OATxpress server, but only converts a new standalone with modifications to EA, after deleting the existing one.

2. Add a Site for this Server to import locations as explained in the following‐steps.

3. If you have Asset Tracking and any custom metadata deployed on OATx‐press, repeat the same on EA, in order to import the metadata correctly.

4. Divide the project OAT Archive (OAR), into two OARs as given below, r to avoid unnecessary and unwanted changes on EA: • For EA (mainly metadata)• For OATxpress (full)

Change the OATxpress ID and Name (optional)

The standalone OATxpress server name and server ID must be unique. If your OATxpress server ID or name conflicts with another OATxpress server already on EA, change them as explained below:

1. Navigate to the file location where the OATxpress is installed.

Note: If you are migrating multiple standalone OATxpress to EA, then make sure that the location name of each standalone OATxpress is unique within the site.

2. Open ofs/conf/savant.properties. 3. Replace the value of property name ‘senseware.id’ with the name used in the

previous step to change the server ID and name.

Note: The steps expalined above should be performed on OATxpress, not on EA.



Export Master Data from Standalone OATxpress.

To export master data from standalone OATxpress:

Note:

• Locations having either EPCIS_ID or GLN are required for exporting. • If you are migrating multiple standalone OATxpress to EA, then make

sure that location name of each standalone OATxpress is unique across all OATxpress servers managed by the Enterprise Administrator.

1. Click Start ‐‐ > Run. The Run dialog box appears.2. Navigate to the command prompt as shown below:

FIGURE 254. The Run Dialog Box

3. Type the command given below at the prompt to export master locations from OATxpress:locationexport ‐fileName [locationXML]

4. Type the command given below at the prompt to export product location from OATxpress:productexport [productXML]

Note:

• Obtain the above locationexport and productexport batch files at $OATxpress/ofs/bin.

• Asset types from different OATxpress servers must be compatible .


Upload Locations to EA To upload locations to EA:

1. Execute the masterdataupload script on $OATEA/ofs/bin.2. Type the command given below at the prompt:

masterdataupload ‐type location ‐fileName [locationXML] ‐site [SiteName]

Note:

• site option specifies the parent site to which the locations are assigned to.

Upload Products to EA To upload products to EA:

1. Execute the masterdataupload or productupload scripts on $OATEA/ofs/bin.

2. Type any one of the command below at the prompt:masterdataupload ‐type product ‐fileName [productXML] –server [Server‐Name]ORproductupload ‐fileName [productXML] ‐server [ServerName]

Note:

• The –server option specifies the OATxpress server to which the products are assigned to.

• Use ʹ*ʹ as wildcard assignment to all known OATXpress servers at the time of product upload.

• If a product has a commissioning range defined in both EA and the product XML, make sure that they do not overlap at the time of product import.

• You can solve the above issue by removing the offending range from the product XML file, so that OATxpress can retrieve a new range from EA.



Save Configuration To save the configuration:

1. Click Configuration on OATxpress.2. Enter a name for the configuration and click Save.

Note:

• The steps explained above should be performed on OATxpress, not on EA.

• If you have changed the server name or server ID, it is mandatory to save the same to a new template. Even if you havenʹt changed the server name or server ID, it is recommended that you save the configuration.

Change the User Management Service

To change the user management service:

1. Navigate to the file location where the OATxpress is installed. 2. Open ofs/config/savant.properties. 3. Search for “services.site=....,UserManagementDefaultServices,....”4. Replace this with “services.site=....,UserManagementSiteServices,....”

Note:

• The above steps are performed to replace the default to EA ‐ managed User Management Service.

• If there are any existing users created on OATxpress, then the same needs to be recreated on EA.

Configure EA and EDM on Standalone OATxpress

To configure EA and EDM:

1. Navigate to ofs/config.properties and modify the information on EA and EDM servers accordingly. See the field descriptions below:

For EA:

CCS_SERVER_ENABLED=TRUE

CCS_SERVER_SYNC_ON_STARTUP=FALSE

CCS_SERVER_NAME=<EA server name>

CCS_SERVER_HOST=<IP address of the EA server>

CCS_SERVER_PORT=<Port number of EA server>


For EDM:

EDM_SERVER_HOST=<IP address of the EDM server>

EDM_SERVER_PORT=<Port number of EDM server>

DM_DATA_COMPRESSION_ENABLED=TRUE

DM_PUSH_MODE= YES

DM_TRANSPORT_SIZE=<Size of data to be synchronized>

DM_WAIT_TIME=<Waiting time before transferring next data block>

DM_SCHDULE_TIME=<Time at which data migration starts>

Note:

• The boolean values given for the above properties may change accordingly based on the requirement.

• If you have changed the server name and server ID as explained in Change the OATxpress ID and Name (optional), then the same needs to be changed in this step as well.OATEDGE_SERIAL_NUMBER=<OATxpress server ID>OATEDGE_NAME=<OATxpress server name>

2. Shutdown OATXpress and run deploy ‐o conf to substitute the new values for EA and EDM. Use the ‐f option, if you have manually changed any of the files in ofs/conf or deployed Asset Tracking.

Mark all Standalone Locations and Products as Deleted

To mark all standalone locations and products as deleted:

1. Remove all the master data created during standalone OATxpress mode.2. Execute the script removemasterdata.bat on $OAT/ofs/bin/. This script does

not take arguments.

Synchronize Master Data To synchronize master data:

1. Restart OATxpress and login to EA.

Note: Ignore any UNDEFINED LOCATION error on this startup.

2. Click Configuration ‐‐ > Servers. 3. Select Synchronize.



Note: Checking the completion of synchronization.

Data migration is asynchronous. You are likely to get a message ʹTime‐out waiting for Master Data Synchronization to complete, it will con‐tinue to run in the backgroundʹ. To check for the completion, periodi‐cally revisit the Servers list page and check for the disappearance of the red asterisk next to the OATxpress server.

Note:

• DO NOT initiate more synchronizations, as this will delay the pro‐cess.

• To check for synchronization error, check the ʹServices at the Site Serverʹ section of the OATxpress Monitoring page.

Reload Configuration and Restart

To reload the configuration:

1. Click Load Configuration to reload the saved CMS template.

Note: A server restart is recommended.

Restart the stopped scenario.

EDM Data Migration

To migrate EDM data:

1. Schedule the EDM data migration when you add the OATxpress server on EA.

2. Select the data that need to be migrated.3. If an EDM was already present and the OATxpress server had migrated data

to EDM, then enable all the data categories (EPC Context, Summary, etc.).The OATxpress server migrates all data categories to EDM if there is no EA.

Note: Enabling only a few data categories will not cause any errors. Tables for the disabled categories will no longer be migrated. However, re‐enabling the categories after migrating some data may cause data inconsisitencies. Hence, it is not advisable to re‐enable the categories.


SECTION V

Uninstallation



CHAPTER 17 Uninstalling the OAT Enterprise Data Manager

Introduction The chapter describes the steps to be followed for uninstalling the OAT Enterprise Data Manager.

To uninstall the OAT Enterprise Data Manager running on Windows, run the Uninstaller and then delete the OAT Enterprise Data Manager installation directory. The Uninstaller does not delete the database instances in an SQL Server database.

To uninstall the OAT Enterprise Data Manager from a server running Linux, you need to delete the OAT Enterprise Data Manager installation directory ( run the uninstaller script as mentioned below to delete).


Uninstalling the OAT Enterprise Data Manager

Uninstalling OAT Enterprise Data Manager on WindowsTo uninstall OAT Enterprise Data Manager running on Windows:

1. Stop OAT Enterprise Data Manager, if it is running.2. From the Start menu, click All Programs ‐‐> OAT Enterprise Data Man‐

ager ‐‐> Uninstall OAT Enterprise Data Manager.The Uninstall OAT Enterprise Data Manager screen appears.

FIGURE 255. The Uninstall OAT Enterprise Data Manager Screen

3. Click Uninstall to launch the process.


FIGURE 256. The Uninstall OATenterprise Screen

FIGURE 257. The Service Removal Dialog Box



4. Click OK on the Service removal dialog.

FIGURE 258. The Uninstall Complete Screen

5. Select:• Yes, to restart the system immediately.• No, to restart the system later.

6. Upon completion, click Done.In Windows Explorer, delete the OAT installation directory.

The uninstallation program deletes only what the installation program installed, so files acquired since installation (log files, compiled JSP files, etc.) remain and prevent the installation directory from being deleted.


Uninstalling OAT Enterprise Data Manager on Linux1. Stop the OAT Enterprise Data Manager server, if it is running.2. Run:

<OAT_Install_Dir>/Uninstaller/Uninstall_OATenterprise

where OAT_Install_Dir is the OAT Enterprise Data Manager installation directory.




CHAPTER 18 Uninstalling the OAT Enterprise Administrator

Introduction To uninstall OAT Enterprise Administrator running on Windows, run the Uninstaller and then delete the OAT Enterprise Administrator installation directory. The Uninstaller does not delete the database instances in an SQL Server database.

To uninstall OAT Enterprise Administrator from a server running Linux, delete only the OAT Enterprise Administrator installation directory by running the uninstaller script as mentioned below.

Uninstalling OAT Enterprise Administrator on WindowsTo uninstall OAT Enterprise Administrator running on Windows:

1. Stop the OAT Enterprise Administrator, if it is running.2. From the Start menu, click All Programs ‐‐> OAT Enterprise Administra‐

tor ‐‐> Uninstall OAT Enterprise Administrator.The Uninstall OAT Enterprise Administrator screen appears.


Uninstalling the OAT Enterprise Administrator

FIGURE 259. The Uninstall OAT Enterprise Administrator Screen







4. Click Ok on the Service removal dialog.


5. Select:• Yes, to restart the system immediately.• No, to restart the system later.

6. Upon completion, click Done.In Windows Explorer, delete the OAT installation directory.



Uninstalling OAT Enterprise Administrator on Linux1. Stop the OAT Enterprise Administrator server, if it is running.2. Run:


where OAT_Install_Dir is the OAT Enterprise Administrator installation directory.




CHAPTER 19 Uninstalling the OATxpress Server

Introduction To uninstall an OATxpress server, you need to run the OATenterprise uninstaller and then delete the OATxpress installation directory. The uninstaller does not delete the oatdb database instance in an Oracle or SQL Server database.

To uninstall OATxpress server running on Linux, you need delete only the OATxpress installation directory by running the uninstaller script as mentioned below.

Uninstalling OATxpress on Windows1. Stop the OATxpress server, if it is running.2. From the Start menu, click All Programs ‐‐> OATxpress ‐‐> Uninstall OATx‐

press.The Uninstall OATxpress screen appears.


Uninstalling the OATxpress Server

FIGURE 263. The Uninstall OATxpress Screen







Click Ok on the Service removal dialog. The Uninstall Complete screen appears.


4. Select:• Yes, to restart your system immediately.• No, to restart your system later.

5. Upon completion, click Done and, delete the OAT installation directory.



Uninstalling OATxpress on Linux1. Stop the OATxpress server, if it is running.2. Run:


where OAT_Install_Dir is the installation directory for OATxpress server.

Uninstalling OATxpress on UbuntuFollow the same procedure used for Linux as outlined in the previous section.




SECTION VI

Appendices



APPENDIX A Installation Knowledge Base

IntroductionThis section describes the fine tuning and checks you can perform post installation.

Log files to be checked

Installation with Apache Tomcat Web Server

setup.log This can have errors only in the database delete section. There should not be any other error messages in this file.

prepareDefault.log There should not be any errors in this file.

deploy_details.log There should not be any errors in this file.


Installation with IBM WebSphere

setup.log This can have errors only in the database delete section. There should not be any other error messages in this file.

prepareDefault.log There should not be any errors in this file.

deploy_details.log This file can display timeout exceptions like

org.apache.soap.SOAPException: [SOAPException: faultCode=SOAP‐ENV:Client; msg=Read timed out; targetException=java.net.SocketTimeou‐tException: Read timed out] if sufficient resources (cpu usage, heap memory for AppServer during install). If it is there, after install run ʺdeploy ‐fʺ from ofs\bin directory

websphere.log This log file can display errors in the AppServer start section, if the AppServer is not running during install.

Installation involving DB2 as DB Type

Need to check <OATenterprise_Install_Dir>\setup\*.out files:

There should not be any errors in these files.

Service NamesLinux Service Names:

OAT Enterprise Data Manager => oatedm

OAT Enterprise Administrator => oatadmin

OATxpress Server => oatxpress


WebSphere ClassLoaderAppServer Parent First

Application Level OFS_OAT Enterprise Administrator => Parent Last

OFS_OATxpress Server => Parent Last

OFS_OAT Enterprise Data Manager => Parent Last

Module Level axis.war => Parent Last

oatedge.war => Parent Last

oatenterprise.war => Parent First

Other WAS Settings on AppServer to be Checked

ClassPath => <OATInstallDir>\ofs\conf

Heapsize => Min and Max both at least 1024m

JIT => has to be disabled

JDBC Provider: Senseware is available only on the JDBC provider for JNDI. OFS does not support more than one DB type on a WAS node.

Note: These settings can all be found and modified using the WebSphere Admin Console Web User Interface.



APPENDIX B OAT Foundation Suite Security

WebApp Security

User Authentication

All users accessing the system via a browser are required to authenticate using unique username/password login.

Each user has an assigned role that determines his/her permissions with respect to WebApp resources. Attempts to access resources for which the user does not have permission will result in redirection to a permissions violation page. Only a user with administrator permissions will be able to assign or change roles.

The model‐view‐controller architecture of the WebApp prevents access to site resources through any channel other than the controller. Attempts to bypass permission checks through URL manipulation will fail; relative paths to files and directories will not resolve. All links are URL encoded (session maintenance depends on URL encoding, not on cookies) and route to the controller.


There are two options for managing user authentication:

• Default authentication (username/password are created and managed under the purview of OFS install)

• External authentication (username/password are created and managed in an external system such as an LDAP database)

Default Authentication

By default, passwords created in OFS expire after 90 days, and the user is prompted to update his or her password during the 14 days before expiration. Both these periods are configurable in jakarta‐tomcat‐5.5.28\webapps\oatedge\WEB‐INF\classes\app_properties.properties (PASSWORD_EXPIRES_IN_DAYS=90, PASSWORD_WARNING_IN_DAYS=14).

External Authentication

Specifying the “external authentication” option at installation will set up the authentication of users against an LDAP database. This is done by configuring the following files:

Tomcat:

• ldap_msad.conf: com.oatsystems.um.url=ldaps://<AD IPaddress>:<AD SSLport>

WebSphere:

• wsjaas.conf: com.oatsystems.um.url=ldaps://<AD IPaddress>:<AD SSLport>

Also required is the configuration of a valid key entry based on a certificate exported from the active directory server keystore for import into the client keystore (Note: only one key is required for all SSL‐secured services; this key may be self‐signed if the customer wishes) in the file: ofs\conf\ofsserver.jks


When a user is authenticated by the external system, but is unknown to the OAT installation, a new user account is created in OAT and made available to all servers in the installation in case the external authentication system is not accessible at some point in the future. Information to authenticate the user is stored securely in OFS with one way hashed encryption; the LDAP browsing user password is stored with 2‐way encryption only if OFS users want to log in based on their account names, not by Creator Name (CN).

Note the following details about external authentication of LDAP server:

• When the user logs into OAT EA or OATxpress, the OFS database stores the user details and password details. If the password cache is disabled, then password details will not be cached, but only the user details will be cached in OFS database.

• LDAP authenticated user details cannot be changed from OAT Enterprise Administrator. The roles of the user can be changed from EA.

• If a user is disabled or deleted in LDAP server, then these changes will not get reflected in OFS automatically. OFS administrator has to disable or delete the user from EA admin console. If the user tries to login to OFS when LDAP Server and EA are connected to each other, then the changes in LDAP server gets reflected in OFS also.

Enterprise Administrator-to-OATxpress Redirect Authentication

When a user who is already logged in to the OAT Enterprise Administrator navigates using the browser to a particular OATxpress server, he/she is authenticated by means of an encrypted token. This expires after a specified time or after logging out from the OAT Enterprise Administrator. By design, if the URL is cut and pasted into another browser prior to loggin out from the OAT Enterprise Administrator, it will function.


Input Data

All input is validated before being stored or used. Special characters that could be used to enter active content through the User Interface (<, >, ʺ, ʹ, &) are escaped to prevent such attacks.

SQL queries and updates that contain input data are executed through parameterized statements, which prevents concatenation of malicious commands.

Transactionality is enforced for all persistence of User Interface input, and the user is informed in each case of success or failure (rollback); User Interface input will not leave the system in an ambiguous state.

Audit Trail

Security‐related events driven by user activity in the WebApp are logged, together with user id, timestamp and a pointer to event detail, to an audit log. These events include:

Logged at WARN level:

• Failed login (wrong password; or, account invalid; expired; inactive)• Failed permission check• Unknown event submission (indicates URL modification)

Logged at INFO level:

• Login• Modification of role permissions• Modification of a user role• Password change• Configuration operation (create/edit location; device; filter; queue; logger;

etc.)

The amount of information logged can be configured by an administrator in the file ofs\conf\log4j‐raf.properties via normal log4j configuration steps.


Secure Transport for Tomcat

WebApps on OAT Enterprise Data Manager, OATxpress servers, and OAT Enterprise Administrator can all be configured to run over HTTPS rather than HTTP. This configuration can be set through the OATenterprise installer by specifying the HTTPS option and providing two port numbers, one for browsing, and another for Web services. For browsing, this results in configuration of the following: app_properties.properties (for webapp code): SSL_ENABLE=true, SSL_PORT=(port for HTTPS browsing).

TOMCAT: in jakarta‐tomcat‐(ver)\conf\server.xml:

• Define a Connector for HTTPS browsing (already defined, just specify port number)

• Comment out Connector for unsecure HTTP browsing

Note: JVM properties pointing to keystore file are already defined in ofs\conf\oat_startup.properties

Secure Transport for WAS Follow the steps below to configure HTTPS on WAS for both browser access and Web services.

1. Use the Java keytool to create two keystore files for client and server; self‐certify, export certificate and exchange/import certificate for both client and server keystores.

Note: OFS provides only a single keystore file ofsserver.jks for both client and server; this works everywhere except on WAS when the client is inside one WebApp (e.g. oatdege.war) and the server is inside another WebApp (e.g. axis.war). For WAS, two separate keystore files for client and server are required; and each should trust the otherʹs certificate.

2. In WAS administration console, Security ‐‐> SSL, create two new JSSE reper‐toires.• The first JSSE repertoire, for browsing (for example,

ofs_HTTPS_browsing), should have client authentication disabled.• The second JSSE repertoire, for Web services (for example,

ofs_HTTPS_webservice), should have client authentication enabled.• Remaining configuration for both repertoires is identical: JSSE provider is

IBMJSSE2, protocol is SSL_TLS; the key file and the trust file should both point to the server keystore file with trusted client certificate.


3. In the WAS administration console, navigate to Servers ‐‐> Application Server ‐‐> server1 (follow appropriate server name) ‐‐> Web Container Set‐tings ‐‐> Web Container Transport Chains, and create two new transport chains. (If an SSL transport chain has already been created for the OFS HTTPS browsing port, for example, 9443, it is only necessary to create one more transport chain for OFS HTTPS Web service port, for example, 9543).• Both transport chains should be based on the SSL‐enabled transport

chain template with security enabled. The first one should specify the HTTPS browsing port (for example, 9443), and its ʺSSL Inbound Channel (SSL_2)ʺ should specify the JSSE repertoire for OFS HTTPS browsing for example, ofs_HTTPS_browsing; see step 2). The second one should specify the HTTPS Web service port (for example, 9543), and its ʺSSL Inbound Channel (SSL_2)ʺ should specify the JSSE repertoire for OFS HTTPS Web service (for example,. ofs_HTTPS_webservice; see step 2).

• HTTPS browsing port and taps Web service port should match the port numbers specified during installation, when enabling HTTPS.

4. In the WAS administration console, Environment ‐‐> Virtual Hosts ‐‐> Default Host ‐‐> Additional Attributes ‐‐> Host Aliases, create entries for both OFS HTTPS browsing port (e.g. 9443) and OFS HTTPS Web service port (for example, 9543).

5. In the WAS administration console, navigate to Servers ‐‐> Application Server ‐‐> server1 (follow appropriate server name) ‐‐> Server Infrastructure ‐‐> Java and Process Management ‐‐> Process Definition ‐‐> Additional Prop‐erties ‐‐> Java Virtual Machine, and add the following into Generic JVM arguments:• ‐Djavax.net.ssl.keyStore=<OAT_Install_Dir>\ofs\conf\client.jks ‐

Djavax.net.ssl.keyStorePassword=apollo• ‐Djavax.net.ssl.trustStore=<OAT_Install_Dir>\ofs\conf\client.jks ‐

Djavax.net.ssl.trustStorePassword=apollo

Note: client.jks should be the keystore file for client with trusted server certificate; change the keystore file path and password to reflect correct local values.

6. Save the changes and restart WAS.

Also required is the configuration of a valid key entry (Note: only one key is required for all SSL‐secured services; may be self‐signed if the user wishes) in the file: <OFS_Install_Dir>\ofs\conf\ofsserver.jks.



Database SecurityAll databases are protected with an encrypted password (stored with 2‐way encryption).

RMI SecurityRMI services can be configured to run over SSL. This configuration can be set in the savant.properties file:

• savant.properties: rmi.security.enable=true

Also required is the configuration of a valid key entry (Note: only one key is required for all SSL‐secured services and it may be self‐signed if the user wishes) in the file:

• ofs\conf\ofsserver.jks

Also, secure RMI authentication is two‐way, which means that client applications will require their own valid key entry in their own keystore files. The exported public certificate from the client keystore must be imported into ofs\conf\ofsserver.jks, and the exported public certificate from ofs\conf\ofsserver.jks must be imported into the client keystore.


JMS SecurityJMS services can be configured to run with ActiveMQ username/password authentication; OFS integrates a JAAS plugin so that the normal OFS username/password can be used for this purpose. This configuration can be set in the savant.properties file:

• savant.properties: jms.broker.secure=true

Note: There is no requirement to run JMS over SSL, but if it were required for a site it is supported for ActiveMQ and should not require any changes in OFS outside the appropriate configuration of ActiveMQ files and the provision of the appropriate keystore/certificates (should be unified with <OAT_Install_Dir>\ofs\conf\ofsserver.jks). See: http://activemq.apache.org/how‐do‐i‐use‐ssl.html.

Web Service SecurityWeb service security is provided via the Apache Rampart 1.3 (Axis2 1.3) WS‐Security implementation; when enabled, SOAP messages will be built with a timestamp, User Token for authentication, digital signature and encrypted message body.

WS‐Security for all services can be set in the axis2.xml and savant.properties files:

• <OAT_Install_Dir>\jakarta‐tomcat‐5.5.28\webapps\axis\WEB‐INF\conf\axis2.xml: <module ref=ʺrampartʺ/> is uncommented; engages Rampart globally for all Web services

• savant.properties: soap.security.enable=true, soap.client.context.enable=true; enables Rampart engagement for all Web service clients

WS‐Security for individual services can be enabled by the user thus:

1. Confirm that <module ref=ʺrampartʺ/> is commented out in <OAT_Install_Dir>\jakarta‐tomcat‐5.5.28\webapps\axis\WEB‐INF\conf\axis2.xml

2. Confirm that soap.security.enable=false in savant.properties 3. Start OFS server


4. Navigate to http://host:port/axis/axis2‐admin/5. Login (admin/axis2)6. Engage Rampart for the particular service in question

The client code of security‐enabled Web services must follow these rules:

• must extend AbstractWebServiceClient• must invoke setSecurityEnabled(true) before SOAP method invocation• if client uses generated stub, it must invoke setClientOptions(stub, true)

instead of setClientOptions(stub)

The password call back handler class com.oatsystems.ws.security.PWCB‐Handler (located in ofs‐util‐ws module) can be customized to provide appropriate password authentication logic for a given solution.

Besides supporting WS‐Security for message encryption, OFS also supports HTTPS for Web service transport encryption (whereas HTTPS for browsing would only require one‐way authentication, HTTPS for Web services requires two‐way authentication). As described earlier, this configuration can be set through the OATenterprise installer by specifying the HTTPS option and providing two port numbers, one for browsing, and another for Web services. For Web services, this results in configuration of the following:

TOMCAT: in jakarta‐tomcat‐(ver)\conf\server.xml:

1. Define a Connector for Web services (already defined; just specify port num‐ber)

2. Comment out Connector for unsecure HTTP access (this should have been done while changing port for browsing)

Note: JVM properties pointing to keystore file are already defined in ofs\conf\oat_startup.properties

On the WAS administrative console:

3. Under Security ‐‐> SSL: create repertoire for Web services, with client authentication ENABLED

4. Under Servers ‐‐> Application Servers ‐‐> server1 ‐‐> Web container setting ‐‐> Web container transport chains: create transport chain with SSL enabled on the port for HTTPS Web services


5. Under Environment ‐‐> Virtual Host ‐‐> default_host ‐‐> Host Aliases: make sure that entry for port for HTTPS Web services exists, and create it if it does not.

6. Under Servers ‐‐> Application Servers ‐‐> server1 ‐‐> Java and Process Man‐agement ‐‐> Process Definition ‐‐> Java Virtual Machine: add JVM startup properties ‐Djavax.net.ssl.key‐Store=<OAT_Install_Dir>\ofs\conf\ofsserver.jks ‐Djavax.net.ssl.keyStore‐Password=apollo ‐Djavax.net.ssl.trustStore=<OAT_Install_Dir>\ofs\conf\ofsserver.jks ‐Djavax.net.ssl.trustStorePassword=apollo

7. Disable unsecure HTTP port in the Transport Chain and Virtual Host pages (should have been done while changing port for browsing)

Also required is the configuration of a valid key entry (Note: only one key is required for all SSL‐secured services; may be self‐signed if the user wishes) in the file: <OAT_Install_Dir>\ofs\conf\ofsserver.jks

Again, if HTTPS is configured for one server in the OFS deployment hierarchy it must be configured for all since it is not possible to mix HTTPS‐enabled with HTTP‐only servers.

Notification Service

The OFS Notification Service client requires a different Web Service Security Configuration from the internal OFS clients. Therefore you need to set the configuration in the notification_wss properties file present in the OFS/conf folder. The OFS Notification will use this configuration to send a notification to all recipients registered on a particular topic. Definition in the properties file is different for non‐.Net and .NET recipients.


Non-.NET Recipients

Define Inflow and Outflow parameters in the notification_wss.properties file for non‐.NET recipients. Following is the default notification_wss.properties file:

# WS-Security Inflow Configurationwssec.client.inflow.property.ct=4wssec.client.inflow.property.0.key=ActionItemswssec.client.inflow.property.0.value=Timestamp Signature Encryptwssec.client.inflow.property.1.key=PasswordCallbackClasswssec.client.inflow.property.1.value=com.oatsystems.ws.secu-rity.PWCBHandlerwssec.client.inflow.property.2.key=SignaturePropFilewssec.client.inflow.property.2.value=client.propertieswssec.client.inflow.property.3.key=EnableSignatureConfirmationwssec.client.inflow.property.3.value=false

# WS-Security Outflow Configurationwssec.client.outflow.property.ct=9wssec.client.outflow.property.0.key=ActionItemswssec.client.outflow.property.0.value=Timestamp Signature Encryptwssec.client.outflow.property.1.key=PasswordCallbackClasswssec.client.outflow.property.1.value=com.oatsystems.ws.secu-rity.PWCBHandlerwssec.client.outflow.property.2.key=SignaturePropFilewssec.client.outflow.property.2.value=client.propertieswssec.client.outflow.property.3.key=EnableSignatureConfirma-tionwssec.client.outflow.property.3.value=falsewssec.client.outflow.property.4.key=Userwssec.client.outflow.property.4.value=ofsclientwssec.client.outflow.property.5.key=SignatureKeyIdentifierwssec.client.outflow.property.5.value=DirectReferencewssec.client.outflow.property.6.key=EncryptionKeyIdentifierwssec.client.outflow.property.6.value=SKIKeyIdentifierwssec.client.outflow.property.7.key=EncryptionUserwssec.client.outflow.property.7.value=dotnetserverwssec.client.outflow.property.8.key=SignaturePartswssec.client.outflow.property.8.value={Element}{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd}Timestamp;{Element}{}Body


WS‐Security Inflow Configuration

Parameters for the inflow configuration are used to configure the inflow secu‐rity handler. Following is a description of the parameters with examples for each:

WS‐Security Outflow Configuration

Parameters for the outflow configuration are used to configure the outflow security handler. Following is a description of the parameters with examples for each:

TABLE 1. Parameters for Inflow Configuration

Parameter Description Example

items Security actions for the inflow First the incoming message should be decrypted and then the signatures should be verified and checked for the availability of the Timestamp: <items> Timestamp Signature Encrypt</items>

passwordCallbackClass Callback class used to obtain pass‐word for decryption and Username‐Token verification

<passwordCallbackClass>org.apache.axis2.secu‐rity.PWCallback</passwordCallbackClass>

signaturePropFile Property file used for signature veri‐fication

<signaturePropFile> sig.properties</signature‐PropFile>

decryptionPropFile Property file used for decryption <decryptionPropFile> dec.properties</decryp‐tionPropFile>

TABLE 2. Parameters for Outflow Configuration

Parameter Description Example

items Security actions for the outflow Add a Timestamp, Sign the SOAP body and Encrypt the SOAP body <items> Timestamp Sig‐nature Encrypt</items>

user The userʹs name Set alias of the private key to be used to sign <user> bob</user>


passwordCallbackClass Callback class used to provide the password required to create the UsernameToken or to sign the mes‐sage

<passwordCallbackClass> org.apache.axis2.security.PWCallback</pass‐wordCallbackClass>

signaturePropFile property file used to get the signa‐ture parameters such as crypto pro‐vider, keystore and its password.

Set example.properties file as the signature property file <signaturePropFile> example.prop‐erties</signaturePropFile>

signatureKeyIdentifier Key identifier to be used in referring the key in the signature

Use the serial number of the certificate <signa‐tureKeyIdentifier> IssuerSerial</signatureKeyI‐dentifier>

encryptionKeyIdentifier Key identifier to be used in referring the key in encryption

Use the serial number of the certificate <encryp‐tionKeyIdentifier>IssuerSerial</encryptionKeyI‐dentifier>

encryptionUser The alias of the public key in the cer‐tificate to use for encryption

<encryptionUser>alice</encryptionUser>

encryptionSymAlgo‐rithm

Symmetric algorithm to be used for encryption

Use AES‐128 <encryptionSymAlgorithm>http://www.w3.org/2001/04/xmlenc#aes128‐cbc </encryptionSymAlgorithm>

encryptionKeyTranspor‐tAlgorithm

Key encryption algorithm Use RSA‐OAEP <parameter name=ʺencryption‐SymAlgorithmʺ>http://www.w3.org/2001/04/xmlenc#rsa‐oaep‐mgf1p </parameter>

signatureParts Sign multiple parts in the SOAP message

Sign Foo and Bar elements qualified by http://app.ns/ns <signatureParts> {Element}{ http://app.ns/ns\ }Foo;{Element}{http://app.ns/ns\ }Bar </signatureParts>

optimizeParts MTOM Optimize the elements speci‐fied by the XPath query

Optimize the CipherValue <optimizeParts> //xenc:EncryptedData/xenc:CipherData/xenc:CipherValue </optimizeParts>

TABLE 2. Parameters for Outflow Configuration


NET Recipients

Define Inflow and Outflow parameters in the notification_wss.properties file for .NET recipients. Open the notification_wss.properties in %OFS_ROOT%\ofs\conf folder and REPLACE the existing properties with the following:

# WS-Security Inflow Configurationwssec.client.inflow.property.ct=4wssec.client.inflow.property.0.key=ActionItemswssec.client.inflow.property.0.value=Timestamp Signature Encryptwssec.client.inflow.property.1.key=PasswordCallbackClasswssec.client.inflow.property.1.value=com.oatsystems.ws.secu-rity.PWCBHandlerwssec.client.inflow.property.2.key=SignaturePropFilewssec.client.inflow.property.2.value=client.propertieswssec.client.inflow.property.3.key=EnableSignatureConfirmationwssec.client.inflow.property.3.value=false

# WS-Security Outflow Configurationwssec.client.outflow.property.ct=9wssec.client.outflow.property.0.key=ActionItemswssec.client.outflow.property.0.value=Timestamp Signature Encryptwssec.client.outflow.property.1.key=PasswordCallbackClasswssec.client.outflow.property.1.value=com.oatsystems.ws.secu-rity.PWCBHandlerwssec.client.outflow.property.2.key=SignaturePropFilewssec.client.outflow.property.2.value=client.propertieswssec.client.outflow.property.3.key=EnableSignatureConfirma-tionwssec.client.outflow.property.3.value=falsewssec.client.outflow.property.4.key=Userwssec.client.outflow.property.4.value=ofsclientwssec.client.outflow.property.5.key=SignatureKeyIdentifierwssec.client.outflow.property.5.value=DirectReferencewssec.client.outflow.property.6.key=EncryptionKeyIdentifierwssec.client.outflow.property.6.value=SKIKeyIdentifierwssec.client.outflow.property.7.key=EncryptionUserwssec.client.outflow.property.7.value=dotnetserverwssec.client.outflow.property.8.key=SignaturePartswssec.client.outflow.property.8.value={Element}{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd}Timestamp;{Element}{}Body


WS‐Security Inflow Configuration

Parameters for the inflow configuration are used to configure the inflow security handler. For details see Parameters for Inflow Configuration for non‐.NET recepients.

WS‐Security Outflow Configuration

Parameters for the outflow configuration are used to configure the outflow security handler. For details see Parameters for Outflow Configuration for non‐.NET recepients.

Following is a description of the outflow parameters that are different for .NET recepients:

• Set SignatureKeyIdentifier to ʺDirectReferenceʺ to make OFS client work with .NET server

•• Set EncryptionUser to dotnetserver instead of ofsserver, which is the alias

for the dotnetserver certificate in ofsclient.jks. • SignatureParts are required for .NET

Web Service Security for WAS

The Rampart WS‐Security implementation relies on the JCE provider ʺBouncycastleʺ (http://www.bouncycastle.org/java.html) for its data encryption/description/signature algorithm. This is included in the OFS Tomcat installation.

In the OFS WAS installation, however, this JCE provider conflicts with the IBM JCE provider, causing OFS login failure. This issue has been overcome by removing the bouncycastle libraries from OFS Web application modules. This solves the login failure problem, but causes secure Web service calls to fail with the error message ʺunsupported encryption or signature algorithm: No such algorithm: http://www.w3.org/2001/04/xmlenc#rsa‐1_5.ʺ


The solution is therefore to install bouncycastle as an IBM JDK extension, as follows:

1. Copy bcprov‐jdk13‐132.jar into the IBM JDK JRE extension folder, for exam‐ple, ʺC:\Program Files\IBM\WebSphere\AppServer\java\jre\lib\extʺ

2. Modify the java.security file in the Java security folder,for example, ʺC:\Pro‐gram Files\IBM\WebSphere\AppServer\java\jre\lib\securityʺ, adding the following line at the end of the ʺList of providers and their preference orders (see above):ʺ section:• security.provider.6=org.bouncycastle.jce.provider.BouncyCastleProvider

3. Restart WAS server.

Keystore Management for SSLNote the following:

• A keystore file can contain n key entries and n trusted certificate entries. The OFS keystore file <OAT_Install_Dir>\ofs\conf\ofsserver.jks will need to contain only one key entry for OFS itself, and 0...n trusted certificate entries, one for each client that communicates with OFS over an SSL‐secured chan‐nel.

• For HTTPS browsing, only one‐way authentication is required, and there‐fore only a server keystore with one key entry is required. However, all other SSL‐secured communication channels require two‐way authentication, and for these it will be necessary to exchange certificates with the keystore files of clients. Note that enabling HTTPS means enabling both HTTPS for brows‐ing and HTTPS for Web services.

• The exchange of certificates for two‐way authentication is symmetrical: a certificate is exported from the server keystore for import into the client key‐store, and a certificate is exported from the client keystore for import into the server keystore.


To create a keystore (say, the server keystore):

FIGURE 267. Command to Create Keystore

To self‐sign the certificate for export:

FIGURE 268. Command to Self‐Sign the Certificate

To export the certificate:

FIGURE 269. Command to Export the Certificate


To import the exported certificate into (client) keystore:

FIGURE 270. Command to Import the Exported Certificate

The above commands use options to allow for scripting; if you are running them manually on the command line, ‐dname and ‐noprompt would be optional.

Ports

TABLE 6. Default Ports in OFS

Product Port Default Number How to Configure

OATxpress server OATxpress server Tomcat admin port (start/stop)

8005 Configurable in server.xml; can be specified at installation

OATxpress server Tomcat HTTPS port


OATxpress server Tomcat HTTPS port: browsing



OATxpress server OATxpress server Tomcat HTTPS port: Web services

8543 Configurable in server.xml

OATxpress server WAS HTTP port

9080 Configurable through WAS console; can be specified at installation

OATxpress server WAS HTTPS port: browsing


OATxpress server WAS HTTPS port: Web services

9543 Configurable through WAS console

OATxpress server SQLServer port

1433 Configurable through SQLServer manager; can be specified at installation

OATxpress server DB2 port

50000 Configurable through DB2 console; can be specified at installation

OATxpress server Ora‐cle port

1521 Configurable through Oracle manager; can be specified at installation

OATxpress server RMI registry port: winsvc

5099 (Used in stopping/starting of OFS services) Configurable through savant.properties

OATxpress server RMI port: workflow engine

6099 Configurable through app_properties.properties, savant.properties




OATxpress server OATxpress server RMI port: monitoring agent

7099 Configurable through savant.properties

OATxpress server RMI port: Software‐AdapterReader

11002 Configurable in database; can be removed entirely via front‐end config

OATxpress server TycoXML device noti‐fication port


OATxpress server TycoXML device com‐mand timeout port


OATxpress server OAT SMX telnet port

18899 Configurable through savant.properties (set to 0 to close)

OATxpress server Tomcat SOAP port


OATxpress server WAS SOAP port


OATxpress server ActiveMQ port

61616 Configurable through activemq.xml, context.xml

OATxpress server ActiveMQ broadcast port (UDP)

6155 Configurable through activemq.xml




OAT Enterprise Administrator OAT Enterprise Administrator Tomcat HTTP port


OAT Enterprise Administrator Tomcat HTTPS port: browsing


OAT Enterprise Administrator Tomcat HTTPS port: Web ser‐vices


OAT Enterprise Administrator WAS HTTPS port


OAT Enterprise Administrator WAS HTTPS port: browsing

9443 Configured through WAS con‐sole; can be specified at instal‐lation

OAT Enterprise Administrator WAS HTTPS port: Web ser‐vices


OAT Enterprise Administrator SQLServer port


OAT Enterprise Administrator DB2 port


OAT Enterprise Administrator Oracle port





OAT Enterprise Administrator OAT Enterprise Administrator RMI registry port: winsvc


OAT Enterprise Administrator RMI port: workflow engine


OAT Enterprise Administrator RMI port: monitoring agent


OAT Enterprise Administrator OAT SMX telnet port

18899 Configured through savant.properties (set to 0 to close)

OAT Enterprise Administrator ActiveMQ port


OAT Enterprise Administrator ActiveMQ broadcast port (UDP)





OAT Enterprise Data Manager OAT Enterprise Data Manager Tomcat HTTP port


OAT Enterprise Data Manager Tomcat HTTPS port: browsing


OAT Enterprise Data Manager Tomcat HTTPS port: Web ser‐vices


OAT Enterprise Data Manager WAS HTTP port


OAT Enterprise Data Manager WAS HTTPS port: browsing


OAT Enterprise Data Manager WAS HTTPS port: Web services


OAT Enterprise Data Manager SQLServer Enterprise DB port


OAT Enterprise Data Manager SQLServer Star DB port


OAT Enterprise Data Manager DB2 Enter‐prise DB port





OAT Enterprise Data Manager OAT Enterprise Data Manager DB2 Star DB port


OAT Enterprise Data Manager Oracle Enter‐prise DB port


OAT Enterprise Data Manager Oracle Star DB port


OAT Enterprise Data Manager RMI registry port: winsvc


OAT Enterprise Data Manager RMI port: workflow engine


OAT Enterprise Data Manager RMI port: monitoring agent


OAT Enterprise Data Manager ActiveMQ port


OAT Enterprise Data Manager ActiveMQ broadcast port (UDP)





Modifying the MQtt port

OFS has three command‐line options to specify the MQtt port number:

install.sh ‐h | ‐‐help | ‐? | ‐Ml <port number> ‐Ms <port number>

‐Ml <port number>: the port number on which the MicroBroker will accept remote connections. Sets Java system property com.ibm.rfid.mbaf.admin.broker.remotePort

‐Ms <port number>: the server port number to which local Microbroker will attempt to connect for communication. Sets Java system property com.oat‐systems.mqtt.server.port

This are the security features available and deployable in the OFS.



APPENDIX C Configuring Files for Products

Introduction The appendix gives details on the xml files the user needs to enter product information for provisioning EPC number to the OFS client.

Using the XML filesProduct and Product attribute definitions can be created and uploaded using the relevant xm files.

Creating and Uploading the ProdAttrDefinition.xml File

The sample files is available at ofs/bin/ProdAttrDefinition.xml. This files should be configures in OATxpress. To create and upload product attribute definitions in the OATxpress database, type the following in a a CommandPrompt.

cd<OAT_install_dir>\ofs\bin

(for example, cd C:\Oatxpress\ofs\bin

createprodattrdefn.bat -fileName ProdAttrDefinition.xml


The product attribute file defines the attribute names and types for all products that can be customized as per the project requirements.

Sample ProdAttrDefinition.xml FileFollowing is a sample ProdAttrdefinition.xml file:

<?xml version="1.0" encoding="UTF-8"?><x:ProductAttributes xsi:schemaLocation="urn:ProdAttrDefinition ../conf/ProdAttrDefinition.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:x="urn:ProdAttrDefinition"><x:Entity name="Product" ><x:Attribute name="Size" display="Size" type="String"/><x:Attribute name="Color" display="Color" type="String"/><x:Attribute name="SalesFloorTarget" display="Sales Floor Target Quantity" type="Integer"/><x:Attribute name="TradeItem" display="TradeItem" type="String" ><x:EnumeratedAttributeValue value="YES"/><x:EnumeratedAttributeValue value="NO"/></x:Attribute><x:Attribute name="ShortDesc" display="Short Description" type="String"/><x:Attribute name="Style" display="Style" type="String"/><x:Attribute name="Department" display="Department" type="String"/><x:Attribute name="Brand" display="Brand" type="String"/><x:Attribute name="Category" display="Category" type="String"/><x:Attribute name="Sub-category" display="Sub-category" type="String"/>


<x:Attribute name="Season" display="Season" type="String"><x:EnumeratedAttributeValue value="Spring"/><x:EnumeratedAttributeValue value="Summer"/><x:EnumeratedAttributeValue value="Fall/Autumn"/><x:EnumeratedAttributeValue value="Winter"/></x:Attribute></x:Entity></x:ProductAttributes>

Description for Components in the ProdAttrdefinition.xmlThe following table provides the description for each component defined in the ProdAttrdefinition.xml file,

TABLE 1.

Display Column Description Mandatory

ProductAttributes Top‐level component for all attributes. This should not be mod‐ified.

Yes

Entity Specifies the product for which the attributes are defined. This should not be modified.

Yes

Attribute Defines attributes associated with the products. There should at least be one attribute in the file. The maximum limit is 100 attributes. NOTE: “Size”, “Color”, “SalesFloorTarget”, and “TradeItem” are mandatory attributes.

Yes

name Name of the attribute. This should not contain spaces.NOTE: The Product extension attribute cannot have an apostrophe (ʹ) in its name. No two attributes can have the same name.

Yes

display Display label for the attribute. The Product Add/Edit page dis‐plays the label of the attribute, not the name.

Yes


Uploading the Product.xml FileTo upload the product in the OATxpress database, type the following in a Com‐mand Prompt:

cd<OAT_install_dir>\ofs\bin

productupload -filename (product.xml) -skuPrefix (company)

(for example, cd C:\OATxpress\ofs\bin)

Sample Product.xml FileFollowing is a sample Product.xml file:

<Manufacturers><ManufacturerexternalIdentifier="FashionGroups"name="HiStyle"/></Manufacturers><Product><ManufacturerRefexternalIdentifier="FashionGroups"/><SKU>78910</SKU><UOM>Item</UOM><StyleCode/><ExternalIdentifier/><Name>BootCutJeans</Name><PackingType/><ProductPureIdentities>

type Defines the type of attribute. This can be one of the following: String, Integer, Double, Date, DateTime.NOTE: Select the date from the pop up calendar for Date Attribute type. Any attribute of the type Date should not have a hyphen (‐) in the attribute name.

Yes

is‐reportable Flag that indicates whether an attribute can be searched or not. No

EnumeratedAttribute‐Value

Specifies the list of valid, enumerated values for an attribute. It is the sub‐component of Attribute.Empty value such as <x:EnumeratedAttributeValue value=ʺ ʺ/> is not supported.

No

TABLE 1.


<GRAI><CompanyPrefix>0044710</CompanyPrefix><AssetType>15003</AssetType><CommissioningRanges><Rangeactive="T"><Start>1</Start><End>10000</End></Range></CommissioningRanges></GRAI></ProductPureIdentities></Product><Product><ManufacturerRefexternalIdentifier="FashionGroups"/><SKU>78911</SKU><UOM>Item</UOM><StyleCode/><ExternalIdentifier/><Name>FormalShirts</Name><PackingType/><ProductPureIdentities><SGTIN><GTIN>04006297111203</GTIN><CompanyPrefixLength>7</CompanyPrefixLength><CommissioningRanges><Rangeactive="T"><Start>1</Start><End>10000</End></Range></CommissioningRanges></SGTIN></ProductPureIdentities></Product><Product><ManufacturerRefexternalIdentifier="FashionGroups"/><SKU>78912</SKU><UOM>Item</UOM><StyleCode/><ExternalIdentifier/><Name>FormalShirt</Name><PackingType/></Product>


<GIAI><CompanyPrefix>0027918</CompanyPrefix><CommissioningRanges><Rangeactive="T"><Start>1</Start><End>10000</End></Range></CommissioningRanges></GIAI></ProductPureIdentities></Product><Product><ManufacturerRefexternalIdentifier="FashionGroups"/><SKU>78921</SKU><UOM>Item</UOM><StyleCode/><ExternalIdentifier/><Name>Corduroys</Name><PackingType/><ProductPureIdentities><USDOD><CAGECode>HH995</CAGECode><CommissioningRanges><Rangeactive="T"><Start>1</Start><End>10000</End></Range></CommissioningRanges></USDOD></ProductPureIdentities></Product><Product><ManufacturerRefexternalIdentifier="FashionGroups"/><SKU>78922</SKU><UOM>Item</UOM><StyleCode/><ExternalIdentifier/><Name>CargoPants</Name><PackingType/><ProductPureIdentities><GID><EPCManager>2684354</EPCManager>


<ObjectClass>16777200</ObjectClass><CommissioningRanges><Rangeactive="T"><Start>1</Start><End>10000</End></Range></CommissioningRanges></GID></ProductPureIdentities></Product><Product><ManufacturerRefexternalIdentifier="FashionGroups"/><SKU>78923</SKU><UOM>Item</UOM><StyleCode/><ExternalIdentifier/><Name>FlannelShirt</Name><PackingType/><ProductPureIdentities><SSCC><CompanyPrefix>0071549</CompanyPrefix><ExtensionDigit>1</ExtensionDigit><CommissioningRanges><Rangeactive="T"><Start>1</Start><End>10000</End></Range></CommissioningRanges></SSCC></ProductPureIdentities></Product></ProductInformation>


Description for Components in the Product.xml FileThe following table provides the description for each component defined in the Product.xml file:

TABLE 2.

Display Column Description Mandatory

Manufacturer Name The company name of the manufacturer; this should be unique among all manufacturers in the database.

Yes

External Identifier A name to use in OATxpress to refer to the manufacturer, which is shorter or more informative than the actual name. This should also be a unique identifier.

Yes

GTIN Company Prefixes Company prefixes allotted to the manufacturer. Yes

Product Name Unique name for the product. Yes

SKU SKU (Stock‐Keeping Unit) assigned to the product. Yes

Style Code Style code for the product Yes

Sites Assigns the OATxpress servers to the product by selecting the OATxpress server

Yes

Tag Encoding Schemes These include SGTIN, SSCC, GID, GRAI, GIAI, DOD, or Custom. Yes

Tag Commissioning Schemes

Commission an EPC range for each scheme assigned to that product.

Yes


APPENDIX D Ubuntu Setup Properties File

Introduction The appendix gives a sample of the Ubuntu Setup Properties File.

Sample of the Ubuntu Setup Properties FileFollowing is a sample of the Ubuntu Setup Properties File:

USER_INPUT_DB_OVERWRITE_RESULTS="yes",""

JVM_MX_HEAP_SIZE_M=1024

JVM_MS_HEAP_SIZE_M=512

USER_INPUT_DB_ENCRYPT=false

USER_INPUT_DB_PASSWD=test

USER_INPUT_SSL=0

USER_INPUT_JMS=0

EXTN=sh

USER_INPUT_DBNAME=XE

USER_INPUT_ENCRYPT=0


USER_INPUT_WEBSERVER_NAME=server1

USER_INPUT_DM_SELECT_RESULTS="","no"

USER_INPUT_ENTERPRISE_SERVER_PORT=9080

USER_INPUT_OATEDGE_SERIAL_NUMBER=0001

TOMCAT_SERVICE_NAME=OATTomcat-SITE

USER_INPUT_DBMS=oracle

WEBSERVER_PORT=9080

USER_INPUT_NEW_APPSERER=no

USER_INPUT_JMS_PROVIDER=Websphere

CHOSEN_DIALOG_BUTTON=0

USER_INPUT_SERVICE_RESULTS=no

USER_INPUT_OATEDGE_PORT=9080

USER_INPUT_SSL_ENABLE=false

USER_INPUT_WS=Tomcat

USER_INPUT_DB_PORT=1521

USER_INPUT_OATEDGE_NAME=oatedge1

USER_INPUT_DB_USER=test

USER_INSTALL_DIR=/home/OATxpress

EPC-IS_VERSION=7.5

USER_INPUT_DB_HOST=localhost

USER_INPUT_SERVER_MODE=SITE

OVERWRITE_DB=yes

INSTALLER_UI=silent

USER_INPUT_ORACLE_INSTALL_DIR=/usr/lib/oracle/xe/app/oracle/product/10.2.0/server

USER_INPUT_ORACLE_INSTALL_DIR_1=/usr/lib/oracle/xe/app/ora-cle/product/10.2.0/server

USER_INPUT_SERVICENAME=XE


USER_INPUT_TOMCAT_SERVER_PORT=8005

USER_INPUT_CCS_SERVER_ENABLED=FALSE

USER_INPUT_TIME_BETWEEN_CONFIG_SYNC=3600

USER_INPUT_CCS_SERVER_SYNC_ON_STARTUP=FALSE

USER_INPUT_I18N=true

SERVER_MODE=SITE



APPENDIX E Configuring WebSphere AppServer and MQ for SOA

Introduction The chapter explains the steps to be followed to configure IBM WebSphere AppServer and MQ to allow OAT SOA to utilize the IBM MQ messaging framework.

Configure WebSphere MQTo use WebSphere MQ as the messaging framework (JMS vendor) for OAT SOA integration, set up the appropriate Queue Manager and Queues in WebSphere MQ. Only two queues are required for OAT Foundation Suite SOA integration.


Queue Manager

If a Queue Manager exists, it is not necessary to create a new one. However, a dedicated Queue Manager enhances manageability. The naming convention for OAT Queue Manager is similar to OAT.XXX.QM, for example, OAT.RFID.QM.

To create a Queue Manager from a command line:

FIGURE 271. Command to Create Queue Manager

Queues

Create two queues:

• Notification Queue – A queue to receive EPCIS events sent from servers.• Master data import Queue – A queue to receive EPCIS master data from

external applications.

To create a Queue from the command line:

FIGURE 272. Command to Create Queue


Configure WebSphere AppServer JNDI ResourceOAT SOA application looks up the JMS resource from WebSphere JNDI, so you must set this up accordingly.

WebSphere JNDI

You can use the WebSphere Admin Console to create this JNDI resource by selecting Resources ‐‐> JMS Providers ‐‐> WebSphere MQ on the left panel. Then select WebSphere MQ queue connection factories and WebSphere queue destinations for adding the corresponding resources.

jndi-soa.properties

Finally, the JNDI names must communicate back to OFS SOA through JNDI‐soa.properties so that message producers and recipients know where to send and receive messages. Following is a sample of the properties file for the scripts mentioned on this page; modify the JNDI names as appropriate.

FIGURE 273. Script Sample of the JNDI‐soa Properties



OAT

APPENDIX F Kettle ETL Setup

Introduction To setup Kettle/Pentaho Data Integration, the user should first install the OAT Enterprise Data Manager server by running the OATenterprise installer, and then import the Kettle metadata repository.

Install OFS OAT Enterprise Data Manager ServerNote that the OAT Enterprise Data Manager should be installed, activated with a valid license key, and running, before proceeding with the Importing Kettle Metadata Repository steps.

Refer to Chapter 3: Installing OAT Enterprise Data Manager (Windows) for instructions on installing OAT Enterprise Data Manager server on Windows, and Chapter 4: Installing OAT Enterprise Data Manager (Linux) for installing the OAT Enterprise Data Manager server on Linux.

Foundation Suite 334

Importing Kettle Metadata RepositoryKettle/Pentaho Data Integration is the tool used for ETL processing. This needs to be configured manually, in a one‐time configuration procedure.

To import the Kettle metadata repository:

1. Launch the Kettle Design tool by executing

<EDM_Install_Dir>\ofs\bin\Spoon.bat (on Windows) or <EDM_Install_Dir>/ofs/bin/Spoon.sh (on Linux).

The Select a repository window appears.

FIGURE 274. The Select a repository Window

2. Choose OFS ETL Repository from the Repository dropdown list and click the Edit button on the right.

The Repository Information dialog appears.


FIGURE 275. The Repository information Dialog Box

3. Click the Create or Upgrade button.A confirmation dialog box appears.

FIGURE 276. The OK Dialog Box

4. Click Yes to confirm.5. Click Yes twice to go back to the Select a repository window, enter “admin”

as the login name and “admin” as the password and click OK to launch the Spoon design User Interface.

6. In the Spoon design User Interface, choose Repository ‐‐> Explore Repository from the menu at the top and launch the Repository Explorer window.


FIGURE 277. The Repository Explorer Window

7. In the Repository Explorer window, choose File ‐‐> Import Repository from XML into directory from the menu at the top.

8. In the file browser find and select ETLRepository.xml (on SQL Server) or ETLRepository.xml.oracle (on Oracle) from <EDM_Install_Dir>\ofs\conf\.kettle directory.

9. Click OK on the Directory Selection dialog. 10. Click Yes, when necessary to confirm directory creation in the repository and

click Close to close the import window. Then click Commit Changes to return to the Spoon User Interface.


APPENDIX G MicroStrategy Configuration

Introduction Integration with MicroStrategy allows sophisticated analysis of data collected through your OAT deployment. This appendix documents procedures for configuring MicroStrategy. Refer to the MicroStrategy installation guide for more details.

The steps you will need to perform to configure MicroStrategy are:

1. Install and Configure OAT Enterprise Data Manager2. Install and Configure MicroStrategy3. Run and Configure the oatentreports Web Application4. Load the Data5. View the Reports6. Configure an MSTR Server Behind a Firewall7. Enable Retailer and Supplier Portal Reports


Install and Configure OAT Enterprise Data Manager

Install OAT Enterprise Data Manager

Install the OAT Enterprise Data Manager by referring to the appropriate chapters in Section II: Installation. The installer allows you to specify if you want to create Enterprise Data Manager, Enterprise Administrator, and EDM Star databases on the same database server. If you decide to create them separately, maintain a record of all the database information that you used.

Install and Configure MicroStrategy

Install MicroStrategy

Install MicroStrategy (MSTR) 8.1.1 on the desired platform (Windows Server 2008 or Solaris OS) by following the MSTR installation guide. The MSTR installer is distributed along with the OFS installer.

Make sure you install MSTR Intelligence Server and the Web Universal. You may or may not install the MSTR Desktop depending on your license restrictions. If you do not have a license to install the MSTR Desktop, you have to use the MSTR Desktop installed on another machine to configure the the MSTR Intelligent Server.

Note: Installing MSTR on Solaris needs root access permissions only if the license is CPU‐based.

You need to install both MSTR version 8.1.1 and the associated hotfix, hotfix 1 for MSTR version 8.1.1.


Prepare the MSTR Metadata Database

The MSTR metadata database, containing MSTR reports for the OAT Enterprise Data Manager, is distributed along with the OFS installer as a database dump. You need to restore the database dump into an existing database, and use it as the repository for your MSTR Intelligence Server. The MicroStrategy metadata is not a part of the installation, but is available in the OFS installer distribution. Contact OAT Professional Services or OAT Support for assistance.

Restore MSTR Metadata Database for SQL Server 2008

Use the MS SQL Server 2008 restore task to restore the database dump in your database. Refer to the database documentation for assistance with this process.

The default database name is mstrmetadata. However, you can use the name of your choice. You also need to create a MSTR user who can access the metadata database and has database owner privileges. There might be a default MSTR user already created in the database. Note that the default MSTR user is ʹoatmstruserʹ and the default password is ‘apollo.’

For MS SQL Server 2008, you also need to create a security login for the MSTR user and make the metadata database accessible by the user.

Restore MSTR Metadata Database for Oracle1. (For Oracle on Linux/UNIX only) Log into the server where the Oracle data‐

base is installed and switch the user to Oracle by issuing:

su - oracle

2. Copy the metadata dump file to the server where Oracle is installed. This file is distributed (typically in a zip archive) together with the OFS installer; the name of the unarchived file should specify ʺoracleʺ and a datestamp, for example, mstrmetadata_oracle_20071129.dmp.

3. Create a user in the Oracle database to own the schema for MSTR metadata (for example: oatmstruser).


4. From the command line, issue the following command to restore the db:

imp oatmstruser/apollo fromuser=mstrmetadatauser touser=oatm-struser file=mstrmetadata_oracle_20071129.dmp buffer=10240000

In the above command, the password for oatmstruser is “apollo” and the db dump file is “mstrmetadata_oracle_20071129.dmp.”

The MSTR metadata database will be restored under the user “oatmstruser.”

Prepare the ODBC Data Sources

The MSTR Intelligence Server uses ODBC data sources to connect to the databases. You need to create an ODBC data source for each database that the MSTR Intelligence Server needs to access: mstrmetadata, EDM and EDM Star databases.

Note: If the EDM and EDM Star schemas share the same database, you only need to create a single ODBC data source for it. Otherwise, you need to create a separate ODBC connection for each database.

Use the credentials of a database user who can access the database (read the data in the database tables) to create the ODBC data source.

Prepare ODBC Data Sources on Windows

In Windows, you may create an ODBC Data Source through the Windows ODBC Administration tool in the Control Panel.

When you create an ODBC Data Source, make sure that you change the default database for the user account (such as oatmstruser) to the database this ODBC Data Source needs to connect to. For example, the ODBC Data Source for the EDM Star database should change the default database to the EDM Star database as shown below:


FIGURE 278. The Microsoft SQL Server DSN Configuration Window

For MS SQL Server, if two separate databases have been created for the EDM and EDM Star schemas, they can share the same database user. You need to create separate ODBC data sources with the same user credentials, but pointing to different databases.

Prepare ODBC Data Sources on Solaris

MSTR Unix installation contains a utility tool called MSTR Control Center. You may start some application tools from the MSTR Control Center, such as ODBC Administration, MSTR Configuration Wizard, MSTR Service Manager, etc. It is recommended that you launch MSTR Control Center for the configuration tasks on Solaris.


The MSTR Control Center is located in the <MSTR_INSTALL_HOME>/bin folder. The command for starting the control center is: ./mstrcontrolcenter.

To create an ODBC data source, do this:

1. From the MSTR Control Center, choose Applications ‐‐> ODBC Administra‐tor.

FIGURE 279. The MSTR Control Center

2. In the ODBC Administrator window, click Add….


FIGURE 280. The ODBC Administrator Window

3. Click Next, choose MicroStrategy ODBC Oracle Wire Protocol driver for Oracle database, and click Next to proceed.


FIGURE 281. The Database Selection Window

4. In the Driver Details window, fill in the information to connect to the Oracle database:• Data Source Name: The name to identify the ODBC Data Source.• Host Name: The host where the Oracle database is located.• SID: The Oracle SID for the database.• Port Number: The port number that the Oracle database is listening to.

By default, it is 1521.5. Click Test and provide the correct userid andpassword to test the connec‐

tion.6. Click Finish, to finish creating the ODBC Data Source.


FIGURE 282. The Driver Details Window

You need to create separate ODBC Data Sources for MSTR metadata, EDM, and EDM Star. For Oracle you need to create separate users who own these schemas and use the associated user with the ODBC Data Source you created.

Configure MSTR Intelligence Server

Configure MSTR Intelligence Server on Windows1. Run MSTR Configuration Wizard by navigating to Start ‐‐> All Programs ‐‐>

MicroStrategy ‐‐> Configuration Wizard.


FIGURE 283. The Welcome to the MicroStrategy Configuration Wizard Window

2. Select the Set up MicroStrategy Intelligence Server option, and click Next.


FIGURE 284. The Connect to Metadata Repository Window

3. Choose the ODBC Data Source Name you created for the MSTR metadata database, specify the username and password, and click Next. Leave the Driver Execution Mode at its default value.


FIGURE 285. The User Authentication Window

4. Enter ʺAdministratorʺ for the MSTR Administrator User Name and click Next. You can leave the Password field blank if you are connecting to the MicroStrategy Intelligence Server for the first time, but it is recommended that you assign a password later for security reasons.


FIGURE 286. The Create, Link, Delete a Server Definition Window

5. Choose Use Selected Server Definition and select OATenterprise from Exist‐ing Server Definitions. Click Next.

Note: Choosing Existing Server Definition will retain all default project configurations such as the report cache expiration time.

6. Click Ok at the prompt and click Next to accept the default port number for MSTR Intelligence Server.


FIGURE 287. The Select Projects Window

7. Check all projects available in this metadata and click Next.


FIGURE 288. The Completing the Server Configuration Wizard Window

8. Review the data and click Finish to modify the server definitions. You may receive a warning that the ODBC data source(s) used by the EDM and EDM Star databases cannot be found on your local machine. If this happens, click OK to ignore and configure the MSTR database instances later.

You will need to stop and start the MSTR service. Wait until the server restarts successfully. When you return to the configuration Welcome page, close the page.


Configure MSTR Intelligence Server on Solaris

MSTR Intelligence Server configuration on Solaris can be done through the MSTR Configuration Wizard.

1. Start the MSTR Configuration Wizard by clicking Applications ‐‐> Configu‐ration Wizard… in the MSTR Control Center. (Refer to the Prepare ODBC Data Sources on Solaris section.) The process is similar to that on Windows.

2. In the Connect to Metadata Repository window, specify the ODBC Data Source to connect to the Metadata Repository, by choosing ORACLEDB for the Oracle database, and specify “mstruser” as the User Name to connect to the Oracle database.

FIGURE 289. The Connect to Metadata Repository Window

Note: If you registered the MSTR Server as a service on the Solaris platform in the Configuration Wizard steps, you need root access to start the MSTR server.


You may use the MSTR control utility to un‐register the server as a service, as described below:

mstrctl [‐m <machine_name> [‐l <login>]] [‐s <server_name>] <request>

[parameters]

• ‐m <machine_name>, ‐‐machine=<machine_name>: executes the request on the specified machine

• ‐l <login>, ‐‐login=<login>: remote machine account, prompting for a pass‐word

• ‐s <server_name>, ‐‐server=<server_name>: the server (product) to which the request refers

• <request> [parameters]: (unregister‐service|us) [instance_name]: unregisters a server instance as a service

Configure MSTR Projects

Navigate to the MSTR Desktop via your Start menu.

Note: MSTR Desktop offers only a Windows version. You need to use a Windows Desktop to remotely connect to your MSTR server if the server is on Solaris.

Connect to MSTR Intelligence Server from a Local Desktop

If the Desktop is the one you installed with MSTR Intelligence, you should be able to find a project source, whose name is the hostname of the system, in the folder list (you have to enable the folder list view from View‐‐> Folder List menu if it is not visible).

A project source is a placeholder for an MSTR intelligence server in the Desktop. All projects available in that MSTR intelligence server are grouped under this project source. If you donʹt see the default %HOSTNAME% project source or it is in a different name, you can always rename the existing one or create a new project source by following the instructions in the next section.


Connect MSTR Intelligence Server From a Remote Desktop

If the Desktop is accessed from a remote machine, you need to create a remote project source for the intelligence server you just installed. To do this:

1. Click any project source in the folder list of the Desktop and right click to choose New Project Source...

FIGURE 290. The Project Source Manager Window

2. Enter the Project source name in the provided field and select the Connec‐tion mode as Server from the dropdown list. You may specify any name as the project source name. The connection mode name should be the host name where you have installed the MSTR Intelligence Server.


3. Accept the default value for other options and click OK to create the project source.

Configure MSTR Projects

Configure MSTR Database Instances for MS SQL Server Database

The OATenterprise project source appears in the Folder List of the MicroStrategy Desktop window. When you are asked for a userid, enter Administrator and the password as apollo.

To configure MicroStrategy Database instances for MS SQL Server:

1. Expand the Administration folder under the OATenterprise project source and choose Database Instance Manager.All the folders residing in the Database Instance Manager will be listed in the right pane.


FIGURE 291. The MicroStrategy Desktop Window

2. Right click the EDMDB item in the right pane and choose Edit.The Database Instances window appears.


FIGURE 292. The Database Instances Window

3. Under General tab, ensure that the EDMDB is selected in the Database con‐nection (default) list, and click the Modify… button on the right. The Database Connections window appears.


FIGURE 293. The Database Connections Window

4. Choose the EDMDB option you have created for EDM database from the Local System ODBC data sources list and “oatmstruser” as the Default data‐base login name.

5. You need to make sure the password for the Database Login Name is correct by clicking the Modify… button. Ensure that you enter the correct password for the “oatmstruser” database login name.


FIGURE 294. The Database Logins Dialog Box

Note: If you cannot find the Database Login Name for your database, then click the New… button on the right and create a new database login name.

6. Click OK to save your changes.

Repeat the same procedure for the EDM Star database, to connect to the correct ODBC data source using the correct database login name.

Configure MSTR Database Instances for the Oracle database

The process for configuring MSTR Database instances for Oracle is similar to that for MS SQL Server. The difference is highlighted below.

When you edit the database instance, choose Oracle 11g as the Database connection type and the Oracle ODBC Data Source Name you have earlier created to connect to the database. Login with the username and password of the user who owns the schemas for the EDM and EDM Star databases.


FIGURE 295. Database Connections Dialog Box

Configure MSTR Database Instances for the DB2 Database

The process for configuring MSTR Database instances for DB2 is similar to that for MS SQL Server. The difference is highlighted below.

When you edit the database instance in MSTR desktop, choose ʺDB2 UDB V9.1 for Linux, UNIX and Windowsʺ as the database connection type in the Database Instance window.


Restart MSTR Intelligence Server on WindowsYou need to restart the MSTR Intelligence Server to make the changes effective.

FIGURE 296. The Windows Task Toolbar

On the Windows task toolbar, double click the MicroStrategy Service Manager icon to display the MicroStrategy Service Manager window.

FIGURE 297. The MicroStrategy Service Manager Window


Click Stop to stop the MSTR Intelligence Server. Wait until the server stops completely and then click Start to start the server. You may also click Restart.

Restart MSTR Server on Solaris

From MSTR Control Center, choose Applications ‐‐> Service Manager…. The Service Manager window appears.

FIGURE 298. The Service Manager Window

Use the same steps as mentioned in the Restart MSTR Intelligence Server on Windows section for starting and stopping the MSTR Intelligence Server.


Run and Configure the oatentreports Web Application

Start Enterprise Data Manager (EDM) Service

You may now start the OAT Enterprise Data Manager service defined as oatedm. See Chapter 12: OAT Enterprise Data Manager Post‐Installation Procedures for details on how to start the server.

Configure the oatentreports Web Application

Ensure that the OAT Enterprise Data Manager is started.

1. To access the Administrator Page of the oatentreports Web application, use the following URL (replace the host name and the port number with the spe‐cific values for your installation of the OAT Enterprise Data Manager):

http://<host>:<port>/oatentreports/servlet/oatentreportsAdmin

Use the Tomcat administrator userid and password to access the Administrator Page. The userid and password are administrator andadministrator.


FIGURE 299. The Administrator (WEB SERVER) Page

2. Under Unconnected servers:, enter the MSTR Intelligence Server host name into the Add a server manually textbox and click Add….The added MSTR Intelligence Server will be listed under WEB SERVER in the left pane.


FIGURE 300. The Administrator (Server Properties) Page

3. Click on the MSTR Intelligence Server name you have just added to display its Connection properties.

4. Select the Automatically connect to Intelligence Server when Web Server or Intelligence Server is restarted option for Connect mode and click Save.


FIGURE 301. The Administrator (Security) Page

5. Click the Security link in the left pane to display the security settings in the right pane.

6. Check the Store MicroStrategy Intelligence Server sessions information in temporary cookies instead of on the Web server checkbox for Cookies Secu‐rity level settings. Click Save to save the changes.


Load the DataYou need to load the data into the EDM Star database to view the reports. Refer to the OAT Foundation Suite Enterprise User Guide for documentation on how to load data into the EDM Star database.

View the ReportsYou may now view the visibility reports by accessing the following URL:

http://<host>:<port>/oatentreports

Configure an MSTR Server Behind a FirewallThe only consideration with respect to MicroStrategy and a firewall setup is to open traffic for the MicroStrategy Intelligence Server Port number (34952) and the MicroStrategy Listener port number (30172).

If the MicroStrategy Intelligence Server name does not show up in a list of available machines, the name may be entered manually. If the name does not resolve, check the Domain Name Server (DNS) configuration.

Enable Retailer and Supplier Portal ReportsA set of reports for retailer and supplier portals is included in the standard report set. However, these reports are disabled by default. Retailer customers must ensure that access to these reports is enabled when the MSTR project is configured.


To enable the retailer reports and supplier portal reports, do the following:

1. Log into MicroStrategy Desktop as the administrator user. 2. Expand OATvisibility ‐‐> Public Objects ‐‐> Reports and select the 8. Retailer

folder on the right panel. Right‐click for a pop‐up menu, and then select Properties.

FIGURE 302. The MicroStrategy Desktop Window

3. In the Properties window, click the Security tab.


4. For the OATaxiom Reporter group, change the Object value and Children value from Denied All to View. Make sure the checkboxes are checked to apply changes to child objects recursively, and to overwrite child objectsʹ access control lists. Click OK to confirm the changes.

Repeat the same process for the Supplier Portal folder.

FIGURE 303. The Retailer Folderʹs Properties Window

You now should be able to access the retailer and supplier portal reports from the OATenterprise Web User Interface.



APPENDIX H Configuring OFS for WAS Data Source

OverviewOFS typically manages the connections to the database using database‐specific JDBC drivers and the Apache Commons Connection Pool. The database param‐eters such as the host name, user name and password are provided to the installer during setup.

WebSphere Application Server (WAS) provides a different implementation of the connection management services in which connection pools are exposed as Data Sources. The WebSphere Admin Console provides an administrative user interface to manage Data Sources.

Administrators might prefer using native WebSphere Data Sources to manage OFS database connections due to IT policies, familiarity with WebSphere tools, or the need for centralized administration in federated deployments. In such cases, OFS can be configured to use WebSphere Data Sources instead of directly connecting to the database.

This Appendix describes the steps involved in configuring OFS to use WAS data source.

Perform the following steps to configure OFS in order to use WAS data source:

1. Configure the connection pool in WebSphere2. Configuring OFS


Configure Connection Pool in WebSphereThe steps involved in configuring the connection pool in WebSphere are as fol‐lows:

1. Define J2C credentials to access the database.2. Create a JDBC provider in the WebSphere Admin Console.3. Create data source from the JDBC provider.4. Test the data source connection.

The subsequent sections explain the above steps in detail.

Defining J2C Credentials

To define the J2C credentials in order to access your database:1. Click on Security ‐> Secure administration, applications and infrastructure in

the left pane of WebSphere Admin Console.2. Secure administration, applications and infrastructure window appears.


FIGURE 304. Secure Administration, Applications and Infrastructure

3. Click Java Authentication and Authorization Service ‐> J2C Authentication Data link under Authentication.Secure administration, applications and infrastructure page for defining authentication data appears.


FIGURE 305. Defining Authentication Data

The above window displays a list of existing user identities and passwords for Java (TM) 2 connector security.

4. Click New button.Configuration ‐ General Properties window appears.


FIGURE 306. Configuration ‐ General Properties

5. Define the new J2C credentials by entering the following details in General Properties.• Alias: Indicates the name of the authentication data entry.• User ID: Indicates the name of OFS database.• Password: Indicates the password that is associated with the user

identity.• Description: Indicates the optional description of authentication data

entry.6. A message appears asking whether you want to save the configuration or

review the details.7. Click on Save to save the changes directly or go to Review and click Save to

update master repository with changes.The newly added J2C Credentials appears in the list.


Creating JDBC Provider

To create JDBC provider within the WebSphere Admin Console:

1. Click Resources ‐> JDBC ‐> JDBC Providers in the left pane of the WebSphere Admin Console.JDBC Providers window appears.

FIGURE 307. JDBC Providers List

2. Select the appropriate Scope from the drop‐down menu.


3. Click the New button.Create New JDBC Provider window appears.

FIGURE 308. Create New JDBC Provider ‐ Step1

4. Enter the following details of the JDBC provider and click Next:• Scope: Indicates the level at which the JDBC provider definition is

visible.• Database Type: Indicates the type of database such as Oracle, Sybase etc.,• Provider Type: Indicates the type of JDBC provider. • Implementation Type: Indicates the data source providers such as

Connection pool, XA or non XA.• Name: Indicates the name of JDBC provider.• Description: Describes the JDBC provider.

5. Database Class Path Information window appears.


FIGURE 309. Create New JDBC Provider ‐ Step2

6. Enter the following path details. Class Path: Indicates the JDBC Driver path.• Directory Location: Observe the following while entering the directory

location:• Go to the location where WebSphere is installed and search for the

path where db2jcc.jar file is saved.• Copy the driver path.• Go to Environment ‐> WebSphere Variables.• Click on the respective JDBC Provider Driver Path link.• Paste the above copied driver path in the Value field. • Click Apply.


Note:

The variable name by default will be DB2UNIVERSAL_JDBC_DRIVER_PATH and the value may be over‐written by the OAT installer.After Xpress/EA/EDM install, check for the WebSphere environment variable ʹDB2UNIVERSAL_JDBC_DRIVER_PATHʹ and reset it to WebSphereʹs JDBC driver path.(for example: ʹD:\Program Files\IBM\WebSphere\AppServer\deploytool\itp\plu‐gins\com.ibm.datatools.db2_1.0.0.v200607211720\driverʹ).

7. Click Next and the Summary window appears.

FIGURE 310. JDBC Provider Summary

8. Click Finish; the existing JDBC Providers list appears.9. Click Save to save the configuration.


Creating Data SourceTo create your data source from the JDBC data source provider:

1. Click Resources ‐> JDBC ‐> JDBC Providers.2. JDBC providers ‐Data Sources window appears with the list of existing pro‐

viders. 3. Click on the JDBC provider name link that you have created in the previous

step.The General Properties window appears.


FIGURE 311. JDBC Provider ‐ General Properties

4. Click Data Sources under Additional Properties.The JDBC Providers ‐ Data Sources window appears.

FIGURE 312. Data Source List

5. Click the New button.Create a Data Source window appears.Note the following while entering data source details:• Provide a unique data source and JNDI name.• Start the JNDI names for data sources with ʹjdbc/ʹ• Select the J2C authentication data defined in the first step.• For cluster deployments, select the appropriate scope so that your

clustered applications can access the data source.


FIGURE 313. Create Data Source ‐ Step1

6. Enter the following data source details.• Scope: Indicates the level at which the resource definition is visible. • JDBC Provider Name: Indicates the name of the JDBC provider that you

have created.• Data Source Name: Indicates the unique name of the new data source.• JNDI Name: Indicates the unique JNDI name of the data source.


7. Select a component‐managed authentication alias that you have created in first step; click Next.The Database Specific Properties window appears.

FIGURE 314. Create Data Source ‐ Step2

8. Enter the following database specific properties for the data source:• Database Name: Indicates the name of the database to which the data

source belongs to.• Driver Type: Indicates the type of the driver.• Server Name: Indicates the name of the server such as localhost. • Port Number: Indicates the port number of database server.

9. Check the Use this data source in CMP option.10. Click Next.

The Data Source Summary window appears.


FIGURE 315. Create Data Source Summary

11. Click Finish. The new data source appears in the JDBC providers list.12. Click Save to save the configuration.

Testing the Data Source ConnectionTo test the data source connection:

It is mandatory that you save the configuration before testing the connection.


1. Click Resources ‐> Data Sources in the left pane of the WebSphere Admin Console window.The Data Source window appears with the list of existing data sources.

FIGURE 316. Data Source List

2. Select the data source you have created and click the Test Connection button on top of the window.The Test result message appears on top of the window.

FIGURE 317. Test Connection Message


Configuring OFS to Use WAS Data SourceTo configure OFS to use WAS Data source:

1. Open ofs/config/ savant and configure as follows:senseware.database.j2ee_datasource_name=<WAS JNDI name for data‐source>

2. Add the properties given below to ofs/conf/custom_service_factory.proper‐ties.

service.CoreServices.priority=20

service.CoreServices=\

com.oatsystems.util.J2EEConnectionManagerProvider, \

com.oatsystems.util.DefaultHibernateUtilProvider, \

com.oatsystems.service.DefaultInstallPropertyManagerProvider, \

com.oatsystems.util.DBStateManagerProvider, \

com.oatsystems.util.MasterCodesRegistry, \

com.oatsystems.service.RmiRegistryService, \

com.oatsystems.service.configwatch.DefaultLog4JConfFileWatchdogImpl

3. Add the same property as given in step 2 to <WAS_HOME}/AppServer\profiles\AppSrv01\installedApps\Premis‐esNodeCell\OFS_SITE_NOV6.ear\oatedge.war\WEB‐INF\classes\app_properties.properties.

4. Replace the server name, node name and cell name appropriately in the above step.

5. Remove jdbc2_0‐stdext.jar, db2jcc*.jar from WEB‐INF/lib of both axis and oatedge.


APPENDIX I Install OFS in a Federated Environment

OverviewTo install OFS on a Websphere federated environment, first install OFS on the Deployment Manager and federate the application to the Websphere Applica‐tion Servers (WAS) controlled by the Deployment Manager. Do not install OFS directly on each of the WAS using the OFS installer. To install OFS on a feder‐ated environment follow the steps detailed in this appendix.

Customizations to the base product are delivered as OAT plugins (OAR). These customizations can be made to the java code (.jar files), jsps (.jsp files), configuration changes (.xml or .properties) without replacing the whole file, schema or others. Details of OAR file deployment in the federated environment are provided in this appendix.

OFS InstallationBefore installing OFS, set the environment variable ‘OAT_SUPPORT_WAS_FEDERATION‘ to true. The OFS installer and the scripts listed below have to be executed on the server that has the WebSphere Deployment Manager.

Follow the installation steps to install OFS. After the OFS install is complete (in this case partial completion as the application is not yet deployed onto the WAS), deploy <OFSInstallDir>\ofs\oatedge.ear from the federated


WAS administrator console manually. This manual deployment is a one time process. During manual deployment, do the following:

1. Use default bindings2. Select the relevant target mappings (multiple servers, clusters etc) for both

the web modules

3. Select the configured virtual_host.

4. After the EAR is deployed, change the class loader order as ‘ Application class loader first’ for application level and individual module level.

5. Clear the CLASSPATH of the application servers.

6. Run the jacl script ‘setJVMProps.jacl’ (not part of the release) from the deployment manager. This script needs to be executed from the command‐line using the wsadmin utility on the deployment manager with the follow‐ing options:

wsadmin.bat –f setJVMopts.jacl <applicationName> <JavaXms> <JavaXmx> <dsn>

Example: wsadmin.bat –f setJVMopts.jacl OFS_SITE 1024 1024 jdbc/oatdsn

jdbc/oatdsn is the jndi name that is specific to an application. Every new node added should make use of this name.

At the end of the above execution, take the XpressName mapping for each nodes. The mapped details have to be used while creating database tables. See Database update for details.


7. For custom OAR deploy (non DB changes), run deploy –f –F from the com‐mand line of the machine that hosts the deployment manager for the node.

8. Restart the application servers. This is necessary because of changes of JVM settings outlined in the following section.

OFS Application Server SettingsThe following configuration/properties are modified for the application. The other properties are from default bindings.

Class Loader In the OFS application level, the class loader mode is set to ‘PARENT_LAST’.

For Apache‐Axis2 (axis) and raf (oatedge) modules OFS application classes have to be loaded first, then the Application Server classes have to be loaded. So for axis and raf module, the class loader mode will be set to ‘PARENT_LAST’.

For ontentreport module (part of EDM) Application server classes have to loaded first, so the class loader mode will be set to ‘PARENT_FIRST’.


Application Security

For the OFS application, there are two default groups (Server Administrator, Default Users) created. By default, authenticated users get the ‘Default Users’ role . Group(s) of users mentioned for administration at the time of installation get ‘Server Administration’ role.

Creating JDBC ProviderPerform the following steps on the server that hosts the deployment manager for the node.

Data Source Name

By default the installer creates ‘sense_cf’ and is used while creating the JDBC provider for the first time. This is not used by the application. So the user has to create a data source name with the database alias and follow the procedure specified in section 7.

JNDI Name

By default the installer creates ‘jdbc/senseware’ and is used while creating the athpplication for the first time. This is not used by the application. So the user has to create a proper JNDI name.

JDBC Providers

During installation, a default JDBC provider (based on database type) is created and the jars for the JDBC provider will point to the jdbc jars from OFS. This eventually sets the WAS environment variable for the JDBC drier path based on DB type (for Oracle: ORACLE_JDBC_DRIVER_PATH, for DB2: DB2UNIVERSAL_JDBC_DRIVER_PATH) . This needs to be changed to use the connection pool.


Creating Connection Pool• Define the J2C credentials to access your database. This is done in:

Security>Secure Administration>Applications>Infrastructure> Java Authentication>Authorization Service>J2C Authentication Data

• Define the database username and password and give it an alias.Then create a Datasource provider in the WAS admin console (Resources > JDBC > JDBC Providers. WAS supports multiple XA or non XA providers. Note that you may have to define WebSphere Environment Variables (Environment > WebSphere Variables) to define JDBC driver path. The variable name by default will be DB2UNIVERSAL_JDBC_DRIVER_PATH and the value may be overwritten by the OAT installer. So after Xpress/EA/EDM has been installed, check for the WebSphere environment variable 'DB2UNIVERSAL_JDBC_DRIVER_PATH' and reset it to WebSphere's JDBC driver path For example: 'D:\Program Files\IBM\WebSphere\AppServer\deploytool\itp\plu-gins\com.ibm.datatools.db2_1.0.0.v200607211720\driver') . For oracle, place the jars inside <WAS_HOME}/AppServer/lib. Make the environment variable ORACLE_JDBC_DRIVER_PATH to point to the above location.

• Next, create your datasource from the datasource provider; select your data‐source provider (created) earlier.Then select Additional properties>DatasourcesCreate your datasource, give it a unique datasource and JNDI name(very important). Usually, JNDI names for datasources start with 'jdbc/'Select the J2C authentication data defined in the first step.

Note: For cluster deployments, ensure that you select the appropriate scope so that your clustered applications can access the datasource.

• Save your configuration and test the datasource connection (select data‐source and select ʹTest Connectionʹ).

• Add the following property in ofs\local\conf\savant.properties.m.senseware.database.j2ee_datasource_name=<WAS JNDI name for data-source>

• Add the following to ofs\local\conf\custom_service_factory.properties.m


service.CoreServices.priority=20service.CoreServices=\ com.oatsystems.service.ThreadCleanupService, \ com.oatsystems.util.J2EEConnectionManagerProvider, \ com.oatsystems.util.DefaultHibernateUtilProvider, \ com.oatsystems.service.DefaultInstallPropertyManagerProvider, \ com.oatsystems.util.DBStateManagerProvider, \ com.oatsystems.util.MasterCodesRegistry, \ com.oatsystems.service.RmiRegistryService, \ com.oatsystems.service.configwatch.DefaultLog4JConfFileWatchdogImpl

• Add the following in ofs\local\conf\webapp\app_properties.properties.m.

SERVICES=s/com.oatsystems.util.DefaultConnectionManagerProvider/com.oatsystems.util.J2EEConnectionManagerProvider

• Remove jdbc2_0‐stdext.jar, db2jcc*.jar from WEB‐INF/lib of both axis and oat‐edge

Note: If you are adding 2 xpress nodes on the same machine, change the rmi port in <WAS_HOME/AppServer\profiles\AppSrv01\installedApps\Premis‐esNodeCell\OFS_SITE.ear\oatedge.war\WEB‐INF\classes\app_properties.properties and also in <WAS_HOME/AppS‐erver\profiles\AppSrv01\installedApps\PremisesNode‐Cell\OFS_SITE.ear\axis.war\conf\savant.properties

• Run the deployer to take the custom changes. See Running the Deployer for details.

Database updateThe conventional OFS installer creates and updates the OFS database. But this will not work for a federated environment. Therefore use the deployer to create and update the database. This deployer has to be executed for each database


instance of OFS. While running the deployer with the –D option, the following options have to be provided:

-H <IP address of the server containing the db>-P <database username> -p <database password> -d <database name> -E <XpressName> -I <XpressID> -M <Deployment Manager name> -o “conf,bin,schema”

Example:

deploy.bat -f –D full –H 172.17.0.21 -p db2admin -P db2admin -d xpdb1 -E oatxpress -I 0003 –M dmgr -o "conf,bin,schema"

Note: The OATxpress name has to be used from the setJVMopts.jacl script. See OFS Installation for details.

Running the DeployerAny OAT plug‐ins (OAR) have to be deployed across the federated nodes. This is done by calling the deployer with the OAR file using the following parameters.

‐f –F <ApplicationName> ‐M <Deployment Manager name> <OARFilename>

Example:

deploy.bat ‐f ‐F ofs_xpress ..\ext\hotfix1.0.oar



APPENDIX J Customizing Reports

IntroductionOFS reports can be customized with configuration changes. This section gives you details on what can be customized in a report. These are the possible customizations:

• Display of search criteria • Validation of search criteria • I18N support – references to the local language resource files

Customization has to be done in a configuration file. There is one configuration file per report. The report search criteria specified in the configuration file must match those specified in the report design file.


Sample Configuration

Each report has one configuration file and one report design file. The report design file contains information for the reports engine to execute the report and display results. This file is similar to code, and should not be modified without sufficient knowledge about how a report is constructed and what tools are used to construct it.The configuration file is a simple text file and contains parameters that can be customized safely.

The sample configuration file considered below is for the ‘EPC at Location’ report. The configuration file is named EpcAtLocationReportResults‐config.properties. The corresponding report design file is named EpcAtLo‐cationReportResults.rptdesign. In general, the configuration file will be named <report‐name>‐config.properties.

Note that some times there are specific report design files for different databases. In such cases, the report design file will be named <report‐name>_<database‐name>.rptdesign. The configuration file name does not include the <database‐name> part of the report design file name. There is only only configuration file even if there are multiple, database‐specific, report design files.

Following is the sample configuration file for the ‘EPC at Location’ report. Explanations of the configuration parameters follow.

report.title=EPC At Location Report

report.bundle=EpcAtLocationReportResults

locations.custom.writer=com.oatsystems.raf.service.birt.BIRTLocationTreeParameterWriter

fromDate.custom.writer=com.oatsystems.raf.service.birt.BIRTCalendarParameterWriter

fromDate.custom.validator=com.oatsystems.raf.service.birt.BIRTCalendarParameterValidator

toDate.custom.writer=com.oatsystems.raf.service.birt.BIRTCalendarWithNowParameterWriter

toDate.custom.validator=com.oatsystems.raf.service.birt.BIRTCalendarParameterValidator

products.custom.writer=com.oatsystems.raf.service.birt.BIRTProductParameterWriter

products.custom.validator=com.oatsystems.raf.service.birt.BIRTProductParameterValidator

locations.value.multi=true


Name Description

report.title This is the name of the report displayed as a header in the UI of the report. This can be dif‐ferent from the <report‐name> mentioned above.

report.bundle This is the name of the properties file used for internalization.

Search Criteria The search parameters for this sample report are:locationsfromDatetoDateproducts

Each of the search parameters can be customized with a ‘custom.writer’. This affects how that parameter is displayed on the search screen of the report. Each of the search parame‐ters can be customized with a ‘custom.validator’. This affects how the search input is vali‐dated when a user enters or selects the search paramter value. The value ‘com.oatsystems.raf.service.birt.BIRTLocationTreeParameterWriter’, for loca‐tions.custom.writer, is the java class that customizes the search parameter display. The list of available custom writers is given in section ‘Available Custom Search Criteria’ below.


Customizing ConfigurationFollowing are the parameters that can be customized in the Configuration file.

Name Description Default report.title This is the title, that is the header in the report. Value depends on the

report.

report.bundle This is the file used for internalization and must be located in $APPSVR/webapp/oatedge/WEB‐INF/classes

None

<field>.value.default <field> specifies one search parameter for this report. The value given in <field> should match the name of the corresponding parameter in the report design file.

<field>.value.default specifies the default value for that search parameter. This value will be pre‐filled for this parameter while dis‐playing the search page of the report. This value can be changed before executing the report.

BIRT default parame‐ter value

<field>.value.required This is used to specify if the search parameter <field> is mandatory or not.

BIRT parameter setting

<field>.value.multi This applies for search parameters that display a list. Possible values are ‘true’ and ‘false’. If this is set to true, a listbox is displayed, if not a dropdown is displayed.

BIRT parameter setting

<field>.value.preset This is used to specify a preset value for the search parameter <field>. If report.skip.parameters is set to true, the search parameter will not be displayed on the search page of the report, and instead the preset value will be used.

None

report.skip.parameters If this is set to true and if all the search criteria has been preset using <field>.value.preset , then the report search criteria page is skipped. The results page is automicatically displayed.

false

<field>.custom.writer This is a java class that customizes the <field> display. For all possible values, see section ‘Available Custom Search Criteria’ below.

None

<field>.custom.validator This is a java class that validates the <field> after the user enters or selects a value in the report search page. For all possible values, see sec‐tion ‘Available Custom Search Criteria’ below.

None


Only the report.title and report.bundle search criteria, that is, the property names are fixed. The other search criteria are different for different reports, for example, location.value.default is valid if there is a report search parameter called ‘location’.

Available Custom Search CriteriaThe values below are meant for <field>.custom.writer and <field>.cus‐tom.validator. Note that writer and validator classes should be used depending on the type of the search parameter. A writer that renders a Date parameter cannot be used for a search parameter of type String.

Following is a list of valid values for “Writer” properties:

sql.extension.db2 These values should not be changed. false

sql.extension.oracle These values should not be changed. false

sql.extension.sqlserver These values should not be changed. false

Property value/Class name Behavior Additional parameters com.oatsystems.raf.ser‐vice.birt.BIRTLocation‐TreeParameterWriter

Outputs a listbox or dropdown list filled with locations with hierar‐chy. If multi‐selectable, selection of a location will automatically select all descendants.

<field>.value.multi, <field>.cus‐tom.writer.prop.cascade_parent

com.oatsystems.raf.ser‐vice.birt.BIRTCalendarPa‐rameterWriter

Outputs 1 text input for date, 1 text input for time, 1 dropdown for AM/PM and a calendar popup. The date time format is localized as defined in global.properties.

None

com.oatsystems.raf.ser‐vice.birt.BIRTCalendar‐WithNowParameterWriter

Same as BIRTCalendarParameterWriter, with the addition of ʹNowʹ checkbox.

None

com.oatsystems.raf.ser‐vice.birt.BIRTCalendarDa‐teOnlyParameterWriter

Same as BIRTCalendarParameterWriter, except that time and AM/PM dropdown are not displayed. Time is assumed to be 12:00 AM

None


Following is a list of valid values for “Validator” properties:

com.oatsystems.raf.ser‐vice.birt.BIRTCalendarPa‐rameterValidator

Retrieves the submitted date & time and returns a String formatted to the field specific output format.

None

com.oatsystems.raf.ser‐vice.birt.BIRTProductPa‐rameterWriter

Outputs a dynamic widget for product selection, containing a SKU text input and table for selected products.

None

Property value/Class name Behavior Additional parameters com.oatsystems.raf.ser‐vice.birt.BIRTCalendarPa‐rameterValidator

Retrieves the submitted date & time and return a String format‐ted to the field specific output format.

None

com.oatsystems.raf.ser‐vice.birt.BIRTProductPa‐rameterValidator

Retrieves the selected products as a specially formatted String for internal processing.

None

Documents

Installation and Configuration Guide - OATSystemssupport.oatsystems.com/training/oat80_docs/Installation_Config.pdf · Installation and Configuration Guide Version 8.0 OATSystems,