Valid values for extensible attributes

Extensible attributes are sets of name/value pairs associated with an object. The name and the type of value are defined in the extensible attribute definition.

Objects that support extensible attributes have an extattrs field, which is a dictionary that contains the name/value dictionary pairs.

Following is an example of using JSON to encode the extensible attributes field:

"extattrs": {
             "attrstring": {"value": "test string"},
             "attrinteger": {"value": -1},
             "attremail": {"value": "test@test.com"},
             "attrdate": {"value": "2011-11-23T11:01:00Z"},
             "attrenum": {"value": "Enum Value"},
             }

where each attribute has a valid type described by its name.

Extensible attributes inheritance

If inheritance is enabled for this extensible attribute, the following fields are supported in the extensible attribute value object:

"attr": {
     "value": <the extattr value>,
     # The following is a read-only field
     "inheritance_source": <reference to the object this EA is inheriting from>,

     # The following are write-only fields
     "inheritance_operation": one of 'INHERIT', 'DELETE' or 'OVERRIDE'
     "descendants_action": {
           "option_delete_ea": one of 'REMOVE' or 'RETAIN'
           "option_with_ea": one of 'CONVERT', 'INHERIT' or 'RETAIN'
           "option_without_ea": one of 'INHERIT' or 'NOT_INHERIT'
     }
}

Following is an example of using JSON to insert a set of extensible attributes exercising the above fields:

"extattrs": {
    "EAname": {
          "descendants_action": {
                "option_with_ea": "RETAIN",
                "option_without_ea": "NOT_INHERIT"},
          "value": "EAvalue"}}

Note: For extensible attributes inheritance to work correctly with Host Record object (record:host) use_for_ea_inheritance should be set to true for one of its IP host addresses: IPv4 Host address object (record:host_ipv4addr) or IPv6 Host address object (record:host_ipv6addr).

inheritance_operation

By default, this field is set to ‘OVERRIDE’ if it is not specified. If it is set to ‘INHERIT’, the value field will be ignored or omitted, and the value will be set to inherit from the object’s parent.

inheritance_source

This is a read-only field. If present, it contains the reference to the object from which the value of the extensible attribute is inherited.

descendants_action:option_delete_ea

This field determines the action to be taken for the object’s children when the extensible attribute is removed. This field is meaningful only when inheritance_operation is set to ‘DELETE’.

If this field is set to ‘REMOVE’, the extensible attributes of the object’s children will also be removed. If it set to ‘RETAIN’, they will be retained.

descendants_action:option_with_ea

This field determines the action to be taken for the object’s children when the extensible attribute is added or modified. This field is meaningful only when inheritance_operation is set to ‘INHERIT’.

If this field is set to ‘CONVERT’ and the extensible attribute value of the object’s children is the same as that of the parent, the value will change to an inherited attribute. If the value is different, it will not be changed.

If this field is set to ‘INHERIT’, the extensible attribute value of the object’s children will be set to inherit from the parent, regardless of its previous value.

If the field is set to ‘RETAIN’, the extensible attribute value of the object’s children will not be modified.

descendants_action:option_without_ea

This field determines the action to be taken for the object’s children when the extensible attribute is added or modified. This field is meaningful only when inheritance_operation is set to ‘INHERIT’ or ‘OVERRIDE’ and the object’s children do not have values set for this extensible attribute.

If this field is set to ‘INHERIT’, the object’s children will have a new extensible attribute added, which is inherited from its parent.

If this field is set to ‘NOT_INHERIT’, no changes will be made to the object’s children.

Extensible attributes search

Extensible attributes require a special search syntax. Searches for extensible attributes are sent by prefixing the extensible attribute name with an asterisk (*). Standard search suffixes can be applied to the extensible attribute if they are supported by the attribute type.

For example, a search for all networks that contain a string extensible attribute named ‘Building’ with a case-insensitive value ‘data center’ should be sent to the server as follows (using HTTP GET):

GET /wapi/v2.12.3/network?*Building:='Data Center'

Extensible attributes update

The extensible attributes field allows +/- to be specified as part of the field name while updating the object, which will respectively add/modify or remove the specified extensible attribute. The appliance returns an error when the specified extensible attribute does not exist. Note that this is supported only when using JSON to access WAPI.

Following is an example of unconditionally removing the “attrstring” and “attrinteger” extensible attributes:

"extattrs-": {
             "attrstring": {},
             "attrinteger": {}
             }

To remove an extensible attribute that has a specific value, the value should be passed to the request as follows:

"extattrs-": {
             "attrstring": {"value": "test string"},
             }

If the specified value is different than the existing value, the appliance returns an error.

Following is an example of adding or updating (if the extensible attribute already exists) the “attrstring” extensible attribute:

"extattrs+": {
             "attrstring": {"value": "new string"}
             }