UCS 3.0 UMC API for Modules

From Univention Wiki

Jump to: navigation, search
Note: Univention Corporate Server (UCS) 3.0 has been released.
Produktlogo UCS kurz.png Version 3.0

This document describes (currently as draft and work in progress) technical details of the API for Univention Management Console Modules in UCS 3.0.

Contents

Introduction

The UMC server provides management services that are provided by so called UMC modules. These modules are implemented in Python (backend) and in Javascript (web frontend). The following page provides information about developing and packaging of UMC modules. It is important to know the details of UMC Architecture and Protocol.

Python API

The Python API for the UMCP is defined in the python module univention.management.console.protocol.

TBD

UMC module API (Python and Javascript)

A UMC module consists of three components

  • A XML document containing the definition
  • The python module defining the command functions
  • The javascript frontend providing the web frontend

XML Definition

The UMC server knows three types of resources that define the functionality it can provide:

  • UMC modules provide commands that can be executed if the required permission is given.
  • Syntax types can be used to verify the correctness of command attributes defined by the UMCP client in the request message or return values provided by the UMC modules
  • Categories help to define a structure and to sort the UMC modules by its type of functionality

All these resources are defined in XML files. The details are described in the following sections

Module definition

The UMC server does not load the python modules to get the details about the modules name, description and functionality. Therefor each UMC module must provide an XML file containing this kind of information. The following example defines a module with the id udm:

<?xml version="1.0" encoding="UTF-8"?>
<umc version="2.0">
  <module id="udm" icon="udm/module" version="1.0">
    <name>Univention Directory Manager</name>
    <description>Manages all UDM modules</description>
    <flavor icon="udm-users" id="users/user">
      <name>Users</name>
      <description>Managing users</description>
    </flavor>
    <categories>
      <category name="domain"/>
    </categories>
    <command name="udm/query" function="query"/>
    <command name="udm/containers" function="containers">
      <attribute name="superordinate" syntax="String" required="False"/>
    </command>
  </module>
</umc>

The module tag defines the basic details of a UMC module

  • id This identifier must be unique among the modules of an UMC server. Other files may extend the definition of a module by adding more flavors or categories.
  • icon The value of this attribute defines an identifier for the icon that should be used for the module. Details for installing icons can be found in the section #Packaging

The child elements name and description define the english human readable name and description of the module. For other translations the build tools will create translation files. Details can be found in the section #Packaging.

This example defines a so called flavor. A flavor defines a new name, description and icon for the same UMC module. This can be used to show several "virtual" modules in the overview of the web frontend. Additionally the flavor is passed to the UMC server with each request i.e. the UMC module has the possibility to act differently for a specific flavor.

As the next element categories is defined in the example. The child elements category set the categories wthin the overview where the module should be shown. Each module can be more than one category. The attribute name is the internal identify of category. The UMC server brings a set of pre-defined categories:

  • favorites: This category is intended to be filled by the user herself.
  • system: Tools manipulating the system itself (e.g. software installation) should go in here.
  • wizards: UMC modules providing a step-by-step assistent to create some kind of configuration should be added to this category
  • monitor: Everything that provides monitor functionality (e.g. simple system statistics) should be placed in this category

At the end of the definition file a list of commands is specified. The UMC server only passes commands to a UMC module that are defined. A command definition has two attributes:

  • name is the name of the command that is passed to the UMC module. Within the UMCP message it is the first argument after the UMCP COMMAND.
  • function defines the method to be invoked within the python module when the command is called.

Each command can have arguments and a return value, which can be specified as child elements of the command. For example

<attribute name="superordinate" syntax="String" required="False"/>

defines an attribute superordinate of type String that is optional. What syntax types are support is defined in the next section.

Syntax definitions

Deprecation warning
Defining extra syntaxes using this method is no longer used with UCS-3.1!

Syntax definitions can help to ensure the correctness of commands passed to the UMC server. Therefor it helps to keeps the server save by dismissing incorrect commands that may crash the UMC module.

Be default the UMC server brings a set of basic and most common syntax definitions:

  • String
  • Boolean
  • Integer
  • Float
  • Selection (only predefined strings are allowed)

Additionally it provides some data structure types:

  • Dictionary
  • List

These syntax types can be used to create own syntax definitions based on these types. There the UMC module must provide an XML file with the definition. Example:

