Virtual Data Center API classes and methods

The BMC Network Automation Web Services API fully exposes the information in the underlying Pod and Container Management (PCM) engine model to facilitate customizations and automated testing. The structure of the BMC Network Automation API reflects the underlying PCM model structure with some concessions made for the differences between the BMC Cloud Lifecycle Management and BMC Network Automation versions of the PCM model. Those differences are masked using Selector Data Transfer Objects (DTOs), which are similar to Union data types in the C programming language. In this case, you can populate some attributes if you select objects by using the BMC Cloud Lifecycle Management paradigm, and other attributes if you select objects by using the BMC Network Automation paradigm.

The Pod and Container Management (PCM) functionality in BMC Network Automation is only available if your deployment has BMC Cloud Lifecycle Management and the Virtual Data Center (VDC) is enabled in your BMC Network Automation. See Enabling-the-Virtual-Data-Center in the BMC Network Automation online technical documentation.

The PCM services and DTOs are distributed as part of the BMC Network Automation Web Services API in the ZIP file described on the Distribution-files page.

The BMC Network Automation Web Services API provides a set of PCM classes which abstract the lower-level web service functionality into a set of easy-to use classes. In addition to the service classes, the PCM portion of the API provides a set of DTO classes. DTOs are related to each service class. The firewall and zone components of the PCM model are implemented entirely as DTOs. See Using the API reference sections in the BMC Cloud Lifecycle Management documentation for information about accessing the Javadoc describing the DTOs.

The following sections document the key methods in each of the PCM classes.

Note

You can find a complete list of methods along with additional details on the method return values, exceptions, and parameters in the Javadoc provided in the BMC Network Automation Web Services distribution files (BCAN_HOME\public\bmc\bca-networks\extras\bcan-ws-clientapi-v.r.mm.zip). See Using the API reference sections in the BMC Cloud Lifecycle Management documentation for information about accessing the Javadoc.

AddressingService class

The AddressingService class offers methods related to acquiring and releasing addresses within a particular container.

Retrieve the WSDL for this service by using the https://server:port/bca-networks/services/AddressingService?wsdl URL.

