locations

The following methods allow for interaction with the ZCON Locations API endpoints.

Methods are accessible via zcon.locations

class ZCONLocationsAPI

add_location_template(name, template=None, **kwargs)

Add a new location template.

Parameters:

• name (str) – The name of the location template.

• template (dict, optional) –

  A dictionary containing the template settings. Possible keys include:

  • template_prefix (str): Prefix of Cloud & Branch Connector location template.

  • xff_forward_enabled (bool): Enable to use the X-Forwarded-For headers.

  • auth_required (bool): Enable if “Authentication Required” is needed.

  • caution_enabled (bool): Enable to display an end user notification for unauthenticated traffic.

  • aup_enabled (bool): Enable to display an Acceptable Use Policy (AUP) for unauthenticated traffic.

  • aup_timeout_in_days (int): Frequency in days for displaying the AUP, if enabled.

  • ofw_enabled (bool): Enable the service’s firewall controls.

  • ips_control (bool): Enable IPS controls, if firewall is enabled.

  • enforce_bandwidth_control (bool): Enable to specify bandwidth limits.

  • up_bandwidth (int): Upload bandwidth in Mbps, if bandwidth control is enabled.

  • dn_bandwidth (int): Download bandwidth in Mbps, if bandwidth control is enabled.

  • display_time_unit (str): Time unit for IP Surrogate idle time to disassociation.

  • idle_time_in_minutes (int): User mapping idle time in minutes for IP Surrogate.

  • surrogate_ip_enforced_for_known_browsers (bool): Enforce IP Surrogate for all known browsers.

  • surrogate_refresh_time_unit (str): Time unit for refresh time for re-validation of surrogacy.

  • surrogate_refresh_time_in_minutes (int): Refresh time in minutes for re-validation of surrogacy.

  • surrogate_ip (bool): Enable the IP Surrogate feature.

Keyword Arguments:

description (str) – The description of the location template.

Returns:

The location template details.

Return type:

Box

Examples

Add a new location template with minimal settings:

print(zcon.locations.add_location_template(name="MyTemplate"))

Add a new location template with additional settings:

template_settings = {
    "surrogate_ip": True,
    "surrogate_ip_enforced_for_known_browsers": False,
    "template_prefix": "office",
    "aup_enabled": True,
    "aup_timeout_in_days": 30,
    "ofw_enabled": True,
    "idle_time_in_minutes": 35,
    "auth_required": True,
    "display_time_unit": "MINUTE",
}
print(zcon.locations.add_location_template(name="MyTemplate", template=template_settings))

delete_location_template(template_id)

Delete an existing location template.

Parameters:

template_id (str) – The ID of the location template to delete.

Returns:

The status code of the operation.

Return type:

int

Examples

Delete a location template:

print(zcon.locations.delete_location_template("123456789"))

get_location(location_id)

Get details for a specific location.

Parameters:

location_id (str) – The ID of the location to retrieve.

Returns:

The location details.

Return type:

Box

Examples

Get details of a specific location:

print(zcon.locations.get_location("123456789"))

get_location_template(template_id)

Get details for a specific location template.

Parameters:

template_id (str) – The ID of the location template to retrieve.

Returns:

The location template details.

Return type:

Box

Examples

Get details of a specific location template:

print(zcon.locations.get_location_template("123456789"))

list_location_templates(**kwargs)

List all existing location templates.

Parameters:

**kwargs – Optional keyword args to filter the results.

Keyword Arguments:

• page (int) – The page number to return.

• page_size (int) – The number of items to return per page.

Returns:

The list of location templates.

Return type:

BoxList

Examples

List all location templates:

for template in zcon.locations.list_location_templates():
    print(template)

list_locations(**kwargs)

List all existing locations.

Keyword Arguments:

• group_id (str) – The ID of the connector group.

• search (str) – The search string to filter the results.

• state (str) – The geographical state of the location.

• ssl_scan_enabled (bool) – Include / exclude locations with SSL scanning enabled.

• xff_enabled (bool) – Include / exclude locations with XFF enabled.

• auth_required (bool) – Include / exclude locations with authentication required.

• bw_enforced (bool) – Include / exclude locations with bandwidth enforcement enabled.

• partner_id (str) – The ID of the partner. Not used for Cloud/Branch connector

• enforce_aup (bool) – Include / exclude locations with AUP enforcement enabled.

• enable_firewall (bool) – Include / exclude locations with firewall enabled.

• location_type (str) –

  The type of location, accepted values are:

  • NONE

  • CORPORATE

  • SERVER

  • GUESTWIFI

  • IOT

  • WORKLOAD

• page (int) – The page number to return.

• page_size (int) – The number of items to return per page.

Returns:

The list of connector locations.

Return type:

BoxList

Examples

List all locations:

for location in zcon.locations.list_locations():
    print(location)

List only IOT locations:

for location in zcon.locations.list_locations(location_type="IOT"):
    print(location)

update_location_template(template_id, **kwargs)

Update an existing location template.

Parameters:

template_id (str) – The ID of the location template to update.

Keyword Arguments:

• name (str) – The name of the location template.

• template (dict) –

  A dictionary containing the template settings. Possible keys include:

  • template_prefix (str): Prefix of Cloud & Branch Connector location template.

  • xff_forward_enabled (bool): Enable to use the X-Forwarded-For headers.

  • auth_required (bool): Enable if “Authentication Required” is needed.

  • caution_enabled (bool): Enable to display an end user notification for unauthenticated traffic.

  • aup_enabled (bool): Enable to display an Acceptable Use Policy (AUP) for unauthenticated traffic.

  • aup_timeout_in_days (int): Frequency in days for displaying the AUP, if enabled.

  • ofw_enabled (bool): Enable the service’s firewall controls.

  • ips_control (bool): Enable IPS controls, if firewall is enabled.

  • enforce_bandwidth_control (bool): Enable to specify bandwidth limits.

  • up_bandwidth (int): Upload bandwidth in Mbps, if bandwidth control is enabled.

  • dn_bandwidth (int): Download bandwidth in Mbps, if bandwidth control is enabled.

  • display_time_unit (str): Time unit for IP Surrogate idle time to disassociation.

  • idle_time_in_minutes (int): User mapping idle time in minutes for IP Surrogate.

  • surrogate_ip_enforced_for_known_browsers (bool): Enforce IP Surrogate for all known browsers.

  • surrogate_refresh_time_unit (str): Time unit for refresh time for re-validation of surrogacy.

  • surrogate_refresh_time_in_minutes (int): Refresh time in minutes for re-validation of surrogacy.

  • surrogate_ip (bool): Enable the IP Surrogate feature.

• description (str) – A description for the location template.

Returns:

The updated location template details.

Return type:

Box

Note

• Any provided keys will update existing keys.

• The template dictionary does not support partial updates. Any provided template will completely overwrite

  the existing template.

Examples

Update the name of a location template:

print(zcon.locations.update_location_template(template_id="123456789", name="MyTemplate"))

Update the template details of a location template:

template_settings = {
    "surrogate_ip": True,
    "surrogate_ip_enforced_for_known_browsers": False,
    "template_prefix": "office",
    "aup_enabled": True,
    "aup_timeout_in_days": 30,
    "ofw_enabled": True,
    "idle_time_in_minutes": 4, # <-- changed to 4 hours
    "auth_required": True,
    "display_time_unit": "HOUR", # <-- changed from minutes to hours
}
print(zcon.locations.update_location_template(template_id="123456789", template=template_settings))