Installing & Maintaining Windows Services

Case Manager makes use of services running on the server – specifically the Time Server and the Queue Server. These servers provide centralised functionality beyond that which the database can provide, with the drawback of requiring additional setup on the server. Up to this point, the servers could run as normal console applications or as installed Windows Services. With the addition of the Instance Directory, the setup complexity increased as the applicable instance had to be specified explicitly as well. A simplified solution was necessary which led to the changes introduced in the version 5.1.15 of Case Manager – a single application (per server application) that can run as a console application or a Windows Service, and integrates the applicable instance selection as part of its installation process.

Definitions

Windows Service

Microsoft Windows can maintain installed applications running in the background. These applications will automatically be started up upon server start-up, and gracefully shut down when the server is shut down.

Instance

An instance, in the context of Case Manager, is a named set of database connection details which are maintained by the Instance Directory – a centralised repository of all available databases. Applications can connect to instances by specifying the applicable instance name on start-up.

Console Application

A console application is a program that does not rely on a graphical user interface (that is, the mouse, windows or forms, or icons) but purely on text-based user interaction. This is typically accessed via a console which allows text commands and feedback (such as the Windows Command Prompt).

Command Line Arguments

When running an application, especially Console applications, one can specify parameters to the application by means of the text trailing the command to run the application. This is very useful for scheduling applications and making it part of a different process – especially when user interaction is not available.

Event Log

The Windows Event Log is a centralised repository where applications can log messages. Windows Services do not have a user interface to communicate possible problems and operation messages, and subsequently makes use of the Event Log to do so. The Event Log can be accessed in Windows through the Event Viewer.

Replacing Legacy Applications

Case Manager, up to 5.1.14, includes (for each the Time Server and the Queue Server) a Console Application and two installation files for Windows Services. These applications are all replaced by the new applications, CaseManagerTimeServer.exe and CaseManagerQueueServer.exe. These applications each encapsulates the functionality of both the console applications and the Windows Services.

Running the Services

The Time Server and Queue Server are built on the new technology that allows the same application to be run as a console application and an installed Windows Service. We’ve added the functionality to associate an installed Windows Service with the instance name (which can be seen in the name of the service). It is very important to note that these applications must run with Administrator privileges.

Running As Console Application

Running the application (the Time Server or the Queue Server) without any command-line arguments will run the server as a console application prompting the user to select the instance to run on. One can specify the instance by name as a command-line argument (-instance) which will start the server console application for that instance. If the instance is not found, the user will be prompted to select a different instance. For convenience, a template batch file, run_instance.bat, is provided that can be used to specify the instance name (especially if the console application is to be scheduled).

Installing as a Windows Service

The command-line argument –install can be used to install the application as a Windows Service. The installation process will prompt the user to select an instance for which the server will be installed. Note that multiple installations of the application is supported to allow servers for different instances. The –instance argument will not prompt the user and use the specified instance to install the Windows Service. One may add the start argument to start the service directly after installation. For convenience, a batch file (install.bat) is available that will prompt the user, install, and start a Windows Service on the selected instance.

Uninstalling Windows Services

Uninstalling an installed Windows Service is as simple as the installation process. By simply specifying the –uninstall command-line argument, the user will be prompted to select the instance whose associated Windows Service is to be uninstalled. The selection, however, is based on what is currently available in the Instance Directory. If a Windows Service should be uninstalled for an instance that is not available in the Instance Directory anymore, one can specify the name of that instance making use of the –instance argument. Again here, we’ve added a batch file (uninstall.bat) for convenience.

Monitoring

The server applications log events (such as start-up and shut-down messages, warnings, and errors) in two channels: Windows Event Log, and log files.

Event Log

A single event log is used for Case Manager servers, named CaseManager, that contain entries from different sources by which we can identify the application and instance. The Queue Server makes use of the source name CmQueueServer , and the Time Server of CmTimeServer. When running the server application, once the instance has been established, the instance name is appended to the source name, separated by a $-sign, for example CmTimeServer$DefaultInstance. The Event log can be accessed through Windows Event Viewer, under the section Applications and Services Logs.

File Logs

Logging information is also written to files in the \CaseManager\CaseManagerLogs directory of the drive where the server application executable resides. Two separate subdirectories, CmQueueServer and CmTimeServer, are created for the Queue and Time Servers, respectively. Once the instance has been established, a log is created in a further subdirectory with the name of the instance. Logging information before establishing the instance is logged in the CmQueueServer and CmTimeServer directories directly.

Troubleshooting

Problem	Suggested Steps
The server shuts down immediately after start-up (Console appilcation).	View the Event Log.
Event log indicates that the service does not have access rights to a namespace	Run the application as Administrator
The user is prompted for an instance even when the instance is specified as command-line argument	Make sure the instance exists (case sensitive) on the Instance Directory
Service does not start up	See Event Log. It may be that the instance is not available, the database is unavailable or versioning.