1 EWA Admin Tool Guide

This document describes the EWA Admin Tool Interface of EWA net which is used to update, manage and maintain the WIS and EPC Databases as well as managing the state of the server.

Besides the software installation, the applications need to have access to certain databases for content data. This content is not installed within the setup of the software but needs to be updated after installation. The aim of this behavior is to decouple software and data update and minimize the downtime of the applications.

This document describes the use and function of the EWA Admin Tool. The following use cases are documented in this description:

Start of the Tool
Starting and Stopping of EWA services
Installing Databases for EPC
Updating Databases for EPC
Removing Databases for EPC
Installing Databases for WIS
Updating Databases for WIS
Removing Databases for WIS
Wiping Database content (Cleanup)
Usage of the Tool
Logging and Troubleshooting

4 Startup of EWA Administration Tool

The EWA net Administration tool can be started using the favorites menu inside the Internet Explorer. This entry is created during installation and is only available on the server.

Picture 1: Start of EWA net Administration tool using the favorites menu

The EWA net Administration tool can be only started on the EWA net server. If the link to this tool is not available, it can be started manually using the command

[EWA_HOME]\ewa_admin\EWAAdmin.exe

where EWA_HOME need to be replaced with the directory where EWA net was installed.

5 Starting, Stopping and Monitoring of EWA core services

With the EWA Administration Tool it is possible to influence the availability of the server and see if it is running. The Administration tool acts as a service monitor and shows if the needed Windows services are running or not.

Picture 2: Service Monitor Page for the Server

Within this panel the EWA net server (application server) can be started and stopped. This is more or less a shortcut for the Windows “Services” view.

Also within this panel the user management database (i.e. for specific user data, FIN Cache,…) can be started and stopped.

Note:
Database “start” and “stop” is not simply starting and stopping services. A “stop” always also stops the corresponding TransBase multiplexer service. And “start” always starts both the database engine and the TransBase multiplexer service.

If the services are stopped the application server will not be available for all users. Please take this into account when starting or stopping services.

6 EPC net / WIS net Database Maintenance

6.1 Starting and stopping the installed Databases

It is possible to see the current state of the running database on the EPC net / WIS net Screen in the Administration Tool. If no database is installed, the traffic light will be off. If the database itself is working and the database service shows a good status, it will show a green traffic light. Else the traffic light will show a red status.

Use the “Start” and “Stop” Buttons to shutdown / start the database and the Transbase service.

Picture 3: EPC net Administration of Database

6.2 Install new Databases

Note:
EPC net / WIS net database installation requires a valid Start Key. The section Enter StartKeys for EPC/WIS shows how to enter a Start Key.

To install a new database into the running application, use the “Install” button. This will start the process of copying the needed database files from DVD to hard disk and attach the databases to the running service. Once a database is installed, the button will be labeled as "Update" to indicate that this action will update the running database.

6.3 Enter StartKeys for EPC/WIS

Note:
It is also possible to enter a valid Start Key in the admin interface of EWA net. You can go to the interface either by selecting “EWA net Admin” from your Favorites “EWA net” folder or directly by its URL http://localhost:9000/EWA-net/Admin. An explanation for entering a StartKey is provided in your Admin Guide.

On the tab “StartKey” it is possible to enter a start key for EPC and WIS.

6.4 EPC net Installation

Initial installation using “archive” and “base” media

EPC requires base and archive DVDs. The archive DVD contains a set of older valid data cards. This archive media is normally published once every year and all subsequent monthly base publications are based on it. The base DVD contains newer data and relies on the data from the archive DVD.

The installation process is quite simple: The User has to start the AdminTool where he clicks on the Install/Update button. The system asks for the first update DVD of the base DVD set. When all base files are copied then the AdminTool requests the archive media DVD. All archive files are copied to the new database and the installation process finishes.

Initially inserting an archive medium before a base medium will lead to an error message.

