Page tree
Skip to end of metadata
Go to start of metadata

MidPoint 4.0 and later

Introduction

Simply speaking archetype is a well-defined object subtype. Employee, Contractor, Project, Workgroup, Application, ... each of them is an archetype.

Please see Archetypes page for a more in-depth introduction to archetype concepts.

Archetype Definition

Archetype definition is a special midPoint object (ArchetypeType):

<archetype oid="7135e68c-ee53-11e8-8025-170b77da3fd6">
   <name>employee</name>
   ...
   <archetypePolicy>
       <!-- definition of archetype icon, color and labels will be here -->
   </archetypePolicy>
   ...
</archetype>

Archetypes define character and behavior of "archetyped" objects in archetypePolicy section. This part of archetype definition specifies what icons, color and labels to use, which templates to apply and so on.

Archetypes work like abstract roles, therefore all objects that need to be "archetyped" can be simply assigned to an archetype. Being a midPoint object, archetype has an natural persistent identifier: OID. OID of the archetype definition is also identifier of archetype itself. Each object of that archetype will contain archetype definition OID in archetypeRef reference:

<user>
   <name>foo</name>
   <archetypeRef oid="7135e68c-ee53-11e8-8025-170b77da3fd6" /> <!-- "employee" archetype -->
   ...
   <assignment>
       <targetRef oid="83614aaa-ee57-11e8-b770-7f3cb1d00719" type="RoleType"/> <!-- some role, that includes another role, that includes "employee" archetype -->
   </assignment>
</user>

In the above example, user was created with the archetype assignment, but without the archetypeRef reference. The archetypeRef reference is computed by midPoint and stored into the object. This reference is needed for easy and efficient resolution of an archetype, because archetype may be assigned indirectly. The archetypeRef reference can also be used to search for all objects of a given archetype.

Archetypes as Abstract Roles

Archetype definitions are abstract roles, which means they essentially work as a role. To apply an archetype to an object simply assign archetype to that object as you would normally assign a role. From that point on archetype applies to that object. Archetypes being abstract roles makes them really powerful. That means archetypes may work as ordinary roles or metaroles:

<archetype oid="7135e68c-ee53-11e8-8025-170b77da3fd6">
   <name>employee</name>
   ...
   <inducement>
       <!-- whatever roles, rules and privileges that an employee needs to have -->
   </inducement>
</archetype>

Being an abstract role, archetype may also be assigned indirectly. E.g. basic employee role may contain inducement for employee archetype, making sure that all holders of basic employee role will have appropriate archetype.

Icons, Colors, Labels

Archetype policy can be used to set custom icon, color and label for "archetyped" objects:

<archetype oid="7135e68c-ee53-11e8-8025-170b77da3fd6">
   <name>employee</name>
   ...
   <archetypePolicy>
        <display>
            <label>Employee</label>
            <pluralLabel>Employees</pluralLabel>
            <icon>
                <cssClass>fa fa-user</cssClass>
                <color>blue</color>
            </icon>
        </display>
    </archetypePolicy>
    ...
</archetype>

The example above is setting custom icon for employee archetype. It also specifies that whenever an employee icon can be used in color then blue color should be used. There is also a label that should be used to display objects of that particular archetype. And also a plural form of the label used when objects of that archetype are listed.

Archetypes And Views

If an archetype is assigned to an object, midPoint honor that archetype definition. E.g. it will display those objects with appropriate icon and color. But otherwise archetype definitions and object lists are not displayed in the user interface by default - except for places such as Repository Objects. This behavior has several reasons: there may be archetype definitions that are just being prepared, definitions that should not be publicly visible, or there may be just too many definitions to be displayed in the menu. Therefore, by default, there will be no additional menu items or "shortcut" buttons for archetypes.

Archetypes can be added to menus and other places of midPoint interface by using object views. All that is needed is simple definition of a view in admin GUI configuration structure:

...
<adminGuiConfiguration>
    <objectCollectionViews>
        <objectCollectionView>
            <identifier>empls-view</identifier>
            <type>UserType</type>
            <collection>
                <collectionRef oid="7135e68c-ee53-11e8-8025-170b77da3fd6" type="ArchetypeType"/> <!-- "employee" archetype -->
            </collection>
        </objectCollectionView>
    </objectCollectionViews>
</adminGuiConfiguration>
...

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.

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.

Assignment Relation

