CLEARWATERWATCHER Guide

Transcription

1 ClearWaterWatcher Guide Programme Document Record ID Key Sub Prog / Project Project Manager Status Draft Owner Version 0.2 Author Mike Kelly Version Date 29/05/2012 CLEARWATERWATCHER Guide Crown Copyright 2012

2 Amendment History: Version Date Amendment History /05/2012 Template document /05/2012 Added uninstall section Reviewers: This document must be reviewed by the following: Name Signature Title / Responsibility Date Version Approvals: This document must be approved by the following: Name Signature Title / Responsibility Date Version Document Control: The controlled copy of this document is maintained in the NHS CFH Electronic Document and Records Management System. Any copies of this document held outside of that system, in whatever format (e.g. paper, attachment), are considered to have passed out of control and should be checked for currency and validity. Glossary of Terms: Terms, acronyms and abbreviations commonly used within NHS CFH can be found in the Glossary of Terms: If any terms are used in this document that are not currently included in the glossary please send them to cfh.glossary@nhs.net. Crown Copyright 2012 Page 2 of 24

3 Contents 1 Introduction Architecture Installation and Configuration Prerequisites Operating System NET Framework ClearWater Data Feed Source Deployment Package Installation Configuration Uninstallation ClearWaterWatcher User Guide Logging Service Start Processing Data Feed Files Service Pause Service Resume Service Stop Source Code Crown Copyright 2012 Page 3 of 24

4 1 Introduction ClearWaterWatcher is a windows service to automate the use of the ClearWater tool. For more information about ClearWater please refer to the ClearWater Guide which is part of the ClearWater deployment package which can be downloaded from: Crown Copyright 2012 Page 4 of 24

5 2 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 to a list of 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 to a list of 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. Crown Copyright 2012 Page 5 of 24

6 3 Installation and Configuration 3.1 Prerequisites Operating System Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP NET Framework.NET Framework 3.5 required. To check if.net Framework 3.5 is installed, confirm that the following folder is present on the computer: C:\WINDOWS\Microsoft.NET\Framework\v3.5.xxxx To download and install.net Framework 3.5 go to: ClearWater ClearWater must be installed and ClearWaterCmd must be configured using its configuration file. To download and install Clearwater go to: If you plan to use notifications from ClearWaterWatcher you must have both a SMTP host ClearWaterWatcher can connect to and an account on the SMTP host that ClearWaterWatcher can use to send s. For example NHSMail provides a SMTP host (accessible from the N3 network) defined as: Host name: send.nhs.net Port: 587 Encryption: TLS/SSL NOTE: The account you use will have an associated password that must be configured for ClearWaterWatcher. If this password is changed, then ClearWaterWatcher must be reconfigured. You may therefore find it useful to have a dedicated account created for ClearWaterWatcher on the SMTP host which has its password policy set to never require change. NOTE: If you plan to use notifications make sure any antivirus software is not using port blocking rules to stop applications and windows services from sending s. If it is you will need to configure the antivirus software to allow the ClearWaterWatcher windows service to send s on the SMTP port you have configured Data Feed Source A data feed source, such as DTS, must be available that will automatically deliver feed files to a named folder. Crown Copyright 2012 Page 6 of 24

7 3.2 Deployment Package CLEARWATERWATCHER - Guide ClearWaterWatcher has been developed using Microsoft Visual C# 2010 Express, the free development tool from Microsoft. This tool however does not support the creation of normal windows deployment packages (InstallShield or Setup Project), therefore the deployment package consists of a ZIP file called: ClearWaterWatcher.zip 3.3 Installation Unzip the contents of the deployment package (ClearWaterWatcher.zip) to a suitable folder on the computer (InstallLocation). The content of the zip file includes: \ClearWaterWatcher Top level folder. \ClearWaterWatcher\Bin Folder that contains executables. \ClearWaterWatcher\Bin\ClearWaterWatcher.exe ClearWaterWatcher application. \ClearWaterWatcher\Bin\ClearWaterWatcher.exe.config ClearWaterWatcher configuration file. \ClearWaterWatcher\Bin\InstallUtil.exe Microsoft Windows Service installation application. \ClearWaterWatcher\Bin\InstallUtilLib.dll Microsoft Windows Service installation DLL. \ClearWaterWatcher\Dev Folder that contains source code. \ClearWaterWatcher\Docs Folder that contains documentation. \ClearWaterWatcher\Docs\ClearWaterWatcher Guide vx.x This document. \ClearWaterWatcher\Test Data Contains a documented set of test cases with associated test data. You need to manually install ClearWaterWatcher as a Windows Service. You can install it on a server or on a desktop computer. You will need administrative privileges to be able to install ClearWaterWatcher as a Windows Service. Open a command prompt on the computer and change directory (CD) to the folder ClearWaterWatcher\Bin. Crown Copyright 2012 Page 7 of 24

