JSON-RPC

This documentation provides technical details of the Net LineDancer integration API. The Net LineDancer server exposes a JSON-RPC1 2.0 API over HTTPS for language neutral integration from external systems. There are many JSON-RPC 2.0 client libraries available for all major languages2. See the Examples directory for sample scripts in various languages.

The use of JSON-RPC means that the underlying data sent to or received from the server is in JSON (JavaScript Object Notation) format. All strings are encoded using UTF-8 encoding, no other encodings are supported.

In addition to the JSON-RPC 2.0 API, some import/export functions are accessed over standard HTTP mechanisms using GET/POST semantics.

The access URL for Net LineDancer is:

https://server/rest?j_username=``username``&j_password=password

Where server, username, and password are values correct for your installation.

The API documentation shows examples of “raw” JSON requests, but it is recommended that you use JSON-RPC libraries appropriate for your language of choice, which will handle the JSON generation for you.

1 http://www.jsonrpc.org/specification
2 http://en.wikipedia.org/wiki/JSON-RPC

Inventory

The inventory API provides the core functionality of manipulating devices in the Net LineDancer inventory, including: adding devices, deleting devices, modifying devices, searching devices, etc.

See the Inventory Objects section for a description of the various objects consumed and returned by these APIs.

Inventory.createDevice

Add a device to the inventory, in the specified network. If the device was created successfully, the return value is null, otherwise an error message is returned.

Parameters

Parameter Type Description
network String Name of an existing network, e.g. “Default”
ipAddress String IPv4 or IPv6 address
adapterId String The ID of the adapter to use for backup, see Appendix A

Return: an error message or null

Inventory.deleteDevice

Delete a device from the inventory.

Parameters

Parameter Type Description
network String Name of an existing network, e.g. “Default”
ipAddress String IPv4 or IPv6 address

Return: null

Inventory.getDevice

The Inventory.getDevice method returns a Device object as described above, or null if the requested device does not exist.

Parameters

Parameter Type Description
network String Name of an existing network, e.g. “Default”
ipAddress String IPv4 or IPv6 address

Return: Device object or null

Inventory.updateDevice

The Inventory.updateDevice method is used to update an existing device in the inventory. It requires only network and ipAddress as parameters, all other parameters are optional.

Parameter Type Description
network String Name of the device’s network
ipAddress String IPv4 or IPv6 address
newNetwork String A new Network name for the device, or null
newIpAddress String A new IP address for the device, or null
newAdapterId String A new AdapterId for the device, or null
newHostname String A new Hostname for the device, or null

Return: null

Python Example:

error = netld.call('Inventory.updateDevice', 'Default', '10.0.0.1', null, null, null, 'newhostname')

Inventory.updateDevices

The Inventory.updateDevices method updates Adapter IDs and/or custom field values for multiple devices in a single operation.

Parameter Type Description
ipCsv String A comma separated list of devices of the form IPAddress@network
adapterId String The new adapter ID or null if it should remain unmodified.
customFields String Array An indexed array of custom fields

The ipCsv parameter is a comma separated list of devices of the form IPAddress@network (e.g. 192.168.0.254@NetworkA,10.0.0.1@NetworkB).

The adapterId parameter is either a new Adapter ID to assign to the specified devices, or null to leave the device’s Adapter ID at their current values. See Appendix A for a list of valid Adapter IDs.

The customFields parameter is an array of UTF-8 string values. The first element of the array corresponds to the Custom 1 custom field, and the fifth element corresponds to the Custom 5 custom field. Elements of the customFields array that are null will leave the corresponding custom fields at their current values.

Return: null

Python example:

netld.call('Inventory.updateDevices',
           '192.168.0.254@NetworkA,192.168.0.252@NetworkA',
           null,
           ['Tokyo HQ', 'Rack 1F-8'])

Inventory Objects

Device

Field Type Description
ipAddress String The IPv4 or IPv6 address of the device
hostname String The hostname of the device
network String The name of the managed network that the device resides in
adapterId String The NetLD “Adapter ID” used to manage this device
deviceType String The type of the device, “router”, “switch”, “firewall”, etc.
hardwareVendor String The hardware vendor who manufactured the device
model String The model number of the device
softwareVendor String The operating system vendor of the device
osVersion String The vendor specific OS version number string
backupStatus String The backup status of the device (SUCCESS, FAILURE, INVALID_CREDENTIAL, etc.)
complianceState Integer The compliance status of the device (0=compliant, 1=unsaved changes, 2=policy violations)
lastBackup Integer The timestamp of the most recent backup (in Unix Epoch time milliseconds)
lastTelemetry Integer The timestamp of the most recent neighbor collection (in Unix Epoch time milliseconds)
memoSummary String The first 60 characters of the device memo, or null
custom1 String The custom1 value, or null
custom2 String The custom2 value, or null
custom3 String The custom3 value, or null
custom4 String The custom4 value, or null
custom5 String The custom5 value, or null
serialNumber String The chassis serial number of the device, or null if not available

