|Tutorial #3: Configuring Scripts in HL7Connect|
Once a script is prototyped, you can configure HL7Connect to use it using the standard web interface for HL7Connect. This tutorial will continue to use the script developed in Tutorial #2
Scripts are assigned to specific events. All the events in HL7Connect are configured from the Global Options (/globals.ksp) or the relevent interface configuration page. This script should be attached to the OnKernelStart event, and this done through the Global Options page.
The script file developed in Tutorial #2 was placed in an arbitrary directory c:\temp. When the HL7Connect Service ("kernel") is configured to execute a script, the script file must be available to the kernel. Since the kernel runs as a service, mapped drives are not available and network shares may not be available. For this reason, the file should be copied onto a local drive for the kernel.
Copy the script from c:\temp where it was developed to <HL7Connect Root>\scripts. You do not need to copy the file to this location, but this a recommended practice
When any event is configured, the same information is required:
The full path name of the file that contains the script to run. $script$ maps the the directory <HL7Connect Root>\scripts, so that the filename $script$\test.js actually means c:\Program Files\HL7Connect\scripts\test.js (assuming that HL7Connect was installed to c:\Program Files\HL7Connect on the server).
You should not use mapped drives or network shares for this file
The name of the routine to call when running the script. This must be a routine that exists in the file identified. The name is case-sensitive for some languages.
A parameter to be passed to the script in event.parameter. The parameter is not required by HL7Connect but can be used in the script as required.
What to do if an error occurs. The following circumstances count as an error with the script:
- The Microsoft Scripting Engine fails to initialize
- The script language is unknown
- The script fails to compile
- The script or the HL7Connect API raises an exception and the script does not catch and handle the exception.
Whatever notifications have been selected for the script will execute, then the kernel will decide what to do about the error. There are 3 options:
Halt Service The kernel will abruptly terminate itself. No cleanup will be preformed Stop Interface The interface will be stopped. This is only available where the event is associated with an interface Ignore The error will be ignored
If this is selected, the Microsoft Script Debugger will be activated on errors in the scripts, or when the script calls "breakpoint". This should be used with care in a production environment, particular when responding to messaging related events, as many actions are time-related, and delays debugging can alter the behaviour of HL7Connect and systems it is interfacing to.
For this tutorial, enter $script$\test.js as the filename, and "test" as the procedure. Choose Halt Service as the on Error action. Save the changes.
If there is an error running this script, HL7Connect will fail to start. If the startup script is stopping HL7Connect from starting, and you still need to start HL7Connect to reconfigure the script setting, you can start HL7Connect in a safe mode in which no interfaces start, and the startup script does not run.