Univention Corporate Server - Manual for developers

Download PDF

High-level Listener modules API

6.2. High-level Listener modules API#

Univention Directory Listener ships with a template in UCS source: management/univention-directory-listener/examples/listener_module_template.py. This should be used as a starting point for new modules. The more complex example in UCS source: management/univention-directory-listener/examples/complex_handler.py can also be used.

Alternatively the implementation can start from scratch:

  1. Create a subclass of univention.listener.ListenerModuleHandler.

  2. Add an inner class called Configuration which at least has the attributes name, description and ldap_filter.

The inner class Configuration is used to configure global module settings. For most properties a corresponding method exists, which just returns the value of the property by default. The methods can be overwritten if values should be computed once on module load.

high_level.get_name()#
Return type:

str

(optional)

The internal name of the handler, see name.

high_level.name: str#

The internal name of the handler, see name <your_module.name<.

high_level.get_description()#

A descriptive text, see description.

high_level.description: str#

A descriptive text, see description.

high_level.get_ldap_filter()#

The LDAP filter string, see filter.

high_level.ldap_filter: str#

The LDAP filter string, see filter.

high_level.get_attributes()#

The list of attributes, for when they are changed, the module is called; see attributes.

high_level.attributes: str#

The list of attributes, for when they are changed, the module is called; see attributes.

high_level.get_priority()#

The priority for ordering; see priority.

high_level.priority: float#

The priority for ordering; see priority.

high_level.get_listener_module_instance()#
Return type:

ListenerModuleHandler

This creates an instance of the handler module and returns it.

high_level.get_listener_module_class()#
Return type:

List[ListenerModuleHandler]

(optional)

Class that implements the module. Will be set automatically by the handlers meta-class.

high_level.listener_module_class: List[ListenerModuleHandler]#
high_level.get_active()#
Return type:

bool

This returns the value of the Univention Configuration Registry Variable listener/module/name/deactivate as a boolean. Setting the variable to False will prevent the module from being called for all changes.

Note

Re-enabling the module will not result in the module being called for all previously missed changes. For this the module must be fully resynchronized.

The handler itself should inherit from univention.listener.ListenerModuleHandler and then overwrite some methods to provide its own implementation:

high_level.create(dn: str, new: Dict[str, List[bytes]])#
Parameters:
Return type:

None

Called when a new object was created.

high_level.modify(dn: str, new: Dict[str, List[bytes]], old: Dict[str, List[bytes]], old_dn: Optional[str])#
Parameters:
Return type:

None

Called when a new object was modified or moved. In case of a move old_dn is set. During a move attributes may be modified, too.

high_level.remove(dn: str, old: Dict[str, List[bytes]])#
Parameters:
Return type:

None

Called when a new object was deleted.

high_level.initialize()#
Return type:

None

Called once when the module is not initialized yet.

high_level.clean()#
Return type:

None

Called once before a module is resynchronized.

high_level.pre_run()#
Return type:

None

Called once each time before a batch of transactions is processed.

high_level.post_run()#
Return type:

None

Called once each time after a batch of transactions is processed.

In addition to those handler functions the class also provides several convenience functions:

high_level.as_root()#
Return type:

None

A context manager to temporarily change the effective UID of the current to 0. Also see listener.SetUID() described in User-ID and Credentials.

high_level.diff(old: Dict[str, List[bytes]], new: Dict[str, List[bytes]], keys: Optional[Iterable[str]], ignore_metadata: bool)#
Parameters:
Return type:

Dict[str, Tuple[Optional[List[bytes]], Optional[List[bytes]]]]

Calculate difference between old and new LDAP attributes. By default all attributes are compared, but this can be limited by naming them via keys. By default operational attributes are excluded unless ignore_metadata is enabled.

high_level.error_handler(dn: str, old: Dict[str, List[bytes]], new: Dict[str, List[bytes]], command: str, exc_type: Optional[Type[BaseException]], exc_value: Optional[BaseException], exc_traceback: Optional[types.TracebackType])#
Parameters:
Return type:

None

This method will be called for unhandled exceptions in create/modify/remove. By default it logs the exception and re-raises it.

property high_level.lo: univention.uldap.access#

This property returns a LDAP connection object to access the local LDAP server.

property high_level.po: univention.uldap.position#

This property returns a LDAP position object for the LDAP base DN.

Any instance also has the following variables:

high_level.logger: logging.Logger#

An instance of logging.Logger.

high_level.ucr: univention.config_registry.ConfigRegistry#

A reference to the shared instance listener.configRegistry.

On this page