Kewill Customs Installation Guide
Kewill Customs Installations Guide
For Release 2.1 – Alliance R07 Patch 3 Compatible
Original Publication: March, 2011
KC Install - 1
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
Table of Contents
Table of Contents..................................................................................................................................... 2
Kewill Customs Installation Guide ......................................................................................................... 4
1.
Introduction .................................................................................................................................... 4
1.1.
Overview of Kewill Customs Installation .............................................................................. 4
1.2.
Kewill Customs Components ................................................................................................. 4
1.3.
Third Party Components ......................................................................................................... 5
1.4.
Kewill Customs Release Number Nomenclature ................................................................. 6
2.
Implementation of Kewill Customs .............................................................................................. 7
2.1.
Implementation Requirements ............................................................................................... 7
2.1.1.
Small to Medium Kewill Customs implementation .............................................................. 7
2.1.2.
Medium to Large Kewill Customs implementation .............................................................. 8
2.1.3.
High Availability Kewill Customs Implementation ............................................................... 8
2.2.
Hardware and Software Requirements ................................................................................. 9
2.2.1.
Hardware Configuration ...................................................................................................... 9
2.2.2.
Terminal Server or Citrix Requirements (optional) ........................................................... 10
Please Note: For Remote Customer Site Implementation ................................................................ 11
3.
Installing Kewill Customs Server .................................................................................................. 11
3.1.
Installing Apache Tomcat on AIX or Linux ......................................................................... 11
3.1.1.
Starting Tomcat on AIX or Linux ....................................................................................... 12
3.1.2.
Stopping Tomcat on AIX or Linux ..................................................................................... 13
3.2.
4.
Installing Kewill Customs Server on AIX or Linux ............................................................. 13
3.2.1.
Installing Kewill Customs Server using the installer on AIX or Linux ................................ 13
3.2.2.
Installing Kewill Customs Server manually on AIX or Linux ............................................. 18
3.2.3.
Installing Database script manually .................................................................................. 21
3.2.4.
Upgrading the Database manually.................................................................................... 24
Installing Kewill Customs Services ............................................................................................ 26
KC Install - 2
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
4.1
Installing Kewill Customs Services on AIX or Linux ............................................................. 26
5. Troubleshooting of Kewill Customs Installation ............................................................................ 28
6.
Installation of Kewill Customs Adapter ........................................................................................ 29
6.1.
Kewill Customs Adapter Prerequisites ............................................................................... 29
6.2.
Apache Tomcat Configuration for RMS .............................................................................. 29
6.3.
Apache Tomcat Configuration for Oracle ........................................................................... 31
6.4.
Installation of Apache Tomcat on Windows ....................................................................... 31
6.4.1.
Configuring the Database Connection - Oracle: ............................................................... 31
6.4.2.
Configuring the Database Connection - Connx: ............................................................... 32
Appendix 1 -- Installing Java Notes ..................................................................................................... 34
Appendix 2 -- Installing Tomcat Notes ................................................................................................ 36
KC Install - 3
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
Kewill Customs Installation Guide
1. Introduction
1.1. Overview of Kewill Customs Installation
Before installing Kewill Customs or upgrading to a later version, Kewill strongly recommends that you
familiarize yourself with the requirements and steps described in this Installation Guide. These
requirements and steps are covered in the following sections:

Implementation of Kewill Customs

Installing Kewill Customs Server

Installing Kewill Customs Services

Troubleshooting Kewill Customs Installation