After the button is pressed, the tool will ask you to insert an EPC net / WIS net data DVD to any DVD drive of your machine. For EpC net it will try to read the “FDARequest.cfg” file which is normally in the folder “MBXX\cfg” of any data DVD. For WIS net the program tries to find the "WISCD000" file in the folder "wis" of the DVD root.

Picture 4: Admin tool requests the data DVD configuration file

If the DVD is inserted just press “OK” - the Tool will search all available drives in PC for the configuration file. If you already had a valid data DVD of EPC net in one of your DVD drives, the tool will have skipped this dialog and started installation immediately.

Note:
If the files should be installed using a network share, use the “Browse…” button and navigate to the corresponding folder on the network share and select the “FDARequest.cfg”/"WISCD000" file in the folder “MBXX\cfg”/"wis" relative from the DVD root.

The Tool will also search all hard drives and mounted Shares for data DVDs.

After the configuration file has been read successfully and the database files could be found, the tool will request to select a target drive for the database content. Select a drive where all database files should be copied to and click “OK”.

Picture 5: Selection of the target drive for database content

The next step in the copy process is to start to copy the ROM files to hard disk. If the source DVD can not be located in any drive of the PC, the Tool will ask for a source for copying the files.

Picture 6: Selection of ROM file source

In this dialog, please select the DVD root directory when the tool requests a file. The path inside the media is searched automatically. If a network share is used as file source, please point to the folder which corresponds to the original DVD root.

The copy process will be visualized with a progress. Please wait until all data has been copied or the Tool asks you for further media.

Picture 7: Copy Progress Dialog

After all database ROM files have been copied, the tool will proceed with the following steps:

Test all copied ROM files for consistency
This step will verify that all files have been copied successfully

Picture 8: Database test Dialog

Ask for confirmation to attach the new files to the running instance
Please press “OK” here to go on with the installation process.
The Tool will attach all new database files to the running instance.
Please wait until the tool has finished this step.

After these steps have been completed successfully, it will show a notification that all needed databases have been copied and activated successfully. The traffic light for the EPC net / WIS net database status will turn to green now.

Picture 9: Successful installation of a database

6.5 Update existing Databases

The update of database content will almost use the same installation process like the initial installation of the database.

The difference in the update step is that you are requested to insert the DVD which contains the setup into any DVD drive. During update the normal setup will be called to update software resources. Please select the appropriate folder where the setup.exe is available if the files could not be found automatically.

Note:
When updating the server, you should ensure that no user is using the applications. Users can continue working while database ROM files are being copied to the hard disk. But after finish of this process the server will be shutdown so users might lose important data.

6.6 Delete a Database

Database can easily be deleted from the system by clicking on the “Delete” button. This button will delete the currently active database.

Note:
Be sure that you notify all users to save important data and to log off from the system as they might loose data when the database will be deleted.

6.7 Switching databases

When a database set was updated, the older version will be kept as backup database. With the activate database button it is possible to switch the backup and the active database. The former active database will be kept as backup.

Note:
Be sure that you notify all users to save important data and to log off from the system as they might loose data when switching the database.

7 Advanced Command line options

This chapter is mainly intended for System Integrators who want to make use of the batch mode of the Admin Tool to allow further customizing of the installation update process, one may want to make use of the command line features of the EWA Admin Tool.

Note:
EWA Admin Tool has been developed for the “local” environment where all software components will be installed on one single server. In a distributed environment like the “central” not all of the features described here will work.

To get an overview of the available options, just issue the following command on a command line:

“C:\Program Files\EWA net\ewa_admin\EWAAdmin” /?

Picture 18: Help to get Usage Hints for EWA Administration Tool

This overview will not capture all options. Further options will be available here in the documentation

7.1 Database control

Admin Tool allows starting and shutting down the Transbase databases individually without the need of knowledge about the special characteristics behind it. There are currently 3 databases that can be controlled:

EWA user management database
WIS net database
EPC net database

The command line is quite easy. You specify which database you want to operate on and which operation you would like to perform: shutdown or boot. The command line for this is:

EWAAdmin.exe [/core | /wis | /epc] [/boot | /shutdown]

