Scripting Reference

With KeyConfigure's embedded JavaScript engine, you can write scripts that access, read, and modify the basic objects in KeyConfigure such as computers, policies, and products. You can also access and open new windows containing these objects, retrieve information from external sources using standards like ODBC and LDAP, and access network resources like web servers and e-mail.

This document provides detailed information on all of the objects and methods available within the scripting environment.

A separate Scripting Tutorial describes how to create JavaScript bundles that will be added to KeyConfigure's Tasks menu and to contextual menus as appropriate. It gives a walk-through of several scripts, starting from the most basic through a more complex script that prompts the user and makes changes to selected computers.

The scripting functionality uses Duktape, a JavaScript engine developed by Sami Vaarala that is a model of good design, coding, and documentation.

Global Objects

The program hosting a script will add some objects to the script's global namespace. These objects expose information to the script and provide access to resources related to the script.

{
  id: "org.domain.my-script",
  name: "My Script",
  script: "script.js"
}

var myobj = bundle.load("someobj.json");
// myobj contains the object defined in the JSON file

var myfile = bundle.load("something.txt");
myfile.forEach(function (line) {
  // line contains one line of the text file
});

var myfile = bundle.load("something.csv");
myfile.forEach({
  header: true,
  callback: function (row, header) {
    // row contains an array with values from one record in the CSV file
    // header contains an array with values from the header line of the CSV file
  }
});

var res = bundle.load("helper.js");
// res contains any result that the script might return

var flan = 2;
console.assert(flan <= 1, "too much flan");
// "too much flan" will be written to the console log

var flan = 2;
if (!(flan <= 1))
  console.error("too much flan");

console.time("my timer");
// some code you want to time
console.timeEnd("my timer");
// elapsed time will be written to the console log

Global Methods

The program hosting a script will add some methods to the script's global namespace. These methods provide some useful utility functions and give a way to control behavior of the host program.

alert("Your changes have been accepted.");

if (alert("Changes will be saved.", true)) {
  // user clicked OK
} else {
  // user clicked Cancel
}

var msg = decode("SGVsbG8sIFdvcmxkIQ==");
// msg -> "Hello, World!"

var hash = digest("SHA256", "Hello, World!");
// hash -> "DFFD6021BB2BD5B0AF676290809EC3A53191DD81C7F70A4B28688A362182986F"

var hmac = digest("HMAC-SHA1", "secret", "Hello, World!", "base64");
// hmac -> "iDqYLcKuRtIPfxBseGqSQbYNw0A="

var blob = encode("Hello, World!");
// blob -> "SGVsbG8sIFdvcmxkIQ=="

print("a line of text");

var answer = prompt({
  fields: [
    {
      id: "message",
      label: "Enter the Message:",
      type: "text"
    },
    {
      id: "frobnicate",
      label: "Run the Frobnication protocol",
      type: "bool"
    }
  ]
});
// answer is falsey if the user cancelled the dialog
if (answer) {
  // answer has the values provided by the user
  alert(answer.message);
  if (answer.frobnicate) {
    // ...
  }
}

quit();
// quit() does not return

var x = random(10);
// x -> 7

var s = random("0123456789ABCDEF", 16);
// s -> "C9E8933DBE3D2B7A"

sleep(3000);

Classes

Several classes are defined by the host program. There are classes for the various KeyServer-related data types, and classes that are based on widely used specifications. These classes are all implemented in native code for performance, and as a bridge between the host program and the script. Any complex script can define its own set of classes as well, using normal JavaScript patterns.

// the file object has been obtained in other code
var counters = { total: 0, empty: 0 };
file.forEach({
  context: counters,
  callback: function (line) {
    this.total++;
    if (!line.length)
      this.empty++;
  }
});

// the mapping was created in KeyConfigure
var imp = new KSImport("purchase", "My Purchase Schema");