Archetypes can define possible object types and relations that can be used in assignments to "archetyped" objects, e.g.:

  • Projects are organizational units that can have members, managers and owners.
  • Business roles have members, owners and approvers. Owners and approvers must be employees.
  • Departments are organizational units that may contain other organizational units (but only if they are of Section archetype), users and business roles.

There is an assignment relation mechanism that can be used for that purpose. The assignment relation specification can be used to limit possible assignment holder object types and assignment relations. This is perhaps best illustrated using an example of a business role:

 <archetype oid="018e7340-199a-11e9-ad93-2b136d1c7ecf">
    <name>Business Role</name>
    ...
    <inducement>
        <assignmentRelation>
            <description>Any user can have business role (can be a member).</description>
            <holderType>UserType</holderType>
            <relation>org:default</relation>
        </assignmentRelation>
        <assignmentRelation>
            <description>Only employees may be owners/approvers for business role.</description>
            <holderType>UserType</holderType>
            <holderArchetypeRef oid="7135e68c-ee53-11e8-8025-170b77da3fd6"/> <!-- Employee archetype -->
            <relation>org:approver</relation>
            <relation>org:owner</relation>
        </assignmentRelation>
    </inducement>
    ...
</archetype>

First assignmentRelation in the above example specifies that any user can be assigned to the business role with default relation. Second assignmentRelation specifies rules for approver and owner relations. Only an employee can be owner or approver of the business role.

Please note that in this case assignmentRelation specifications are placed in the inducement of the archetype, not assignment. We want to apply assignmentRelation to "archetyped" objects. And that is exactly what inducements do. But archetype definition are itself first-class midPoint objects - and they are also abstract roles. Therefore archetype definition can have assignments pointing to it, such as owner of an archetype definition. Therefore the assignmentRelation statements in the assignment also make sense if we want to control what objects can be assigned to the archetype definition. But placing assignmentRelation in inducement is the usual case.

Open and Closed Assignment Relations

Assignment relation specifies which objects can be assignment to other objects. But how to interpret the situation when there is no assignment relation specified? This may mean two different things:

  • Open world: Assignment relation is not used at all. Any assignments to any objects is possible. This is the behavior compatible with midPoint 3.9 and earlier. And we still want to maintain that compatibility.
  • Closed world: No assignment relations are possible. Only those relations that are explicitly specified should be allowed. This may be applicable in an ideal state when all the archetype functionality is finished. But midPoint is not there yet.

The decision is that midPoint 4.0 will be open to assignment relations. Which means that any assignment to any object is still possible (limited by authorizations, of course).  Which means that assignment relation specification is used mostly to render a new GUI buttons for a better convenience. But otherwise it will not limit midPoint capabilities. This decision was made to allow smoother transition from midPoint 3.x. Later midPoint versions will bring more archetype-related functionality. The next step will be a setting that can change the default behavior from open to closed. The plan is also to allow wildcard assignment specification (specification that is empty and that allows any assignment), which can be used to selectively allow open behavior for archetypes. That should allow fine-grain control.

Order Constraints

Assignment relation applies only to assignments by default. Therefore it controls when an assignment can be made. It does not apply to inducements - yet. In later midPoint versions there will be an element that can specify "order constraints". In that case assignment relation could specify properties of inducements, including high-order inducements. However, the implementation in midPoint 4.0 is limited to assignments.

Default Definition

Archetype definitions can specify details of behavior for "archetyped" objects. But there are also objects that do not have any archetype. We may want to specify behavior for those objects as well. And in fact this was possible in midPoint for ages, even though it was not explicitly denoted as having anything to do with archetypes. There is defaultObjectPolicyConfiguration container in system configuration object:

<systemConfiguration>
   ...
   <defaultObjectPolicyConfiguration>
      <type>UserType</type>
      <objectTemplateRef oid="10000000-0000-0000-0000-000000000222"/>
   </defaultObjectPolicyConfiguration>
   ...
</systemConfiguration>

In fact, the data structure of defaultObjectPolicyConfiguration is almost identical to the structure of archetypePolicy in the archetype definition. And it also works in almost the same way. This is the definition that is applied to non-archetyped objects of that particular type. And parts of that definition may also apply to archetyped objects, as this definition is merged with archetypePolicy. Of course, archetypePolicy will override any aspects of the default specification. But the aspects that are not defined in archetypePolicy are taken from the default global policy.

In midPoint 4.0 there may be some limitations, e.g. changing global object icons or colors in the system configuration may not work properly. Those things were hardcoded in midPoint user interface for years. And as this is mostly a user interface functionality it is not easy to hunt down and fix all the issues. But those things should steadily improve in following midPoint versions.