PageData

Attribute Type Description
offset Integer The starting offset in the results to begin retrieving pageSize number of Device objects. This value is required when PageData is used as a parameter.
pageSize Integer The maximum number of Device objects to retrieve in a single method call. This value is required when PageData is used as a parameter.
total Integer This value is set and retrieved from the server when an offset of zero (0) is passed. This indicates the total number of Device objects available. This value is ignored when PageData is used as a parameter.
devices Array An array of Device objects. This value is ignored when PageData is used as a parameter.

Configuration

The configuration API provides the core functionality of retrieving configuration history and managing draft configurations.

Methods in this API return various “configuration objects” (e.g. ChangeLog) which encapsulate attributes of configuration history in Net LineDancer. These configuration objects are expressed in JSON format. The following JSON objects are returned by these APIs.

A Change object is expressed in JSON format seen here:

{
    "author": "smith",
    "path": "/running-config",
    "mimeType": "test-plain",
    "type": "A",
    "size": 4321,
    "previousChange": 1361241698,
    "revisionTime": 1361249887,
    "head": true,
    "hasMemo": false,
    "mappingType": "backup",
    "mappingId": "31"
}

Attribute Type Description
author String The netLD username who made the change that was recorded, if known. ‘n/a’ if not available.
path String The filesystem path of the configuration on the device
mimeType String The MIME-type of the configuration file. Possible values are ‘text/plain’, ‘application/octet-stream’ (binary), ‘application/x-tar’ (binary).
type String The kind of change recorded. Possible values are ‘M’ (modification to existing configuration), ‘A’ (addition of a never before seen configuration), ‘D’ (a deleted configuration)
size Integer The size of the configuration in bytes
previousChange Integer The timestamp of the previous configuration revision in milliseconds (in Unix Epoch time). Can be null.
revisionTime Integer The timestamp when the configuration was backed up, in milliseconds (in Unix Epoch time).
head Boolean “true” if this revision is the latest, “false” otherwise.
hasMemo Boolean “true” is there is a memo for this configuration, “false” otherwise.
mappingType String undocumented.
mappingId String undocumented.

A ChangeLog object is expressed in JSON format seen here:

{
    "timestamp": 2311232341,
    "changes": [<Change> objects]
}

Attribute Type Description
timestamp Integer The ‘Unix Epoch’ timestamp (in milliseconds) when the configuration was recorded
changes Array An array of Change objects, reflecting configurations that were captured at the same time (timestamp)

A PageData object is expressed in JSON format seen here:

{
    "offset": 0,
    "pageSize": 10,
    "total": 27,
    "changeLogs": [<ChangeLog> objects]
}
Attribute Type Description
offset Integer The starting offset in the results to begin retrieving pageSize number of ChangeLog objects.
pageSize Integer The maximum number of ChangeLog objects to retrieve in a single method call.
total Integer This value is set and retrieved from the server when an offset of zero (0) is passed. This indicates the total number of ChangeLog objects available.
changeLogs Array An array of ChangeLog objects

A Revision object is expressed in JSON format seen here:

{
    "path": "/running-config",
    "author": "n/a",
    "mimeType": "text/plain",
    "size": 4321,
    "previousChange": 1361241698,
    "content": <BASE64 ENCODED STIRING>
}
Attribute Type Description
path String The filesystem path of the configuration on the device
author String The netLD username who made the change that was recorded, if known. ‘n/a’ if not available.
mimeType String The MIME-type of the configuration file. Possible values are ‘text/plain’, ‘application/octet-stream’ (binary), ‘application/x-tar’ (binary).
size Integer The size of the configuration in bytes
previousChange Integer The timestamp of the previous configuration revision in milliseconds (in Unix Epoch time). Can be null.
content String The configuration file content, encoded in Base64 format

Configuration.retrieveSnapshotChangeLog

Retrieves the configuration history for the specified device.

Parameters

Parameter Type Description
network String Name of an existing network, e.g. “Default”
ipAddress String IPv4 or IPv6 address
pageData JSON Object A PageData object specifying the starting offset and pageSize.

Return: a PageData object

Sample Request JSON:

{
   "jsonrpc": "2.0",
   "method": "Configuration.retrieveSnapshotChangeLog",
   "params": {
              "network": "Default",
              "ipAddress": "192.168.0.254",
              "pageData": {
                           "offset": 0,
                           "pageSize": 10
                          }
             },
   "id": 1
}
The PageData object that is returned will contain an attribute called changeLogs, which is an array of ChangeLog objects.
If the initial offset that is passed is zero (0), the returned PageData object will also contain a populated total attribute,
telling you how many total results are available. By incrementing the offset by pageSize you can retrieve subsequent pages of
results. When offset + pageSize is greater than or equal to total there are no more results available.

Sample Response JSON:

{
   "jsonrpc": "2.0",
   "id": 1,
   "result": {
      "offset": 0,
      "pageSize": 10,
      "total": 1,
      "changeLogs": [
         {
            "changes":[
               {
                  "author": "brettw",
                  "path": "/running-config",
                  "mimeType": "text/plain",
                  "type": "A",
                  "size": 1601,
                  "previousChange": 1400922143000,
                  "revisionTime": 1410324618000,
                  "mappingType": "backup",
                  "mappingId": 4,
                  "hasMemo": false,
                  "file": false,
                  "head": true
               },
               {
                  "author": "brettw",
                  "path": "/startup-config",
                  "mimeType": "text/plain",
                  "type": "A",
                  "size": 1601,
                  "previousChange": 1400922143000,
                  "revisionTime": 1410324618000,
                  "mappingType": "backup",
                  "mappingId": 4,
                  "hasMemo": false,
                  "file": false,
                  "head": true
               }
            ],
            "timestamp": 1410324618000
         }
      ]
   }
}

Configuration.retrieveRevision

Retrieve a revision of a configuration for the specified device.

Parameters

Parameter Type Description
network String Name of an existing network, e.g. “Default”
ipAddress String IPv4 or IPv6 address
configPath String The path of the configuration file to retrieve. This should be the same value as the path attribute in a Change object.
timestamp Integer The timestamp (in Unix Epoch milliseconds) of the configuration to retrieve. This should be the same value as the revisionTime attribute in a Change object returned by retrieveSnapshotChangeLog. If timestamp is omitted, the latest revision is retrieved.

Return: a Revision object

Sample Request JSON:

{
   "jsonrpc": "2.0",
   "method": "Configuration.retrieveRevision",
   "params": {
              "network": "Default",
              "ipAddress": "192.168.0.254",
              "configPath": "/running-config",
              "timestamp": 1410324618000
             },
   "id": 1
}

Sample Response JSON:

{
   "jsonrpc": "2.0",
   "id": 1,
   "result": {
      "lastChanged": 1410324618000,
      "path": "/running-config",
      "author": "brettw",
      "mimeType": "text/plain",
      "size": 1601,
      "prevChange": null,
      "runStart": 0,
      "content": <Base64 encoded string>
   }
}

Credentials

The credentials API provides the core functionality for device authentication credentials in Net LineDancer.

Methods in this API return various “credentials objects” (e.g. CredentialConfig) which encapsulate attributes of specific credentials in Net LineDancer. These configuration objects are expressed in JSON format.

A dynamic CredentialConfig object is expressed in JSON format seen here:

{
   "priority": 1,
   "addressSet": {
      "addresses": [
         "0.0.0.0/0"
      ]
   },
   "name": "LVI",
   "managedNetwork": "Default",
   "flat": false
}

Here is an example of a static CredentialConfig object. Note the empty addresses list and flat value of true:

{
   "priority": 0,
   "addressSet": {
      "addresses": [ ]
   },
   "name": "Static",
   "managedNetwork": "Default",
   "flat": true
}
Attribute Type Description
priority Integer A lower priority number indicates higher placement in the list of credential configurations. These credentials will be tried before others with a higher number.
addressSet Object A container for “addresses”. Consider this a “fixed” element.
addresses String Array An array of IP Addresses, IP Wildcards, and IP/CIDR expressions the a “dynamic” CredentialConfig applies to. This should be empty for static credential configurations.
name String The name of the CredentialConfig as seen in the user interface.
managedNetwork String The name of the network that this configuration applies to. If there are no user-created networks this value should be Default.
flat Boolean true if the CredentialConfig represents a “static” configuration, false if it is dynamic.

An example CredentialSet object is expressed in JSON format seen here:

{
   "name": "Lab Credentials #1",
   "username": "lvi",
   "password": "lvi",
   "enableUsername": "lvi",
   "enablePassword": "lvi",
   "roCommunityString": "public",
   "snmpUsername": "v3user",
   "snmpAuthPassword": "v3pass",
   "snmpPrivPassword": "v3priv",
   "priority": 0
}
Attribute Type Description
name String Name of the credential set. In the case of dynamic credentials this is any user defined name; for static credentials the name MUST be an IP address (IPv4 or IPv6).
username String The VTY username
password String The VTY password
enableUsername String The enable username
enablePassword String The enable password
roCommunityString String The SNMP read-only community string
snmpUsername String The SNMPv3 username
snmpAuthPassword String The SNMPv3 password
snmpAuthPriv String The SNMPv3 private password
priority Integer A lower priority number indicates higher placement in the list of credential sets. These credentials will be tried before others with a higher number. Inapplicable to static credentials