Method	Description
acquireNatAddress()	(Deprecated in version 8.5.01) Acquires an address from the public or private address pool associated with the private address pool from which the specified private address was already acquired.
acquireNatAddress2()	(Version 8.5.01 and later) Acquires an address from the public or private address pool like the acquireNatAddress() method, but with the following differences: Includes registerDNS, an additional parameter to register the DNS. If this parameter and performDnsOperation, the global parameter, are set to true, the API call first acquires the IP address and then, depending on the value of the registerDNS flag, also adds a DNS record to the DNS servers. Includes additionalParams, an array of NameValueDTO that can be used to pass any additional parameters to only the third-party IPAM workflows in BMC Atrium Orchestrator for further customization. Note: This API does not support DNS registration and deregistration in BMC Network Automation. Set registerDNS to false for this API.
acquirePhysicalServerNicAddress()	(Deprecated in version 8.5.01) Acquires an address for the specified physical NIC that is being provisioned to the specified attach point (physical port) in the specified physical switch.
acquirePhysicalServerNicAddress2()	(Version 8.5.01 and later) Acquires an address for the specified physical NIC like the acquirePhysicalServerNicAddress() method, but with the following differences: Includes registerDNS, an additional parameter to register the DNS. If this parameter and performDnsOperation, the global parameter, are set to true, the API call first acquires the IP address and then, depending on the value of the registerDNS flag, also adds a DNS record to the DNS servers. Includes additionalParams, an array of NameValueDTO that can be used to pass any additional parameters to only the third-party IPAM workflows in BMC Atrium Orchestrator for further customization.
acquireRogueAddress()	Acquires the next available address from the specified address pool.
acquireSpecificNatAddress()	(Deprecated in version 8.6.00.001) Acquires a specific address from the public address pool associated with the private address pool from which the specified private address was already acquired.
acquireSpecificNatAddress2()	(Version 8.6.00.001 and later) Acquires a specific address from the public address pool associated with the private address pool from which the specified private address was already acquired, but with the following difference: Includes skipAcquireIPAMOperation, an additional parameter that indicates whether BMC Network Automation should skip the actual Acquire Address operation on the IPAM system. If this parameter is set to true, the desired address is in an "acquired" state in the IPAM system, and BMC Network Automation simply confirms that the desired address is in the "Used address list" without performing the Acquire Address operation on the IPAM system. If this parameter is set to false, BMC Network Automation performs the Acquire Address operation on the IPAM system.
acquireSpecificPhysicalServerNicAddress()	(Deprecated in version 8.6.00.001) Acquires an address for the specified physical NIC that is being provisioned to the specified attach point (physical port) in the specified physical switch.
acquireSpecificPhysicalServerNicAddress2()	(Version 8.6.00.001 and later) Acquires an address for the specified physical NIC that is being provisioned to the specified attach point (physical port) in the specified physical switch, but with the following difference: Includes skipAcquireIPAMOperation, an additional parameter that indicates whether BMC Network Automation should skip the actual Acquire Address operation on the IPAM system. If this parameter is set to true, the desired address is in an "acquired" state in the IPAM system, and BMC Network Automation simply confirms that the desired address is in the "Used address list" without performing the Acquire Address operation on the IPAM system. If this parameter is set to false, BMC Network Automation performs the Acquire Address operation on the IPAM system.
acquireSpecificRogueAddress()	(Deprecated in version 8.6.00.001) Acquires the specified desired address from the specified address pool.
acquireSpecificRogueAddress2()	(Version 8.6.00.001 and later) Acquires the specified desired address from the specified address pool, but with the following difference: Includes skipAcquireIPAMOperation, an additional parameter that indicates whether BMC Network Automation should skip the actual Acquire Address operation on the IPAM system. If this parameter is set to true, the desired address is in an "acquired" state in the IPAM system, and BMC Network Automation simply confirms that the desired address is in the "Used address list" without performing the Acquire Address operation on the IPAM system. If this parameter is set to false, BMC Network Automation performs the Acquire Address operation on the IPAM system.
acquireSpecificVirtualServerNicAddress()	(Deprecated in version 8.6.00.001) Acquires an address for the specified virtual NIC that is being provisioned to the specified attach point (virtual port created from a virtual port type) in the specified virtual switch.
acquireSpecificVirtualServerNicAddress2()	(Version 8.6.00.001 and later) Acquires an address for the specified virtual NIC that is being provisioned to the specified attach point (virtual port created from a virtual port type) in the specified virtual switch, but with the following difference: Includes skipAcquireIPAMOperation, an additional parameter that indicates whether BMC Network Automation should skip the actual Acquire Address operation on the IPAM system. If this parameter is set to true, the desired address is in an "acquired" state in the IPAM system, and BMC Network Automation simply confirms that the desired address is in the "Used address list" without performing the Acquire Address operation on the IPAM system. If this parameter is set to false, BMC Network Automation performs the Acquire Address operation on the IPAM system.
acquireVirtualServerNicAddress()	(Deprecated in version 8.5.01) Acquires an address for the specified virtual NIC that is being provisioned to the specified attach point (virtual port created from a virtual port type) in the specified virtual switch.
acquireVirtualServerNicAddress2()	(Version 8.5.01 and later) Acquires an address for the specified virtual NIC like the acquireVirtualServerNicAddress() method, but with the following difference: Includes registerDNS, an additional parameter to register the DNS. If this parameter and performDnsOperation, the global parameter, are set to true, the API call first acquires the IP address and then, depending on the value of the registerDNS flag, also adds a DNS record to the DNS servers. Includes additionalParams, an array of NameValueDTO that can be used to pass any additional parameters to only the third-party IPAM workflows in BMC Atrium Orchestrator for further customization.
excludeIPAddresses()	(Deprecated in version 8.5.00) Excludes given IP addresses from address pools.
getDnsInfo()	Retrieves the DNS information of the specified address, irrespective of whether the IP address is acquired or not from an address pool.
reincludeIPAddresses()	(Deprecated in version 8.5.00) Re-includes given IP addresses (that were previously excluded) into address pools.
releaseAllServerNicAddresses()	(Deprecated in version 8.5.01) Releases the addresses previously acquired for all NICs (physical or virtual) associated with the specified server back to their address pools and removes their references from the container.
releaseAllServerNicAddresses2()	(Deprecated in version 8.6.00.001) Releases the addresses previously acquired for all NICs like the releaseAllServerNicAddresses() method. This method includes additionalParams, an array of NameValueDTO that can be used to pass any additional parameters to only the third-party IPAM workflows in BMC Atrium Orchestrator for further customization.
releaseAllServerNicAddresses3()	(Version 8.6.00.001 and later) Releases the addresses previously acquired for all NICs like the releaseAllServerNicAddresses2() method, but with the following difference: Includes skipReleaseIPAMOperation, an additional parameter that indicates whether BMC Network Automation should skip the actual Release Address operation on the IPAM system. If this parameter is set to true, the desired address is in a "released" state in the IPAM system, and BMC Network Automation simply removes the NIC details from its database without performing the Release Address operation on the IPAM system. If this parameter is set to false, BMC Network Automation performs the Release Address operation on the IPAM system. (Version 8.7.00 and later) This method also releases any associated NAT addresses.
releaseNatAddress()	(Deprecated in version 8.5.01) Releases the specified public NAT address back to its address pool and removes its reference from the container.
releaseNatAddress2()	(Deprecated in version 8.6.00.001) Releases the specified public NAT address like the releaseNatAddress() method. This method includes additionalParams, an array of NameValueDTO that can be used to pass any additional parameters to only the third-party IPAM workflows in BMC Atrium Orchestrator for further customization. Note: This API does not support DNS registration and deregistration in BMC Network Automation version 8.5.01.
releaseNatAddress3()	(Version 8.6.00.001 and later) Releases the specified public NAT address like the releaseNatAddress2() method, but with the following difference: Includes skipReleaseIPAMOperation, an additional parameter that indicates whether BMC Network Automation should skip the actual Release Address operation on the IPAM system. If this parameter is set to true, the desired address is in a "released" state in the IPAM system, and BMC Network Automation simply removes the NIC details from its database without performing the Release Address operation on the IPAM system. If this parameter is set to false, BMC Network Automation performs the Release Address operation on the IPAM system.
releasePhysicalServerNicAddress()	(Deprecated in version 8.5.01) Releases an address previously acquired for the specified physical server NIC back to its address pool and removes its reference from the container.
releasePhysicalServerNicAddress2()	(Deprecated in version 8.6.00.001) Releases an address previously acquired for the specified physical server NIC like the releasePhysicalServerNicAddress() method. This method includes additionalParams, an array of NameValueDTO that can be used to pass any additional parameters to only the third-party IPAM workflows in BMC Atrium Orchestrator for further customization. (Version 8.7.00 and later) This method also releases any associated NAT addresses.
releasePhysicalServerNicAddress3()	(Version 8.6.00.001 and later) Releases an address previously acquired for the specified physical server NIC like the releasePhysicalServerNicAddress2() method, but with the following difference: Includes skipReleaseIPAMOperation, an additional parameter that indicates whether BMC Network Automation should skip the actual Release Address operation on the IPAM system. If this parameter is set to true, the desired address is in a "released" state in the IPAM system, and BMC Network Automation simply removes the NIC details from its database without performing the Release Address operation on the IPAM system. If this parameter is set to false, BMC Network Automation performs the Release Address operation on the IPAM system.
releaseRogueAddress()	(Deprecated in version 8.6.00.001) Releases a previously acquired rogue address back to its address pool and removes it reference from the container. (Version 8.7.00 and later) This method also releases any associated NAT addresses.
releaseRogueAddress2()	(Version 8.6.00.001 and later) Releases a previously acquired rogue address back to its address pool and removes it reference from the container like the releaseRogueAddress() method, but with the following difference: Includes skipReleaseIPAMOperation, an additional parameter that indicates whether BMC Network Automation should skip the actual Release Address operation on the IPAM system. If this parameter is set to true, the desired address is in a "released" state in the IPAM system, and BMC Network Automation simply removes the NIC details from its database without performing the Release Address operation on the IPAM system. If this parameter is set to false, BMC Network Automation performs the Release Address operation on the IPAM system.
releaseVirtualServerNicAddress()	(Deprecated in version 8.5.01) Releases an address previously acquired for the specified virtual server NIC back to its address pool and removes its reference from the container.
releaseVirtualServerNicAddress2()	(Deprecated in version 8.6.00.001) Releases an address previously acquired for the specified virtual server NIC like the releaseVirtualServerNicAddress() method. This method includes additionalParams, an array of NameValueDTO that can be used to pass any additional parameters to only the third-party IPAM workflows in BMC Atrium Orchestrator for further customization.
releaseVirtualServerNicAddress3()	(Version 8.6.00.001 and later) Releases an address previously acquired for the specified virtual server NIC like the releaseVirtualServerNicAddress2() method, but with the following difference: Includes skipReleaseIPAMOperation, an additional parameter that indicates whether BMC Network Automation should skip the actual Release Address operation on the IPAM system. If this parameter is set to true, the desired address is in a "released" state in the IPAM system, and BMC Network Automation simply removes the NIC details from its database without performing the Release Address operation on the IPAM system. If this parameter is set to false, BMC Network Automation performs the Release Address operation on the IPAM system. (Version 8.7.00 and later) This method also releases any associated NAT addresses.