8 Run the command: CLEARWATERWATCHER - Guide InstallUtil ClearWaterWatcher.exe You will see a series of progress messages from the command, ending with the message The transacted install has completed. ClearWaterWatcher is now installed as a Windows Service. To check that it is installed open the Windows Services Manager: Go to Start > Control Panel Crown Copyright 2012 Page 8 of 24

9 Open Administrative Tools CLEARWATERWATCHER - Guide Open Services You should see ClearWaterWatcher installed and not started. CAUTION: Do not start the ClearWaterWatcher service until you have configured it. Crown Copyright 2012 Page 9 of 24

10 3.4 Configuration CLEARWATERWATCHER - Guide The application uses the configuration file: InstallLocation\ClearWaterWatcher\Bin\ClearWaterWatcher.exe.config This is a.net application configuration file in XML format: <?xml version="1.0" encoding="utf-8"?> <configuration> <appsettings> <add key="inputpath" value="d:\clearwaterwatcher\test Data\Input"/> <add key="feedfromdts" value="true"/> <add key="feedfilter" value="*.dat"/> <add key="successpath" value="d:\clearwaterwatcher\test Data\Success"/> <add key="failurepath" value="d:\clearwaterwatcher\test Data\Failure"/> <add key="clearwaterexe" value="d:\clearwater\bin\clearwatercmd.exe"/> <add key=" host" value="smtphost"/> <add key=" port" value="25"/> <add key=" ssl" value="false"/> <add key=" username" value="username"/> <add key=" password" value="password"/> <add key=" address" value="clearwaterwatcher@somewhere.com"/> <add key="sendsuccess notification" value="true"/> <add key="success list" value="fred@somewhere.com;betty@somewhere.com"/> <add key="sendfailure notification" value="true"/> <add key="failure list" value="fred@somewhere.com"/> </appsettings> </configuration> You can change the configuration settings in this file by directly editing the file. The configuration file contains the following configuration items: InputPath FeedFromDTS FeedFilter SuccessPath FailurePath ClearWaterExe Full path name to the folder in which the data feed source will place files. UNC is supported. If true then data feed source is DTS. If false then data feed source is not DTS. The filter string used to determine what files are monitored for in InputPath. To watch changes in all files, set to an empty string (""). To watch for changes in a certain type of file, set to file type extension for example "*.txt". If FeedFromDTS is enabled this should be set to *.dat. Full path name to the folder in which data feed files are moved if ClearWaterCmd successfully loads the data. UNC is supported. Full path name to the folder in which data feed files are moved if ClearWaterCmd fails to load the data. UNC is supported. Full path name to the ClearWaterCmd.exe application. UNC is supported. Note: ClearWaterCmd MUST BE already configured using its Crown Copyright 2012 Page 10 of 24

11 own configuration file. Host Port SSL Username Password The SMTP host name either as a DNS name, for example send.nhs.net, or IP address, for example If using a DNS name make sure your local DNS service can resolve it, for example within a windows command prompt try: nslookup send.nhs.net If no notifications are required then either set to an empty value: value = Or leave current value as this configuration item is not used if no notifications are configured. The SMTP port number. The standard port number for SMTP is 25 and the standard port number for secured SMTP is 465. If no notifications are required then either set to a value of 0: value = 0 Or leave current value as this configuration item is not used if no notifications are configured. If true then a SSL/TLS encrypted connection will be made with the SMTP host. If false then an unencrypted connection will be made with the SMTP host. If no notifications are required then leave current value as this configuration item is not used if no notifications are configured. The username for the account ClearWaterWatcher will use to send notifications. If no notifications are required then either set to an empty value: value = Or leave current value as this configuration item is not used if no notifications are configured. The password for the account ClearWaterWatcher will use to send notifications. If no notifications are required then either set to an empty value: value = Or leave current value as this configuration item is not used if no notifications are configured. Address The address for the account ClearWaterWatcher will use to send notifications. If no notifications are required then either set to an empty Crown Copyright 2012 Page 11 of 24