An example PageData object is expressed in JSON format seen here:

{
    "offset": 0,
    "pageSize": 10,
    "total": 27,
    "credentialSets": [<CredentialSet> objects]
}
Attribute Type Description
offset Integer The starting offset in the results to begin retrieving pageSize number of CredentialSet objects.
pageSize Integer The maximum number of CredentialSet objects to retrieve in a single method call.
total Integer This value is set and retrieved from the server when an offset of zero (0) is passed. This indicates the total number of CredentialSet objects available.
credentialSets Array An array of CredentialSet objects

Credentials.getCredentialConfig

Retrieves a single credential configuration CredentialConfig object.

Parameters

Parameter Type Description
network String Name of an existing network, e.g. “Default”
configName String Name of a dynamic or static credential configuration

Return: a CredentialConfig object

Sample Request JSON:

{
   "jsonrpc": "2.0",
   "method": "Credentials.getCredentialConfig",
   "params": {
              "network": "Default",
              "configName": "LogicVein"
             },
   "id": 1
}

Sample Response JSON:

{
   "jsonrpc": "2.0",
   "id": 1,
   "result": {
      "priority": 2,
      "addressSet": {
         "addresses": [
            "0.0.0.0/0"
         ]
      },
      "name": "LogicVein",
      "managedNetwork": "Default",
      "flat": false
   }
}

Credentials.saveCredentialConfig

Save a single credential configuration. This method can be used to save a new configuration, or renaming an existing one. Note: after call this method you must call the commitEdits or discardEdits method. If you are making many changes, it is recommended that all changes are should be made before a final call to commitEdits.

Parameters

Parameter Type Description
network String Name of an existing network, e.g. “Default”
oldConfigName String When renaming a credential configuration, this value should be the “old” (original) name of the configuration, and object in the credentialConfig parameter should contain the new name. This can be null in all other cases.
credentialConfig Object A CredentialConfig object

Return: the updated CredentialConfig object

Sample Request JSON:

{
   "jsonrpc": "2.0",
   "method": "Credentials.saveCredentialConfig",
   "params": {
              "network": "Default",
              "oldConfigName": "LogicVein",
              "credentialConfig": {
                                   "priority": 1,
                                   "addressSet": {
                                                  "addresses": [ "0.0.0.0/0" ]
                                                 },
                                   "name": "LogicVein2",
                                   "managedNetwork": "Default",
                                   "flat": false
                                  }
             },
   "id": 1
}

Credentials.deleteCredentialConfig

Delete a single credential configuration. Note: after call this method you must call the commitEdits or discardEdits method. If you are making many changes, it is recommended that all changes are
should be made before a final call to commitEdits.

Parameters

Parameter Type Description
network String Name of an existing network, e.g. “Default”
configName String Name of a dynamic or static credential configuration

Return: nothing

Sample Request JSON:

{
   "jsonrpc": "2.0",
   "method": "Credentials.deleteCredentialConfig",
   "params": {
              "network": "Default",
              "configName": "LogicVein"
             },
   "id": 1
}

Credentials.getCredentialSets

Get the credential sets associated with a specified credential configuration.

Parameters

Parameter Type Description
pageData Object A credentials page data object (see above)
network String Name of an existing network, e.g. “Default”
configName String Name of a dynamic or static credential configuration
ipOrCidr String Can be to search among static CredentialSets based on IP or IP/CIDR, can be “null”
sortColumn String Should be “null” for dynamic configurations, or “ipAddress” for static credential configurations
descending Boolean The sort order of the CredentialSet objects, only applicable to static configurations

Return: A PageData object containing a collection of CredentialSet objects

The PageData object that is returned will contain a property called credentialSets, which is an array of CredentialSet objects. If the initial offset that is passed is zero (0),
the returned PageData object will also contain a populated total attribute, telling you how many total results are available. By incrementing the offset by pageSize you can
retrieve subsequent pages of results. When offset + pageSize is greater than or equal to total there are no more results available.

Sample Request JSON:

{
   "jsonrpc": "2.0",
   "method": "Credentials.getCredentialSets",
   "params": {
              "pageData": {
                           "offset": 0,
                           "pageSize": 10,
                           "total": 0,
                           "credentialSets": [ ]
                          },
              "network": "Default",
              "configName": "LogicVein",
              "ipOrCidr": null,
              "sortColumn": "ipAddress",
              "descending": false
             },
   "id": 1
}

