The tool described here is in early stages of its development. Although useful even now, please use with care.
Experience with more complex deployments shows that there is a need of a tool that would facilitate development of a midPoint-based solution. Here is a first prototype of such a tool: the midPoint Eclipse plugin.
Installation is done directly into Eclipse using the following update site: https://download.evolveum.com/downloads/midpoint-eclipse-plugin/. For more information, please see the installation HOWTO.
First of all, make sure your midPoint is up and running. The required version is 3.4.1; but full functionality requires a more current version:
|midPoint 3.4.1||All except the one mentioned below.|
|midPoint v3.5devel-322-g7dc89ef (September 19th, 2016)|
"Dry run" (i.e. invoking preview changes instead of real execution) for selected bulk actions.
|midPoint v3.5devel-323-g11d9fd5 (September 20th, 2016)||Fixes bug that prevents modifying more than one object via bulk action (!)|
This fix is also present in support-3.4 branch.
As for the plugin, please use at least version 0.10.0 (preferably the latest one that contains some bugfixes and improvements). Versions before 0.10.0 are not compatible with midPoint 3.4.1 or later.
The first thing that has to be done is to configure connection to midPoint server or servers. So, open midPoint -> Preferences and fill-in connection information. You could then test the connection.
(Note that for midPoint 3.4.1, the server version is reported as "unknown".)
You can create more servers if you need to. For example servers for development, QA, or production.
For each server you can fill-in the following information:
|Name||Name that is used to identify a server for example in logging messages. If left empty, server's URL is used as an identifier.||Development, Testing, Production, ...|
|URL||URL that is used to connect to the server. It is obligatory.||http://localhost:8080/midpoint|
|Login||User name that will be used to connect to the server. It should have administrative rights.||administrator|
|Password||Password used to connect to the server.||5ecr3t|
|Short name||Symbol that will be used when generating files specific to the server (e.g. action outputs or log fragments). Can be omitted. By default, it is not used.||dev, test, prod|
|Properties file||Values for "macros" in the form of $(name) that will get automatically resolved when objects are uploaded to this server. See below.||/eclipse/workspace/Project123/servers/development.properties|
|Log file||Server log file. This is used to show log file content (or fragments of it) in the plugin.||/usr/share/tomcat7/logs/idm.log|
The configuration is saved in your workspace directory as ".metadata/.plugins/org.eclipse.core.runtime/.settings/com.evolveum.midpoint.eclipse.ui.prefs" file.
Before continuing, create at least one Eclipse project. It should not be a Java project. Best choice is a general project.
This Eclipse plugin can be used in many ways, in various contexts. For example:
Let us visit features of the plugin that could be helpful in these scenarios.
As first real step, let's have a look at the server objects. So, select midPoint -> Browse server objects, or simply press Alt+F1. The following window will open:
In the upper part of the window you can formulate a query. The easiest way is to use empty query (i.e. not touch anything) and just hit Search (or Alt+S). You'll see all objects on the server:
You can restrict the query by:
Note that because of quite bizarre midPoint bug it is not possible to select an abstract type (like Object or Focus) along with any type that precedes it in the list. You can work around by selecting concrete types (or limiting use of abstract types to one).
After executing a query, you can view the object or objects by using Show button, pressing Alt+H or simply double-clicking on an object. The object(s) will be downloaded to newly created file (like scratch/gen/00000.xml) and opened in XML editor.
Other options (Download, Generate and Execute) will be covered later.
Now imagine you want to systematically work with objects in your Eclipse workspace: you would like to edit them and upload to server as necessary.
There are more ways how to do this:
Downloading can be done in two ways:
The result is basically the same. In the first option you can select exactly which objects to download. In the second one, a configuration specified in plugin preferences is used instead:
You see that all objects except for users, shadows, report outputs, connectors, certification campaigns and nodes are downloaded.
By default, objects are stored in tree structure, like this:
The structure is determined by "Downloaded file name pattern" option (objects/$T/$n.xml by default). It is advised to start with this setting.
You can then edit these objects or add new ones.
For example, you can create a user or a query. You can do it at any place in your workspace. It is recommended to place objects in the appropriate part of objects tree (even if they are not downloaded), and to keep actions and queries in separate folders under the project root.
There are a couple of ways to facilitate this task.
Concerning the fourth option: you can use Ctrl+Space to select a template, like this:
After clicking on "user object" you'll see the following:
Now you can simply fill-in missing data, and enter additional user properties. OID can be generated by invoking midPoint -> Miscellaneous -> Generate random OID. After that, it is shown in plugin console as well as placed into clipboard. You can then simply paste it at appropriate place.
Currently there is only a few templates, but more will appear in future.
After creating an object you can upload it by selecting midPoint -> Upload/execute or pressing Alt+F2. This can be done for one XML file (containing one or more objects) or even for selection of more files and/or directories.
Objects are uploaded and bulk actions are executed.
Action execution deserves a few more words. To try it, please create the following file (queries/query.xml):
<?xml version="1.0"?> <search> <type>UserType</type> <searchFilter> <substring> <matching>polyStringNorm</matching> <path>name</path> <value>user1</value> <anchorStart>true</anchorStart> </substring> </searchFilter> <action> <type>log</type> </action> </search>
Before invoking the action, please make sure the midPoint server log file is set up:
(Note that although midPoint can provide log file content via REST interface, the plugin can currently work only with the log that is stored as a file.)
After setting up the log file position, execute query.xml by selecting it and clicking on Upload/execute button (or by selecting midPoint -> Upload/execute from main menu or Transfer-related actions -> Upload/execute from the popup menu or by pressing Alt+F2).
After execution you should see the following:
Outputs of the execution, namely:
are stored in your eclipse workspace (by default, in scratch/runs subdirectory), and can be opened there, or by clicking on respective hyperlinks down in the midPoint console. For example, the data output looks like this:
By setting appropriate preferences you can configure automatic opening of selected windows after execution of actions, and also automatic execution of selected actions after upload. This is meant e.g. to facilitate mappings testing and bugfixing - to minimize number of clicks you have to do:
It is possible to compare local (Eclipse) and remote (midPoint) versions of one or more files by selecting them and choosing Compute differences command. It looks like this:
(We selected "objects" directory and invoked Compute differences.)
For each file, four results are provided:
These files can be accessed by clicking on links in the console window, of by directly opening the files in "diff" directory. Note that it is possible to use Eclipse mechanisms to compare local and remote versions of the file, leading to a graphical information about the changes:
It is possible to configure items that should be excluded from comparison. By default, all operational items are excluded, but you can specify any others.
This plugin provides a simple mechanism of "macro expansion" allowing to provide system-specific values for individual objects. For example, you can have something like this:
<resource> ... <connectorConfiguration> <icfc:configurationProperties xmlns:icfcldap="http://midpoint.evolveum.com/xml/ns/public/connector/icf-1/bundle/com.evolveum.polygon.connector-ldap/com.evolveum.polygon.connector.ldap.LdapConnector"> <icfcldap:port>$(ldapPort)</icfcldap:port> <icfcldap:host>$(ldapHost)</icfcldap:host> <icfcldap:baseContext>$(ldapBaseContext)</icfcldap:baseContext> <icfcldap:bindDn>$(ldapAdmin)</icfcldap:bindDn> <icfcldap:bindPassword> <t:clearValue>$(ldapPassword)</t:clearValue> </icfcldap:bindPassword> <icfcldap:pagingStrategy>auto</icfcldap:pagingStrategy> <icfcldap:vlvSortAttribute>entryUUID</icfcldap:vlvSortAttribute> <icfcldap:operationalAttributes>ds-pwp-account-disabled</icfcldap:operationalAttributes> <icfcldap:operationalAttributes>isMemberOf</icfcldap:operationalAttributes> </icfc:configurationProperties> ... </resource>
And the values for LDAP host, port, base context, and so on can be specified independently for each managed server. They are stored in property files that are configured for the servers:
ldapPort=1389 ldapHost=localhost ldapAdmin=uid=idm,ou=Administrators,dc=example,dc=com ldapPassword=secret ldapBaseContext=dc=example,dc=com
After uploading the object, you can see that macros got resolved:
Besides $(property-name) you can use the following:
|$(@filename)||Take file with 'filename' (relative to the position of file when the symbol was used) and use the file content to replace the $(...) symbol.||$(@notifications.txt) in system configuration objects.|
|$(#project.name)||Name of the current project.|
|$(#project.dir)||OS directory of the current project.||Useful e.g. when configuring CSV resource pointing to a file that is contained directly within Eclipse project.|
|$(#server.displayName)||Name of the currently selected server (to which the file is being uploaded).|
Current restriction is that the text between parentheses - i.e. (...) - cannot contain whitespaces.
It is quite useful to tell Eclipse about the midPoint schemas, so it can check the validity of XML files and it can provide hints (content assist) when editing them. Although not 100% error-free, it is a big help.
It is done by these steps:
In order to Eclipse to provide content help you need to specify namespaces explicitly in the edited file. When typing just use usual ctrl+space or wait for popup to appear after stating the prefix (e.g. <q:)
Creating new GUI bulk action script sample:
<search xmlns="http://midpoint.evolveum.com/xml/ns/public/model/scripting-3" xmlns:c="http://midpoint.evolveum.com/xml/ns/public/common/common-3" xmlns:q="http://prism.evolveum.com/xml/ns/public/query-3"> <type>c:UserType</type> <searchFilter> <q:equal> <q:path>c:fullName</q:path> </q:equal> </searchFilter> <action> <type>recompute</type> </action> </search>
As said, this plugin is in early stages of its development. Some of the known limitations are:
We would like to hear any experiences and suggestions regarding this plugin.