1.8 Location Interface

The Location interface provides methods for getting information about a device’s location and for manipulating the location.

1.8.1 Definitions

ZENworks Endpoint Security Management provides two different lists of locations: a Network Location List and an Assigned Location List. Using these two lists, information about four types of locations is tracked: a Network location, an Assigned location, a Mobile location, and a Security location. A brief description is provided for both of the lists and each location:

Network Location List: Contains all locations defined in the ZENworks Management Zone. These locations may be associated with a set of network environments. The list always contains at least one location that is marked as the Mobile (Unknown) location that is used when the current environment does not match any defined network environments.
Assigned Location List: Contains only the locations that the device is allowed to apply as Security locations. Normally, this list is provided via the Location Assignment policy. This list always contains at least one location that is marked as the Mobile (Unknown) location. The Mobile location is used when the current environment does not match any locations included in the Assigned Location List.
Network Location: The location, taken from the Network Location List, that the current network environment best matches.
Assigned Location: The location, taken from the Assigned Location List, that the current network environment best matches.
Security Location: The location, from the Assigned Location List, that determine which of the security policies are being enforced. Normally, this is the same as the Assigned location. However, scripting or other rules (such as the VPN policy) can force the Security location to change.
Mobile Location: The location, from the Assigned Location List, that has been designated as the default Assigned location if the current network environment does not match any location definitions. This is frequently referred to as the Unknown location.

1.8.2 Data Types

LocationAssignment

The LocationAssignment object provides information about the current location. It is returned when working with a location from the Assigned Location List.

Data Types:

string Id — A unique identifier for the location in the system.

string Name — The name of the location.

DateTime DateModified — The last time the location definition was modified.

int Order — The order of precedence between two locations being compared for network environment match.

bool Mobile — True if the location is the Unknown location.

bool AllowsManualChange — True if the user is allowed to change into or out of this location.

bool ShowInMenu — True if the user should see this location listed in the choice of locations menus.

Functions:

bool Match(string value)

Returns true if the value provided matches the ID or Name value for the location.

LocationNetwork

The LocationNetwork object provides information about the current location. It is returned when working with a location from the Network Location List.

Data Types:

string Id — A unique identifier for the location in the system.

string Name — The name of the location.

DateTime DateModified — The last time the location definition was modified.

int Order — The order of precedence between two locations being compared for network environment match.

bool Mobile — True if the location is the Unknown location.

Functions:

bool Match(string value)

Returns true if the value provided matches the ID or Name value for the location.

LocationChange

The LocationChange object provides information about the last location change and why the current location change is being enforced. It is returned when changing the current Security location or can be asked for directly.

Data Types:

string Reason — One of the following:

none — No change has occurred yet.
policy — A policy update caused the location change.
manual — The location change was manually initiated (for example, by the user).
network — A network environment change caused a match with the new location.
rule — A rule, such as a VPN rule or a script, requested the location change.
permanent — A rule requested a permanent location change. The location change remains in effect until another permanent change is requested or the current request is cancelled.

string Producer — The Endpoint Security Agent component that requested the location change. This value can be empty.

string RuleId — The ID of the rule that made the location change request. This value an be empty.

string RuleName — The name of the rule that made the location change request. This value an be empty.

int Level — The level that the request was made.

LocationAssignment SecurityLocation — Information about the current Security location resulting from the location change.

1.8.3 Security Location Methods

The Security Location methods deal with the security location, retrieving the current security location, and setting a new location from the script. The Manual location change methods perform the same functions as if the user initiated a request for the location change and follow the same restriction as those put on the user. When the current security location does not allow manual changes, the script or the user is not able to switch into or out of the location. If the destination location does not allow manual changes, the request is ignored because the location change cannot be switched into by a manual change.

The Rule location change methods allow the script to change from any location to another without restrictions. When a user initiates a manual change, it fails if a location is involved that does not allow manual changes. However, when a script uses the Rule location change (or an internal VPN/Network Environment rule), the location change is allowed regardless of the manual change settings.

The Permanent location change methods allow the script to block changes by internal rules (VPN/Network Environments) and other scripts running in the system. This is done by disabling the location decider code in the Endpoint Security Agent and requiring other scripts/rules to provide the equivalent or higher level before the location can be changed. The internal “VPN” rule in the system uses this method to control location changes when the internet is present. The level it sets is 100.

The final component is the ability to re-enable the location decider. This is controlled by the level setting of the request.

LocationAssignment Query.SecurityLocation

Description:

Gets the current Security location.

LocationChange Action.ManualLocationChange(string toLocation)

	Description:	Switches to the toLocation if a permanent location has not been set and policy permits.
	Parameters:	toLocation — The name or ID of the location being switched to. The request is ignored if the toLocation is not in the Location Assignment policy or if policy does not allow manual location changes.
	Returns:	Returns the LocationChange object so the caller can see if the request was honored.

LocationChange Action.ManualLocationChangeWithSource(string fromLocation, string toLocation)

Description:

If the current location is the fromLocation, switches to the toLocation if a permanent location has not been set and policy permits.

Parameters:

fromLocation — The name or ID of the location being switched from. The request is ignored if the fromLocation is not the current location, or if policy does not allow manual location changes.

toLocation — The name or ID of the location being switched to. The request is ignored if the toLocation is not in the Location Assignment policy or if policy does not allow manual location changes.

Returns:

Returns the LocationChange object so the caller can see if the request was honored.

LocationChange Action.RuleLocationChange(string toLocation)

	Description:	Switches to the toLocation if a permanent location has not been set.
	Parameters:	toLocation — The name or ID of the location being switched to. The request is ignored if the toLocation is not in the Location Assignment policy or if policy does not allow manual location changes.
	Returns:	Returns the LocationChange object so the caller can see if the request was honored.