// the submitted object is created in other code
imp.submit(...);
var stat = imp.status();
// only care about priority 0 through 4 (warning):
if (stat && stat.priority <= 4) {
  var desc = stat.summary
              || (stat.details && stat.details[0])
              || { code: "unspecified" };
  print("error " + desc.code + " on record " + stat.record + ": " + desc.comment);
}

{
  record: 1,
  code: 4211,
  priority: 4,
  level: "warning",
  summary: {
    code: 6201,
    priority: 6,
    level: "info",
    comment: "create Acme Widget 2017 20 Node"
  },
  details: [
    {
      code: 4211,
      priority: 4,
      level: "warning",
      field: "purchaseCurrency",
      value: "Federation Credits",
      comment: "unmapped string 'Federation Credits' for enumerated field 'purchaseCurrency'"
    },
    ...
  ]
}

// normally the mapping would be stored on the server,
// or would be loaded from the script's support folder
var imp = new KSImport("purchase", {
  Mappings: {
    "orderRecipient": "Recipient",
    "purchaseOrderID": "PO Number",
    "purchaseDescription": "Description",
    "purchaseQuantity": "Units",
    ...
  },
  ...
});
// normally field names would be derived from an external source
imp.open([
  "PO Number",
  "Recipient",
  "Description",
  "Units",
  ...
]);
// normally records would be retrieved from an external source
imp.submit([
  "27B/6",
  "Harry Tuttle",
  "Bentley WaterCAD",
  1,
  ...
]);
imp.close();

// the open call does not provide field names
imp.open();
// field names and values are provided on submittal
imp.submit({
  "PO Number": "27B/6",
  "Recipient": "Harry Tuttle",
  "Description": "Bentley WaterCAD",
  "Units": 1,
  ...
});
imp.close();

// normally the user would be prompted for the comment
var jour = new KSJournal("samp", "done");
jrnl.prepare({
  level: "notice",
  comment: "The deed is done"
});
jrnl.commit();

// this method can be called directly on the KSJournal class
KSJournal.register({
  type: "samp",
  code: "done",
  action: "enabled",
  name: "Sample Script has completed"
});

// get any object of the desired type
var view = new KSView("computer");
view.select();
view.forEach(function (obj) {
	// print out all the properties of the object
	for (var key in obj)
		print(key);
	// return true to end the enumeration
	return(true);
});

// the policy object has been obtained in other code
policy.name = "XYZWrite Policy";
policy.notes = "Name changed at " + (new Date()).toString();
policy.commit();

// the view object has been obtained in other code
var total = 0;
view.forEach(function (obj) {
   total++;
});

// the view object has been obtained in other code
var counters = { total: 0 };
view.forEach({
  context: counters,
  order: [ "name", "id" ],
  callback: function (obj) {
    this.total++;
  }
});

view.select({
  field: "name",
  match: [
    "Rosencrantz",
    "Guildenstern"
  ]
});

view.select("(name='Rosencrantz')||(name='Guildenstern')");

var ld = new Ldap("ldaps://server.ad.sample.net");

ld.search("dc=ad, dc=sample, dc=net",
  {
    attributes: [ "cn" ],
    filter: "(cn=Sam Pearson)",
    scope: "sub",
    callback: function (dn, entry) {
      print("match: " + dn);
      print("   cn: " + entry.cn);
    }
  });

var mail = new Mail("mail.sample.net");
mail.open();

var mail = new Mail("mail.sample.net");
if (!mail.open("somebody@sample.net", "s3cr3t")) {
    var error = mail.error();
    if (!error)
        alert("connection failed");
    else if (typeof error == "string")
        alert(error);
    else
        alert(error.join("\n"));
}

// the mail server must support PLAIN, LOGIN, or CRAM-MD5
var mail = new Mail("mail.sample.net");
mail.open("somebody@sample.net", "s3cr3t");

// the mail server must support OAUTHBEARER
var mail = new Mail("mail.sample.net");
mail.open("somebody@sample.net", "vF9dft4qmTc2...dGEuY29tCg==", 1);