<?xml version="1.0" encoding="UTF-8"?>
<umc version="2.0">
  <definitions>
    <syntax base="String" name="UCR-Variable">
      <regex-invalid>.*[\r\n!"ยง$%&amp;()\[\]{}=?`+#',;&lt;&gt;].*</regex-invalid>
    </syntax>
    <syntax base="String" name="UCR-Value">
      <regex-invalid>.*[\r\n].*</regex-invalid>
    </syntax>
    <syntax base="Dictionary" name="UCR-Variables">
      <item key="UCR-Variable" value="UCR-Value"/>
    </syntax>
    <syntax base="Selection" name="UCR-SearchOption">
      <choice name="all"/>
      <choice name="key"/>
      <choice name="value"/>
      <choice name="description"/>
    </syntax>
  </definitions>
</umc>

A syntax definition must provide the base type and a new name'. Depending on the base type the available child elements differ:

  • String
    • regex-invalid defines a regular expression. If it matches, the value is invalid
    • regex defines a regular expression. Only if it matches the value is valid
  • Dictionary
    • item defines the syntax types of the list elements. The attribute key defines the syntax type of the key and the attribute value for its value.
  • Selection
    • choice defines a valid string for the selection. The value must be set in the attribute name

Category definitions

The pre-defined set of categories can be extended by each module. Example:

<?xml version="1.0" encoding="UTF-8"?>
<umc version="2.0">
  <categories>
    <category id="favorites">
      <name>Favorites</name>
    </category>
    <category id="system">
      <name>System</name>
    </category>
    <category id="wizards">
      <name>Wizards</name>
    </category>
    <category id="monitor">
      <name>Surveillance</name>
    </category>
  </categories>
</umc>

Python module

The python API for UMC modules primary consists of one base class that must be implemented. As an addition to python API provides some helper:

  • exception classes
  • translation support
  • logging functions
  • UCR access

In the definition file for the UMC module specifies functions for the commands provided by the module. These functions must be implemented as methods of the class Instance that inherits from univention.management.console.modules.Base.

The following python code example matches the definition in the previous section:

from univention.management.console import Translation
from univention.management.console.config import ucr
from univention.management.console.modules import Base, UMC_OptionTypeError, UMC_OptionMissing, UMC_CommandError
from univention.management.console.log import MODULE
 
from .ldap import UDM_Module, UDM_Settings, ldap_dn2path, get_module
 
_ = Translation( 'univention-management-console-modules-udm' ).translate
 
class Instance( Base ):
  def query( self, request ):
    ...
  def containers( self, request ):
    module_name = request.options.get( 'objectType' )
    if not module_name or 'all' == module_name:
      module_name = request.flavor
    if not module_name:
     raise UMC_OptionMissing( 'No valid module name found' )
 
    module = UDM_Module( module_name )
    self.finished( request.id, module.containers + self.settings.containers( request.flavor ) )

Each command methods has one parameter that contains the UMCP request. Such an object has the following properties:

  • id is the unique identifier of the request
  • options contains the arguments for the command. For most commands it is a dictionary.
  • flavor is the name of the flavor that was used to invoke the command. This might be None

The containers method in the example above shows how to retrieve the command parameters and what to do to send the result back to the client. Important is that returning a value in a command function does not send anything back to the client. Therefor the function finished must be invoked. The first parameter is the identifier of the request that will be answered and the second parameter the data structure containing the result. As the result is converted to JSON it must just contain data types that can be converted. The finished function has two further optional parameters. message may contain a human readable text explaining the result and success is a boolean parameter defining the success of the operation. By default success is true. By setting success' to False the UCM module sends an error status back to the client. Another way to send an error message back to the client is by raisig one of the following exceptions:

  • UMC_OptionTypeError: The type of a given option does not match
  • UMC_OptionMissing: One required option is missing
  • UMC_CommandError: A general error occurred

The base class for modules provides some properties and methods that could be useful when writing UMC modules:

  • Properties
    • username: The username of the owner of this session
    • password: The password of the user
  • Methods
    • init: Is invoked after the module process has been initialised. At that moment, the settings, like locale and username and password are available.
    • permitted: Can be used to determine if a specific UMCP command can be invoked by the current user. This method has two parameters: The command name and the options.

UMC Store API

In order to encapsulate and ease the access to module data from the JavaScript side, a store object offers a unified way to query and modify module data. The UMC JavaScript API comes with an object store implementation of the Dojo store API. This allows the JavaScript code to easily access/modify module data and to observe changes on the data in order to react immediately. The following methods are supported:

  • get(id): Returns a dictionary of all properties for the object with the specified identifier.
  • put(dictionary, options): modifies an object with the corresponding properties and an optional dict of options.
  • add(dictionary, options): Adds a new object with the corresponding properties and an optional dict of options.
  • remove(id): Removes the object with the specified identifier.
  • query(dictionary): Queries a list of objects (returned as list of dictionaries) corresponding to the given query which is represented as dictionary. Note that not all object properties need to be returned in order to save bandwidth.

The UMC object store class in JavaScript will be able to communicate directly with the Python module if the following methods are implemented:

  • <module>/get: Expects as input a list if unique IDs (as strings) and returns a list of dicts as result. Each dict entry holds all object properties.
  • <module>/put: Expects as input a list of dicts where each entry has the properties object and options. The property object holds all object properties to be set (i.e., this may also be a subset of all possible properties) as a dict. The second property options is an optional dict that holds additional options as a dict.
  • <module>/add: Expects similar input values as <module>/put.
  • <module>/remove: Expects as input a list of dicts where each entry has the properties object (containing the object's unique ID (as string)) and options. The options property can be necessary as a removal might be executed in different ways (recursively, shallow removal etc.).
  • <module>/query: Expects as input a dict with entries that specify the query parameters and returns a list of dicts. Each entry may hold only a subset of all possible object properties.

Further references:

Packaging

A UMC module consists of serveral files that must be installed at a specific location. As this mechanism is always the same there are debhelper tools making package creation for UMC modules very easy.

The following example is based on the package for the UMC module UCR.

A UMC module may be part of a source package with multiple binary packages. The examples uses a own source package for the module.

As a first step create a source package with the following files:

univention-management-console-module-ucr
univention-management-console-module-ucr/debian
univention-management-console-module-ucr/debian/univention-management-console-module-ucr.umc-modules
univention-management-console-module-ucr/debian/rules
univention-management-console-module-ucr/debian/changelog
univention-management-console-module-ucr/debian/control
univention-management-console-module-ucr/debian/copyright
univention-management-console-module-ucr/debian/compat

All these files are standard debian packaging files except univention-management-console-module-ucr.umc-modules. This file contains information about the locations of the UMC module source files:

Module: ucr
Python: umc/python
Definition: umc/ucr.xml
Syntax: umc/syntax/ucr.xml
Javascript: umc/js
Icons: umc/icons

The keys in this file of the following meaning:

  • Module: The internal name of the module
  • Python: A directory that contains the python package for the UMC module
  • Definition: The filename of the XML file with the module definition
  • Javascript: A directory containing the javascript source code
  • Icons: A directory containing the icons required by the modules web frontend
  • Syntax (optional): The filename of the XML file with the syntax definitions
  • Category (optional): The filename of the XML file with the category definitions

The directory structure for such a UMC module file would look like this:

univention-management-console-module-ucr/umc
univention-management-console-module-ucr/umc/syntax
univention-management-console-module-ucr/umc/syntax/ucr.xml
univention-management-console-module-ucr/umc/js
univention-management-console-module-ucr/umc/js/ucr.js
univention-management-console-module-ucr/umc/js/de.po
univention-management-console-module-ucr/umc/de.po
univention-management-console-module-ucr/umc/icons
univention-management-console-module-ucr/umc/icons/16x16
univention-management-console-module-ucr/umc/icons/16x16/ucr.png
univention-management-console-module-ucr/umc/icons/24x24
univention-management-console-module-ucr/umc/icons/24x24/ucr.png
univention-management-console-module-ucr/umc/icons/64x64
univention-management-console-module-ucr/umc/icons/64x64/ucr.png
univention-management-console-module-ucr/umc/icons/32x32
univention-management-console-module-ucr/umc/icons/32x32/ucr.png
univention-management-console-module-ucr/umc/ucr.xml
univention-management-console-module-ucr/umc/python
univention-management-console-module-ucr/umc/python/ucr
univention-management-console-module-ucr/umc/python/ucr/de.po
univention-management-console-module-ucr/umc/python/ucr/__init__.py

If such a package has been created a few things need to be adjusted

  • debian/compat
7
  • debian/rules
%:
	dh $@
 
override_dh_auto_build:
	dh-umc-module-build
	dh_auto_build
 
override_dh_auto_install:
	dh-umc-module-install
	dh_auto_install
  • debian/control
Source: univention-management-console-module-ucr
Section: univention
Priority: optional
Maintainer: Univention GmbH <packages@univention.de>
Build-Depends: debhelper (>= 7.0.50~),
 python-support,
 univention-management-console-dev,
 python-all
Standards-Version: 3.5.2
XS-Python-Version: all

Package: univention-management-console-module-ucr
Architecture: all
Depends: univention-management-console-server
Description: UMC module for UCR
 This package contains the UMC module for Univention Configuration Registry
Personal tools