Pre-Defined Archetypes

MidPoint is designed to fit in many environments and those environments may be unlike each other is a very significant way. However, there are still few things that most of the environments have in common. There are types of objects that are used in almost any midPoint deployment. Therefore midPoint 4.0 has a few default archetypes that can be used as starting point for further midPoint configuration:

ArchetypeMember Object TypeMember ObjectsDescription
System UserUseradministratorArchetype for system users, i.e. non-person users that are needed for system to work. This may be (root-like) system administrator, application users and so on.
System RoleRolesuperuser, approver, reviewer, delegator

Archetype for roles that are essential from the system point of view. Those are usually roles for the most powerful system administrators, roles for internal usage in the system (e.g. by tasks) and so on.

Business RoleRolenone

Archetype for roles that have meaning from the business perspective. Business roles are usually assigned directly to users, often by using request-and-approve processes. Business roles are usually composed from smaller roles.

Manual Provisioning CaseCasenone, assigned dynamically
Archetype for cases that describe manual provisioning operations.
Operation RequestCasenone, assigned dynamicallyArchetype for cases that describe operation requests, e.g. role assignment requests.
Approval CaseCasenone, assigned dynamicallyArchetype for approval cases, e.g. role assignment approval.

Some of the archetypes are provided as a starting point for system configuration. This is namely the Business Role archetype. Feel free to modify those archetypes. Those are provided in the initial objects mostly to keep the terminology of midPoint deployments somehow aligned. This makes communication in midPoint community smoother.

There are also archetypes that are essential for proper midPoint functionality, e.g. the archetypes for cases. While you can still modify those, you should have good understanding of how midPoint works and what effects can those changes may have. Please be careful here.

Authorizations

Archetype can be used as a criterion in authorizations:

  <authorization>
    <action>...</action>
    <object>
      <archetypeRef oid="00000000-0000-0000-0000-000000000321"/>
    </object>
  </authorization>

Limitations

Following limitations for archetype functionality apply in midPoint 4.x:

  • Only User, Role, Org and Service archetypes are supported in 4.0. Archetypes are designed to work with many object types, including tasks and resources. And in theory, archetypes may be applied to archetypes themselves, creating meta-archetypes. But all of that is not fully supported yet. Some of that extra functionality may work, but it is not tested properly. Therefore use it at your own risk only.
  • Performance limitation: Do not create too many archetypes. They all need to be cached in RAM. Tens or even hundreds are perfectly fine. Thousands or more may be a problem.
  • AssignmentRelation works only in archetypes. While theoretically assignmentRelation can be placed in any assignment/inducement, this is not yet supported. It must be a first-order inducement (inducement order must be 1). Assignment relation in metaroles or other mechanism that requires higher-order inducement or inducement chaining are not supported yet.
  • assignment/inducement that contains assignmentRelation must be always active (non-conditional, no activation)
  • AssignmentRelation in archetype assignment is not fully supported yet.
  • AssignmentRelation must be (almost) fully specified to work well in midPoint 4.0. Only the archetype definition may be missing. Object type and relation must always be specified. Full support for wildcard assignmentRelations is planned for later midPoint versions.
  • AssignmentRelation only applies to limit the assignments between objects. It does not support limitations of inducements yet. I.e. there is no support for order constraints in the assignment relation specification. That is planned for later midPoint versions.
  • AssignmentRelation does not limit the assignments that can be created - yet. The default behaviour of assignments is open (see above). Assignment relation is used in midPoint 4.0 mostly to render special button for user convenience.
  • Archetype assignments are not supposed to change during the lifetime of an object. Archetypes should be set once, ideally at the beginning of lifecycle (object created from GUI with an archetype, archetype set by inbound mapping, etc.). The archetype should be fixed and it should never change. That is expected behavior for midPoint 4.0. This behavior can can change in later midPoint versions. However, there still will be some limitations about archetype change. Change of archetype may mean change of object schema, therefore this will always be a sensitive operation.
  • There is no user interface to conveniently manage archetype definitions yet.
  • Archetypes of archetypes (meta-archetypes) are not supported yet.
  • Archetype colors are not applied in the user interface consistently. E.g. the color of "summary panel" on user details page will be red, regardless of the archetype, as red is currently color associated with users. This is planned to be improved later.
  • User type colors from 3.x are currently hardcoded in the system. Therefore users are displayed in the menu as red. The plan is to be able to configure this behavior in the future.

Please see Archetype Improvements (Planned Feature) for future plans regarding archetype functionality development.

See Also

  • No labels