Maintaining midPoint Configuration as Files

Last modified 07 Sep 2022 03:49 +02:00

midPoint configuration objects are currently represented in XML. They can be created as XML files and imported to midPoint using "Configuration" - "Import object" menu entry. You can also manually edit (as XML) and export current configuration using "Configuration" - "Repository objects" menu entry. For some objects there is also a GUI way how to configure them - for example most of the System Configuration can be configured in GUI, roles (without mappings) can be configured in GUI. But you should know why is good to maintain some configuration objects outside of midPoint. The main reason is - configuration backup and versioning in systems such as git. If your configuration is stored as files, you can import it to other midPoint installations or environments. For example you can have the same set of roles in production and testing systems while the resource configurations may be different in connection parameters. To make a copy of configuration object with only connection parameters different is trivial and saves your precious time.

If you want to use XML objects and import them to midPoint, you can:

use some of our samples and modify them to satisfy your requirements. Especially resource samples may be very helpful. For example you can use our OpenLDAP samples and just change connection parameters.
create XML object from scratch. This is not recommended if you are only starting with midPoint because you would need to know midPoint XML schema.

OID

Each object must have "oid" attribute. We recommend to create static OID when preparing the object for midPoint, otherwise midPoint repository will generate on when importing (but you will not know the value unless you look to repository objects). The OID value must be globally unique and can be generated by e.g. command line utility "uuid". For example:

vix@bugstomper:~$ uuid
b26554d2-41fc-11e5-a652-3c970e44b9e2
vix@bugstomper:~$

Notice the same value generated by "uuid" used in the sample now:

<?xml version="1.0" encoding="UTF-8"?>
<objects xmlns="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:c="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
         xmlns:xsd="http://www.w3.org/2001/XMLSchema"
         xmlns:ri="http://midpoint.evolveum.com/xml/ns/public/resource/instance-3"
         xmlns:icfs="http://midpoint.evolveum.com/xml/ns/public/connector/icf-1/resource-schema-3"
         xmlns:icfc="http://midpoint.evolveum.com/xml/ns/public/connector/icf-1/connector-schema-3"
         xmlns:my="http://whatever.com/my"
         xmlns:q="http://prism.evolveum.com/xml/ns/public/query-3"
         xmlns:mr="http://prism.evolveum.com/xml/ns/public/matching-rule-3">

        <resource oid="b26554d2-41fc-11e5-a652-3c970e44b9e2">
        <name>Corporate Directory</name>

If you use fixed OID in resources, you can create also roles and refer to resource OID there:

<role oid="aaa10967-ca0f-11e3-bb29-002f9d717e5b"
        xmlns="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
        xmlns:c="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
        xmlns:t="http://prism.evolveum.com/xml/ns/public/types-3"
        xmlns:ri="http://midpoint.evolveum.com/xml/ns/public/resource/instance-3"
        xmlns:q="http://prism.evolveum.com/xml/ns/public/query-3"
        xmlns:ext="http://midpoint.evolveum.com/xml/ns/custom/project/extension-1">
    <name>Contractor</name>
    <description>Assign to temporary users</description>
     <inducement>
        <construction>
                <!-- This is the OID of the "Corporate Directory" resource -->
                <resourceRef oid="b26554d2-41fc-11e5-a652-3c970e44b9e2" type="c:ResourceType"/>
        </construction>
      </inducement>
</role>

This is how you can prepare your objects outside of midPoint. All further modifications should be then done in XML file and reimported to midPoint (using "Overwrite" option). If you use git, you will see all your changes in configuration and their history.

What about midPoint GUI?

You can use midPoint GUI to create objects that you don’t want to keep versioned as XML files, or you can use midPoint GUI to create objects and then export them using "Configuration" - "Repository objects" menu entry. Please note that XML files produced by midPoint (or rather by XML processing libraries) can contain more clutter than XML files created by you. For example see how namespace declarations differ when are being exported in the following samples (also see how "ref" element is exported as "c:ref" and matchingRule "mr" prefix repeating in each matchingRule element). Also, XML comments are never stored in midPoint repository.