Installing Kewill Customs Adapter
1.2. Kewill Customs Components
The following sections describe the Kewill Customs’ components and third-party applications and
programs that are installed and configured during the installation process.
KC Component
Version
Description
Kewill Customs User Interface
Matches the version on this
document
User interface for Shipment
Processing, maintenance and
administration of Kewill Customs.
This is the application that will be
downloaded to the client via Java
Webstart.
Kewill Customs Server
Matches the version on this
document
The backend for Shipment
Processing, maintenance and
administration of Kewill Customs.
Connects and maintains Kewill
Customs’ database.
KC Install - 4
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
KC Component
Version
Description
Kewill Customs Services
Matches the version on this
document
Scheduling of jobs for Forms and
Reports printing, formatting,
sending receiving of ABI
messages from US Customs.
And also, for processing of
interfaces to other systems, e.g.,
Accounting Systems.
Kewill Customs Adapter
Matches the version on this
document
Optional component which
facilitates integration from other
system to Kewill Customs via
EDI or XML.
9.01 or later
Optional component which
facilitates integration from other
system to Kewill Customs via
EDI or XML. Works with Kewill
Customs Adapter.
Kewill Ebiz
Note: Installation of Ebiz will not
be covered in this document.
1.3. Third Party Components
3rd Party Component
Apache Tomcat
Version
6.0.30 or later version of 6.0 for
AIX, Linux and Windows
5.5.26 or later version of 5.5 for
Open VMS
Description
Required to run Kewill Customs.
The application server where
Kewill Customs components will
be installed.
Note: Installation of Apache
Tomcat on VMS will not be
covered in this document.
Java SDK
1.6_10 or later version of 1.6
Required to run Kewill Customs.
Note: Installation of Java SDK
will not be covered in this
document for VMS, AIX and
Linux.
KC Install - 5
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
3rd Party Component
Oracle Database
Version
10g release 2
Description
Required to run Kewill Customs
Note: Installation of Oracle
Database will not be covered in
this document.
MQ Server
7.0 or later
Optional component if immediate
response from US Customs is
not required.
Kewill Customs supports MQ
Server and Client mode
connection to US Customs.
1.4. Kewill Customs Release Number Nomenclature
Overview
Kewill Customs releases are named with the following nomenclature:
Example: Release 1.2.3.4 where
1 = Major Release version #1
2 = Minor Release version #2
3 = Patch version #3
4 = Minor Patch version #4
KC Install - 6
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
2. Implementation of Kewill Customs
2.1. Implementation Requirements
Kewill Customs is highly scalable system, depending on business requirements Kewill Customs can
be implemented in the following setup described in the diagram below:
2.1.1.
Small to Medium Kewill Customs implementation
Internet
Router/Firewall
Citrix/Terminal
Server
WAN Users
VPN Tunnel
Application Server
MQ Client
Database
Server
US Customs
Network Printer
LAN Users
KC Install - 7
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
2.1.2.
Medium to Large Kewill Customs implementation
Internet
Router/Firewall
Citrix/Terminal
Server
WAN Users
Database
Server
VPN Tunnel
MQ Server
Application Servers
US Customs
Network Printer
LAN Users
2.1.3.
High Availability Kewill Customs Implementation
Internet
Router/Firewall
Citrix/Terminal
Server
WAN Users
LAN Users
Load Balancer
Application Servers
VPN Tunnel
US Customs
Database
Servers
MQ Server
Network Printer
KC Install - 8
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
2.2. Hardware and Software Requirements
2.2.1.
Hardware Configuration
The following table shows the minimum hardware and software requirements that must be in
place before installing the Kewill Customs Server and Kewill Customs Services.
No. of Users
Application/Database
Server CPU (64 bit)
Application
Server Memory
Database Server
Memory
Application
Server Disk
Space
Up to 25
1 server x 1 Quad
Core or equivalent
8GB
2GB
50GB
Up to 50
1 server x 1 Quad
Core or equivalent
16GB
2GB
50GB
Up to 100
2 server x 1 Quad
Core or equivalent
2 server x 16GB
4GB
2 server x 50GB
Up to 100
1 server x 2 Quad
Core or equivalent
32GB
4GB
100GB
Over 100
Custom Configuration
Note: The disk space for the database server is dependent on the number of transactions per year.
Component
Operating System
Server
Workstation
Ubuntu Linux Server 9 or later
with 2.6 Kernel or equivalent.
Windows XP Professional with
SP2 or later
or
or
AIX 5.3 or later
Windows 7 with SP1 or later
or
Open VMS 8.3 or later
or
Windows 2003 with SP2 or later,
Windows 2008 with SP1 or later
CPU
Memory
Intel Xeon Quad Core with 2Ghz
or higher
Intel Dual Core with 1Ghz or
higher
See Hardware Configuration
chart
1GB minimum, 2G is optimal
KC Install - 9
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
Component
Server
Ethernet Card
Workstation
100Mb or better
100Mb or better
HP Laser Jet or equivalent
connected to server or network
HP Laser Jet or equivalent
connected to workstation or
network
Report Viewer
Not Applicable
Adobe Reader 8 or later
Internet Browser
Not Applicable
Internet Explorer 6 or later
Printer
or
Mozilla Firefox 3 or later
Remote Access
Remote Desktop Server or VNC
Server for Windows Server
platform
This is needed when installing
remotely, or if you don’t have
access to the server console.
XWindows Server or VNC Server
for AIX and Linux platform
SSH server or Telnet server for
AIX and Linux platform on
manual installation of Kewill
Customs
2.2.2.
Remote Desktop Client or VNC
Client for Windows XP or 7
XWindows Client or VNC Client
for Windows XP or 7
Putty (SSH Client) or Telnet
Client for Windows XP or 7
Terminal Server or Citrix Requirements (optional)
Minimum
Requirements

