The many services of NET SatisFAXtion are accessible from applications written in a variety of programming languages, including script languages such as VBScript and JavaScript.  Script applications can be launched in several ways, from ASP pages running on a web server to .VBS or .JS files launched from a menu short-cut

The NET SatisFAXtion Script Engine provides a way to simplify scripting, by starting and stopping scripts when NET SatisFAXtion itself starts and stops.  This is ideal for scripts that work closely with the fax server, using the CAS API.  For example, by being launched from the Script Engine, a script that examines the CSID on received faxes to determine routing will only be running when access to the fax server is assured.
 

Getting Started

Script execution begins with two "startup" script files, SystemStartup.js and CustomStartup.js, located in the "NET SatisFAXtion\Scripts" directory.  The SystemStartup.js script contains code to launch the "Logging & Fax Export" script as well as other scripts provided by FaxBack.  This file should never be modified, as it will be overwritten in future fax server updates.  However, the CustomStartup.js script, that works the same way as SystemStartup.js, will never be overwritten in future updates and is therefore safe for custom modification.  If CustomStartup.js does not exist, SystemStartup.js can be copied and used as a basis for CustomStartup.js.

Startup scripts must include a function called main() that accepts four parameters: iTags, casInst, sessionId, and scriptInst.  When the fax server loads, the Script Engine loads and parses each startup script, and then calls the script's main() function on a new thread.  The script can immediately access the fax server using the CAS API, and other operating system services such as Scripting.FileSystemObject can be used.

The scriptInst parameter passed to main() should be used with the IsCanceled CAS method to minimize CPU utilization from scripts that operate in a loop and perform tasks periodically, but otherwise remain idle during a sleep period.  When the fax server is stopped, IsCanceled returns a non-zero value, allowing the script to exit gracefully.

function main(iTags, casInst, sessionId, scriptInst)
  {
  var CAS = new ActiveXObject("CASX.CAS");
  
  while (CAS.IsCanceled(5000,scriptInst) == 0)
    {
      // TODO: This script is executed every 5 seconds
    }
  return(null);
  }        

Simplifying Development

Debugging scripts that are launched by the Script Engine can be a complicated process, but there are techniques that greatly simplify script development and debugging.  The main complexity arises from the way that the Script Engine quietly terminates scripts that encounter a syntax error or attempt to perform an illegal operation, such as use an uninitialized object.  Locating the source of the failure is up to the developer, but there are techniques that aid in this process.

Tracing the execution of a script can be accomplished using the OutputDebugString CAS method.  A string passed to this method is passed directly to the Win32 OutputDebugString() function, and is therefore picked up by any debugger or debug monitor.  Another technique, more appropriate for when the fax server is loaded as an application (not as a service), is the alert CAS method, that passes a string directly to the Win32 MessageBox() function.

function main(iTags, casInst, sessionId, scriptInst)
  {
  var CAS = new ActiveXObject("CASX.CAS");

  while (CAS.IsCanceled(5000,scriptInst) == 0)
    {
    CAS.alert("Hello!");

    CAS.OutputDebugString("See you in 5 seconds...");
    }

  return(null);
  }      

An easy way to run script in a separate process is to load it from an .HTA file (HTML Application).  The following example, ScriptTest.hta, is an HTA that loads CustomStartup.js, but calls main() by passing zeros for all parameters.  When started in this manner, all script errors and the line number where the error occurred are displayed.  The main() function in a script can easily detect that it is being loaded from an HTA by comparing the scriptInst parameter to 0.

<html>
<head>
<HTA:APPLICATION 
 APPLICATIONNAME="Script Test"
 BORDER="thin"
 CAPTION="yes"
 SHOWINTASKBAR="yes"
 SINGLEINSTANCE="no"
 WINDOWSTATE="normal"
>
<script language="JScript" src="CustomStartup.js"></script>
</head>
<body>
<input type=button value="Call main()" onclick="main(0,0,0,0)">
</body>
</html>