var mail = new Mail("mail.sample.net");
mail.open("somebody@sample.net", "s3cr3t");
mail.send(
    "somebody@sample.net", // must use a plain e-mail address
    "jdoe@example.org",    // must use plain e-mail addresses
    {
        Subject: "Some Topic",
        From: "Some Body <somebody@sample.net>",
        To: "John Doe <jdoe@example.org>",
        body: "This is the body of the message."
    });

var db = new Odbc("DSN=TheDataSource");
db.open({ labelled: true });
db.prepare("SELECT name,age FROM People WHERE department = 'Staff'");
db.execute(function (row) {
    print(row.name + " is " + row.age + " years old");
  });
db.close();

var db = new Odbc({
    DSN: "TheDataSource"
  });

db.prepare("INSERT INTO People (name, age, department) VALUES ('Bilbo Baggins', 111, 'Acquisitions')");
db.execute({
    complete: function (res, err) {
      if (err)
        print("error inserting row: " + err);
    }
  });

version: 1

Prompt Field Types

The modal and non-modal user prompt mechanisms require a list of fields that the user will be asked to enter. Prompt fields can each have one of several available types. The fields are listed in an array of objects whose properties define the behavior.

{
  id: "message",
  type: "text",
  label: "Enter the Message:",
  default: "Hello, World!",
  required: false
}

{
  id: "guess",
  type: "long",
  label: "Pick a number (1-10):",
  min: 1,
  max: 10,
  required: true
}

{
  id: "save",
  type: "bool",
  label: "Save Changes",
  default: true
}

{
  id: "meeting_time",
  type: "date",
  label: "Meeting Time:",
  required: true
}

{
  id: "scary",
  type: "menu",
  label: "Scariest Beast:",
  options: [ "Lions", "Tigers", "Bears" ],
  default: 1
}

{
  id: "flavor",
  type: "menu",
  label: "Flavor:",
  options: [
    { label: "Vanilla", value: "fudge" },
    { label: "Chocolate", value: "city" },
    { label: "Strawberry", value: "fields" }
  ],
  default: "fudge"
}

{
  id: "listfile",
  type: "file",
  label: "List of Names:",
  required: true
}

{
  id: "policy",
  type: "aobj",
  label: "Policy:",
  table: "policy",
  required: true
}

{
  id: "passphrase",
  type: "pass",
  label: "Enter your Password:"
}

{
  id: "secret",
  type: "hide",
  default: "hide this from view"
}

{
  type: "note",
  label: "Please fill in the items below"
}

{
  type: "foot",
  label: "* Required"
}

Patterns

This section describes a few coding patterns that are typically used when writing scripts for extending KeyConfigure. There are many variations on the examples we'll give below, so they should be used to get an idea for how your scripts should work, and not strict, formal definitions for how they must work.

Main script closure pattern

The main script is loaded, parsed, and executed exactly as it is written. There are no separate entry points or “onXxxx” event handlers that need to be defined. However, the script should be contained within a simple closure that serves two purposes: it protects the global namespace from getting polluted with the script's variables, and it allows the script to return a value. Returning a value is necessary to implement non-modal user prompts.

The basic pattern looks like this:

(function () {

  // your script's code goes here

})();

One addition to this pattern is used when you return a value, for example when implementing a non-modal user prompt:

(function () {

  // your script's code goes here
  return( ... );

})();

There are other common JavaScript tricks you can use. For example you could pass certain commonly accessed global objects into the function that provides the closure. This might provide a small performance boost for longer more complex scripts.

Non-modal user prompt pattern

Many scripts will need to request some information from the user before they can proceed with their task. The best way to accomplish this is to use a non-modal user prompt dialog, which does not block the user from accessing other windows within KeyConfigure.

To have KeyConfigure display a non-modal prompt dialog your script must return an objec that describes what the prompt dialog should look like and what information it should request. Here is the general idea:

(function () {

  // your script can do some preliminary work here if necessary

  return({
    version: 1,
    setup: {
      title: "Title For Dialog",  // title is optional
      fields: [
        {
          // first field definition
          id: "a_field",
          ...
        },
        {
          // second field definition
          id: "another_field",
          ...
        }
      ]
    },
    proceed: function (params) {
      // more code to continue performing the script's task.
      // the values that the user provided are in params
    }
  });

})();