2 GHz processor or better

200 MB memory/user. This is in addition to OS requirements.
Note: 64 bit server is required to accommodate more users/server. 32 bit
servers have a memory limitation.

5-10 GB of free disk space per user.

Current TSS or Citrix OS.

Direct network access to the Application server - preferably high speed
Sun Java Runtime 1.5 or greater (Available at Java.com).

Adobe Reader 8 or greater.

Direct or network access to printer for local printing of PDF.
KC Install - 10
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
Please Note: For Remote Customer Site Implementation
Implementation Notes 
for Remote Customers

The implementation of Kewill Customs at remote customer sites over a
WAN requires Citrix or TSS to provide the required performance for
remote sites.
The remote client sites would access the application server through the
Citrix or TSS server. The Citrix or TSS server must be local to the
application server as well. If it cannot be local, a high speed connection
between the two is required.
3. Installing Kewill Customs Server
3.1. Installing Apache Tomcat on AIX or Linux
Step
1
Action
Comment
Verify that the following ulimits are set
correctly for Alliance login OS username:
Note: If not set correctly, root username is
required to edit /etc/security/limits.
Command to use: ulimits -a
time(seconds)
unlimited
data(kbytes)
unlimited
stack(kbytes)
65526
memory(kbytes) unlimited
2
Get apache-tomcat-5.5.26.tar.gz from
the installation media.
3
FTP apache-tomcat-5.5.26.tar.gz to
home directory of alliance, e.g.,
/home/alliance.
4
Copy apache-tomcat-5.5.26.tar.gz to
/kcustoms.
5
Unzip apache-tomcat-5.5.26.tar.gz,
using unzip or gunzip, e.g., gunzip
apache-tomcat-5.5.26.tar.gz
6
Extract or untar apache-tomcat5.5.26.tar, e.g., tar –xvf apache-tomcat-
KC Install - 11
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
Step
Action
Comment
5.5.26.tar
7
Navigate to /kcustoms/apache-tomcat5.5.26/bin, and edit catalina.sh. Right
after the commented lines, add the
following 2 lines:
(See below for the two lines to be added.)
Add these 2 lines: JAVA_HOME=/usr/java5_64; export JAVA_HOME
JAVA_OPTS='-Xms1536m -Xmx1536m -Xmaxe256m Djava.awt.headless=true Dicustoms.abi.root.dir=/alliance/RUNTIME/; export JAVA_OPTS
3.1.1.
Starting Tomcat on AIX or Linux
Step
Action
Comment
1
Login as alliance username using telnet.
2
In $ or shell prompt, type in “ps –eaf |
grep java”.
If Kewill Customs is running, the result of the
command will look like below. If so, proceed
to Stopping Tomcat.
If not, proceed to step 3.
3
Navigate to “/kcustoms/apache-tomcat5.5.26/bin”
4
Then type in “./catalina.sh start”
5
To verify that the application is up and
running, use the command in step 2.
Expected Command
Results
alliance 827588
1 124 11:13:46 pts/7 69:24
/usr/java6_64/bin/java –Xms1536m -Xmx1536m -Xmaxe256m Djava.awt.headless=true
Djava.util.logging.manager=org.apache.juli.ClassLoaderLogM
anager -Djava.util.logging.config.file=/kcustoms/apachetomcat-5.5.26/conf/logging.properties Djava.endorsed.dirs=/kcustoms/apache-tomcat5.5.26/common/endorsed -classpath :/kcustoms/apachetomcat-5.5.26/bin/bootstrap.jar:/kcustoms/apache-tomcat5.5.26/bin/commons-logging-api.jar Dcatalina.base=/kcustoms/apache-tomcat-5.5.26 KC Install - 12
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
Dcatalina.home=/kcustoms/apache-tomcat-5.5.26 Djava.io.tmpdir=/kcustoms/apache-tomcat-5.5.26/temp
org.apache.catalina.startup.Bootstrap start
3.1.2.
Stopping Tomcat on AIX or Linux
Step
Action
1
Log in as Alliance username using telnet.
2
Navigate to “/kcustoms/apache-tomcat5.5.26/bin”
3
Type in “./catalina.sh stop”
4
Use the command in step 2 of Starting
Tomcat to verify that application is really
stopped. If it is not, proceed to step 5.
5
For some reason if the process of java is
still hanging around after stopping it. Use
“kill -9” to hard stop the process.
Note
Comment
This command will abruptly kill the process
and throw away any pending transaction, so
use this command carefully.

