entity module - Platform - BlueCat Gateway - 21.11.2

Gateway Administration Guide

Product name
BlueCat Gateway

The entity class wraps up BAM API entities and provides methods common across all types. The class include ‘constants’ naming those types.

class bluecat.entity.Entity(api, api_entity, ver='')

Bases: bluecat.api_object.APIObject

Instantiate an entity. Entities are hashable and comparable with the = operator.

Parameters Description
api API instance used by the entity to communicate with BAM.
api_entity The entity returned by the BAM API.


AliasRecord = 'AliasRecord'

Configuration = 'Configuration'

CustomOptionDef = 'CustomOptionDef'

DHCP4Range = 'DHCP4Range'

DHCP6Range = 'DHCP6Range'

DHCPDeploymentRole = 'DHCPDeploymentRole'

DHCPMatchClass = 'DHCPMatchClass'

DHCPRawOption = 'DHCP_RAW'

DHCPServiceOption = 'DHCPServiceOption'

DHCPSubClass = 'DHCPSubClass'

DHCPV4ClientOption = 'DHCPV4ClientOption'

DHCPV6ClientOption = 'DHCPV6ClientOption'

DHCPV6RawOption = 'DHCPV6_RAW'

DHCPV6ServiceOption = 'DHCPV6ServiceOption'


DNSOption = 'DNSOption'

DNSRawOption = 'DNS_RAW'

DNSSECSigningPolicy = 'DNSSECSigningPolicy'

DenyMACPool = 'DenyMACPool'

DeploymentRole = 'DNSDeploymentRole'

DeploymentScheduler = 'DeploymentScheduler'

Device = 'Device'

DeviceSubtype = 'DeviceSubtype'

DeviceType = 'DeviceType'

Entity = 'Entity'

EnumNumber = 'EnumNumber'

EnumZone = 'EnumZone'

ExternalHostRecord = 'ExternalHostRecord'

GenericRecord = 'GenericRecord'

HINFORecord = 'HINFORecord'

HostRecord = 'HostRecord'

IP4Address = 'IP4Address'

IP4Block = 'IP4Block'

IP4IPGroup = 'IP4IPGroup'

IP4Network = 'IP4Network'

IP4NetworkTemplate = 'IP4NetworkTemplate'

IP4ReconciliationPolicy = 'IP4ReconciliationPolicy'

IP6Address = 'IP6Address'

IP6Block = 'IP6Block'

IP6Network = 'IP6Network'

InterfaceID = 'InterfaceID'

InternalRootZone = 'InternalRootZone'

Kerberos = 'Kerberos'

KerberosRealm = 'KerberosRealm'


Location = 'Location'

MACAddress = 'MACAddress'

MACPool = 'MACPool'

MXRecord = 'MXRecord'

NAPTRRecord = 'NAPTRRecord'

NetworkInterface = 'NetworkInterface'

NetworkServerInterface = 'NetworkServerInterface'

PublishedServerInterface = 'PublishedServerInterface'

RPZone = 'RPZone'

Radius = 'Radius'

RecordWithLink = 'RecordWithLink'

ResponsePolicy = 'ResponsePolicy'

SRVRecord = 'SRVRecord'

Server = 'Server'

StartOfAuthority = 'StartOfAuthority'

TFTPDeploymentRole = 'TFTPDeploymentRole'

TFTPFile = 'TFTPFile'

TFTPFolder = 'TFTPFolder'

TFTPGroup = 'TFTPGroup'


TXTRecord = 'TXTRecord'

Tag = 'Tag'

TagGroup = 'TagGroup'

User = 'User'

UserGroup = 'UserGroup'

VendorClientOption = 'VendorClientOption'

VendorOptionDef = 'VendorOptionDef'

VendorProfile = 'VendorProfile'

View = 'View'

VirtualInterface = 'VirtualInterface'

Zone = 'Zone'

ZoneTemplate = 'ZoneTemplate'

add_access_right(recipient_id, value, overrides='', properties='')