In this script we are returning a prompt object that tells KeyConfigure what to add to the prompt dialog, and what to do when the user fills out the requested information and clicks OK. Line 6 gives the object a version so KeyConfigure behavior will be the same for future releases. The setup.fields array on lines 9-20 lists the field descriptions in the order that they will be shown in the prompt dialog. See Prompt Field Types for information on the types of fields that can be used.

When the user click OK, KeyConfigure creates an object containing properties that match the id of each of the fields. This object is then passed to the proceed function defined by the script. In the sample code above we've defined two fields with ids ”a_field” (line 12) and ”another_field” (line 17). So the object passed to proceed will have properies with these same names, accessed like in the following code:

    ...
    proceed: function (params) {
      // more code to continue performing the script's task.
      // the values that the user provided are in params
      ... params.a_field ...
      ... params.another_field ...
    }
    ...

The type of each property depends on the type that was used when defining the corresponding field. Note that the name “params” is not special, and can be anything you want in your own scripts.

The proceed function is called only if the user clicks OK in the prompt dialog. If your script needs to know when the user clicks Cancel, provide a cancel function in the prompt object:

    ...
    cancel: function () {
      // user clicked the Cancel button
    }
    ...

Although it is best to limit the number of separate times the user is prompted for a given task, it is possible to “chain” prompt dialogs by returning a prompt object from the proceed (or cancel) function.

Progress feedback pattern

For tasks that run longer than a few seconds, KeyConfigure will display an “Activity” window with a progress bar. For simple scripts, KeyConfigure can handle the progress bar without extra help. When a script calls an iterating method like forEach(), KeyConfigure can advance the progress bar as the iteration proceeds.