Alliance username must be used in restarting and stopping Kewill
Customs because its environment is set accordingly.

Kewill Customs is a stateless application so the users don’t have to log out
of their screens. The application should be able to recover once the server
is up and running.
3.2. Installing Kewill Customs Server on AIX or Linux
Kewill Customs can be installed using its installer on server console. If for some reason the installation
needs to be perform remotely or the server console can’t be accessed, proceed to section 3.2.2 for
manual installation.
3.2.1.
Installing Kewill Customs Server using the installer on AIX or Linux
If Java 1.6 is installed on AIX or Linux Server double-clicking on Kewill Customs installer
kc.installer_2.1.0.jar on the desktop console of the server will automatically launch the
installation wizard.
If the installation doesn’t start, check the execute privilege flag on kc.installer_2.1.0.jar and
make that flag is set correctly for the user running the installer.
KC Install - 13
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
Once the installer is running, Setup Wizard will guide you through the steps to install Kewill
Customs’ components. The wizard will proceed through a series of screens:
1. Welcome screen. Click Next button.
2. Release Notes screen. This is a good time to review the release notes, then click Next
button.
3. Kewill End-User License Agreement screen. Click Accept, then click Next button.
4. Stop Apache Tomcat screen. Make sure Apache Tomcat is not running, then click Next
button.
5. Kewill Customs Home Directory screen. Enter and make sure to point the installer to
appropriate Kewill Customs’ directory. It is recommended to put it on /kcustoms directory.
Then click Next Button.
KC Install - 14
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
6. Apache Tomcat Home Directory screen. Make sure to point the installer to the root
directory of Apache Tomcat.
7. Kewill Customs Application Name screen. This will be the web application name of
Kewill Customs. It is recommended to call it kcustoms.
KC Install - 15
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
8. Database Connection screen. Enter and make sure that the database connections are
correct. This information will be used by the installer to run the database scripts and to
set up the connection to the database. When you are done, click Next button.
KC Install - 16
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
9. Application Server Info screen. Enter the IP and port address of Apache Tomcat, then
click Next button.
10. Application Log Filename screen. Make sure that the location has enough disk space
to hold the log files of the application. Ideally, it should be able to hold a month’s worth of
logs for diagnostics of potential issues in the application. Then click Next button.
KC Install - 17
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
11. Progress screen. At this point the installer will back up previous Kewill Customs
installation, if there is any and proceed to install the application.
12. Script Processors screen. At this point the installer will run the database scripts when
done, click Next button.
13. Summary of Installation screen. Review the summary notes and check if there are any
critical error in the installation.
14. Proceed to Post Installation Tasks.
3.2.2.
Installing Kewill Customs Server manually on AIX or Linux
Overview
Step
1
The table below provides the steps required for the manual setup process.
Action
Comment
Get Kewill Customs web archive file
kcustoms.war from supplied media.
KC Install - 18
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
Step
Action
Comment
2
Transfer kcustoms.war to the home
directory of Alliance user.
3
Log in to the application server using
telnet.
Copy kcustoms.war to
/kcustoms/apache-tomcat5.5.26/webapps.
4
At this point, the war file should have been Refer to section 3.1.1 and 3.1.2 on how to
automatically exploded by Tomcat. If not, stop and restart Tomcat.
try to stop and restart Tomcat.
Step
5
Action
Comment
Once exploded, navigate to
/kcustoms/apache-tomcat5.5.26/webapps/kcustoms
To point web start to the correct URL,
replace and set the following lines:
Edit icustoms.jnlp to point web start to
the correct URL.
<property
name="icustoms.primary.url"
From:
value="http://10.146.1.171:8080/
kcustoms/MainController"/>
To:
<property
name="icustoms.primary.url"
value="http://HOST_IP:8080/
kcustoms/MainController"/>
Where:

6
HOST_IP is the IP address of the
application server that is hosting Tomcat
and visible to users.
Navigate to /kcustoms/apache-tomcat5.5.26/webapps/kcustoms/WEB-INF
To point the server component to the correct
URL replace and set the following lines:
Edit web.xml to point the server
component to correct URL.
From:
<init-param>
<paramname>icustoms.primary.url</paramname>
<paramvalue>http://10.146.1.171:8080/
kcustoms/MainController</paramvalue>
KC Install - 19
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
Step
Action
Comment
</init-param>
To:
<init-param>
<paramname>icustoms.primary.url</paramname>
<param-value>http:HOST_IP:8080/
kcustoms/MainController</paramvalue>
</init-param>
Note: See definition of HOST_IP on Step 5
above.
7
Navigate to /kcustoms/apache-tomcat5.5.26/webapps/kcustoms/WEBINF/classes.
Example:
<param name="File" value="/
kcustoms/logs/customs.log" />
Edit log4j.xml, and point the log file to
appropriate location.
KC Install - 20
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
Step
8
Action
Comment
Navigate to /kcustoms/apache-tomcat5.5.26/webapps/kcustoms/WEBINF/classes/META-INF.
To point to the correct database server and
database username, replace and set the
following lines:
Edit persistence.xml to point to correct
database server and database username.
<property name="toplink.jdbc.url"
value="jdbc:oracle:thin:@DATABASE_IP
:1521:DATABASE_SID" />
<property name="toplink.jdbc.user"
value="DB_SCHEMA" />
<property
name="toplink.jdbc.password"
value="DB_PASSWORD" />
Where:

DATABASE_IP is the IP address of the
database server.

DATABASE_SID is the name of Oracle
database. Usually, the dba should
provide this info.

DB_SCHEMA is the database username
that were created to access Alliance
database. The default for Kewill
Customs is “kcapps”.

