DataCollectionTarget

Abstract class that represents any object that can collect data. Extends NetObj.

Instance attributes

From NetObj

aiHint: String: Hint for AI anomaly profile generation.

alarms ⇒ array: List of active Alarms for this object.

alarmStats ⇒ array: Integer array that consists of 5 numbers - each number represents number of alarms for this and child objects for each of severity.

alias: String: Object alias. For interfaces it is automatically collected on configuration poll (e.g. from SNMP ifAlias).

asset ⇒ Asset: Reference to asset class of asset linked to this object. null if no asset is linked or the script has no read access to the asset.

assetId: int: Id of linked asset object.

assetProperties ⇒ AssetProperties: Reference to asset properties class of asset linked to this object.

backupZoneProxy: Node: Currently selected backup zone proxy (null if zoning is disabled, backup proxy is not assigned, or the script has no read access to the proxy node)

backupZoneProxyId: int: ID of currently selected backup zone proxy (0 if zoning is disabled or backup proxy is not assigned)

category: String: Object’s category name

categoryId: int: Object’s category ID

children ⇒ array: List of direct child objects. Only objects the script has read access to are included. Use classof to differentiate.

city: String: Postal address - city.

comments: String: Object comments.

country: String: Postal address - country.

creationTime: int64: Object creation time as UNIX timestamp

customAttributes ⇒ HashMap: Hash map of object custom attributes.

district: String: Postal address - district.

geolocation ⇒ GeoLocation: Object geographical location.

guid: String: Object GUID as string.

id: int: Unique object identifier.

ipAddr: String: Primary IP address. Deprecated and will be removed in a future version, use ipAddress instead.

ipAddress ⇒ InetAddress: Primary IP address.

isInMaintenanceMode: bool: Maintenance mode indicator (true if object currently is in maintenace mode).

maintenanceInitiator: int: Maintenance initiator user id

mapImage: String: GUID of object image used for representation on the maps.

name: String: Object name.

nameOnMap: String: Object name displayed on map.

parents ⇒ array: List of direct parents for this object (most likely either Container or Cluster). Templates and objects the script has no read access to are not included.

postcode: String: Postal address - postal code.

primaryZoneProxy: Node: currently selected primary zone proxy (null if zoning is disabled, primary proxy is not assigned, or the script has no read access to the proxy node)

primaryZoneProxyId: int: ID of currently selected primary zone proxy (0 if zoning is disabled or primary proxy is not assigned)

region: String: Postal address - region.

responsibleUsers: Array: Array with user objects that are added as responsible users for this object. Objects are User or UserGroup

state: int: Current object state. One of: Node State, Cluster State, Sensor State

status: int: Current object status.

streetAddress: String: Postal address - street.

type: int: Object type.

templates: Array

Returns array of templates (Template) applied on this object. Only templates the script has read access to are included. Return value also affected by trusted nodes settings.

// Log names and ids of all accessible templates for current node
templates = $node.templates;
for (t : templates)
{
	trace(1, "Template object: name='" .. t.name .. "' id=" .. t.id);
}

Instance methods

From NetObj

bind(childObject): void

Bind childObject to the current object as a child.

Table 1. Parameters
childObject	NetObj	Object to bind as a child to the current object.

Return

false if the script lacks modify access to the current object; otherwise null, whether or not the link was made. Invalid object types, incompatible bindings and bindings that would create a loop cause a runtime error.

bindTo(parentObject): void

Bind current object to parentObject as a child.

Table 2. Parameters
parentObject	NetObj	Object to bind as a parent to the current object.

Return

calculateDowntime(tag, periodStart, periodEnd): Array

Calculate node downtime

Table 3. Parameters
tag	String	downtime tag
periodStart	Integer	Unix timestamp of the period start
periodEnd	Integer	Unix timestamp of the period end

Return

Array of DowntimeInfo objects, or null if no downtime was recorded for the tag in the period.

clearGeoLocation(): void: Clears GeoLocation data from the node

createUserAgentNotification(message, startTime, endTime, showOnStartup=false): int

Send a User Support Application notification to the nodes at or below this object. Set startTime and endTime to 0 for an instant notification. See User Support Application Notifications.

Table 4. Parameters
message	String	message to be sent
startTime	Integer	start time of message delivery (UNIX timestamp)
endTime	Integer	end time of message delivery (UNIX timestamp)
showOnStartup	Boolean	`TRUE` to show message on startup (optional, defaults to false)

Return

Message id.

delete(): void: Deletes current object.

deleteCustomAttribute(name): String

Delete custom attribute.

Table 5. Parameters
name	String	Name of the attribute to delete.

Return