Description:

Parameter	Description
/core	Operate on the EWA user management database
/wis	Operate on the WIS net database
/epc	Operate on the EPC net database
/boot	Boot the specified database
/shutdown	Shutdown the database. This will also invalidate any open connection without reconfirmation.

Example call:

EWAAdmin /wis /shutdown

will shutdown the WIS net database.

Note:
When shutting down databases in most cases it may also make sense to shutdown the application server, too. After doing your maintenance be sure to boot the application server again.
There is no command line in EWAAdmin.exe as this can easily be achieved by issuing the command lines
net stop “EWA net Server”
to stop the application server or
net start “EWA net Server”
to start the application server again. This command must be issued on the server machine where the EWA net application server is running of course.

7.2 Update (Database and Software)

If you want to start an update without the user being forced to start Admin Tool and click some buttons you can easily start the update process from the command line. Simply select the application part you would like to operate on (WIS net or EPC net). Admin Tool will then automatically start the update process for the regarding application.

The command line looks like this:

EWAAdmin.exe [/wis | /epc] [/license licensebits] [/force] [/source Path] [/target Drive]* [/nofork] [/noswupdate] [/unattended] [/v]

Description:

Parameter	Description
/epc	Update EPC net
/wis	Update WIS net
/license	Optional: Provide the access authorization bits on the command line. For EPC net this is quite useful as it restricts the number of ROM files to be copied. When this parameter is specified a dedicated access authorization check is skipped. Note: You cannot provide a crypted StartKey here
/force	Optional: Enforce the copying of ROM files though they might already be installed on the system. This helps replacing corrupt ROM files.
/source Path	Optional: Defines the source path from where to find and copy the database files. Te source parameter can be specified multiple times if multiple source directories are required. Besides the specified source paths the program always searched all available drives for the needed files if the file can not be found in the defined source path.
/target Drive	Optional: Specify a target drive for the ROM files. You can repeat this option for several drives
/nospacecheck	Optional: Flag to specify whether the free space check on the target drive should be omitted. If specified, the program will not check for sufficient free space on target drive.
/nobuffertune	Optional: Flags the instance to skip Windows buffering optimizations. In rare cases the file copy speed breaks down during the update process to a few KB/s instead of several MB/s. Initially the program has been optimized to allow fast copy performance without impact of running server. If the file copy of the database media is very slow, this command line option can try to skip the optimizations. Do not use this option if the program is copying in a reasonable speed.
/nofork	Optional: In a normal call the program copies itself to %TEMP% and executes there. If the process should be watched, this parameter can be used to prohibit the copy of the application to %TEMP%. Note: When using this option the integrated software update will fail. In this case please call the software update manually!
/noswupdate	Optional: Enforces the program to skip consistency checks and does not run software update during database update. Note: When using this option you have the possibility to skip a software update when installing new database content. Nevertheless is it highly recommended that you always update the software together with the database update. If you decide to de-couple the software and database installation processes this is fine - but do not forget to update the software, too. The software update will check which software component versions are installed and only updated components will be refreshed. For not updated components at least the language resource, help and what's new files are updated. In summary: If you do not run the software update, the users will see old help and what's new files.
/unattended	Optional: Suppresses confirmation dialogs and allows batch execution of the program
/v	Optional: Enables debug logging for troubleshooting (verbose mode)

Note:
When specifying parameters containing special characters like "-" or "/" please quote those parameters.
Example:
Use
EWAAdmin.exe /source "C:\EWA-net"
instead of
EWAAdmin.exe /source C:\EWA-net
The latter one will fail as the commandline parser will think there is another parameter hidden on the commandline.

7.3 Cleanup database

You can remove any installed databases from the system by the command line, too.

The command line looks like this:

EWAAdmin.exe [/clean | /cleanwis | /cleanepc]

Description:

Parameter	Description
/clean	Removes all (EPC net AND WIS net) databases
/cleanwis	Removes the WIS net database(s)
/cleanepc	Removes the EPC net database(s)

