Library

Browse and search developer information

ClearWaterWatcher User Guide

By Connecting for Health | 2012

Introduction

ClearWaterWatcher is a windows service to automate the use of the ClearWater tool. For more information about ClearWater please refer to the ClearWater User Guide.

Architecture

ClearWaterWatcher has been developed in C# using the .NET Framework 3.5. It consists of a single application called ClearWaterWatcher which is installed and run as a windows service.

ClearWaterWatcher as a windows service, once installed, runs constantly on either a server or an always-on desktop. It is controlled as a normal windows service from the Windows Services Control panel.

ClearWaterWatcher assumes a data feed source, such as DTS, will automatically deliver data feed files to a named input folder.

ClearWaterWatcher constantly monitors for the arrival of new data feed files in the input folder. When it detects a new data feed file it will:

  • Invoke ClearWaterCmd to load the new data feed file.
  • If successful will move the data feed file to a named success folder, add an information event to the Windows Application Event Log and optionally send a success notification email to a list of email addresses.
  • If not successful will move the data feed file to a named failure folder, add an information event to the Windows Application Event Log and optionally send a failure notification email to a list of email addresses.

It is the responsibility of an administrator to archive or delete files within the named success and failure folders.

It is the responsibility of an administrator to deal with failed data feed files.

If ClearWaterWatcher is stopped and then restarted, it will process any new data feed files that have been stored in the named input folder in the interim.

ClearWaterWatcher

Logging

ClearWaterWatcher logs both information and error events to the Windows Application Log. To view log events:

Go to Start > Control Panel

Figure 1 - Control panel.

Figure 1 – Control panel.

Open Administrative Tools

Figure 2 - Administrative Tools.

Figure 2 – Administrative Tools.

Open Event Viewer and select the Application log

Figure 3 - Application log.

Figure 3 – Application log.

You will see all the application log events. Log events are categorised into information, error and warning. ClearWaterWatcher generated events will have a source set to ClearWaterWatcher. You can filter the view just to see ClearWaterWatcher events by selecting View > Filter… from the menu and then selecting ClearWaterWatcher from the drop down Event source list (note: ClearWaterWatcher will only be in the list if there are actually any ClearWaterWatcher events in the log).

Figure 4 - ClearWaterWatcher log events.

Figure 4 - ClearWaterWatcher log events.

Figure 4 – ClearWaterWatcher log events.

By double clicking on an event you can view its properties.

Figure 5 - Event properties.

Figure 5 – Event properties.

It is strongly recommended that you check the event log on a regular basis for any reported errors. If your organisation has a systems management system in use (for example Microsoft System Center or Tivoli), then consider using this to monitor, alert and report on ClearWaterWatcher events in the windows application log.

Service Start

If you have configured the service start type to be automatic, then the service will be started automatically every time the computer is rebooted. Otherwise run Windows Service Manager and then double click ClearWaterWatcher to open the properties dialog.

Figure 6 - Service properties.

Figure 6 – Service properties.

Click the Start button. A progress bar is displayed and the service status is changed to Started if the service is successfully started. If the service cannot start then an error message will be displayed and the service will remain in the Stopped state.

Figure 7 - Service properties.

Figure 7 – Service properties.

When the service is started it first reads and checks the configuration file. Checks include:

  • Testing that the InputPath exists
  • Check that if FeedFromDTS is enabled FeedFilter is set to “*.dat”
  • Testing that the SuccessPath exists
  • Testing that the FailurePath exists
  • Testing that ClearWaterExe exists and can be run
  • Check that if SendSuccessEmailNotification is enabled at least one email address is defined in SuccessEmailList
  • Check that if SendFailureEmailNotification is enabled at least one email address is defined in FailureEmailList

If a test or check fails an error event is written to the Windows Application Log and the service is not started. You should check the error event, correct the problem and then try to restart the service.

The service will then process all the data feed files it finds in the InputPath. It processes data feed files as described in the next section. These data feed files will have been received after the service was last stopped. If there are a large number of files there may be a delay while they are processed.

The service then starts watching the InputPath for new data feed files received. Specifically it watches for any new file that matches the FeedFilter. When it sees a new file it processes the file as described in the next section.

The service finally on start up writes an information event to the Windows Application Log to say that “ClearWaterWatcher Service Has Started”.

Note – the service only reads its configuration file when it is started. Therefore if you need to make a change to its configuration you should:

  • Make the changes in the configuration file
  • Stop the service
  • Start the service

Processing Data Feed Files

A data feed file is processed by running ClearWaterCmd with the full path name of the file given as the only command argument. If there is a problem running ClearWaterCmd then an error event is written to the Windows Application Log, the file is left in InputPath and no further processing steps are taken for the file.

If ClearWaterCmd reports a failure in loading the file the following processing steps occur:

STEP 1: An information event is written to the Windows Application Log that includes the reason for the failure as reported by ClearWaterCmd to its standard output. You will need to look in ClearWaterCmd’s error log for more detailed information about the cause of the failure.

STEP 2: The file is moved from InputPath to FailurePath. If there is a problem in doing this an error event is written to the Windows Application Log, the file is left in the InputPath folder and the next processing step is taken.

STEP 3: If FeedFromDTS is enabled then there should be a control file with the same name as the data file but a file extension of .ctl. The control file should have been created before the data file in the folder by DTS. The existence of the control file is first checked for. If it cannot be found an error event is written to the Windows Application Log and the next processing step is taken. If found the file is moved from InputPath to FailurePath. If there is a problem in doing this an error event is written to the Windows Application Log, the file is left in InputPath and the next processing step is taken.

STEP 4: If SendFailureEmailNotification is enabled, then to each email address defined in FailureEmailList an email is sent. The format of the email is:

Figure 8 - Failure email.

Figure 8 – Failure email.

If there is a problem in sending an email an error event is written to the Windows Application Log.

If ClearWaterCmd reports a success in loading the file the following processing steps occur:

STEP 1: An information event is written to the Windows Application Log.

STEP 2: The file is moved from InputPath to SuccessPath. If there is a problem in doing this an error event is written to the Windows Application Log, the file is left in the InputPath folder and the next processing step is taken.

STEP 3: If FeedFromDTS is enabled then there should be a control file with the same name as the data file but a file extension of .ctl. The control file should have been created before the data file in the folder by DTS. The existence of the control file is first checked for. If it cannot be found an error event is written to the Windows Application Log and the next processing step is taken. If found the file is moved from InputPath to SuccessPath. If there is a problem in doing this an error event is written to the Windows Application Log, the file is left in InputPath and the next processing step is taken.

STEP 4: If SendSuccessEmailNotification is enabled, then to each email address defined in SuccessEmailList an email is sent. The format of the email is:

Figure 9 - Success email.

Figure 9 – Success email.

If there is a problem in sending an email an error event is written to the Windows Application Log.

Service Pause

You can pause the started service by running Windows Service Manager and then double click ClearWaterWatcher to open the properties dialog.

Figure 10 - Service properties.

Figure 10 – Service properties.

Click the Pause button. A progress bar is displayed and the service status is changed to Paused if the service is successfully paused. If the service cannot be paused then an error message will be displayed and the service will remain in the Started state.

Figure 11 - Service properties.

Figure 11 – Service properties.

When the service is paused it stops watching the InputPath for new data feed files received. It then writes an information event to the Windows Application Log to say that “ClearWaterWatcher Service Has Paused”.

You may want to pause the service to be able to manage files within the InputPath without triggering the service to process them.

Service Resume

You can resume the paused service by running Windows Service Manager and then double click ClearWaterWatcher to open the properties dialog.

Figure 12 - Service properties.

Figure 12 – Service properties.

Click the Resume button. A progress bar is displayed and the service status is changed to Started if the service is successfully resumed. If the service cannot be resumed then an error message will be displayed and the service will remain in the Paused state.

Figure 13 - Service properties.

Figure 13 – Service properties.

When the service is resumed it restarts watching the InputPath for new data feed files received. It then writes an information event to the Windows Application Log to say that “ClearWaterWatcher Service Has Resumed”.

Note –  service resume will NOT process all the data feed files it finds in the InputPath that may have been received after the service was paused. It will only process new files received after it has been resumed. To process all the data feed files it finds in the InputPath that may have been received after the service was paused, you need to stop and then start the service.

Service Stop

You can stop the started service by running Windows Service Manager and then double click ClearWaterWatcher to open the properties dialog.

Figure 14 - Service properties.

Figure 14 – Service properties.

Click the Stop button. A progress bar is displayed and the service status is changed to Stopped if the service is successfully stopped. If the service cannot be stopped then an error message will be displayed and the service will remain in the Started state.

Figure 15 - Service properties.

Figure 15 – Service properties.

When the service is stopped it stops watching the InputPath for new data feed files received. It then writes an information event to the Windows Application Log to say that “ClearWaterWatcher Service Has Stopped”.

Source Code

The source code for ClearWaterWatcher is provided in the folder:

InstallLocation\ClearWaterWatcher\Dev

ClearWaterWatcher has been developed using Microsoft Visual C# 2010 Express. The Visual Studio solution file is called:

InstallLocation\ClearWaterWatcher\Dev\ClearWaterWatcher.sln

When opened by Microsoft Visual C# 2010 Express you will see one project as shown in figure 16.

Figure 16 - Microsoft Visual Express Project.

Figure 16 – Microsoft Visual Express Project.

The ClearWaterWatcher project contains the source code for the ClearWaterWatcher application. It contains the following objects shown in table 1.

Table 1 - ClearWaterWatcher project.

Table 1 – ClearWaterWatcher project.