ContainerBlueprintService class

The ContainerBlueprintService class provides container blueprint related operations.

Retrieve the WSDL for this service by using the https://server:port/bca-networks/services/ContainerBlueprintService?wsdl URL.

Method	Description
describeIncompatability()	Returns a description of the ways in which the specified container blueprint is incompatible with the specified pod.
getAllBlueprints()	(Version 8.5.01 and later) Returns information about all the container blueprints.
getAllBlueprintNames()	Returns a list of all container blueprint names.
getBlueprint()	Returns information about the given container blueprint.
getCompatibleBlueprintNames()	Returns a list of container blueprints compatible with the specified pod.
getRuntimeParamNames()	(Deprecated in version 8.5.00) Returns the set of runtime parameter names in container blueprint.
isCompatible()	Returns true if the specified container blueprint is compatible with the specified pod; false otherwise.
provisionContainer()	Provisions a container on the specified pod using the specified container blueprint.
reprovisionContainer()	(Deprecated in version 8.5.00) Reprovisions a container by using an updated version of the blueprint which was used to originally provision it. Use reprovisionContainer2().
reprovisionContainer2()	(Version 8.5.00 and later) Reprovisions a container by using the specified container name and blueprint name. Reprovisioning a container updates the structure of the container by using the new blueprint, which involves the following actions: Adding new content that is present in the blueprint but missing from the container Modifying existing content in a limited fashion