8 Update Process Description

When using the update database options in the Administration tool a process is executed which handles the database update. The following steps are processed during a database update:

Access authorization check
The current access authorization from the disk is read out and interpreted. If the access authorization is not valid, the update will stop and an error message will be displayed to the user.
The interpreted access authorization can be overridden using the /license command line parameter
Request for Source Media
The Administration tool searches for suitable source media. The priority is a source path which was given by command line. If none was specified or nothing was found in this path, the tool looks in all drives for suitable content. If none is found, the user is requested to select a source path or to insert a DVD media.
SW and Data Consistency Check
The program checks if both WIS and EPC are in use. If both applications are used, then the program checks if a software update will also take place with the data update. If an update is also taking place which is not a "hotfix" update, then the user is requested to insert the media of the other application to show that a consistent update with both medias is possible.
This step is skipped if the flag /noswupdate is issued.
Check Update Possibilities
A small program (ewa\setup\checker.exe) is executed on the source media to check if an integrated data and software update is possible with this database release. Depending on the return code of this application, the process can continue or not.
If the result of this application shows that the integrated update is not possible and e.g. with this data update also the Administration tool program needs to be updated, the user will be requested to have a longer downtime and run the software setup before updating the databases. Software setup is then called by the tool and after successful update it will be re-launched.
This step is skipped if the flag /noswupdate is issued. In this case you need to ensure that the database can be installed with the current software version!
Read Database Definition
The database meta information is read by the tool using the descriptor files from the source media.
Read Software Version
The software version information is read from the source media for later purposes.
This step is skipped if the flag /noswupdate is issued.
Database Structure Version Check
The program checks if the new database has a structure version which is sufficient for the software which is installed. If the version is too old, the update of the database will fail and the program will complain.
User Update Confirmation
The user will be asked to confirm the update to the new database version if this is not the initial database which is installed.
This confirmation is skipped when running in /unattended mode
Update Lock Collision Check
It is checked if the current active database is the same like the one which will be installed. In this case the user needs to acknowledge the shutdown of the server additionally since the web server needs to be shut down before copying the files to have the database files not locked.
File Copy
All needed database files are copied from the source media to the target drive. The user will be asked for the target drive to copy to.
The target selection can be skipped using the /target parameter
Test Database Files
The database ROM files which have been copied are tested if copied successful.
Integrated Software Update
If the media contains a newer software release as currently on the disk, integrated software update will be executed.
This step will be omitted when using the /noswupdate flag. You need to manual run the software update using the command line [Source]\ewa\setup\setup.exe /u.
Write Database Information to Registry
Meta information of the new database is written to system registry.
Web Server Shutdown
Database Service Shutdown
Old Database Detach
The old databases are going to be detached from the Transbase database
Update Registry of Current Database
Launch Pre Installation Hook
If a pre installation hook is specified, this will be launched.
Attach new Database to Transbase
Launch Post Installation Hook
If a post installation hook is specified, this will be launched.
Remove Old or Incompatible Versions
Database backup releases which are too old or are not compatible with the new software are removed from the user's system for both the database being updated as well as for the database of the other application. Thus inconsistent software-database constellations are prevented for both applications after an integrated software update. Only one backup version is kept.
Re-Init Internal Objects
Start Database Service
Start Web Server
Clean disk and remove unused files from hard drive
Run actions for Daily Updates (if installation references a WIS net database, access authorization allows this and Daily Update is configured correct)
Show Success Message to User

If the update can proceed using a integrated update (when no major software changes are required) the application server will be down between Step 13 and Step 23. This downtime will be usually around 5 minutes. If the update check in step 4 detects that a longer downtime is required, the application will be unavailable from step 4 until step 23.

9 Logging & Troubleshooting

If the EWA Administration tool is not working, please use the following steps to determine why the application is not working:

Check if the application was installed successfully
Check if enough space is available on the target drive when installing new databases
Check the log files which are written by the EWA Administration Tool.
The log files are located in
“EWA_HOME\install\logs\log.00”