Parameters Description
recipient_id The object ID of the user or user group the access right is applied to.
value The value of the access right being added.
overrides A list of type-specific overrides.
properties A string including the following options:
  1. workflowLevel

  2. deploymentAllowed

  3. quickDeploymentAllowed

Returns: Object ID of a created Access Right.

add_as_child_to(parent_id:int, refresh:bool=True)

Add the current object as child to a parent entity.

Note: This method uses addEntity from Address Manager API. It is a generic method for adding entities. However, it does not allow all types. For the supported options, please refer to the Address Manager API Guide for the specific version.
Parameters Description
parent_id(int) ID of the parent entity.
refresh(bool, optional) Indicates whether the current object’s fields (and overall state) should be refreshed with the values from BAM once the addition occurs. Defaults to True.

Returns: ID that the object receives once added in BlueCat Address Manager.

Return type: int


api = g.user.get_api()     # a user-aware bluecat.api.API instance
configuration_id = 100001  # ID of a Configuration
configuration = api.get_entity_by_id(configuration_id)

key = TSIGKey(api)
key.name = "master1"
key.algorithm = "hmac-sha512"
key.length = 512
key.generated = True

id = key.add_as_child_to(configuration.id, refresh=True)

New in version 20.3.1.


Delete the entity from the BAM database.


Get an AccessRight for this entity for a specific user or a user group.

Parameters Description
recipient_id The object ID of the user or user group the access right is applied to.

Returns: An AccessRight object.


Get an iterator for all access rights for an Entity.

Returns: An iterator for all access rights of an Entity.

get_child_by_name(name, entity_type)

Get a specific named immediate child entity of a given type.


Get all the immediate children of an entity of the given type.

Parameters Description
entity_type Entity type to search for

Returns: Generator object iterating over all children of specified type.


Get deployment roles for the entity.

Parameters Description
types An optional list of deployment role types (documented in the deployment_role class). If the list is empty all types are returned.

get_entities_by_name(name, entity_type, start=0, count=100)

Get entities (of certain type) with a specified name that are children of the current entity.

Parameters Description
name(str) Name of the requested entities.
entity_type Type of the requested entities.
start(int, optional) Beginning position in a complete list of results. Useful for pagination. Defaults to 0.
count(int, optional) Number of requested elements. Useful for pagination. Defaults to 100.

Returns: A generator over a sequence of instances of the corresponding entity type.

Return type: generator

Raises: BAMException – There is an error in communicating with BAM or the request cannot be serviced by BAM. For example bad input parameters.


Obtain a view from a configuration entity.

from bluecat.constants import EntityType

configuration_name = 'Sandbox'  # name of parent configuration
name = 'DMZ West'               # name you search by
api = g.user.get_api()          # a user-aware bluecat.api.API instance
configuration = api.get_configuration(configuration_name)

entities = configuration.get_entities_by_name(name, EntityType.VIEW, start=0, count=10)

for entity in entities:


Get the BAM ID of an entity.


Get all the linked entities of a given type

Returns: Iterator for a given type entities.


Get the BAM name of the entity.


Get the parent entity or None if the entity is at the top of the hierarchy.


Walk up the entity hierarchy and return the Configuration entity; if none was found, returns None; if starting entity is configuration, returns itself.

Returns: An iterator of parent configuration objects


Walk up the entity hierarchy and return the first parent entity of the given type or, if none was found, raise PortalException.


Get the BAM type of the entity.




Get the BAM ID of the entity.


Is this the null entity? (ID == 0).

link_entity(entity_id, properties='')

Link caller Entity object with another whose ID is ‘entity_id’. This method can be called by any side of a linking relationship between Entity objects.

Parameters Description
entity_id The ID of the Entity object to be linked, or to link.
properties Adds object properties, including user-defined fields.

Returns: The caller Entity object.


Get the BAM name of the entity.


Downloads an updated object from BAM.


Set the BAM name of the entity.


Change to JSON


Entity type of the entity object.


Persist any changes to the entity to the BAM database.