More complex scripts that call more than one iterating method or otherwise run through a loop can give KeyConfigure hints about the stages of progress as they are performed. For example, this partial script calls two iterating methods:

  var list = [];
  app.selection.forEach(function (obj) {
    list.push(obj);
  }

  var viewport = new KSViewport("policy");
  viewport.view.forEach(function (obj) {
    list.push(obj);
  }

If this script happens to run long enough that the Activity window is displayed, you would see the progress bar fill from left to right as the first forEach method ran, and then again from left to right as the second forEach method ran. We can help KeyConfigure show a more unified progress by telling it how many iterations will be run, and when each one completes. To do this we'll use the app.progress object.

  app.progress.open(2);
  var list = [];
  app.selection.forEach(function (obj) {
    list.push(obj);
  }
  app.progress.advance();

  var viewport = new KSViewport("policy");
  viewport.view.forEach(function (obj) {
    list.push(obj);
  }
  app.progress.advance();
  app.progress.close();

In this new script we've still got all the code from the previous version, and we've added some progress hints. On line 1 we tell KeyConfigure that there are two main stages to our task. Once the first iteration is complete, we tell KeyConfigure (line 6) that we've completed a stage. Then again when the second iteration is finished we tell KeyConfigure (line 12). Finally on line 13 we indicate that the two-stage process is complete. The basic pattern is to call app.progress.open() with the number of stages in our task, then call app.progress.advance() that many times, and lastly balance the open() with a call to app.progress.close().

Now we'll look at a script that calls two iterating methods and runs one for loop:

  var list = [];
  app.selection.forEach(function (obj) {
    list.push(obj);
  }

  var viewport = new KSViewport("policy");
  viewport.view.forEach(function (obj) {
    list.push(obj);
  }

  for (var i = 0; i < list.length; i++) {
    // do something with list[i]
  }

Since the for loop is within the script, KeyConfigure cannot handle the progress bar for that loop. We can use the app.progress object to move the progress bar during that loop, and integrate that with the overall progress of the three main stages of our task:

  app.progress.open(3);
  var list = [];
  app.selection.forEach(function (obj) {
    list.push(obj);
  }
  app.progress.advance();

  var viewport = new KSViewport("policy");
  viewport.view.forEach(function (obj) {
    list.push(obj);
  }
  app.progress.advance();

  app.progress.open(list.length);
  for (var i = 0; i < list.length; i++) {
    // do something with list[i]
    app.progress.advance();
  }
  app.progress.close();

  app.progress.advance();
  app.progress.close();

The first difference is that we've told KeyConfigure, via the app.progress.open() method on line 1, that there are three stages in our script. So that is a promise that we'll advance() three times (on lines 6, 12, and 21) before we close() (on line 22).

We'll take care of the for loop using the same basic methods: first we call app.progress.open() on line 14 indicating the number of times we are going to go through the loop (list.length times). Then, as we progress through the loop we call advance(), line 17, resulting in the proper number of calls promised to open(). Then on line 19 we balance out the open() with a close().

Keep in mind that handling the progress feedback is completely optional, and does not affect what your script can do. The only way it matters is in how well the progress bar reflects the actual progress of your script, and that only matters if your script takes longer than a few seconds. There are a few other methods available in the app.progress object, see app.progress object.

Bundles

Script bundles are folders that contain the main script file, a manifest file that provides some information about what the script does, storage template files used to create persistent storage objects for the script to use, and other supporting files.

Bundle structure

The bundle folder must have the extension “.jst”. The manifest file, contents detailed below, must be named “manifest.json”. The manifest provides the name of the main script (default “script.js”). Storage files are placed in a folder named “storage”, and a “support” folder contains resources that the script can load.

bundle-name.jst

manifest.json

script.js

storage

localStorage.json

support

somefile.txt

somedata.json

Bundles for scripts that do not need persistent storage or don't have extra resource files can leave out the corresponding folders. Storage template files have some restrictions on their names, as described in the localStorage section. Files in the support folder can be “.js”, “.json”, “.plist”, “.csv”, or other plain text files and can have any name that does not include the characters “:”, “/”, or “\”.

Working with Bundles

Sometimes it is easier to transfer a bundle as an archive instead of as a folder with separate files. For example, JavaScript bundles provided by Sassafras Software are typically archived in a ZIP-formated .jst file. If you want to create your own jst archives in a way that KeyConfigure (and ks-jst) accept, you can use any ZIP program. Make sure that the ZIP file you create does not contain the bundle folder itself, and only the contents of that bundle folder. It is also easy to create jst bundle archives using the ks-jst command-line tool.

For macOS users, BBEdit provides a convenient way to edit archived bundles. Open a compressed bundle in BBEdit to edit any file in the bundle, then save and BBEdit will add the changes to the file within the compressed bundle. Adding new files to the bundle requires that you recompress the bundle folder.

Manifest properties

The manifest contains a single JSON-formatted object with properties that describe aspects of the script. The simplest manifest file looks like this:

{
  "id" : "org.domain.my-script",
  "name" : "My Script"
}

The manifest can also provide an alternate name for the main script file, and a “target” property that describes what type of object the script can work with:

{
  "id" : "org.domain.my-script",
  "name" : "My Script",
  "script" : "script.js",
  "target" : {
    "table" : "computer",
    "required" : true,
  }
}

ks-jst command-line tool

Scripts that do not require a selection of objects in order to run and do not need to open a viewport can be executed by a command-line tool named “ks-jst”. This tool is useful for running scripts on a schedule, or in other cases where the full user interface of KeyConfigure is not needed. There is basic support for user prompting and alerting. For scripts that are written to expect user input but must run unattended, there is a mechanism for providing the input via a JSON-formatted file.

The command line usage for ks-jst is:

ks-jst [options] [files...]

When a script runs in KeyConfigure it can share the authenticated connection that exists to the server. With ks-jst, if objects from the KeyServer are needed, the server's host must be given and an Administrator name and password must also be supplied. Bundled scripts can be run, and non-bundled scripts are also supported. You can even provide a sequence of JavaScript commands via the command line, and these will be executed in the order given.