GenieACS Provision Scripts and Making Sense of Declare

GenieACS provisioning scripts have a function named declare() but what that actually returns is extremely poorly documented.

This is my attempt to understand what this actually returns.

Fetching Values

Fetching values is important because it allows a script to determine what to do based on how a device is currently configured.

There are two scenarios. Fetching a non-wildcard path, and fetching a path containing a wildcard.

Non-Wildcard (or Scalar)

let obj = declare("DeviceID.Manufacturer", {value:now});

This returns a variable of type “object”. This consists of the keys:

{
  value: objValue,               // object (containing the value and value type)
  path: "DeviceID.Manufacturer", // path (string)
  size: 1
}

Where objValue is:

{
  0: "TP-Link",    // string (the value)
  1: "xsd:string", // string (the type)
  length: 2        //number
}

So this is pretty straightforward to fetch the value:

log( obj.value[0] );

Wildcard

How can I list all the leaf paths from a branch? Treat the result as an “iterator“.

let obj = declare("InternetGatewayDevice.WANDevice.*", {value:now});

for (let iter of obj) {
  log( iter.path );
}

// OUTPUTS:
//   InternetGatewayDevice.WANDevice.1
//   InternetGatewayDevice.WANDevice.2
//   InternetGatewayDevice.WANDevice.3
//   InternetGatewayDevice.WANDevice.X_TP_DSLNumberOfEntries

We can combine this with a regular expression to only display the enumerated leaves:

let obj = declare("InternetGatewayDevice.WANDevice.*", {value:now});

for (let iter of obj) {
  if ( ! /[.][0-9]+$/.test( iter.path ) )
    continue;

  log( iter.path );
}

// OUTPUTS:
//   InternetGatewayDevice.WANDevice.1
//   InternetGatewayDevice.WANDevice.2
//   InternetGatewayDevice.WANDevice.3

Deleting All Records

All the records under a branch can be deleted:

// path: 0 means zero instances under this branch
declare(`${wantedWANConnectionDevice}.WANPPPConnection.[]`, {path: now}, {path: 0});

Note that if the value of path is changed to a positive non-zero number then that specifies how many instances of that branch should exist/remain after that command (e.g. if path is 1 and there are no instances then create a new instance).

Creating New Record

(this section is untested)

A new record can be created using filter syntax which will cause the filtered parameters to be created as part of the record.

e.g.

declare(`${wantedWANConnectionDevice}.WANPPPConnection.[Username:${username},Password:${password},Enable:true]`, {path: now}, {path: 1});