Sample Response JSON:

{
   "jsonrpc": "2.0",
   "id": 1,
   "result": {
      "offset": 0,
      "pageSize": 10,
      "total": 2,
      "credentialSets": [
         {
            "name": "Lab Credentials #1",
            "username": "lvi",
            "password": "lvi",
            "enableUsername": "lvi",
            "enablePassword": "lvi",
            "roCommunityString": "public",
            "snmpUsername": "",
            "snmpAuthPassword": "",
            "snmpPrivPassword": "",
            "priority": 0
         },
         {
            "name": "Lab Credentials #2",
            "username": "test",
            "password": "test",
            "enableUsername": "test",
            "enablePassword": "test",
            "roCommunityString": "public",
            "snmpUsername": "test",
            "snmpAuthPassword": "test",
            "snmpPrivPassword": "test",
            "priority": 1
         }
      ]
   }
}

Static credential sets will look identical to dynamic credential sets with the exception that the name property will contain the IP address of the device that the credential set is associated with.

Credentials.saveCredentialSets

Save a collection of credential sets. Note: after call this method you must call the commitEdits or discardEdits method. If you are making many changes, it is recommended that all changes are
should be made before a final call to commitEdits.

Parameters

Parameter Type Description
network String Name of an existing network, e.g. “Default”
configName String Name of a dynamic or static credential configuration
credentialSets Array An array of CredentialSet objects

Return: nothing

Sample Request JSON:

{
   "jsonrpc": "2.0",
   "method": "Credentials.saveCredentialSets",
   "params": {
              "network": "Default",
              "configName": "LogicVein",
              "credentialSets": [
                  {
                     "name": "Lab Credentials #1",
                     "username": "newUsername",
                     "password": "lvi",
                     "enableUsername": "newEnable",
                     "enablePassword": "lvi",
                     "roCommunityString": "public",
                     "snmpUsername": "",
                     "snmpAuthPassword": "",
                     "snmpPrivPassword": "",
                     "priority": 0
                  }
              ]
             }
   "id": 1
}

Credentials.deleteCredentialSets

Delete a collection of credential sets. Note: after call this method you must call the commitEdits or discardEdits method. If you are making many changes, it is recommended that all changes are should be made before a final call to commitEdits.

Parameters

Parameter Type Description
network String Name of an existing network, e.g. “Default”
configName String Name of a dynamic or static credential configuration
credentialSets Array An array of CredentialSet objects

Return: nothing

Sample Request JSON:

{
   "jsonrpc": "2.0",
   "method": "Credentials.deleteCredentialSets",
   "params": {
              "network": "Default",
              "configName": "LogicVein",
              "credentialSets": [
                  {
                     "name": "Old Credentials #1",
                     "username": "lvi",
                     "password": "lvi",
                     "enableUsername": "newEnable",
                     "enablePassword": "lvi",
                     "roCommunityString": "public",
                     "snmpUsername": "",
                     "snmpAuthPassword": "",
                     "snmpPrivPassword": "",
                     "priority": 0
                  },
                  {
                     "name": "Old Credentials #2",
                     "username": "test",
                     "password": "test",
                     "enableUsername": "test",
                     "enablePassword": "test",
                     "roCommunityString": "public",
                     "snmpUsername": "",
                     "snmpAuthPassword": "",
                     "snmpPrivPassword": "",
                     "priority": 1
                  }
              ]
             }
   "id": 1
}

Scheduler

NOTE: This API has significant and incompatible changes in the next major release. You will need to update any scripts that use these APIs.

The scheduler API provides access to job management, scheduling and execution. Job types include tools, configuration backup, Smart Changes, and reports.

See the Scheduler Objects section for a description of the various objects consumed and returned by these APIs.

Scheduler.addJob

Save (or replace) the job defined by the specified JobData.

Parameters

Parameter Type Description
jobData JobData A JobData job definition object
replace Boolean true if an existing job with the same name replaced, false otherwise

Return: the JobData object with jobId property populated.

Scheduler.deleteJob

Delete the specified job.

Parameters

Parameter Type Description
managedNetwork String The name of the network in which the job is defined
jobName String The name of the job to delete

Return: true if the Job was deleted successfully, false otherwise

Scheduler.getJob

Get the JobData for the specified device.

Parameters

Parameter Type Description
managedNetwork String The name of the network in which the job is defined
jobName String The name of the job

Return: a JobData object.

Scheduler.scheduleJob

Create a “trigger” (schedule) for a job.

Parameters