DB_PASSWORD is the password of
database username. The default for
Kewill Customs is “kcapps”.
9
Restart Tomcat to put the new settings
into effect.
The application should be accessible on this
URL: http:HOST_IP:8080/kcustoms/
Note: See definition of HOST_IP on Step 5
above.
3.2.3.
Installing Database script manually
Database Install
Note that Database Install must be done by a DBA or under supervision
of Kewill DBA Services.
The table below describes the steps required for installing the database on top
of Alliance R07 Patch 2 Hotfix 1.
After running the install scripts, the upgrade scripts has to be perform to bring
the database to the latest patch or hotfix of Kewill Customs.
KC Install - 21
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
Create a database user for Kewill Customs:
Step
Action
1
Run sqlplus, and login as SYSTEM (dba for Oracle).
2
Using sqlplus, run the following:
a.
install\db-2.0\create_kc_user.sql
Grant the Alliance table to Kewill Customs:
Step
Action
3
Run sqlplus, and login as TPSDBA (database username/schema of Alliance).
4
Using sqlplus, run the following script from the installation media:
b. install\db-2.0\grant_alliance_tables.sql
KC Install - 22
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
Create the synonyms of Alliance table to Kewill Customs:
Step
Action
5
Run sqlplus, and login as KCAPPS (database username/schema of Kewill
Customs).
6
Using sqlplus, run the following script from the installation media:
c.
install\db-2.0\create_kc_synonyms.sql
Scripts creating and inserting Kewill Customs required tables and data:
Step
Action
7
Run sqlplus, and login as TPSDBA (database username/schema of Alliance).
8
Using sqlplus, run the following script from the installation media:
d. install\db-2.0\create_kc_tables.sql
e.
install\db-2.0\populate_kc_tables.sql
KC Install - 23
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
3.2.4.
Upgrading the Database manually
Database Upgrade
Note that Database Upgrade must be done by a DBA or under
supervision of Kewill DBA Services.
The table below describes the steps required for upgrading the database on
top of Alliance R07 Patch 2 with Kewill Customs 2.0 or 2.0.1.
Step
Action
1.
Run sqlplus, and login as TPSDBA (database username/schema of Alliance).
2.
Using sqlplus, run the following script from the installation media in the
following order:
Note: The 2.0.2.x scripts are not required to run if the system has Kewill
Customs 2.0.2.x already.
a.
upgrade\db-2.0.2\data\VALIDATION_TABLE_X_REF.sql
b.
upgrade\db-2.0.2\data\VALIDATION_MESS.sql
c.
upgrade\db-2.0.2\data\VALIDATION_CONTROL.sql
d.
upgrade\db-2.0.2.2\data\SYSTEM_PARAMETER.sql
Note: The 2.0.3 scripts are required to run if upgrading from Kewill Customs
2.0.2.x to 2.0.3
e.
upgrade\db-2.0.3\schema\PREFERENCE_KEYS.sql
f.
upgrade\db-2.0.3\schema\SECURITY_PREFERENCES.sql
g.
upgrade\db-2.0.3\data\ID_GEN.sql
h.
upgrade\db-2.0.3\data\VALIDATION_TABLE_X_REF.sql
i.
upgrade\db-2.0.3\data\VALIDATION_MESS.sql
j.
upgrade\db-2.0.3\data\VALIDATION_CONTROL.sql
k.
upgrade\db-2.0.3\data\SYSTEM_PARAMETER.sql
l.
upgrade\db-2.0.3\data\SECURITY_PREFERENCES.sql
Note: The 2.0.3.1 scripts are required to run if upgrading from Kewill Customs
2.0.2.x or 2.0.3
m.
upgrade\db-2.0.3.1\data\VALIDATION_CONTROL.sql
KC Install - 24
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
n.
upgrade\db-2.0.3.1\data\VALIDATION_MESS.sql
o.
upgrade\db-2.0.3.1\data\VALIDATION_TABLE_X_REF.sql
Grant the Alliance table to Kewill Customs:
Step
Action
3.
Run sqlplus, and login as TPSDBA (database username/schema of Alliance).
4.
Using sqlplus, run the following script from the installation media:
f.
install\db-2.0\grant_alliance_tables.sql
Create the synonyms of Alliance table to Kewill Customs:
Step
Action
5.
Run sqlplus, and login as KCAPPS (database username/schema of Kewill
Customs).
6.
Using sqlplus, run the following script from the installation media:
g. install\db-2.0\create_kc_synonyms.sql
KC Install - 25
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
4. Installing Kewill Customs Services
4.1 Installing Kewill Customs Services on AIX or Linux
Step
Action
Comment
1
Copy the directory /kcustoms/apachetomcat-5.5.26 to /kcustoms/apachetomcat-5.5.26-2.
2
Navigate to /kcustoms/apache-tomcat5.5.26-2/conf.
From:
<Server port="8005"
shutdown="SHUTDOWN">
Edit server.xml to change the default port
number of the second Apache Tomcat.
<Connector port="8080"
maxHttpHeaderSize="8192"…
<Connector port="8009"
enableLookups="false"
redirectPort="8443"
protocol="AJP/1.3" />
To:
<Server port="8006"
shutdown="SHUTDOWN">
<Connector port="8081"
maxHttpHeaderSize="8192"…
<Connector port="8010"
enableLookups="false"
redirectPort="8443"
protocol="AJP/1.3" />
3
Navigate to /kcustoms/apache-tomcat5.5.26-2/webapps/kcustoms/WEBINF/classes.
Enable the following services by removing
XML comment (<!-- -->) tag surrounding
them:
Edit service.xml to enable the Kewill
Customs Reports background processes.
ReportSchedulerHandler
ReportQueueHandler
EMailQueueHandler
PrintQueueHandler
4
Navigate to /kcustoms/apache-tomcat5.5.26-2/webapps/kcustoms/WEB-
From:
KC Install - 26
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
Step
Action
Comment
INF/classes.
<param name="File" value="/
kcustoms/logs/customs.log" />
Edit log4j.xml, and point the log file to
appropriate location.
To:
<param name="File" value="/
kcustoms/logs/report_customs.log" />
5
At this point, the setup is done and starts
Tomcat.
Refer to section 3.1.1 and 3.1.2 on how to
stop and restart Tomcat.
KC Install - 27
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
5. Troubleshooting of Kewill Customs Installation
To check if Kewill
Customs is operating
correctly
The URL below can be used to check if Kewill Customs is operating correctly.
Use a browser to pull up:
http://ip_address:8080/kcustoms/MainController
Example: http://69.48.135.27:8080/kcustoms/MainController
The response should be: Hello!MainController is alive and well.
To check the memory
usage
The URL below can be used to check the memory usage and manage the
instances of Kewill Customs web application context. Use a browser to pull up:
http://ip_address:8080/manager/status
Example: http://69.48.135.29:8080/manager/status
(See below for sample Status results).
Sample Status:
Note