Previous value of the attribute, or null if it did not exist. Stored values "true" and "false" are returned as boolean. false is also returned if the script has no modify access to the object (see access check), so it is ambiguous; read the attribute back to check whether it was deleted.

enterMaintenance([comment]): void

Enable maintenance mode for the object.

Table 6. Parameters
comment	String	Optional. Maintenance comment, recorded with the maintenance mode change.

expandString(string): String

Expand string by replacing macros with their values.

Table 7. Parameters
string	String	String to expand

Return

Formated string

>>> $node.expandString("%n")
My node name

forceAutobindPoll(): bool: Schedule forced autobind poll for this object. The poll is executed asynchronously on the poller thread pool; the method returns immediately after scheduling.

Return

TRUE if the poll was scheduled, FALSE if the caller has no modify access to the object or autobind poll is not applicable to this object type.

forceConfigurationPoll(): bool

Schedule forced configuration poll for this object. The poll is executed asynchronously on the poller thread pool; the method returns immediately after scheduling.

Return

TRUE if the poll was scheduled, FALSE if the caller has no modify access to the object or configuration poll is not applicable to this object type.

// Re-read node configuration after changing its SNMP settings
$node.setSNMPCommunity("public");
if (!$node.forceConfigurationPoll())
   println("Cannot schedule configuration poll");

forceDiscoveryPoll(): bool: Schedule forced network discovery poll for this object. The poll is executed asynchronously on the poller thread pool; the method returns immediately after scheduling.

Return

TRUE if the poll was scheduled, FALSE if the caller has no modify access to the object or network discovery poll is not applicable to this object type.

forceInstanceDiscoveryPoll(): bool: Schedule forced instance discovery poll for this object. The poll is executed asynchronously on the poller thread pool; the method returns immediately after scheduling.

Return

TRUE if the poll was scheduled, FALSE if the caller has no modify access to the object or instance discovery poll is not applicable to this object type.

forceMapUpdatePoll(): bool: Schedule forced map update poll for this object. The poll is executed asynchronously on the poller thread pool; the method returns immediately after scheduling.

Return

TRUE if the poll was scheduled, FALSE if the caller has no modify access to the object or map update poll is not applicable to this object type.

forceRoutingTablePoll(): bool: Schedule forced routing table poll for this object. The poll is executed asynchronously on the poller thread pool; the method returns immediately after scheduling.

Return

TRUE if the poll was scheduled, FALSE if the caller has no modify access to the object or routing table poll is not applicable to this object type.

forceStatusPoll(): bool: Schedule forced status poll for this object. The poll is executed asynchronously on the poller thread pool; the method returns immediately after scheduling.

Return

TRUE if the poll was scheduled, FALSE if the caller has no modify access to the object or status poll is not applicable to this object type.

forceTopologyPoll(): bool: Schedule forced topology poll for this object. The poll is executed asynchronously on the poller thread pool; the method returns immediately after scheduling.

Return

TRUE if the poll was scheduled, FALSE if the caller has no modify access to the object or topology poll is not applicable to this object type.

getCustomAttribute(name): String

Returns value of the custom attribute with the provided name.

Table 8. Parameters
name	String	Name of the attribute to get value from.

Return

Attribute value, or null if the attribute does not exist. Stored values "true" and "false" are returned as boolean.

Alternatively, attributes can be accessed as instance attribues (with ., attribute should exist) or by using attribute@object notion (which will return null instead of runtime error if attribue is missing).

getResponsibleUsers(tag) ⇒ array

Returns list of responsible users with specific tag. Full list is acceessible via .responsibleUsers

List of allowed tags are controlled by server configuration variable Objects.ResponsibleUsers.AllowedTags.

Table 9. Parameters
tag	String	Tag. `null` returns all responsible users, same as `.responsibleUsers`.

Return

Array with user objects that are added as responsible users for this object. Objects are User or UserGroup

This function return empty list if no users or groups are found for the tag.

isChild(object): bool

If provided object is child of this object

Table 10. Parameters
object	NetObj	Object to check

Return

TRUE if provided object is child of this object

isDirectChild(object): bool

If provided object is direct child of this object

Table 11. Parameters
object	NetObj	Object to check

Return

TRUE if provided object is direct child of this object

isDirectParent(object): bool

If provided object is direct parent of this object

Table 12. Parameters
object	NetObj	Object to check

Return

TRUE if provided object is direct parent of this object

isParent(object): bool

If provided object is parent of this object

Table 13. Parameters
object	NetObj	Object to check

Return

TRUE if provided object is parent of this object

leaveMaintenance(): void: Disable maintenance mode for the object.

