Custom Field

class CustomField(api)

Bases: FeatureBase

create(label, name, classes, data_type, allowed_characters=None, allowed_values=None, category=None, date_only=None, default_values=None, display_after=None, error_message=None, help_text=None, localization_table=None, localized_help=None, localized_label=None, localized_set=None, mandatory=None, mask=None, maximum_length=None, minimum_length=None, policyable=None, regular_expression=None, render_hidden=None, render_read_only=None, single=None, time_only=None, get_if_already_exists=True)

Creates a Custom Field (or Metadata Item). Custom fields appear in the UI unless render_hidden = True. If the custom field should be implemented on a folder policy, then set policyable=True, otherwise the custom field cannot be enforced on a policy, but will instead apply to all objects that belong to one of the classes. If it is configured to be policyable, the classes still apply. For example, if one of the classes is set to “X509 Certificate”, then all objects that are a “X509 Certificate” will inherit the custom field. If it is set to be policyable and is locked to a specific value, only “X509 Certificate” objects under the policy folder will have that value locked.

Parameters

  • label (str) – The label text for the custom field.

  • name (str) – The name of the custom field object.

  • classes (list) – The classes that this field applies to.

  • data_type (int) – The field type as an integer.

  • allowed_characters (List[str]) – A set of allowable alphabetic, numeric, or symbols.

  • allowed_values (List[str]) – An array of allowable values.

  • category (str) – Absolute path to the item category.

  • date_only (bool) – If True, a calendar date is required.

  • default_values (List) – List of default values.

  • display_after (str) – Appears after a list of Custom Field values.

  • error_message (str) – The error message when an error is encountered.

  • help_text (str) – The tool tip for the UI.

  • localization_table (str) – A list or dictionary of strings from another language.

  • localized_help (Union[List[str], Dict]) – The localized help text that describes the Metadata Custom Field.

  • localized_label (str) – A localized label text describing the Metadata Custom Field.

  • localized_set (str) – A list of localization settings.

  • mandatory (bool) – If True, this field is required.

  • mask (str) – The set of characters to use to hide user input in the UI.

  • maximum_length (int) – Maximum number of allowed characters.

  • minimum_length (int) – Minimum number of allowed characters.

  • policyable (bool) – If True, the custom field can be enforced on a policy folder.

  • regular_expression (str) – The regular expression to control user input.

  • render_hidden (bool) – If True, hides the field from the UI.

  • render_read_only (bool) – If False, the user can change the default values (if not locked by policy).

  • single (bool) – If False, the user can select/input multiple items.

  • time_only (bool) – If True, time of day is required.

  • get_if_already_exists (bool) – If the objects already exists, just return it as is.

Returns

The custom field Item data.

delete(custom_field, remove_data=True)

Deletes a custom field and all instances of it, including policy settings. If remove_data = False, then an exception will be raised if there is existing data for the custom field on any object.

Parameters

  • custom_field (Union[config.Object, metadata.Item, str]) – Config Object or name of the custom field.

  • remove_data (bool) – If True, then deletes the custom field regardless of data existing on the custom field on any object that implements it.

get(name=None, raise_error_if_not_exists=True)
Parameters

  • name (str) – The name of the custom field object.

  • raise_error_if_not_exists (bool) – Raise an exception if the custom field does not exist.

Returns

Config Object of the custom field object.

get_item_details(custom_field=None)
Parameters

custom_field (Union[config.Object, metadata.Item, str]) – Config Object or name of the custom field object.

Returns

The custom field Item data.

list()

Lists all custom fields registered in TPP.

Returns

List of each custom field Item data.

read(obj, custom_field)

Reads the effective value(s) of a custom field (which includes for policy values). Value(s) may be None.

Parameters
Returns

A EffectiveValues object with these properties

  • locked bool - If True, the values are locked by the policy.

  • policy_dn str - Distinguished Name (DN) of the policy folder locking the values.

  • values List[str] - List of values.

Return type

EffectiveValues

read_policy(folder, custom_field, class_name)

Reads the effective value(s) of a custom field set on a policy. Value(s) may be None.

Parameters
Returns

A PolicyValues object with these properties

  • locked bool - If True, the values are locked by the policy.

  • values List[str] - List of values.

Return type

PolicyValues

update(custom_field, allowed_characters=None, allowed_values=None, category=None, classes=None, data_type=None, date_only=None, default_values=None, display_after=None, error_message=None, help_text=None, label=None, localization_table=None, localized_help=None, localized_label=None, localized_set=None, mandatory=None, mask=None, maximum_length=None, minimum_length=None, name=None, policyable=None, regular_expression=None, render_hidden=None, render_read_only=None, single=None, time_only=None)

Updates a custom field’s properties. If a parameter is None it does not affect the current setting of that property. Property values are not reset to their defaults.

Parameters

  • custom_field (Union[config.Object, metadata.Item, str]) – Config Object or name of the metadata object.

  • label (str) – The label text for the custom field.

  • name (str) – The name of the custom field object.

  • classes (list) – The classes that this field applies to.

  • data_type (int) – The field type as an integer.

  • allowed_characters (List[str]) – A set of allowable alphabetic, numeric, or symbols.

  • allowed_values (List[str]) – An array of allowable values.

  • category (str) – Absolute path to the item category.

  • date_only (bool) – If True, a calendar date is required.

  • default_values (str) – List of default values.

  • display_after (str) – Appears after a list of Custom Field values.

  • error_message (str) – The error message when an error is encountered.

  • help_text (str) – The tool tip for the UI.

  • localization_table (str) – A list or dictionary of strings from another language.

  • localized_help (str) – The localized help text that describes the Metadata Custom Field.

  • localized_label (str) – A localized label text describing the Metadata Custom Field.

  • localized_set (str) – A list of localization settings.

  • mandatory (bool) – If True, this field is required.

  • mask (str) – The set of characters to use to hide user input in the UI.

  • maximum_length (int) – Maximum number of allowed characters.

  • minimum_length (int) – Minimum number of allowed characters.

  • policyable (bool) – If True, the custom field can be enforced on a policy folder.

  • regular_expression (str) – The regular expression to control user input.

  • render_hidden (bool) – If True, hides the field from the UI.

  • render_read_only (bool) – If False, the user can change the default values (if not locked by policy).

  • single (bool) – If False, the user can select/input multiple items.

  • time_only (bool) – If True, time of day is required.

Returns

The custom field Item data.

write(obj, custom_field, values, keep_existing=True)

Writes a set of values to a custom field on the specified obj. If keep_existing = False, then all custom fields related to the obj are reset to their default values.

Parameters
write_policy(folder, custom_field, class_name, values, locked=False)

Writes a set of values to a custom field on the specified folder. The custom field MUST be policyable. To ensure, use :meth:get to get the current settings and verify that policyable=True. If not, use :meth:update to update the custom field with policyable=True.

Parameters