ContainerService class

The ContainerService class provides container-related lifecycle operations.

Retrieve the WSDL for this service by using the https://server:port/bca-networks/services/ContainerService?wsdl URL.

Method	Description
connectPhysicalServerNic()	Executes a job to configure the specified attach point (port) in the physical switch to support traffic on its associated VLAN.
deprovisionContainer()	Deprovisions a container.
getAllContainerNames()	Returns a list of all container names.
getAllContainerNodes()	Returns information about all nodes in a container.
getAllContainerPairs()	Returns information about all pairs in a container.
getContainer()	Returns information about the given container.
getContainerJobs()	Returns the IDs of the jobs that were executed during provisioning and deprovisioning of the given container.
getContainerNamesInPod()	Returns the container names associated with a given pod.
getRuntimeParamNames()	(Deprecated in version 8.5.00) Returns the runtime parameters that would be needed if you were to modify the container to toggle component states as specified.
modifyContainer()	Modifies the container by toggling dynamic components (NIC segments, VLBs, and VFWs) as specified.

DNSService class

The DNSService class provides methods for DNS registration and deregistration for non-BMC Network Automation containers such as Amazon Web Service (AWS) and Azure in BMC Cloud Lifecycle Management. This public API further calls the BMC Atrium Orchestrator DNS workflows, which perform DNS registration and de-registration.

