Query Examples
MidPoint provides multiple mechanisms to query data and search for information. This page provides basic information and examples of advanced search using midPoint query language (MQL) in midPoint GUI.
The page is intended for users who understand midPoint concepts and architecture (IDM operators, administrators, engineers, etc.) who can use MQL in deeper analyses, and search for objects and their relations in GUI.
Basic Information
MQL is designed to query objects in the midPoint repository, filter objects, set up object references, and so on. The language closely follows the midPoint data model. Names of properties, attributes, and all data items are directly taken from the midPoint data model (e.g. fullName, activation/effectiveStatus).
MQL provides the following comparison operators: "=", "!=", "<", "⇐", ">", ">=" with their usual meaning. Strings may also be compared using the "startsWith", "endsWith", "contains" and "fullText" operators. Note that the fullText operator requires configuration of the fulltext index.
It also provides logical operators "and", "or" and "not". Execution of complex queries may be ordered using brackets.
Objects in midPoint are bound by relations (assignments, inducements, etc.). MQL provides dereferencing mechanism with the “@” operator which allows searching for objects using attributes and values in references. See usage examples.
You can create complex queries also using the "matches" operator and "exists" operators. See usage examples.
For more information on operators, refer to midPoint Query Language.
How to Start
In each view in GUI, search is set to Basic by default. To be able to use MQL queries, you need to open the search options and select Advanced.
Each query searches for objects within the currently opened view in GUI. If you want to search for all objects of a specific type, you need to select the relevant view (All users, All roles, All services).
It is necessary to be familiar with the internal structure of midPoint objects. You should know the basic names of attributes, have an understanding of the assignment/targetRef attribute and the roleMembershipRef attribute. To find the name of a specific attribute, use the Edit raw button on the object details page.
Search queries are case-sensitive. For example, the query givenName = "John"
is different from givenName = "john"
.
Saved Searches
You can save filters for future use by clicking the Save filter button.
Advanced Query Examples
See examples of MQL queries below.
Search by Attributes in Objects and References
Request | Advanced query | Details |
---|---|---|
Find users with a specific given name. |
|
|
Find users with the last name starting with a specific string. |
|
|
Find roles with the name ending with a specific string. |
|
Searching in All roles view. |
Find services where the Application URL extension attribute contains a specific string. |
|
Attributes specific to a deployment are in objects stored as extension attributes in the <extension> XML element. To search for these attributes, you need to include "extension/" in the attribute name. |
Find disabled users in the All users view. |
|
|
Find multiple roles specified by name. |
|
The |
Search by attributes in referenced objects |
||
Find a user with a specific assignment. |
|
The dereferencing operator “@” states that everything coming after it relates to the referenced object. |
Find users with an indirectly assigned service object. |
|
The indirect assignment of a service object represents "access to application". |
Find users of a specific archetype. |
|
|
Find members (not owners) of the ABC role. |
|
The role owners have the role assigned as |
Logical operators in search |
||
Find all external users with a specific given name. |
|
|
Search by dates and times |
||
Find all users created after a particular date. |
|
|
Find all users created on a particular date (e.g. 22/10/2022). |
|
|
Find users modified at a specific second. |
|
|
Search by object OID |
||
Find 1 object specified by its OID. |
|
The list of OIDs may contain one or more OIDs. |
Search Through Assignments or Other References
These searches are valid in views listing objects, such as users, roles, or services. For searches in the object panels, see searching for objects marked by object marks.
Request | Advanced query | Details |
---|---|---|
Find users with directly assigned specific roles. |
|
|
Find users with specific roles assigned (directly or indirectly). |
|
Note that |
Find users without a service assigned (directly or indirectly). |
|
|
Find users without a role or service assigned (directly or indirectly). |
|
|
Find roles without inducements. |
|
This combines the |
Find users without a directly assigned role or service. |
|
The assignment attribute only contains direct assignments. |
Find owners of roles, i.e. users with roles to which they are assigned as owners. |
|
The relation value is of the QName type and therefore no quotation marks are used. |
Find users with accounts in a specific resource. |
|
The resource is identified by OID. |
Find users with an account in a specific resource. |
|
Same as the previous query, only in this case, the resource is identified by its name. |
Find users who have roles with specific extension attributes assigned. |
|
This is a complex query that searches for all assignments of a role identified by the value of a specific extension attribute. |
Searching within ORGs |
||
Find all users who are members of an ORG. |
|
The dot describes the user object. |
Find all users who are members of an ORG specified by its name. |
|
The query is the same as the previous query, only in this case, the ORG is conveniently specified by its name. |
Find a manager of an ORG. |
|
If the ORG is specified by its name, then the |
Searching in referenced objects With MQL, you can search in objects that are referenced by other objects. |
||
In the roles view, find all roles that are assigned to a specific user. |
|
The dot is important in the query as it specifies the object. |
Searching for Objects Marked by Object Marks
Since 4.9
This functionality is available since version 4.9.
|
Request | Advanced query | Details |
---|---|---|
Find all shadows with the "Suspicious" object mark. |
|
If used within the resource Accounts or Entitlements panels in GUI, the query returns only shadows related to the particular resource. |
Find all users that have shadows with the "Suspicious" object mark. |
|
The exact meaning of the query is: "Return objects with linked shadows that have an active object mark with the name Suspicious." |
Searching in All Accesses Panel
View in the "All accesses" panel displays the content of the "roleMembershipRef" attribute. This means that you need to exclude the attribute name from your queries.
Request | Advanced query | Details |
---|---|---|
Find all assigned roles. |
|
You can also use ServiceType for services or OrgType for organizational units. |
Find all accesses starting with the gallery in the display name. |
|
The view shows display names of objects, i.e. searching for a name element could return confusing results if the name and displayName are different. |
Find all applications to which a user has access. |
|
This searches for all references with the "Application" archetype. You can search for "Application role" or "Business role" in the same way. |
Searching in Assignments Panels
Views in assignments panels display the content of the "assignment" attribute, i.e. you need to exclude the name of this attribute from queries.
Request | Advanced query | Details |
---|---|---|
Find all directly assigned roles. |
|
|
Find all assignments (roles or other) with the name starting with "C". |
|
Dereferencing (searching with “@”) only works in the assignment panel when repository search is enabled. |
Searching in Tasks
The standard task object structure is not designed for searching.
Therefore, an additional affectedObjects
element is used since midPoint 4.8.
This enables you to search for tasks by affected objects and their execution mode.
Request | Advanced query | Details |
---|---|---|
Find all tasks running on users. |
|
|
Find all tasks that perform reconciliation. |
|
Include namespace specification "c:" in the activity type. |
Find all tasks that perform an operation with the XYZ resource. |
|
|
Find all tasks that perform reconciliation on the XYZ resource. |
|
You can use archetypes or resource OIDs, however, dereferenced names are easier to read. |
Find all simulation tasks. |
|
Simulation tasks are in the "preview" mode. Standard tasks that also execute changes have the "full" execution mode. |
Searching in Audit Events
You can utilize MQL also in Audit Log Viewer which enables you to review failed events, select specific objects and operations.
There is no specific timeframe defined for Advanced search. In audit searches, especially if they are extensive, it is recommended to specify timestamps for better performance.
Request | Advanced query | Details |
---|---|---|
Find all events initiated by a specific user. |
|
|
Find all events related to a specific user. |
|
This is also possible via object OID, without dereferencing: |
Find all events in a specific day. |
|
|
Find all events within a specific time range. |
|
|
Find all events of a specific type. |
|
|
Find all events in which a specific attribute was updated. |
|
Include the "c:" prefix in the name of the attribute. |
Find all failed events since a specific date. |
|
You cannot use scripting in GUI searches. Therefore, the dates must be defined explicitly and updated if necessary. |
Find all events related to the "XYZ" resource. |
|
You can also use the resource OID, without dereferencing: |
Find all events related to the "john" account in the "XYZ" resource. |
|
The delta components |
Find all events related to user "JohnDoe" in the "XYZ" resource. |
|
While the previous query was searching for modifications of an account in a resource, this query provides audit events in the specified resource related to a specific user (not only accounts but potentially also entitlements or accounts with different names). |
Find all events generated by specific task (any run). |
|
|
Find all events generated by a specific task (single run). |
|
The task identifier is unique for each run of the task. |
Find all object modifications that did not go well. |
|
|
Searching in audit deltas |
||
Find all events in which accounts in the "XYZ" resource were created or modified. |
|
See Also
-
midPoint Query Language - The main page of MQL.
-
Searchable items - Which items/elements/attributes can be searched.
-
Errors while using midPoint query - Error messages with troubleshooting suggestions.
-
Using expressions in midPoint Query language - Expressions in MQL.