manage(): void: Sets object to managed state. Has no affect if object already managed. Returns false and does not change the state if the object is a decommissioned node. Since 6.2.6

readMaintenanceJournal([startTime], [endTime]): Array

Read maintenance entries

Table 14. Parameters
startTime	Integer	Optional. Period start as UNIX timestamp. `0` or omitted means no lower bound.
endTime	Integer	Optional. Period end as UNIX timestamp. `0` or omitted means no upper bound.

Return

Array with MaintenanceJournalRecord objects, or null on database error

rename(name): void

Rename object.

Table 15. Parameters
name	String	New object name

setAlias(name): void

Set object alias name

Table 16. Parameters
name	String	New alias name

setCategory(idOrName): bool

Set object category id or name (used to get object display image)

Table 17. Parameters
idOrName	String	ID or name of category

Return

TRUE on success, FALSE if the category is not found or the caller has no modify access to the object.

setComments(comment, [isMarkdown]): void

Set object comments

Table 18. Parameters
comment	String	Comment to be set
isMarkdown	Boolean	Optional second argument ( v 5.1.2 ). If it is logical "true", Markdown indicator will be added if not present already; if it is logical "false" (but not NULL), Markdown indicator will be removed if present; if it is NULL or omitted, comment will be set as is (retaining existing behavior).

setCustomAttribute(key, value, [inherit]): String

Update or create custom attribute with the given key and value.

Table 19. Parameters
key	String	Attribute key
value	String	Attribute value
inherit	Boolean	Optional parameter. If not set - inheritance will not be changed. `true` to inherit, `false` not to inherit.

Return

$node.setCustomAttribute("location", "Rack 12");
if ($node.getCustomAttribute("location") != "Rack 12")
   println("Cannot set custom attribute");

setGeoLocation(newLocation): void

Sets node geographical location.

Table 20. Parameters
newLocation	GeoLocation

setMapImage(image): bool

Sets object image, that will be used to display object on network map

Table 21. Parameters
image	String	GUID or name of image from image library. `null` or all-zero GUID resets the image.

Return

TRUE on success, FALSE if the image is not found in image library or the caller has no modify access to the object.

setNameOnMap(name): void

Sets object’s name, that will be used to display object on network map

Table 22. Parameters
name	String	New object’s name on map

setPostalAddress(country, region, city, district, streetAddress, postcode): void

Sets object’s postal address. Each argument must be a string or null. A null or empty value clears the corresponding field.

Table 23. Parameters
country	String	Country. `null` or empty to clear.
region	String	Region. `null` or empty to clear.
city	String	City. `null` or empty to clear.
district	String	District. `null` or empty to clear.
streetAddress	String	Street address. `null` or empty to clear.
postcode	String	Postal code. `null` or empty to clear.

setStatusCalculation(type, …): int

Sets status calculation method.

Table 24. Parameters
type	Integer	Status calculation type. One of status calculation types
…	Integer(s)	If single threshold or multiple thresholds type is selected, then threshold or thresholds in percentage should be provided as next parameters.

Return

1 on success, 0 if type is not a valid status calculation type. false if the caller has no modify access to the object.

setStatusPropagation(type, …): int

Sets status propagation method.

Table 25. Parameters
type	Integer	Status propagation type. One of status propagation types
…	Integer(s)	For fixed value type - value (object status) should be provided. For relative - offset should be provided. For translated - status mapping should be provided (4 numbers: object status to propagate for Warning, Minor, Major and Critical).

Return

1 on success, 0 if type is not a valid status propagation type. false if the caller has no modify access to the object.

unbind(object): void

Unbind provided object from the current object.

Table 26. Parameters
object	NetObj	Object to unbind from the current object.

unbindFrom(object): void

Unbind current object from the provided object.

Table 27. Parameters
object	NetObj	Object to unbind from the current object.

unmanage(): void: Set object into unmanaged state. Has no effect if object is already in unmanaged state.

writeMaintenanceJournal(description): bool

Add entry to maintenance journal

Table 28. Parameters
description	String	Message to be added

Return

TRUE if the entry was added, FALSE on failure or if the caller has no maintenance access to the object.

applyTemplate(template): bool

Apply template to this object.

Table 29. Parameters
template	Template	Template object to apply

Return

true if template was applied, false if a template from the same exclusion group is already applied to this object or the caller has no modify access to the object. Since 6.2.3

createDCI(origin, name, description, dataType, [pollingInterval], [retentionTime]) ⇒ DCI

Create a new data collection item on this object.