Note

This API supports only IPv4 DNS records, not IPv6 DNS records.

Retrieve the WSDL for this service by using the https://server:port/bca-networks/services/DNSService?wsdl URL.

Method	Description
deregisterDNS()	Deregisters the DNS by using the host name and IP address from the specified DNS server.If a DNS record is not found in the DNS server, deregistration does not fail; instead, the API returns true.
registerDNS()	Registers the DNS by using the host name and IP address in the specified DNS server.

IPAMService class

The IPAMService class provides IP address management-related operations.

Retrieve the WSDL for this service by using the https://server:port/bca-networks/services/IPAMService?wsdl URL:

Method	Description
acquireAddress()	Acquires the next available IP address from the pool. Once an address is acquired it cannot be acquired again before it is released.
acquireBlock()	Acquires an entire block of addresses, including the startAddress and extending to startAddress+blockSize (exclusive). If the range of addresses involved is not entirely free, an IllegalArgumentexception occurs.
acquireSpecificAddress()	Acquires an IP address from the pool. If the specified address is not free, an IllegalArgumentexception occurs.
createRange()	Creates a range of continuous pools of the specified size and returns the list of pool IDs. You can specify the network and subnet mask in the dotted decimal or CIDR format. Note: If the pools do not exist in the IP Address Management (IPAM) system, they will be automatically created as a side effect of reserving them.
deletePool()	Deletes an address pool with the specified pool ID.
deleteRange()	Frees and deletes all of the specified pools, which are assumed to comprise a particular range that was previously reserved.
excludeAddresses()	Excludes specified IP addresses with given exclusion scopes from address pools. The input to the excludeAddresses() API is NameValueDTO where the <name> tag specifies the optional exclusion scopes and the <value> tag specifies the IP addresses to be excluded. If the exclusion scope is null or empty, addresses are excluded globally. In other words, the specified addresses are excluded for use within all pods and containers. Note: The exclusion scope value is not considered for the Infoblox IPAM provider. As a result, addresses are excluded at a global level. If the exclusion scope has a non-null value, the specified addresses are excluded only from those subnets that have a matching exclusion scope as described below: If the exclusion scope value is the same as the pod name, the address is excluded for use within the pod address ranges and pod address pools owned by the specified pod. If the exclusion scope value is the same as the container.container name, the address is excluded for use within the address spaces owned by the specified container. This API is supported for the BMC Network Automation home-grown IPAM provider and third-party IPAM providers.
freePool()	Releases or unallocates all the addresses that are previously acquired from the pool.
getExcludedAddresses()	Returns a list of excluded IP addresses with optional matching input exclusion scope. If exclusion scope is not specified, it fetches a list of excluded IP addresses with GLOBAL scope.
getFreeAddresses()	Returns a list of free IP addresses from address pool with specified pool ID.
getPool()	Returns the address pool details of specified pool ID.
getPools()	Returns a list of address pools from the IPAM system.
getUsedAddresses()	Returns a list of used IP addresses from an address pool with a specified pool ID.
reincludeAddresses()	Reincludes specified IP addresses that were earlier excluded with given exclusion scope into address pools. The input to the reincludeAddresses() API is NameValueDTO where the <name> tag specifies the optional exclusion scopes and the <value> tag specifies the IP addresses to be reincluded. If the exclusion scope is null or empty, addresses which are excluded globally are reincluded. If the exclusion scope has a non-null value, the specified addresses are reincluded only from those subnets that have a matching exclusion scope as described below: If the exclusion scope value is the same as the pod name, the address, which was earlier excluded, is reincluded for use within the pod address ranges and pod address pools owned by the specified pod. If the exclusion scope value is the same as the container.container name, the address, which was earlier excluded, is reincluded for use within the address spaces owned by the specified container. This API is only supported for the BMC Network Automation home-grown IPAM provider because the operation is not supported for third-party IPAM providers.
releaseAddress()	Releases the specified IP address from the given address pool.
reservePool()	Reserves a specific pool that is not part of any particular range. You can specify the subnet mask in the dotted decimal or CIDR format.

