User Scripting API

Last modified by Admin on 2024/10/01 02:06

cogScript-oriented APIs to manipulate users and groups
TypeJAR
CategoryAPI
Developed by

XWiki Development Team

Rating
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard

Compatibility

Since 10.8RC1

Installable with the Extension Manager

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

Since 12.2 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:

{{velocity}}
// 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):

$services.user.allProperties.editor

Serializing a user

XWiki 13.8+

It is possible to serialize a user reference with the default serializer using the script service:

{{velocity}}
#set ($userReference = $api.returning.user)
Retrieved user: $services.user.serialize($userReference)
{{/velocity}}

User Manager

{{velocity}}
// 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:

{{velocity}}
##########################
## 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:

{{velocity}}
# 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.8.0):

Get Connected