LocationChange Action.RuleLocationChangeWithSource(string fromLocation, string toLocation)

Description:

If the current location is the fromLocation, switches to the toLocation if a permanent location has not been set.

Parameters:

fromLocation — The name or ID of the location being switched from. The request is ignored if the fromLocation is not the current location, or if policy does not allow manual location changes.

toLocation — The name or ID of the location being switched to. The request is ignored if the toLocation is not in the Location Assignment policy or if policy does not allow manual location changes.

Returns:

Returns the LocationChange object so the caller can see if the request was honored.

LocationChange Action.PermanentLocationChange(string toLocation, int level)

Description:

Switches to the toLocation and turns off the location decider.

Parameters:

toLocation — The name or ID of the location being switched to. The request is ignored if the toLocation is not in the Location Assignment policy.

level — The request is permitted only if the current change level is less than or equal to this level.

Returns:

Returns the LocationChange object so the caller can see if the request was honored.

LocationChange Action.PermanentLocationChangeWithSource(string fromLocation, string toLocation, int level)

Description:

If the current location is the fromLocation, switches to the toLocation and turns off the location decider.

Parameters:

fromLocation — The name or ID of the location being switched from. The request is ignored if the fromLocation is not the current location.

toLocation — The name or ID of the location being switched to. The request is ignored if the toLocation is not in the Location Assignment policy.

level — The request is permitted only if the current change level is less than or equal to this level.

Returns:

Returns the LocationChange object so the caller can see if the request was honored.

LocationChange Action.ReenableLocationDecider(int level)

	Description:	Re-enables the location decider.The location decider waits for a location change event (network environment change, manual change, script, etc.) to occur before making any changes. If you want to change to the current location immediately, you should get the current Assigned location (LocationAssignment Query.AssignedLocation) and assign it as the current Security location (LocationChange Action.PermanentLocationChange(string toLocation, int level) before re-enabling the location decider.
	Parameters:	level — The request is permitted only if the current change level is less than or equal to this level.
	Returns:	Returns the LocationChange object so the caller can see if the request was honored.

1.8.4 Mobile (Unknown) Location Methods

The Mobile location is often referred to as the Default location or Unknown location. This location is used when no other assigned location matches the current network environment and no rule has overridden the location decider’s decisions.

LocationAssignment Query.MobileLocation

	Description:	Gets the current Mobile location.
	Returns:	The LocationAssignment object with the current Mobile location information.

1.8.5 Assigned Location Methods

The Endpoint Security Agent is provided a list of locations that it is allowed to use as Security locations. This list is passed to the agent via the Location Assignment policy. The location decider uses this list to determine the best matching location based on the current network environment. That location is called the Assigned location. Scripts cannot change Assigned Locations list or the Assigned location, but they can use it for determining actions and deciding which locations the script may wish to set as the current Security location.

LocationAssignment Query.AssignedLocation

	Description:	Gets the current Assigned location.
	Returns:	The LocationAssignment object with the current Assigned location information.

ObjectMatchList Query.AssignedLocationList

	Description:	Gets the list of Assigned locations available to the device.
	Returns:	An ObjectMatchList that contains the Assigned locations.

SafeArray Query.AssignedLocationArray()

	Description:	Gets the list of Assigned locations available to the device.
	Returns:	A VB SafeArray that contains the Assigned locations.

1.8.6 Network Location Methods

The Endpoint Security Agent receives the list of all locations defined in the ZENworks Management Zone. From this Network Location List, the location decider determines the best location based on the network environment. This is referred to as the Network location. Currently, the ZENworks Adaptive Agent can use this location to determine closest servers and to determine whether or not certain actions (such as bundle downloads) are allowed. A script cannot change the Network location, but it can use the Network location to determine actions, just like the ZENworks Adaptive Agent.

LocationAssignment Query.NetworkLocation

Description:

Gets the current Network location.

ObjectMatchList Query.NetworkLocationList

	Description:	Gets the list of Network locations available to the device.
	Returns:	An ObjectMatchList that contains the Network locations.

SafeArray Query.NetworkLocationArray()

	Description:	Returns the list of Network locations available to the device; returned as a Visual Basic SafeArray.
	Returns:	A VB SafeArray that contains the Network locations.

1.8.7 JScript Example

function DisplayAssignedLocation(loc) 
{
    Action.Trace("Location = " + loc.Name);
    Action.Trace("Id = " + loc.Id);
    Action.Trace("Date Modified = " + loc.DateModified);
    Action.Trace("Order: " + loc.Order);
    Action.Trace("Mobile: " + loc.Mobile);
    Action.Trace("Allow Manual Change: " + loc.AllowsManualChange);
    Action.Trace("Show in menu: " + loc.ShowInMenu);
}

Action.Trace("");
Action.Trace(" ******** Security Location ********* ");
Action.Trace("");
DisplayAssignedLocation(Query.SecurityLocation);

1.8.8 VBScript Example

Function DisplayAssignedLocation (loc)
Action.Trace "Location = " & loc.Name
Action.Trace "Id = " & loc.Id
Action.Trace "Date Modified = " & loc.DateModified
Action.Trace "Order: " & loc.Order
Action.Trace "Mobile: " & loc.Mobile
Action.Trace "Allow Manual Change: " & loc.AllowsManualChange
Action.Trace "Show in menu: " & loc.ShowInMenu
End Function

Action.Trace ""
Action.Trace " ******** Security Location ********* "
Action.Trace ""
DisplayAssignedLocation Query.SecurityLocation