Zone

Represents network zone. 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: 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.

proxyNodes: Array<Node>: Array of Node objects that are currently set as proxies for this zone. Proxy nodes the script has no read access to are not included.

proxyNodeIds: Array<Integer>: Array of integers representing identifiers of node objects that are currently set as proxies for this zone.

uin: int: Zone UIN (Unique Identification Number).

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.