PowerDomain

Object represents power domain - segment of power distribution path within a Facility (grid entry, generator, UPS, PDU, busway). Can be nested under another power domain. Can contain power domains, racks, chassis, clusters, nodes, and sensors. Extends DataCollectionTarget.

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: Added in version 5.1

Primary IP address.

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

isMaintenanceScheduled: bool: TRUE if there is a scheduled task that will put this object into maintenance 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.

timeZone: String: Effective time zone name (IANA name, e.g. Europe/Riga). Time zone is inherited from parent objects if not set on this object directly. null if time zone is not set. Use setTimeZone() to change.

timeZoneRule: String: POSIX TZ rule string of the effective time zone (e.g. EET-2EEST,M3.5.0/3,M10.5.0/4). Time zone is inherited from parent objects if not set on this object directly. null if time zone is not set.

type: int: Object type.

From DataCollectionTarget

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);
}

autoBindScript: String: Source of the script for automatic binding.

domainType: int: Power domain type as one of the numeric values.

domainTypeName: String: Symbolic name of power domain type (GRID_ENTRY, GENERATOR, UPS, PDU, BUSWAY, or OTHER).

feedTag: String: Free-form feed label, conventionally A or B. May be empty.

isAutoBindEnabled: bool: Indicate if automatic binding is enabled.

isAutoUnbindEnabled: bool: Indicate if automatic unbinding is enabled.

ratedPower: int: Nameplate power in watts. 0 if undeclared.

Instance methods

From NetObj

bind(childObject): bool

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

true if the objects were linked; false if the link is refused because deletion of either object has started, or the script lacks modify access to the current object. Invalid object types, incompatible bindings and bindings that would create a loop cause a runtime error.

bindTo(parentObject): bool

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, or null if the script’s security context lacks the Manage user support application notifications system right.

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, structured values as hash map or array. 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. For attribute names starting with $$ the method returns null and does not delete anything.

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, structured values as hash map or array. Names starting with $$ always return null.

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.

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. Hash map, array, JsonObject or JsonArray is stored as structured (JSON) value.
inherit	Boolean	Optional parameter. If not set - inheritance will not be changed. `true` to inherit, `false` not to inherit.

Return

Previous value of the attribute, or null if it did not exist. Stored values "true" and "false" are returned as boolean, structured values as hash map or array. 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 set. For attribute names starting with $$ the method returns false and does not set anything.

$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.

setTimeZone(name, [rule]): bool

Set object’s time zone. Time zone is inherited by child objects that do not have their own setting. Passing null or empty string as name removes object’s own setting; time zone inherited from parent objects, if any, stays in effect.

Table 26. Parameters
name	String	IANA time zone name (e.g. `Europe/Riga`). `null` or empty to remove object’s own setting.
rule	String	Optional POSIX TZ rule string (e.g. `EET-2EEST,M3.5.0/3,M10.5.0/4`). If omitted, the rule is resolved from `name` using the server’s system time zone database; must be provided if the server cannot resolve the name.

Return

TRUE on success, FALSE if the caller has no modify access to the object, the name is malformed, the rule cannot be parsed, or the name cannot be resolved.

$node.setTimeZone("Europe/Riga");
println($node.timeZone);      // Europe/Riga
println($node.timeZoneRule);  // EET-2EEST,M3.5.0/3,M10.5.0/4

$node.setTimeZone(null);      // revert to time zone inherited from parents

unbind(object): void

Unbind provided object from the current object.

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

unbindFrom(object): void

Unbind current object from the provided object.

Table 28. 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 29. 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.

From DataCollectionTarget

applyTemplate(template): bool

Apply template to this object.

Table 30. 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.

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

Create a new data collection item on this object.

Table 31. 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 32. 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 33. Parameters
flag	Boolean	If configuration polling should be enabled.

enableDataCollection(flag): void

Enable or disable data collection polling.

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

enableStatusPolling(flag): void

Enable or disable status polling.

Table 35. 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 36. 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 37. 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 38. 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 39. 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 40. 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 41. 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 42. 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 43. 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 44. Parameters
template	Template	Template object to remove

createNode(name, primaryHostName, zoneUIN) ⇒ Node

Create new node under current object.

Table 45. Parameters
name	String	Node name. Also used as primary host name or IP address if `primaryHostName` is omitted or empty.
primaryHostName	String	Optional. Primary host name or IP address.
zoneUIN	Integer	Optional. New node’s zone UIN. `0` if omitted.

Return

Newly created node of Node class, or null if failed to create or the script has no Create access right on this object. If the new object cannot be linked to this parent, it is deleted and null is returned.

createPowerDomain(name, domainType, feedTag, ratedPower) ⇒ PowerDomain

Create new power domain under current object.

Table 46. Parameters
name	String	New power domain’s name
domainType	Integer	Optional. One of the power domain types. `5` (OTHER) if omitted or not valid.
feedTag	String	Optional. Free-form feed label, conventionally `A` or `B`. Truncated to 15 characters.
ratedPower	Integer	Optional. Nameplate power in watts. `0` (undeclared) if omitted.

Return

Newly created power domain of PowerDomain class, or null if failed to create or the script has no Create access right on this object. If the new object cannot be linked to this parent, it is deleted and null is returned.

createRack(name, height, width, depth) ⇒ Rack

Create new rack under current object.

Table 47. Parameters
name	String	New rack’s name
height	Integer	Optional. Rack height in units. `42` if omitted or not positive.
width	Integer	Optional. External cabinet width in millimetres. `600` if omitted or not positive.
depth	Integer	Optional. External cabinet depth in millimetres. `1000` if omitted or not positive.

Return

Newly created rack of Rack class, or null if failed to create or the script has no Create access right on this object. If the new object cannot be linked to this parent, it is deleted and null is returned.

createSensor(name, deviceClass, gateway, modbusUnitId) ⇒ Sensor

Create new sensor under current object.

Table 48. Parameters
name	String	Sensor name
deviceClass	Integer	Sensor device class, one of the following values. Optional, `SensorDeviceClass::Other` if omitted.
gateway	Node	Gateway node used for communication with the sensor. Optional, `null` for none. Any other object class is a runtime error.
modbusUnitId	Integer	MODBUS Unit ID. Optional, `255` if omitted.

Return

Newly created sensor of Sensor class, or null if failed to create or the script has no Create access right on this object. If the new object cannot be linked to this parent, it is deleted and null is returned.

setAutoBindMode(enableBind, enableUnbind): void

Set automatic bind mode for the object. Does nothing and returns false if the script has no Modify access right on this object.

Table 49. Parameters
enableBind	Boolean	Script should be used for automatic binding.
enableUnbind	Boolean	Script should be used for automatic unbinding.

setAutoBindScript(script): void

Update automatic binding script source. Does nothing and returns false if the script has no Modify access right on this object.

Table 50. Parameters
script	String	Script source.

Constants

Table 51. Power domain types
Value	Name	Description
0	GRID_ENTRY	Utility grid entry point
1	GENERATOR	Backup generator
2	UPS	Uninterruptible power supply
3	PDU	Power distribution unit
4	BUSWAY	Busway
5	OTHER	Other