Manage schema extensions in midPoint GUI
|
Since 4.9
This functionality is available since version 4.9.
|
You can configure custom schemas in the midPoint graphical user interface (GUI). After each change, the schema is reloaded and you can immediately see the new attributes in the GUI panels of the extended object type.
For an introduction to and technical information about schema extensions, see Schema Extension.
Introduction and terminology
-
Custom schema extensions serve to extend the native set of focal object type attributes.
-
One schema can contain multiple focal object type extension definitions—you can extend, e.g., the user and organization types in one schema.
-
In an extension definition, you define items, i.e., attributes, to be added to the extended focal object type. For instance, favorite color attribute extending the user object type.
-
Each schema extension item is of a certain data type which signifies what type of data it holds; e.g., String for texts or Int for integers.
-
Once you save a schema, your options to modify it in the GUI are limited. See modification limitations for details.
Create new schema extension
The new schema extension wizard consists of several screens that correspond to the structure of schema extensions:
-
Basic information about the schema.
-
Information about the extension the schema defines; i.e., which focal object type you are extending (e.g., User) or name of the extension.
-
Definition of items in the extension, i.e, the attributes and their properties by which you extend the focal object type.
Figure 1. New schema extension entry point
To create a new schema extension:
-
In Schemas > All schemas, click New schema.
-
In the New schema screen that appears, select the From Scratch tile.
-
If you select Use Existing Schema, you will be prompted to select an existing schema to which you will add a new extension of an object type. The wizard then starts with the Basic information about structural definition screen.
-
-
Fill in basic schema details:
-
Name: A unique descriptive identifier of the schema, e.g., UserExtension.
-
Namespace: A namespace for the schema, e.g., http://example.com/xml/ns/mySchema.
-
Default prefix: An optional constant prefix which should be used for the namespace.
-
-
In the next Basic information about structural definition screen, name the extension and define what focal object type you are extending.
-
In the next Items screen, add items to the schema extension.
-
You do not have to add items now. You can click Save settings to save the new schema extension and add items later. This is useful if you need to define an enumeration for a schema item, for instance.
-
-
Click Save settings to save the new schema extension when you are done.
Adjust existing schema
In existing schema extensions, you can:
-
Add new items to existing focal object type extensions.
-
Change item and schema display names.
-
Adjust some properties of the existing items with regards to the existing schema update limitations.
-
Define new enumeration types.
To edit an existing schema extension:
-
Go to Schemas > All schemas.
-
Click a schema name to open it for editing.
Figure 2. Schema extension definitions view
Add new focal object type extension
One schema can extend multiple focal object types. To add a new extension:
-
Open a schema for editing.
-
In Definitions, click New definition
-
Select Structure.
-
In the form that appears, fill in the structural definition details:
-
Name: Name the new extension, e.g., UserExtensionType.
-
Extension: Select the focal object type to extend, e.g., User.
-
Optionally, define a human-friendly Display name, Help, and Documentation for the extension.
-
-
In the next Items screen, click New item to add schema extension items.
Figure 3. Basic structural information about the new schema extension
Add schema extension items
To add items (i.e., focal object type attributes) to a schema extension:
-
Open a schema for editing.
-
In Definitions, select a complex type to which you want to add new items, e.g., UserExtensionType.
-
Click New item.
-
In the Create new item modal dialog that appears, select the data Type of the new item.
For example:-
Textual attributes: String
-
Whole numbers: Int (not to be confused with Integer type; see supported data types)
-
An enumeration you have defined previously.
-
-
Click Create
-
Fill in the item properties:
-
Basic properties:
-
Name: A descriptive identifier by which midPoint knows the item. Ideally unique within the object type (otherwise, you need to specify the schema namespace when using it). Must be unique within the schema. May contain national characters but not special characters and white spaces.
-
Display name: A human-friendly name of the item.
-
Order: Determines the item placement within GUI forms.
-
Required: Defines optionality of the item. You can later change it only from required to optional, not vice versa.
-
Multivalue: Defines whether the item can hold a single value (False) or more of them (True). You can later change it only from single- to multivalue, not vice versa.
-
Indexed: Set to True if you want to search by the item.
-
-
Click Edit at the far right of the row to define additional details:
-
For instance, you can write a Help text which is displayed when user hovers over the icon.
-
You can use Display hint: Hidden to hide an item from GUI forms.
-
-
Click Done to return to the basic form.
-
-
You can add as many items as you need before saving the schema.
-
Save the schema changes when you are done adding items:
-
If you are adjusting an existing schema, click Save schema at the top right.
-
If you went through the new schema wizard, click Save settings beneath the items form. You can return and add more items later.
Saving the schema will redirect you to the schema list. See existing schema management for further steps you can take. To see your schema extension from the end user’s perspective, open what you have extended (e.g., a user) and check the edit form for the new attributes.
-
|
Think before you save
Until you save the changes, you can edit everything you have added. After you save, some aspects of the new schema lock according to the schema editing limitations. Be sure to check your work before you save. |
Figure 4. The last screen of the new schema wizard: items (attributes) in the custom schema extension
Create value enumeration
An enumeration type in a schema extension is the appropriate choice when an object property value must be constrained to a known list of options—for example, a department code, job category, or shirt size. In the GUI, midPoint displays enumeration items in a dropdown list containing the pre-defined values.
Before you can create a schema item that uses a value enumeration, you need to define the enumeration. When creating a new schema extension, this means:
-
Save the schema before adding the enumeration item, even if the schema contains no items at all.
-
Define the enumeration (see below).
-
Add the item that uses the enumeration—select the enumeration as its data type in the first step as you would select Int for numbers or String for texts.
Figure 5. Schema extension definitions view with a new preferredShirtColor attribute using Colors enumeration as its type
|
The enumeration must be defined in the schema where you use it. |
Define list of values
-
With a schema opened for editing, select Definition.
-
Click New definition.
-
Select Enumeration.
-
Name the enumeration definition; e.g., Colors. You cannot change the name later.
-
Click Next: Values.
-
Click New value to add a value to the enumeration.
-
Specify the value in the Value column and, optionally, document the value in the Documentation column. You cannot change the value later.
-
Click Save settings to save the enumeration.
Figure 6. Enumeration values definition
This is how enumeration attributes display in GUI forms:
Figure 7. Enumeration in user edit form
Limitations
When you define a new schema, you can change anything within the schema until you save the schema. After you save the schema, your options to modify it in the GUI are limited as per the schema lifecycle.
Deleting schemas is forbidden because some objects may contain values in the items the schema defines. Another reason is that you need the schemas items for correct representation of deltas in audit records.
Unneeded schemas and items may be labeled as removed, items can be hidden from the GUI forms, but they must remain in the midPoint repository.
In the GUI, once you save your schema:
-
Your cannot change the namespace of the schema.
-
Your cannot change the name and extension of a complex type.
-
Your cannot change the name and data type of an item.
-
The value of the Required attribute of an item cannot change from false to true or undefined.
-
The value of the Multivalue attribute of an item cannot change from true to false or undefined.
-
You cannot mark a container item as indexed.
-
You cannot change Object reference target type of a reference item.
-
You cannot change the name of an enumeration.
-
You cannot change the value of an enumeration item.
These limitations apply only to the GUI. If you know what you are doing, you can make any changes directly in the XML definition of the schema.
Was this page helpful?
YES
NO
Thanks for your feedback