.. SPDX-FileCopyrightText: 2025 Univention GmbH
..
.. SPDX-License-Identifier: AGPL-3.0-only

.. _nubus-domain-extended-attributes:

Expand management modules
=========================

The domain management modules allow the comprehensive management of data in a domain.
*Extended attributes* offer the possibility of integrating additional attributes
to directory objects in the domain management
that the Nubus standard scope doesn't cover.
Third party vendors can also employ *extended attributes* for the integration of their solutions in Nubus.

You manage *extended attributes* in the *LDAP directory* management module.
In the directory structure, go to :menuselection:`univention --> custom attributes`.
You can edit existing attributes
or create *extended attributes* through clicking :guilabel:`Add`
and selecting *Settings: extended attribute*.
:numref:`nubus-domain-extended-attributes-figure`
shows an example for an *extended attribute*.

You can internationalize *extended attributes*.
In this case, compile the name and description in English,
because English is the default language for management modules.

This page provides a reference for managing *extended attributes*
and addresses functional administrators.
It describes the following tabs:

* :ref:`nubus-domain-extended-attributes-tab-general`
* :ref:`nubus-domain-extended-attributes-tab-module`
* :ref:`nubus-domain-extended-attributes-tab-ldap-mapping`
* :ref:`nubus-domain-extended-attributes-tab-umc`
* :ref:`nubus-domain-extended-attributes-tab-data-type`

.. _nubus-domain-extended-attributes-figure:

.. figure:: /images/domain_extended_attribute.*
   :alt: Extended attribute for managing a car license
   :width: 871px

   *Extended attribute* example for managing a car license

.. seealso::

   :ref:`nubus-domain-ldap`
      for information about the *LDAP directory* management module.

.. _nubus-domain-extended-attributes-tab-general:

General tab - extended attributes
---------------------------------

.. _nubus-domain-extended-attributes-tab-general-field-name:

Unique name
   The name of the *extended attribute*.
   The name must be unique in a container.

   .. FIXME: Clarify, if that change is correct. In the original text it referred to an LDAP object. Is this really the name of the LDAP object? This seems to be wrong.

UDM CLI name
   Specify this name,
   if you want to use the *extended attribute*
   through the command line interface of the Univention Directory Manager
   or the *UDM HTTP REST API*.

   .. TODO: Added REST API here. Clarify, if it's true.

   After saving the *extended attribute*,
   this field automatically adopts the value from the :ref:`nubus-domain-extended-attributes-tab-general-field-name` field
   and you can subsequently modify it.

Short description
   Used as title of the input field in management modules
   or as the attribute description in the command line interface.

Translations of short description
   You can save translated short descriptions in several languages
   so that Nubus shows the title of *extended attributes* also with other language settings
   in the respective national language.
   You need to assign the respective short description to a language code,
   for example ``de_DE`` or ``fr_FR``.

Long description
   Management modules show the long description as tool tip in input fields.

Translations of long description
   You can also save translated short descriptions in different languages.
   Nubus shows them as tool tip.
   You need to assign the respective long description to a language code,
   for example ``de_DE`` or ``fr_FR``.

.. _nubus-domain-extended-attributes-tab-module:

Module tab - extended attributes
--------------------------------

Modules to be extended
   Specify the management modules
   that you want to expand with the *extended attribute*.
   An *extended attribute* can apply for multiple modules.

Required options
   You can only practically use some *extended attributes*,
   if they have certain object classes activated on the *Options* tab.
   You can save one or more options in this input field
   so that Nubus shows the *extended attribute* or opens it for editing.

Hook class
   Nubus uses the functions of the hook class specified here during saving,
   modifying, and deleting objects with *extended attributes*.
   For additional information, see
   :external+uv-ucs-dev-reference:ref:`udm-hook`
   in :cite:t:`developer-reference`.

.. _nubus-domain-extended-attributes-tab-ldap-mapping:

LDAP mapping tab - extended attributes
--------------------------------------

LDAP object class
   Defines the object class
   to which the attribute entered in the
   :ref:`nubus-domain-extended-attributes-tab-ldap-mapping-field-ldap-attribte`
   field belongs.

   Nubus provides predefined LDAP schema extensions for *extended attributes*
   with the object class ``univentionFreeAttributes``.
   For more information, see :external+uv-ucs-manual:ref:`domain-ldap-extensions`.

   If you provide a value in this field,
   Nubus automatically adds this LDAP class to LDAP objects
   that you want to extend with the *extended attribute*.

.. _nubus-domain-extended-attributes-tab-ldap-mapping-field-ldap-attribte:

LDAP attribute
   The name of the LDAP attribute
   where Nubus stores the value.
   The specified LDAP object class must include the LDAP attribute.