LoadBalancerService class

The LoadBalancerService class provides operations for administering server load balancing within a given container.

Retrieve the WSDL for this service by using the https://server:port/bca-networks/services/LoadBalancerService?wsdl URL.

Method	Description
addPool()	Executes a job to add a pool of the specified type to the specified Virtual Load Balancer (VLB) device. Note: BMC Network Automation cannot create an LB pool and a pool entry in one request.
addPoolEntries()	Executes a job to add the specified entries to the specified pool in its associated VLB device.
disablePoolEntries()	Executes a job to disable the specified entries in the specified pool in its associated VLB device.
enablePoolEntries()	Executes a job to enable the specified entries in the specified pool in its associated VLB device.
getAllPoolNames()	Returns names of load balancer pools within the load balancer in the specified container and zone.
getPool()	Returns the specified load balancer pool and all of its entries.
removePool()	Executes a job to remove the specified pool from its associated VLB device. Note: If the removePool() action fails for a LB pool created in BMC Network Automation versions earlier than 8.3.02 HF#5, see Upgrading from versions earlier than 8.3.01 HF#5 to 8.8.00 for details.
removePoolEntries()	Executes a job to remove the specified entries from the specified pool from its associated VLB device.

PodService class

The PodService class provides pod-related operations.

Retrieve the WSDL for this service by using the https://server:port/bca-networks/services/PodService?wsdl URL.

Method	Description
addAddressPool()	Adds an address pool with the given information to the specified pod.
addExtendedVlanPool()	Adds an extended VLAN pool with the given information to the specified pod. For an extended pool (a pool supporting VXLAN), the VLAN pool range is from 0 to 2²⁴, as compared to the standard VLAN pool, which has pool range from 0 to 4096.
addVlanPool()	Adds a VLAN pool with the given information to the specified pod.
deleteAddressPool()	Deletes an address pool with the given name and given pool address from the specified pod.
deletePod()	Deletes a pod with a specified name.
deleteVlanPool()	Deletes a VLAN pool with the given name from the specified pod. If multiple VLAN pools exist with the given VLAN pool name (as can happen when they are chained from the BMC Network Automation GUI ), this call deletes all the pools whose VLANs are not used.
getAllPodNames()	Returns the names of all pods.
getAllPodNodes()	Returns information about all the nodes in a pod.
getAllPodPairs()	Returns information about all the pairs in a pod.
getPod()	Returns information about a given pod.

SecurityService class

The SecurityService class provides operations for administering firewall security within a given container.

Retrieve the WSDL for this service by using the https://server:port/bca-networks/services/SecurityService?wsdl URL.

Method	Description
addFirewallRules()	Executes a job to add rules to a particular ACL in a Virtual Firewall (VFW). Note: Although BMC Network Automation allows you to add a disabled firewall rule, BMC Network Automation never transfers the rule to the device.
addPathRules()	Adds path rules and returns FirewallAclUpdateDTO as a response.
addPathRules2()	Adds path rules and returns PathRuleDTO as a response.
getAllFirewallRules()	Returns all firewall rules for the specified ACL in a VFW.
getAllPathRules()	Returns all path rules for the specified container from the BMC Network Automation database.
persistExternalPathRules()	Persists high level path rules in BMC Network Automation.
removeFirewallRules()	Executes a job to remove rules from a particular ACL in a VFW (if they are present).
removePathRules()	Removes path rules (if they are present).
replaceFirewallRules()	Executes a job to replace rules in a particular ACL in a VFW.
Note: You can access the rules for a particular ACL either by using the name or the nameWIthinFirewall parameter of the interface. In the BMC Cloud Lifecycle Management GUI, the Network Containers > Manage Firewall Rules > Interface values map to the values in the Name or Name Within Firewall column in the Container view > VFW > Managed Interface section in the BMC Network Automation GUI.