User Scripting API
 | Script-oriented APIs to manipulate users and groups |
| Type | JAR |
| Category | API |
| Developed by | |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Bundled With | XWiki Standard |
| Compatibility | Since 10.8RC1 |
Table of contents
Description
The user module provides various script oriented APIs. It's also possible to extend it by registering a org.xwiki.script.service.ScriptService component with a hint prefixed with "user.".
Following are the default set of user related APIs:
- user: $services.user The entry point of this module is the script service with the identifier user which then provide several "sub-script services". It will also contains user related manipulation APIs in the future.
- group: $services.user.group This script service is dedicated to groups manipulation.
Examples
Resolving a User
Note that you can pass a String to APIs accepting a UserReference and it'll be converted automatically to a UserReference. For special references, use $services.user.superAdminUserReference, $services.user.guestUserReference and $services.user.currentUserReference.
The following return a UserProperties object:
// Get direct properties for the SuperAdmin user
$services.user.getProperties($services.user.superAdminUserReference)
// Get direct properties for the Guest user
$services.user.getProperties($services.user.guestUserReference)
// Get direct properties for the current user
$services.user.properties
// Get all properties for the current user (thus with full fallbacks)
$services.user.allProperties
// Get properties for a user
$services.user.getProperties("JohnDoe")
// Get properties for a user in a specific wiki
$services.user.getProperties("somewiki:XWiki.JohnDoe")
{{/velocity}}
Example: Get the editor for the current user (including fallbacks):
Serializing a user
XWiki 13.8+
It is possible to serialize a user reference with the default serializer using the script service:
#set ($userReference = $api.returning.user)
Retrieved user: $services.user.serialize($userReference)
{{/velocity}}
User Manager
// Check if a user exists
$services.user.exists("JohnDoe")
// Check if current user exists
$services.user.exists($services.user.currentUserReference)
{{/velocity}}
Member's groups
Get the Document References of the groups the current user belongs to:
##########################
## Get all groups
# Search for the groups in all wikis
#set($allGroupsInAllWikis = $services.user.group.getGroupsFromAllWikis($xcontext.userReference))
# Search for the groups in the same wiki as the user
#set($allGroupsInUserWiki = $services.user.group.getGroupsFromMemberWiki($xcontext.userReference))
# Search for the groups in current wiki
#set($allGroupsInCurrentWiki = $services.user.group.getGroups($xcontext.userReference, $xcontext.database, true))
##########################
## Get only direct groups
# Search for the groups in all wikis
#set($directGroupsInAllWikis = $services.user.group.getGroups($xcontext.userReference, $NULL, false))
# Search for the groups in the same wiki as the user
#set($directGroupsInUserWiki = $services.user.group.getGroups($xcontext.userReference, $xcontext.userReference.wikiReference, false))
# Search for the groups in current wiki
#set($directGroupsInCurrentWiki = $services.user.group.getGroups($xcontext.userReference, $xcontext.database, false))
{{/velocity}}
Group's members
Get the members of some group:
# Get all the members by resolving sub-groups
#set($allGroupsInAllWikis = $services.user.group.getMembers('xwiki:XWiki.MyGroup'))
# Get only the direct members
#set($allGroupsInUserWiki = $services.user.group.getMembers('xwiki:XWiki.MyGroup', false))
{{/velocity}}
Prerequisites & Installation Instructions
We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).
You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.
Dependencies
Dependencies for this extension (org.xwiki.platform:xwiki-platform-user-script 16.9.0):
- org.xwiki.commons:xwiki-commons-script 16.9.0
- org.xwiki.platform:xwiki-platform-user-api 16.9.0