Table 30. Parameters
origin	String or Integer	Data origin. Possible values: `"internal"`, `"agent"`, `"snmp"`, `"websvc"`, `"push"`, `"winperf"`, `"smclp"`, `"script"`, `"ssh"`, `"mqtt"`, `"driver"`, `"modbus"`, `"ethernetip"` (case-insensitive). Alternatively, you can use Data origin constants.
name	String	Name of the metric (e.g. `"Agent.Version"`).
description	String	Human readable description.
dataType	String or Integer	Type of the collected data. Possible values: `"int32"`, `"uint32"`, `"int64"`, `"uint64"`, `"counter32"`, `"counter64"`, `"float"`, `"string"`. Alternatively, you can use DCI data type constants.
pollingInterval	String	Polling interval in seconds, or `null` or `"0"` for server-default value. Optional.
retentionTime	String	Retention time in days, `"0"` for "Do not save collected data to database", or `null` for server-default value. Optional.

Return

Newly created DCI object, or null if origin or data type is invalid or the caller has no modify access to the object.

dci = $node.createDCI("agent", "Agent.Version", "Agent Version", "string");
println(dci.id);

deleteDCI(dciId): bool

Delete data collection item from this object. DCIs created from a template are managed by that template and cannot be deleted this way.

Table 31. Parameters
dciId	Integer	DCI ID.

Return

true on success, false on failure (caller has no modify access to the object, DCI not found, or DCI was created from a template).

dci = $node.findDCIByName("Temporary.Metric");
if (dci != null)
   $node.deleteDCI(dci.id);

enableConfigurationPolling(flag): void

Enable or disable configuration polling.

Table 32. Parameters
flag	Boolean	If configuration polling should be enabled.

enableDataCollection(flag): void

Enable or disable data collection polling.

Table 33. Parameters
flag	Boolean	If data collection polls should be enabled.

enableStatusPolling(flag): void

Enable or disable status polling.

Table 34. Parameters
flag	Boolean	If status polls should be enabled.

findAllDCIs(name, description, tag, relatedObject): Array

Find all DCIs on this object matching the given filters. All parameters are optional; omitted or null parameters are not used for filtering. Name, description, and tag filters support glob patterns (? and *) and are case-insensitive.

Table 35. Parameters
name	String	Name filter (glob pattern). Optional.
description	String	Description filter (glob pattern). Optional.
tag	String	User tag filter (glob pattern). Optional.
relatedObject	NetObj or Integer	Related object or object ID. Optional.

Return

Array of DCI objects matching the filters.

// Find all CPU-related DCIs
for (d : $node.findAllDCIs("System.CPU.*"))
   println(d.name .. " = " .. d.cachedValue);

findDCIByDescription(description) ⇒ DCI

Find a DCI on this object by description (exact case-insensitive match).

Table 36. Parameters
description	String	Description of the DCI.

Return

DCI object or null if not found.

findDCIById(id) ⇒ DCI

Find a DCI on this object by its ID.

Table 37. Parameters
id	Integer	DCI ID.

Return

DCI object or null if not found.

findDCIByName(name) ⇒ DCI

Find a DCI on this object by metric name (exact case-insensitive match).

Table 38. Parameters
name	String	Metric name of the DCI.

Return

DCI object or null if not found.

dci = $node.findDCIByName("System.CPU.Usage");
if (dci != null)
   println("CPU Usage: " .. dci.cachedValue);

findDCIByTag(tag) ⇒ DCI

Find a DCI on this object by user tag (exact case-insensitive match).

Table 39. Parameters
tag	String	User tag value.

Return

DCI object or null if not found.

findDCIByTagPattern(pattern) ⇒ DCI

Find a DCI on this object by user tag using a case-insensitive glob pattern.

Table 40. Parameters
pattern	String	Glob pattern to match against user tags.

Return

First matching DCI object or null if not found.

pushDCIData(dciId, value, [timestamp]): bool

Push a new value to a DCI from script. The DCI must be a single value DCI with origin set to "Push" or "OpenTelemetry (OTLP)".

Table 41. Parameters
dciId	Integer	DCI ID.
value	String	New value for the DCI.
timestamp	Integer	Timestamp in milliseconds since epoch (1 Jan 1970 00:00:00 UTC). Optional, current time is used if not specified.

Return

true on success, false on failure (DCI not found, wrong origin, not a single value DCI, or value was not accepted).

dci = $node.findDCIByName("My.Push.Metric");
$node.pushDCIData(dci.id, "42");

readInternalParameter(name): String

Reads object internal metric (metric with source "Internal").

Table 42. Parameters
name	String	Metric name.

Return

Metric value, or null if the metric cannot be read.

removeTemplate(template): void

Remove template from this object.

Table 43. Parameters
template	Template	Template object to remove