Parameter Type Description
triggerData TriggerData The schedule (trigger) definition

Return: an updated TriggerData object.

Scheduler.unscheduleJob

Delete a “trigger” (schedule) for a job.

Parameters

Parameter Type Description
managedNetwork String The name of the network in which the schedule is defined
triggerData String The schedule (trigger) name
jobName String The name of the job

Return: a boolean, true if the trigger was found and deleted.

Scheduler.runNow

Execute a job defined by the specified JobData.

Parameters

Parameter Type Description
jobData JobData A JobData job definition object

Return: an ExecutionData object.

Scheduler.runExistingJobNow

Execute a job defined by the specified JobData.

Parameters

Parameter Type Description
managedNetwork String The name of the network in which the job is defined
jobName String The name of the job to run

Return: an ExecutionData object.

Scheduler.getExecutionDetails

Get paged ExecutionData objects representing the execution history of jobs in the scheduler.

Parameters

Parameter Type Description
pageData ExecutionPageData Page object for execution data
sortColumn String The name of an ExecutionData attribute to sort by, null for default sort order
descending Boolean true if the sort should be descending

Return: an updated ExecutionPageData object.

Scheduler.getExecutionDataById

Get an ExecutionData object by its id for a specific job execution.

Parameters

Parameter Type Description
executionId Integer The ID of a specific job execution, obtained from the ExecutionData object returned when it was run or from the Scheduler.getExecutionDetails API.

Return: an ExecutionData object.

Scheduler Objects

JobData

Field Type Description
jobName String The name of the job
description String The description of the job
managedNetwork String The name of the network in which the job is defined
jobType String One of the pre-defined NetLD job types (see below)
jobParameters Map A map (hash) of job parameter name/value pairs that are specific to each jobType (see below)

TriggerData

Field Type Description
triggerName String The name of the schedule (trigger)
jobName String The name of the job
jobNetwork String The name of the network in which the schedule (trigger) is defined
timeZone String The timezone name
cronExpression String The cron expression

ExecutionData

Field Type Description
id Integer The execution ID
jobName String The name of the job
managedNetwork String The name of the network in which the job is defined
executor String The username of the user who executed the job
startTime 64-bit Integer The start time of the job as a Unix epoch value
endTime 64-bit Integer The end time of the job as a Unix epoch value. This value is null until the job has completed execution, and can be used to “poll” the execution status until this value becomes non-null.
completionState Integer 0=normal, 1=cancelled, 2=misfired (schedule missed)
status String One of: “OK”, “WARN”, “ERROR”, “ABORT”

ExecutionPageData

Attribute Type Description
offset Integer The starting offset in the results to begin retrieving pageSize number of ExecutionData objects.
pageSize Integer The maximum number of ExecutionData objects to retrieve in a single method call.
total Integer This value is set and retrieved from the server when an offset of zero (0) is passed. This indicates the total number of ExecutionData objects available. This value is ignored when ExecutionData is used as a parameter.
executionData Array An array of ExecutionData objects. This value is ignored (and optional) when ExecutionPageData is used as a parameter.

Job Types

Type Name Type Description
“Backup Configuration” Network device configuration backup.
“Bulk Update” SmartChange execution.
“Discover Devices” Network device discovery.
“Script Tool Job” Pre-definied read/write tool execution.

Job Parameters (per Job Type)

Job parameters are stored in a map (hash) of string name/value pairs. All job parameter names and values are UTF-8 strings. Even “Boolean” and “Integer” values should be stored as strings such as “true” or “5432”.

Most (but not all) jobs share a common set of “device resolution” parametersused to specify the set of devices that the job applies to (see Device Resolution Parameters)

Device Resolution Parameters

The documentation below for each specific type will declare whether these values are applicable.

Name Type Value Description
ipResolutionScheme String A single scheme name, or comma-separated list of scheme names. See Inventory.search for documentation regarding supported values.
ipResolutionData String The query associated with the scheme(s) specified. If there are multiple schemes specified, the query parameter should contain new-line (\n) characters between each query scheme query string. See Inventory.search documentation for examples of multi-scheme query values.
managedNetwork String The name of the network in which the devices are resolved. This value should be the same as the managedNetwork defined in the JobData object.

“Backup Configuration”

Ruby example:

job = {
    'managedNetwork' => 'Headquarters',
    'jobName' => "HQ backup",
    'jobType' => 'Backup Configuration',
    'description' => '',
    'jobParameters' => {
        'ipResolutionScheme' => 'ipAddress',
        'ipResolutionData' => '192.168.0.0/16',
        'managedNetwork' => 'Headquarters'
    },
}

execution = netld['Scheduler.runNow', job]

“Bulk Update”

  • Device resolution parameters required.

