Skip to end of metadata
Go to start of metadata

TODO: figure

MidPoint has quite a rich user schema with many attributes that are common for most IDM deployments.  But if there are attributes that are not really common the best option is to extend user schema. It is quite easy. The User schema is extended by adding appropriate XSD file to the midPoint installation. The schema extension is not stored in the database because it may influence the database schema and therefore may create a chicken-egg problem.

The custom schema extension is specified in the XML Schema Description (XSD) format similarly to other schemas in midPoint. It is using XSD annotations to specify details that XSD cannot specify. E.g. it is using an a:extension annotation to bind the complex type definition to the midPoint object type.

Example

Following example provides a custom schema extension. It extends the schema of UserType as is defined by the a:extension XSD annotation. The example defines two properties: officeNumber and favoriteColor.

Custom schema extension

This file is all it takes to extend the schema. It extends user with two custom attributes:

Name

Display Name

Type

 

officeNumber

office number

string

Optional, single-value

favoriteColors

favorite color

string

Optional, multi-value

Attribute name is the name by which midPoint knows the attribute. It is used in mappings and configuration. Display name is what midPoint will display in forms and reports. Attribute type determines the type and range or attribute values. The schema may also define attribute multiplicity, whether it is mandatory or optional, define order in which it will be displayed in forms, define a help text, etc. Most of that is defined using XSD annotations and it is optional.

Defining the schema extension is all that midPoint needs to make full use of the attribute. Once it is defined in the schema midPoint will display the attribute in the GUI and it will be displayed using suitable user field, checked for mandatory value, the attribute may be used in mappings, etc. It will behave as if it always was a part of midPoint. The small additional configuration is required only when these attributes are used in mappings. Then you have to give configuration know in which namespace it should look for an attribute definition. This is namespace introduced in field targetNamespace from a header of the extension xsd file.

A more complex schema examples are provided in the subversion trunk/samples/schema directory.

Installing Custom Schema Extension

Currently the custom schema extension has to be available to midPoint at the startup time. Therefore it is not stored in the identity repository (database) and cannot be dynamically changed when the system is running.

The schema files has to be placed in the schema subdirectory of midpoint.home directory. The name of the file does not matter as long as it ends with .xsd extension. There also may be subdirectories. When MidPoint starts it scans the directory and all subdirectories and loads all the schemas that it finds there.

After any change in custom schema extension definition(s), you need to restart midPoint.

Data Types Supported

Extension items fall into two categories depending on how they are stored in midPoint repository: indexed and not indexed.

  1. Not indexed items are stored in object's XML representation only. So they are preserved by the repository, but it is not possible to select objects by their values. E.g. in the example above, it is possible to formulate a query "give me all users with extension/officeNumber = '111'" but not "give me all users with extension/favoriteColor = 'green'".
  2. Indexed items are stored in object's XML representation, as well as in extra columns that are used for querying objects based on their properties' values. So they can be used in object queries.

For non-indexed extension items, all data types are supported.

For indexed items, the following types might be used:

TypeIn which database table the values are stored
xsd:stringm_object_ext_string
xsd:intm_object_ext_long
xsd:short
xsd:long
xsd:integerm_object_ext_string - note that these types are really stored as strings, because they don't fit into "long" type range. (E.g. xsd:integer is java BigInteger, xsd:decimal is java BigDecimal). This means the support for these types is quite limited: inequality comparators "less than", "more than" don't work at all, and the equality test is to be used with a great care, as it can provide false negative results (e.g. 0.4999999999 vs. 0.5 vs 0.5000000001).
xsd:decimal
xsd:double
xsd:float
xsd:booleanm_object_ext_boolean
xsd:dateTimem_object_ext_date
c:PolyStringTypem_object_ext_poly
c:ObjectReferenceTypem_object_ext_reference
enumerationsm_object_ext_string

The default value for indexed flag (i.e. the XSD annotation) is true for the above supported types, and false otherwise.

In midPoint versions before 3.6, the indexed=false setting was ignored for all non-string types, i.e. they were always stored in the repository. For midPoint 3.6, all types except for references obey the indexed setting. References are still always stored as indexed.

Until midPoint 3.6, querying references in schema extension was in fact not implemented. Starting from 3.6, references in extensions can be queried just any other statically-defined references.

 

 Using midPoint types

It is possible to define custom attributes using midPoint types. For example, if there is a need to specify various activation status types for users in your environment, it is possible to define custom attribute for activation using ActivationStatusType type. If there is another requirement e.g. for supporting more than one password for the user, ProtectedStringType can be use in such a case. To allow using of midPoint types, proper schemas have to be added to the extension schema definition using import element as the example bellow shows:

 

 

 

  • No labels