12 value: value = Or leave current value as this configuration item is not used if no notifications are configured. SendSuccess Notification Success List SendFailure Notification Failure List If true then when a data feed file has been successfully loaded by ClearWaterCmd, an will be sent to all addresses defined in Success List. If false then when a data feed file has been successfully loaded by ClearWaterCmd no notifications will be sent. A list of one or more addresses to which an is sent if ClearWaterCmd successfully loads a data feed file. If more than one address is given, separate each address using the ; character. For example: value = fred@test.com;betty@test.com If no success notifications are required then either set to an empty value: value = Or leave current value as this configuration item is not used if no success notifications are enabled. If true then when a data feed file has failed to be loaded by ClearWaterCmd, an will be sent to all addresses defined in Failure List. If false then when a data feed file has failed to be loaded by ClearWaterCmd no notifications will be sent. A list of one or more addresses to which an is sent if ClearWaterCmd fails to load a data feed file. If more than one address is given, separate each address using the ; character. For example: value = fred@test.com;betty@test.com If no failure notifications are required then either set to an empty value: value = Or leave current value as this configuration item is not used if no failure notifications are enabled. As a windows service ClearWaterWatcher is installed with a default service configuration. Crown Copyright 2012 Page 12 of 24

13 To view or change this service configuration run Windows Service Manager and then double click ClearWaterWatcher to open the properties dialog. ClearWaterWatcher is installed with a startup type of Manual. This means that you will need to manually start the service from the Windows Service Manager. Every time the computer is rebooted you will need to manually start the service. You can change the startup type to Automatic which will then automatically start the service every time the computer is rebooted. ClearWaterWatcher is installed with log on as Local system account. This is the windows account the service will use to run. For a detailed description of local system account see: You can change the account used if required. Crown Copyright 2012 Page 13 of 24

14 The log on account must have the following privileges: Be able to read and write to the InputPath folder Be able to read and write to the SuccessPath folder Be able to read and write to the FailurePath folder Be able to read and execute ClearWaterCmd Be able to read and write to all folders and files ClearWaterCmd uses If ClearWaterCmd is configured to connect to SQL Server using integrated security, then the log on account must be added as a login account to SQL Server. Crown Copyright 2012 Page 14 of 24

15 3.5 Uninstallation CLEARWATERWATCHER - Guide To remove ClearWaterWatcher you need to manually uninstall ClearWaterWatcher as a Windows Service. You will need administrative privileges to be able to uninstall ClearWaterWatcher as a Windows Service. Open a command prompt on the computer and change directory (CD) to the folder ClearWaterWatcher\Bin. Run the command: InstallUtil /u ClearWaterWatcher.exe You will see a series of progress messages from the command, ending with the message The uninstall has completed. ClearWaterWatcher is now uninstalled as a Windows Service. Crown Copyright 2012 Page 15 of 24

16 4 ClearWaterWatcher User Guide 4.1 Logging ClearWaterWatcher logs both information and error events to the Windows Application Log. To view log events: Go to Start > Control Panel Open Administrative Tools Open Event Viewer and select the 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 Crown Copyright 2012 Page 16 of 24

17 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). By double clicking on an event you can view its 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. Crown Copyright 2012 Page 17 of 24

18 4.2 Service Start CLEARWATERWATCHER - Guide 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. 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. Crown Copyright 2012 Page 18 of 24

19 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 SendSuccess Notification is enabled at least one address is defined in Success List Check that if SendFailure Notification is enabled at least one address is defined in Failure List 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 4.3 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 Crown Copyright 2012 Page 19 of 24

20 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 SendFailure Notification is enabled, then to each address defined in Failure List an is sent. The format of the is: From: Address Subject: ClearWater data file load failure notification Body: ClearWater failed to load file: '<file name> because: <reason> If there is a problem in sending an 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 SendSuccess Notification is enabled, then to each address defined in Success List an is sent. The format of the is: From: Address Subject: ClearWater data file load success notification Body: ClearWater successfully loaded file: '<file name> If there is a problem in sending an an error event is written to the Windows Application Log. Crown Copyright 2012 Page 20 of 24

21 4.4 Service Pause CLEARWATERWATCHER - Guide You can pause the started service by running Windows Service Manager and then double click ClearWaterWatcher to open the properties dialog. 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. 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. Crown Copyright 2012 Page 21 of 24

22 4.5 Service Resume CLEARWATERWATCHER - Guide You can resume the paused service by running Windows Service Manager and then double click ClearWaterWatcher to open the properties dialog. 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. 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. Crown Copyright 2012 Page 22 of 24

23 4.6 Service Stop CLEARWATERWATCHER - Guide You can stop the started service by running Windows Service Manager and then double click ClearWaterWatcher to open the properties dialog. 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. 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. Crown Copyright 2012 Page 23 of 24

24 5 Source Code CLEARWATERWATCHER - Guide 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: The ClearWaterWatcher project contains the source code for the ClearWaterWatcher application. It contains the following objects: app.config ClearWaterWatcherInstaller.cs ClearWaterWatcher.cs Program.cs.NET application configuration file. C# class to install the application as a windows service. C# class for the main logic of the application. C# Main method that runs the application. Crown Copyright 2012 Page 24 of 24