Windows 1E NightWatchman Agent scripting reference

What NightWatchman power-off scripts do

NightWatchman is designed to ensure that systems are shut down or logged off in a consistent manner. This takes the onus off the user to shut down their machine and assists in desktop management, software delivery and energy saving.

Being able to shut down systems is only half the solution; the other half requires a means of saving open, edited files on the machine being shut down. In NightWatchman this task is performed by the power-off scripts.

Power-off scripts are run by NightWatchman before initiating a power-off. The purpose of the scripts is to protect unsaved data before power-off can commence by interacting with the open application windows.

A particular script is designed to shut down a particular process
The script for a process will run at least once for each running process
A particular script may be run multiple times if the process has multiple open documents
The scripts are designed to fail with an error if anything unexpected happens.

An important point to remember is that NightWatchman scripts are designed to protect data. In the event of any problems being encountered by the scripts the power down sequence will abort to prevent loss of data.

When NightWatchman begins a power-off or log-off operation, it performs the following sequence of actions for each top-most application window in each Windows session:

Find the process the window is running in.
Find a NightWatchman script in the NightWatchman scripts directory with the same name as the process.
Run the script with CScript.exe. The window handle (HWND) of each application window will be passed on the command line to the script.

Any given process may have multiple windows open, representing different documents. The corresponding scripts will be run in turn for each window. For example, you may be editing a number of documents in Microsoft Word. In this instance, there is one process that represents Microsoft Word and one corresponding NightWatchman power-off script. The script will be run multiple times, once for each open Microsoft Word document.

Power-off script development

There are many ways of developing NightWatchman power-off scripts. We recommend one particular way that makes the process of developing a script for a particular application easier. A NightWatchman power-off script can be written in VBScript to handle the intelligent shutdown of applications, so that no data is lost when performing a user log-off.

Setup the script.
1. Find the application's process name from Task Manager. For example, the process name for Microsoft Word is WINWORD.
2. Create a new script in the NightWatchman scripts directory with the same root name as the process. By default, the NightWatchman script directory is:
```
C:\Program Files\1E\NightWatchman\Scripts
```
  So, depending on the type of scripting language used, the script for a process calledACMEAPPis saved in this directory as:
```
ACMEAPP.vbs
```
  or
```
ACMEAPP.js
```
3. If you are creating a .vbs script, copy the contents of the ScriptTemplate.txt file (located in the Scripts folder under the NightWatchman installation directory) and paste into the new file created in step 2. Replace placeholders, for example do a global search and replace <Process Name> with ACMEAPP.
Gather information for the application.
1. Use a Windows spy utility, such as Spy++ to gather information on the application windows. These will be used in the script to access the interface for the application.
  - Determine the main application class type.
  - Find the child dialog classes.
  - Retrieve information about any message boxes that may require interaction when closing the application.
2. Determine if there are any automation objects for the application.
3. Check for embedded applications and other processes.
  - Find any Windows that are in different processes.
  - Determine any problems related to automation objects.
General script sequence.
The following sequence is used by all the provided NightWatchman power-off scripts – as such it is a tried and tested method for safely saving open files:
1. Find the application window.
2. Close all child dialogs.
3. Run expectors to help close dialogs.
4. Save and close documents from automation objects or Initiate a close.
5. Use expectors to handle save messages.
6. Save and close documents from the UI using SendKeys.
7. Wait and check that the application window closes.

Things to keep in mind

The following points should be kept in mind when developing NightWatchman power-off scripts:

NightWatchman script timeouts.
- Will the script you are writing be fast enough to complete before the NightWatchman script timeout expires?
- Should you extend the NightWatchman script timeout value?
When multiple applications of the same type are running.
- All the child dialogs of the applications can be closed generically.
- Be careful that applications are not switched over during closure.
Be aware of application states. You should know that applications may be in different states when the attempt at closure occurs. You need to cater for these in your scripts if you want to close successfully.
- Which windows can be open in the application?
- What messages are displayed in different circumstances during closure?
- Is there anything that could interrupt the sequence you are assuming in the power-off script?

Running and testing a new power-off script

The following points give indicators of how the newly developed NightWatchman script can be tested before being placed in a production environment.

Test the script from the command-line.
Before attempting to launch the script from a NightWatchman prompted power-off, test it in a stand-alone mode from a command line. To do this, start the target application with an open test document (nothing critical, just in case the closure fails) and run the power-off script.
Note
The majority of the functionality in the template script relies on the fact that the script helper is installed. This takes place when the NightWatchman Agent is installed, so the script cannot be tested until this is done.
The following shows an example command line for theacmeapp.vbsscript.
```
CScript acmeapp.vbs –DEBUG=7 
```
The use of the–DEBUG=7switch prompts any script based on thescripttemplat.txtfile to generate a debug log file, which is useful if the script fails to shut down the application.
What if the script fails.
Check the log file for the script. By default this is created in C:\temp as follows:
```
NWM<scriptname>.log file 
```
where<scriptname>is script. So the log file in our example is calledNWMACMEAPP.log
Rerun the script on a locked workstation.
After testing the script successfully from the command-line in a basic situation, re-run the script on a locked workstation. This simplest way of doing this is to add:
```
Wscript.Sleep( 5000 ) 
```
at the start of your power-off script. Then when running the script from the command-line, you have a reasonable amount of time to lock the workstation by hand before the main body of the script commences.
Test the script in situ with a NightWatchman power-off.
The final test is to have the new power-off script running alongside all the other NightWatchman power-off scripts. To do this, open and edit test documents in all the Microsoft Office applications and also have your target application open with an edited document. Then, trigger an immediate power-off from NightWatchman. This runs all NightWatchman power-off scripts enabling you to monitor their interaction and check for any immediate errors. If the power-off is successful, on restarting the machine, check all test documents have been saved correctly.

In this section:

NightWatchman Enterprise 7.3