In version 14.06 Scheduler.addJob is not supported for this job type. Only Scheduler.runExistingJobNow is currently supported. This means that the SmartChange (“bulk update”) must first be created through the browser user interface.

Name Type Value Description
replacementMode String Valid values are: “perdevice” or “perjob”.
templateXml String This string property should be copied verbatim from the JobData object for the SmartChange, retrieved from the Scheduler.getJob API.
replacements String An XML string defining the replacement values to be applied to the SmartChange template. See the documentation below for specific format.

The “replacements” XML content is very similar between perdevice and perjob type SmartChanges.

In the “perjob” case, there is a single <config> tag defined, containing a <replacement> tag for each replacement defined in the SmartChange template. The “name” attribute of a <replacement> tag must match exactly the name of a replacement defined in the template. The “value” expressed between the opening and closing <replacement> tags must be a Base64 encoded value. This is the value that will be substituted in the template before execution.

Per-job example replacements XML

<configs>
  <config>
    <replacement name="IP Address">MTkyLjE2OC4wLjI1NA==</replacement>
    <replacement name="VLAN ID">MTAw</replacement>
  </config>
</configs>

The “perdevice” replacements XML is similar to the “perjob” XML, with two notable exceptions. The <config> tag must now contain a “device” attribute whose value is the IP address of the device, followed by an @ character, and finally a managed network name. Note that if the SmartChange job definition was created in a network called “Headquarters”, then a device that is defined to be in another networks, e.g. %2210.0.0.1@Default%22, will be ignored.

The second difference from a “perjob” XML definition is that there is one <config> and set of <replacement> tags for each device in the job.

Per-device example replacements XML

<configs>
  <config device="10.0.0.211@Default">
    <replacement name="IP Address">MTkyLjE2OC4wLjI2NB==</replacement>
    <replacement name="VLAN ID">MTIzNA==</replacement>
  </config>
  <config device="10.0.2.3@Default">
    <replacement name="IP Address">aWprbA==</replacement>
    <replacement name="VLAN ID">OTAxMg==</replacement>
  </config>
</configs>

Note: the replacements names of “IP Address” and “VLAN ID” are merely example replacement names, not pre-defined or required names.

“Discover Devices”

  • Device resolution parameters not required.
Name Type Value Description
communityStrings String Additional SNMP community string or comma-separated list of strings
boundaryNetworks String Comma-separated list of discovery boundary networks (CIDR)
crawl String A “boolean” value indicating whether the discovery should use neighbor/peer information to discover additional devices
includeInventory String A “boolean” value indicating whether the discovery should automatically include current inventory devices. This option is only meaningful when “crawl” is also set to “true”
addresses String A comma-separated list of IP address “shapes” to include in the discovery. See below.

Python example:

job_data = {
    'managedNetwork': 'Headquarters',
    'jobName': 'Discover lab devices',
    'jobType': 'Discover Devices',
    'description': '',
    'jobParameters': {
        'addresses': '10.0.0.0/24,10.0.1.0/24',
        'managedNetwork': 'Headquarters',
        'crawl': 'false',
        'boundaryNetworks': '10.0.0.0/8,192.168.0.0/16,172.16.0.0/12',
        'includeInventory': 'false',
        'communityStrings': 'public'
    }
}

execution = netld_svc.call('Scheduler.runNow', job_data)

Plugins

The plugins API provides access to tool job execution results.

NOTE: This API has significant and incompatible changes in the next major release. The name of this service endpoint is likely to change. You will need to update any scripts that use these APIs.

Plugins.getExecutionDetails

Get the list of ToolRunDetails, one per device, for the given scheduler execution ID. Note that currently only the SmartChange (“bulk update”) job contains accessible tool execution records.

Parameters

Parameter Type Description
executionId Integer The execution ID of the tool job.

Return: an array of ToolRunDetails objects or null

Plugins Objects

ToolRunDetails

Field Type Description
id Integer The ID of the tool detail record, used to retrieve the text of the detail from the detail URL endpoint (see below)
ipAddress String The IP address of the device of this detail record
managedNetwork String The name of the network in which the device is defined
executionId Integer The ID of the job execution
error String An error string if one exists, or null
gridData String A CSV of execution values, one row per device
startTime 64-bit Integer The start time of the job as a Unix epoch value
endTime 64-bit Integer The end time of the job as a Unix epoch value.

Some tools return all of their data in the gridData attribute, others contains additional textual output from the device, available from the URL endpoint below.

Individual output detail for each device in an execution is available through the following URL endpoint:

https://<host>/servlet/pluginDetail?executionId=<executionId>&recordId=<id>