The “Free memory” must not exceed or be equal to “Max memory”. If it is,
the Kewill Customs application needs to be restarted.
KC Install - 28
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
6.
Installation of Kewill Customs Adapter
Overview
The Kewill Customs Adapter is an integration module for Kewill Customs.
The following table describes the installation steps for the Kewill Customs
Adapter. The instructions have been separated into three areas:
1. Prerequisites
2. Tomcat Configuration
3. Installation of Program
4. Configuring the Database Connection
6.1. Kewill Customs Adapter Prerequisites
Prerequisites required
for installation:
1. Sun JDK version 1.5
2. Apache Tomcat version 5.5.

Apache Tomcat can be downloaded at:
http://tomcat.apache.org/download-55.cgi
6.2. Apache Tomcat Configuration for RMS
Windows:
1. Open the Tomcat Configuration tool.
2. Click on the Java tab
3. Append the following line to the Java Options:
-Dicustoms.database.type=RMS
[See screenshot below]
KC Install - 29
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
Sample of change in Apache Tomcat Properties window:
Unix/Linux
Edit <Tomcat_Install>/bin/catalina.sh
1. Append the following line to the JAVA_OPTS
-Dicustoms.database.type=RMS
Note on Memory: The memory setting on Apache Tomcat has to be set accordingly. The size of
the memory is dependent on the capacity, load of the system and size of XML
files.
For initial setting, it is recommended to set the following:
On windows, Apache Tomcat Properties:
Initial memory pool: 1024
Maximum memory pool: 1024
On Unix, append the following line to JAVA_OPTS:
-Xms1024m –Xmx1024m
KC Install - 30
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
6.3. Apache Tomcat Configuration for Oracle
Note for Oracle: No special configuration is required for Oracle.
6.4. Installation of Apache Tomcat on Windows
Note on using a Servlet These installation instructions are for Tomcat. Please read the web archive
Container other than deploy instructions of the Servlet Container if using a Servlet Container other
Tomcat
than Tomcat.
Step
1
Action
Comment
Copy the compressed program file
kcadapter.war to the
<Tomcat Install>/webapps folder.
2
6.4.1.
Step
3
Start Tomcat if it is not already started.
Tomcat will create a new folder called
adapter under webapps. The adapter
folder contains the extracted application
files.
Configuring the Database Connection - Oracle:
Action
Comment
Navigate to the folder:
<Tomcat Install>/webapps/kcadapter/
WEB-INF/classes/META-INF
4
Edit the file persistence.xml
5
Locate the <properties> tag within the
file.
6
Set the correct values for the following
properties:
It should be towards the end of the file.
a. toplink.jdbc.url – the database
connection string
KC Install - 31
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
e.g. for Oracle :
jdbc:oracle:thin:@<database
server>:<port>:<sid>
The correct values should be
substituted for <database
server>, <port>, <sid>.
[Contact the database
administrator to find out these
values.]
b. toplink.jdbc.user – the database
username
c. toplink.jdbc.password – the
password for the above database
user
6.4.2.
Configuring the Database Connection - Connx:
Step
7
Action
Comment
Navigate to the folder:
<Tomcat Install>/webapps/adapter/
WEB-INF/classes/META-INF
8
Edit the file persistence.xml
9
Locate the <properties> tag within the
file.
10
Comment out the Oracle Connection
properties and uncomment the Connx
Connection properties.
11
Set the correct values for the following
properties:
It should be towards the end of the file.
a. toplink.jdbc.url – the database
connection string
For Connx :
jdbc:connx:DD=<DSN>;GATEWAY=<
gateway>;PORT=7500
The correct values should be
substituted for <DSN>, <gateway>.
[Contact the database administrator to
find out these values.]
b. toplink.jdbc.user – the database
KC Install - 32
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
username
c. toplink.jdbc.password – the
password for the above database
user
12
You are done.
KC Install - 33
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
Appendix 1 -- Installing Java Notes
Notes
Action
Comment
1
When installing java, change the Install
Folder from the default location
[See screenshots below for sample.]
For example: Change from
C:\Program
Files\Java\jdk1.5.0_14
Change to
C:\Java\jdk1.5.0_14
2
Ensure that none of the folder names
have spaces in them and are not too
long.
Sample of changing Java Install Folder from the default location:
KC Install - 34
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
Sample of modified Java Install Folder destination location:
KC Install - 35
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
Appendix 2 -- Installing Tomcat Notes
Notes
1
Action
Comment
When installing Tomcat, change the
Install Folder from the default location.
[See screenshots below for sample.]
For example: Change from
C:\Program Files\Apache
Software Foundation\Tomcat
5.5
Change to
C:\Java\Apache\Tomcat5.5
2
Make sure that none of the folder
names have spaces in them and are not
too long.
Sample of changing Tomcat Install Folder from the default location:
KC Install - 36
Copyright © 2011 by Kewill Inc.
Kewill Customs Installation Guide
Sample of modified Install Folder destination location:
Copyright © 2011 Kewill Inc.
[last revision date: 01/21/11]
KC Install - 37
Copyright © 2011 by Kewill Inc.