Archetypes Design Notes

ArchetypeType is a special type (subclass) of AbstractRole type. In that aspect it is very similar to Role, Org or Service - and it behaves in that way. But in addition to normal role-like behavior archetype is giving the objects some character. Or identity. Archetype determines how the objects should be displayed (icon, color). Archetypes may later determine schema extension of the object. Archetypes may dictate object templates and lifecycle model. Therefore lifecycles are quite special, because they defined fundamental character of an object.

In essence, archetypes work as other role-like objects. Object is associated with an archetypes by using ordinary assignment:

Archetypes are defined almost like ordinary role:

However, there are few differences. Fist of all, archetypes needs to be processed by user interface in a very efficient way. Archetypes define object icons, colors and other presentation aspects. If the user interface is supposed to have any reasonable performance this needs to be determined very efficiently. But archetypes are role-like objects, they can be assigned directly, indirectly, conditionally, they can even change (although this may be limited). User interface cannot afford to evaluate all of that for every row of in a search results table. Therefore there is short-cut: archetypeRef. This is a reference that is automatically computed by midPoint (similar to roleMembershipRef). The archetypeRef reference points to all applicable archetypes for that specific object:

Based on the information in archetypeRef reference the user interface can easily determine all applicable archetypes. And therefore user interface can quickly display appropriate icon, color and label.

Archetypes define how objects looks like and how they behave. More specifically:

There is a special archetypePolicy item to specify archetype-related configuration:

Content of archetypePolicy container is very similar to defaultObjectPolicyConfiguration container in system configuration. It essentially defines the same thing. The defaultObjectPolicyConfiguration in system configuration is based on subtypes and it will probably get deprecated in some point in 4.x lifetime. Archetypes should be a replacement for subtypes.

Archetypes are really neat mechanism. However, there is problem related to the way how midPoint Clockwork and Projector works. Projector needs to evaluate object template first. Because object template may influence assignments (e.g. automatic assignment mappings). Assignments are evaluated after object template. But archetype is specified in an assignment. And we need to evaluate archetype to determine object template. But we need object template to evaluate assignments.

This is not archetype-specific problem. Similar problem exists in case if we would want object template to be specified in organizational structure (e.g. per-tenant object template).

This can be obviously solved (or at least mitigated) with re-structuring projector and evaluating the assignments in two passes. But that is likely to complicate projector code. Significant refactoring may be needed to achieve full functionality. And it might not be solved completely, as we may need some kind of priority evaluation of some assignments. We can hardcode priority evaluation of archetypes in 4.0 - especially given the limitations described below. However, this problem will need a complete solution sooner or later.

Archetypes are concepts of midPoint object structure and typing. Although it contains some parts related to presentation, archetypes in themselves are core midPoint concept. There will be quite a lot user interface code related to artifacts. But there is almost no default user interface behavior when archetypes is added to the system. In fact, such archetype will be almost invisible for the user interface. User interface needs to be configured to take full advantage of archetypes.

By default, archetypes should be properly displayed when listing objects. E.g. there should proper icons and colors for users. But that is pretty much all about the default behavior. There will be no extra links in the menu, no buttons and so on. All of that depends on the configuration of views. And there are several good reasons for that behavior:

However, it is actually easy to properly display an archetype in the user menu using a view:

This can be defined in global system configuration or in a role. Such view should create "Employees" link in the menu in the "Users" section.

Collection reference may get quite complex (see below). But in this case a simple collectionRef pointing to an archetype should be enough.

The view specifies a way how a collection of objects is displayed. Creating appropriate menu item is just one of the aspects. The view may also define how the actual list of objects looks like. The view specifies the columns, defaults search settings and so on. However, when the view is bound to an archetype, it can do even a bit more. Such view can automatically render buttons to create new objects. It is quite simple for views that use just one archetype. It may be more complex for mixed views, such as organizational structure views (see below).

TODO: archetypes as top-level menu items

We already have mechanism for explicit filter-based explicit filter-based object collections. However, it would not be convenient if we had to define explicit collection for each archetype. And listing objects based on archetypes is going to be a very common operations. Therefore archetypes will work as implicit collections. Configuration of a view can point directly to archetype definition and it will work as a collection of an objects of that type (see above).

Archetypes cat act as collection in two slightly distinct ways:

TODO: explicit collection that use archetypes as base, e.g. "active employees"

Definition of archetype display properties:

The definition above specifies that this archetype should be referred to as "Employee". When displaying the name in plural, then it should be "Employees". The plural form is used for example in views. There is also icon, specified as an cssClass. And when the icon is displayed is should be displayed in blue.

It is important to remember that those display properties specify properties of the type. Those are not properties of the archetypes object itself and those are not properties of each individual object either. The display properties are interpreted in different ways depending on when they are defined:

Archetypes display the shape and color of a base icon for that particular archetype. However, user interface can decorate the base icon with a couple of overlays. The overlays specify object lifecycle state, activation status or operation (if used in buttons and links).

Archetypes are supposed to also define relations, e.g.:

In fact, this is not really specific to archetypes. Any object which could be a target of an assignment should be able to specify constraints about the type (and archetype) of assignment holder. And types of allowed relations. This just gets much more interesting when archetypes are used.

Assignment and relation constraints can be specified using assignmentRelation container:

The assignmentRelation mechanism can be used to limit assignment of the archetype itself. E.g. we may want to limit employee archetype in such a way that it can only apply to UserType:

Initial implementation of assignmentRelation in midPoint 4.0 can be very simple, e.g. it can be limited:

Post-4.0: Later midPoint versions will probably relax those limitations. Therefore we will need a mechanism to compute effective assignment constraints as operational property - in a similar way as we compute roleMembershipRef. We can use effectiveAssignmentRelation element for this purpose. However, what needs to be figured out is how GUI could discover assignable objects for a particular holder type. Therefore it can be expected that at least effectiveAssignmentRelation/holderType will need to be indexed.

Another concern is compatibility. Before 4.0, when no assignmentRelation existed, all objects could be assigned freely with any relation. However, after 4.0 we want to be able to specify that a particular object type (archetype) is not assignable at all. Therefore it would be better to assume that the object cannot be assigned unless there is an explicit assignmentRelation specification. Yet, that would conflict with default behavior of midPoint 3.x. And in fact this default behavior may be too strict. Default midPoint configuration would be almost useless. Therefore we need some kind of setting to control the default behavior: allow any assignment (compatibility), allow no assignment (strict).

TODO Q: can "default archetype" (see below) be used for this purpose?

Archetypes can be used together with organizational structure in two related, but somehow different ways:

Heterogeneous mode: organizational unit may contain objects of many archetypes. E.g. employees, external workers, business roles, resources, applications. In this case each object must have explicitly assigned archetype. Therefore each object will have at least two assignments: archetype assignment and organizational unit assignment. This cannot be really simplified, as there may be too many combinations of archetypes and organizational structure placement. This approach is ideal for functional organizational trees, multi-tenant organizations and so on.

In hetero-mode will user interface render a selection of various "create" buttons in organizational tree: create employee, create external user, create business role and so on. User interface will need to analyze assignmentRelation of the parent organizational unit to find out which specific buttons to render. If such a button is used, then user interface will prepare new object with two assignments: assignment to organizational unit and assignment to archetype.

Homogeneous mode: organizational unit may contain objects of a single archetype (or a handful of well-defined archetypes). E.g. all organizational units in project-based organizational structure are projects. In this case the project will only have one assignment - assignment to "project root" organizational unit. The "project root" org will have inducement that sets project archetype for every sub-org.

In homo-mode the user interface does not really know what are the archetypes induced by the "project root". Therefore it can only render a generic "create suborg" button. If that button is pressed the GUI will pre-populate new object with a single assignment to the "project root" org. There will be no archetype information. Which may be a problem, because GUI may take advantage of archetype information, e.g. to render a proper icon for a new object. But this mode can still be useful. And this can be improved later by introducing "inducedArchetype" informational property in assignmentRelation structure.

Hetero-mode is usually preferred. It is almost certain, that homo-mode will not even work properly in 4.0.

Post-4.0

TODO: structural, auxiliary, abstract

Post-4.x: Later (5.0) it may be possible for an archetype to define its own schema extension.

Similar functionality should be possible even in 4.x. But the deployer need to define all possible extension items in the schema extension in midPoint home. Then per-archetype object templates can be used to limit the number of extension items applicable for each archetype. But this "add all, remove excess" approach is quite troublesome to maintain - especially for large schema extensions.

In midPoint 5.0 this should be reversed: midPoint should start with empty schema extension, then archetypes will add only those extension elements that are needed. Archetype definition will contain schema definition snippet. This means that all archetype definitions will need to be pre-processed and the schema definition snippets injected into Prism schema registry. But this should work well. We are doing similar thing for relation definitions already.

However, even in 5.0 we may still need to define all those "flexible" extension elements on schema top-level (global) - similarly to LDAP schema. This may be needed to properly process search queries. Or alternatively we may need to extend search queries to be archetype-aware. This needs to be further analyzed.

TODO: "Default archetype" in system config? E.g. to specify default assignmentRelation for all non-archetyped objects.

We needed to know all applicable archetypes for each object. And we need to have that stored. RoleMembershipRef would work quite well for that with simple archetypes. But once we have type hierarchy, then roleMembershipRef won’t work. There (most likely) won’t be assignment/inducement relation between archetypes in type hierarchy. Therefore the supertypes won’t make it into roleMembershipRef. Therefore we need archetypeRef. We need all supertypes there. We need that for searching. E.g. searching for "person" archetype should also return objects that have "employee" archetype. That information may not be in roleMembershipRef.

Subtypes will work in midPoint 4.x in the same way as they worked in 3.x. But they are no longer recommended and their use will be deprecated sometime during the 4.x midPoint development. Subtype functionality will no longer be exteded. Archetypes are supposed to completely replace subtypes.

Clever reader will surely notice similarity to LDAP object classes. Indeed, LDAP was quite a big inspiration. Why reinvent the wheel? LDAP principles work quite well. Therefore it is better to reuse them than to reinvent the ideas. Of course, we have made full validation of the approach that it actually matches the purposes of midPoint design. And it does.

Collections do not explicitly define type (e.g. UserType). Types are specified when a collection is used. This makes sense, as there may be collections that work with many types, e.g. organizational structure collections.

Therefore also archetype do not explicitly define type to which they can apply. The type can be specified indirectly with assignmentRelation. Theoretically, archetype may be applied to several types. But that is not supported yet. And not sure whether this is a good idea at all.