Where <host> is the NetLD server, <executionId> is the job execution ID, and <id> is the individual record ID contained in the ToolRunDetails record for a specific device.

Typically, the Plugins.getExecutionDetails API is used to obtain a list of ToolRunDetails records, and then for each record (one per device) the URL endpoint is accessed to obtain the textual output from the device.

See the Python example scripts in the SDK for example uses.

Compliance

The compliance API provides access to compliance policies, rules, and violation information.

NOTE: This API has significant and incompatible changes in the next major release. You will need to update any scripts that use these APIs.

Compliance.getRuleSet

Get the compliance ruleset for the given ID

Parameters

Parameter Type Description
ruleSetId Integer The ID of the desired RuleSet object

Return: the RuleSet object or null

Compliance.getPolicies

Get the list of policies in a given managed networks.

Parameters

Parameter Type Description
network String The managed network

Return: an array of PolicyInfo objects

Compliance.getPolicy

Get the policy definition by ID.

Parameters

Parameter Type Description
policyId Integer The ID of the desired policy

Return: a Policy object or null

Compliance.getViolationsForDevice

Get the list of current violations for a given device.

Parameters

Parameter Type Description
network String The managed network of the device
ipAddress String The IP address of the device

Return: an array of Violation objects

Compliance.getViolationsForPolicy

Get the list of current violations for a given policy.

Parameters

Parameter Type Description
policyId Integer The ID of the desired violations policy

Return: an array of Violation objects

Compliance Objects

RuleSet

Field Type Description
ruleSetId Integer The rule set ID
ruleSetName String The name of the rule set
adapterId String The Adapter ID of the device
configPath String The device configuration this rule applies to
ruleSetXml String The rule set definition
networks Array An array of managed networks this rule set is available for
readOnly Boolean A boolean flag indicating whether or not this rule set is editable

PolicyInfo

Field Type Description
policyId Integer The policy’s ID
policyName String The name of the policy
network String The managed network the policy is in
enabled Boolean A boolean flag indicating whether or not this policy is enabled
coveredDevice Integer The number of devices covered by this policy
violatingDevices Integer The number of devices in violation of this policy

Policy

Field Type Description
policyId Integer The policy’s ID
policyName String The name of the policy
network String The managed network the policy is in
adapterId String The Adapter ID of the device
configPath String The device configuration this policy applies to
resolutionScheme String A single scheme name or comma-separated list of scheme names
resolutionData String The query associated with the scheme(s) specified

Violation

Field Type Description
policyId Integer The ID of the Policy in violation
ruleSetId Integer The ID of the RuleSet in violation
ipAddress String The IP Address of the device in violation
network String The managed network of the device in violation
message String The violation message
severity Integer The violation severity. 1 for WARNING, 2 for ERROR

Device Adapter IDs

Adapter ID
SonicWALL::SonicOS
A10::AX1000
Adtran::NetVanta
Alaxala::AXS
Alcatel::Omniswitch
AlliedTelesis::FS900M
AlliedTelesis::Series8700SL
AlliedTelesis::XSeries
AlliedTelesyn::Rapier
Alteon::AD3
Anritsu::PureFlowGS
APC::SmartUPS
Apresia
Aruba::ArubaOS
BlueCoat::ProxySG
Brocade::FabricOS
CheckPoint::SecurePlatform
Checkpoint::vpn1edge
Cisco::Three005
Cisco::ACNS
Cisco::Airespace
Cisco::ArrowPoint
Cisco::CatOS
Cisco::CS500
Cisco::GSS
Cisco::IOS
Cisco::Linksys
Cisco::LocalDirector
Cisco::MDS
Cisco::Nexus
Cisco::SecurityAppliance
Cisco::VxWorks
Cisco::WAAS
Cisco::WLSE
Citrix::NetScaler
Dell::PowerConnect
DLINK::DGS
Enterasys::Matrix
Enterasys::SecureStack
Enterasys::SSR
Enterasys::VerticalHorizon
Extreme::Switch
Extreme::XOS
F5::BigIP
F5::ThreeDNS
Fortinet::FortiGate
Foundry::EdgeIron
Foundry::FastIron
Fujitsu::SRS
Furukawa::FX
H3C::Switch
HP::ProCurve
HP::ProcurveM
Huawei::VRP
Juniper::DX
Juniper::JUNOS
Juniper::MSS
Juniper::ScreenOS
Mitsubishi::ST
NEC::IX2025
NEC::WA1020
Nortel::Accelar
Nortel::BayRS
Nortel::BayStack
Nortel::Contivity
Nortel::Passport
Nortel::Passport1600
Nortel::Tiara
Paloalto::PA500
Vyatta::OFR
YAMAHA::RT107e