Remove object class if the attribute is removed
   If activated
   and if someone deletes the value of an *extended attribute* in a management module,
   Nubus removes the LDAP attribute from the LDAP object.

   If the LDAP object doesn't use further attributes of the registered object class,
   Nubus also removes the LDAP object class from the LDAP object.

.. _nubus-domain-extended-attributes-tab-umc:

UMC tab - extended attributes
-----------------------------

Do not show this extended attribute in the UMC
   Activate this option,
   if you want this *extended attribute* only for internal administration
   instead of by an administrator,
   for example indirectly by scripts.

   If activated, you can only set this attribute through
   the Univention Directory Manager command line interface
   or the *UDM HTTP REST API*.
   Management modules don't show the *extended attribute*.

   .. TODO: Added REST API here. Clarify, if it's true.

Exclude from UMC search
   Activate this option
   if you don't want the *extended attribute*
   to show up in the search window of a wizard.
   It removes the *extended attribute* from the list of available search criteria.

   Only use this option in exceptional cases.

Ordering number
   If you manage several *extended attributes* on one tab,
   you can influence the order of the individual attributes on the tab here.
   Nubus adds the *extended attributes* in ascending order of their numbers
   to the end of the tab or the group in question.

   Assigning consecutive position numbers results
   in ordering the attributes on the left and right alternately in two columns.
   Otherwise, the positioning starts in the left column.
   If *extended attributes* have the same position number, their order is random.

Overwrite existing widget
   In some cases it's useful to overwrite predefined input fields with *extended attributes*.
   If you configured the internal UDM name of an attribute,
   Nubus overwrites its input field with this *extended attribute*.

   You can identify the UDM attribute with the
   :command:`univention-directory-manager` command,
   see :external+uv-ucs-manual:ref:`central-udm`.
   This option may cause problems
   if you apply it to a mandatory attribute.

Span both columns
   By default, Nubus groups all input fields into two columns.
   Use this option for overlong input fields
   that need the full width of the tab.

Tab name
   The name of the tab in management modules
   on which the *Management UI* shows the *extended attribute*.
   You can also add tabs here.

   If you don't provide a tab name,
   Nubus uses *user-defined*.

Translations of tab name
   You can provide translations for tab names
   by assigning translations to the corresponding language code,
   for example ``de_DE`` or ``fr_FR``.

Overwrite existing tab
   If activated,
   Nubus overwrites the tab before it positions the *extended attributes* on it.
   You can use this option to hide existing input fields on a predefined tab.

   .. note::

      This option can cause problems with compulsory fields.
      If the overwritten tab used translations,
      the overwriting tab must include identical translations.

Tab with advanced settings
   You can place rarely used settings on the *extended settings* tab.

Group name
   Groups allow the structuring of a tab.
   The *Management UI* separates a group by a gray horizontal bar.
   You can expand groups to show their entries
   or collapse them to hide entries.

   If you don't specify a group name for an *extended attribute*,
   the *Management UI* positions the attribute above the first group.

Translations of group name
   To translate the name of the group,
   add translated group names for the corresponding language code in this input field,
   for example ``de_DE`` or ``fr_FR``.

Group ordering number
   If one tab shows multiple groups,
   use this position number
   to specify the order of the groups.
   The *Management UI* shows the groups in ascending order of their position numbers.

.. _nubus-domain-extended-attributes-tab-data-type:

Data type tab - extended attributes
-----------------------------------

Syntax class
   Nubus performs a syntax check,
   when you enter values in management modules.

   Apart from standard syntax definitions (``string``) and (``integer``),
   you have three possibilities for expressing a binary condition.
   At LDAP level, the strings ``true`` and ``false`` represent the syntax ``TrueFalse``.
   The strings ``TRUE`` and ``FALSE`` correspond to the OpenLDAP boolean values
   with the syntax ``TrueFalseUpper``.
   The syntax ``boolean`` doesn't save any value or the string ``1``.

   The syntax ``string`` is the default.
   You can find an overview of the additionally available syntax definitions
   and instructions on integrating your own syntax in :cite:t:`developer-reference`.

Default value
   If you define a value as default value for the *extended attribute*,
   Nubus initializes new objects with this default value.
   You can still edit the value manually during object creation.
   Existing objects remain unchanged.

Multi value
   This option defines whether you can enter a single value or multiple values in the input mask.
   The scheme definition of the LDAP attribute specifies
   whether you can use one or several instances of the attribute in one LDAP object.

Value required
   If activated,
   you must enter a value for the *extended attribute*
   to create or save the object.

Editable after creation
   This option defines
   whether you can only modify the object saved in the *extended attribute*
   when saving the object,
   or whether you can also modify it subsequently.

Value is only managed internally
   If activated,
   you can neither modify the object manually,
   nor at creation time, nor later.
   This option is useful for internal state information
   through a hook function or internally inside a management module.

Copyable
   Nubus automatically fills out values of this *extended attribute* into the form
   when copying an object.