The original object (on disk):

...
                <attribute>
                    <ref>ri:l</ref>
                    <outbound>
                        <expression>
                            <variable xmlns:my="http://whatever.com/my">
                                <name>my:defaultLocation</name>
                            <value xsiType="xsd:string">middle of nowhere</value>
                            </variable>
                            <script>
                                <description>XPath expression that is using a variable declared above</description>
                                <language>http://www.w3.org/TR/xpath/</language>
                                <returnType>scalar</returnType>
                                <code xmlns:my="http://whatever.com/my">
                                    $my:defaultLocation
                                </code>
                            </script>
                        </expression>
                    </outbound>
                </attribute>
...
                <attribute>
                    <ref>ri:uid</ref>
                    <displayName>Login Name</displayName>
                    <matchingRule>mr:stringIgnoreCase</matchingRule>
                    <outbound>
                        <strength>weak</strength>
                        <source>
                            <description>Source may have description</description>
                            <path>$user/name</path>
                        </source>
                    <!-- We need to put iterationToken here as well, otherwise effect described in MID-2139 occurs -->
                    <expression>
                        <script>
                            <code>name + iterationToken</code>
                        </script>
                    </expression>
                    </outbound>
                    <inbound>
                        <target>
                            <description>Targets may have description</description>
                            <path>$c:user/c:name</path>
                        </target>
                    </inbound>
                </attribute>

The same object XML after export:

...
        <attribute>
            <c:ref>ri:l</c:ref>
            <outbound>
               <expression>
                  <variable>
                     <name xmlns:my="http://whatever.com/my">my:defaultLocation</name>
                     <value xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                            xsi:type="xsd:string">middle of nowhere</value>
                  </variable>
                  <script>
                     <description>XPath expression that is using a variable declared above</description>
                     <language>http://www.w3.org/TR/xpath/</language>
                     <returnType>scalar</returnType>
                     <code>
                                    $my:defaultLocation
                                </code>
                  </script>
               </expression>
            </outbound>
         </attribute>
...
         <attribute>
            <c:ref>ri:uid</c:ref>
            <displayName>Login Name</displayName>
            <matchingRule xmlns:mr="http://prism.evolveum.com/xml/ns/public/matching-rule-3">mr:stringIgnoreCase</matchingRule>
            <outbound>
               <strength>weak</strength>
               <source>
                  <description>Source may have description</description>
                  <c:path>$user/name</c:path>
               </source>
               <expression>
                  <script>
                     <code>name + iterationToken</code>
                  </script>
               </expression>
            </outbound>
            <inbound>
               <target>
                  <description>Targets may have description</description>
                  <c:path>$c:user/c:name</c:path>
               </target>
            </inbound>
         </attribute>

Although this is not entirely bad, but the XML files produced by export will be longer and sometimes less readable.

The following objects can be created using GUI in midPoint 3.4:

Users (of course)
Organizations (of course)
Roles: can be created and modified, but currently you cannot define mappings / associations in roles using GUI. So the role editor can be best used to form "business roles" from your existing roles.
Tasks
Reports
System Configuration modifications ("Configure" - "System"; "Logging" etc.)

In most of our projects, we need to create and maintain configuration at least for: Resources, Roles and Object Templates.

Resource Wizard

Resource Wizard is a part of midPoint GUI which has been implemented to simplify creation of resources without using samples. The OID is automatically generated and the connection parameters are dynamically created using connector schema after the connector for the resource is selected. As midPoint evolved during and after creation of resource wizard (e.g. generic synchronization, entitlements and associations), the resource configuration using the wizard became "less simple" than we anticipated. That’s why we intend to further change and simplify the resource wizard in the future midPoint releases.

Best practice is using the resource wizard for basic resource configuration. If you need to configure schema handling with complex mappings and especially with multiple object types, then we recommend to export the resource to XML and maintain as XML file.

Was this page helpful?

YES NO

Thanks for your feedback