POST /v1/addDeviceInstance - BlueCat Address Manager - 9.1.0

Address Manager API Guide

Locale
English (United States)
Product name
BlueCat Address Manager
Version
9.1.0

Description

Adds a device instance. Use this method to provision new devices for the network. This method combines a number of existing API methods into one:
  • It assigns the next available, or manually defined, IP address.
  • It optionally adds a DNS host record and MAC address that are linked to the IP address.
  • It returns the property string containing the IP address, netmask, and gateway.
When configured with a DNS host record, addDeviceInstance updates the DNS server to immediately deploy the host record.
Attention: Limitations
  • If the addDeviceInstance API is used to add a static host record and this record is either updated or deleted followed by a full deployment, the changes will not be sent to BDDS resulting in duplicate host records.

    After either updating or deleting a static host record that was added using the addDeviceInstance API, a quick, differential, or selective deployment must be performed prior to performing a full deployment. Failing to do so will result in duplicated records on BDDS.

    A quick deployment is only effective if initiated by the same user that performed the initial change.

  • Static host records are not visible on BDDS, but are visible in BAM in the following scenario:
    • When a static host record is added using the addDeviceInstance API and the same host record is deleted then deployed through the Address Manager user interface proceeded by the recreation of the original static host record on the same IP address using the addDeviceInstance API during the deployment.

      The static host record that is visible in BAM will become visible on BDDS once another deployment is performed.

  • If the addDeviceInstance API is used more than once to add the same static host record with the allowDuplicateHosts DNS deployment option set to true, the host record will be linked to two different IP addresses in BAM. However, on BDDS, only one IP address is linked to the host record.

    The static host record that is visible in BAM will become visible on BDDS once another deployment is performed.

Parameters

Name Description
configName

Location: query

Type: string

Name of parent configuration. If the value is empty or cannot be found, an exception will be thrown.
deviceName

Location: query

Type: string

IP address or device name of the new instance. This is reserved for future use.
ipAddressMode

Location: query

Type: string

Accepted values are:
  • REQUEST_STATIC — Use to get the next available static IP address.
  • REQUEST_DHCP_RESERVED - Use to get the next available DHCP reserved IP address (reserved for future use).
  • PASS_VALUE - use to pass an existing IP address. Metadata values will only be updated to the newly assigned IP address only.
ipEntity

Location: query

Type: string

If ipAddressMode is REQUEST_STATIC or REQUEST_DHCP_RESERVED, this must be the network where the IP address will be provisioned from in the format of an IP address range in CIDR format or range.

If ipAddressMode is PASS_VALUE, this must be an IP address.

macAddressMode

Location: query

Type: string

Accepted values are:
  • REQUEST_VALUE - Reserved for future use.
  • PASS_VALUE - Use to manually provide the MAC address linked to the IP address.

If you specify an empty string, the MACEntity parameter will be ignored.

macEntity

Location: query

Type: string

If macAddressMode is PASS_VALUE, this must be a MAC address. If macAddressMode is REQUEST_VALUE, this is a MAC mask.
options

Location: query

Type: string

The options string contains four properties: skip, offset, excludeDHCPRange, and allowDuplicateHosts.
  • skip —this is optional. It is applied to REQUEST_STATIC and REQUEST_DHCP_RESERVED for ipAddressMode. It is used to specify the IP address ranges or IP addresses to skip, separated by comma. A hyphen (–), not a dash (-), is used to separate the start and end addresses.
  • offset —this is optional. It is applied to REQUEST_VALUE for ipAddressMode. This is to specify from which address to start to assign IPv4 Address.
  • excludeDHCPRange —this specifies whether IP addresses in DHCP ranges should be excluded from assignment or not. It is applied to REQUEST_STATIC only for ipAddressMode. The value is either true or false; the default value is false. The value will always be set to true if the ipAddressMode is REQUEST_DHCP_RESERVED.
  • allowDuplicateHosts —this specifies whether the IP address can be added to an existing host record or not. The value is either true or false; the default value is false.
  • staticHost —specifies whether a static host or a dynamic host is created. The value is either true or false; the default value if false. The value “true” creates a static host and the value “false” creates a dynamic host.
Note: The values for skip and offset must be IPv4 addresses and must appear in dotted octet notation.
recordName

Location: query

Type: string

Name of the host record to add. This cannot be empty if both viewName and zoneName are specified and in use. The viewName, zoneName, and recordName parameters must be used together: the values must all be an empty string, or they must all be populated with specific values.
Note: If all three parameter values are an empty string, DNS objects will not be created but an IP address will be assigned from a network and linked to a MAC address.
viewName

Location: query

Type: string

Name of parent view.
Note: Specify an empty string ("") for all viewName, zoneName, and recordName parameters to ignore DNS object creation.
zoneName

Location: query

Type: string

Parent zone of the record. This must be specified and existing if the viewName parameter is an empty string and existing.
Note: Specify an empty string for all viewName, zoneName and recordName parameters to ignore DNS object creation.

Responses

Code Description
201

Type: string

Returns the property string containing IP address, netmask, and gateway.