How do I get the list of all users?

[Julien Hoarau]

How do I get the list of all users within a Confluence plugin?

[Matt Ryall · Accepted solution]

Rather than using one of the methods that returns old users (some of which are deprecated), use a user search API to query for a limited subset of users in the system. Both the old Atlassian-User and the new CrowdService APIs allow you to search for users using boolean queries, and limit the number of results you get back.

• CrowdService.search() - new API
  
• UserAccessor.findUsers() - old API

Here's an example of searching for the names of the first 100 active users in Confluence with the CrowdService search() method:

PropertyRestriction<Boolean> restriction = Restriction.on(UserTermKeys.ACTIVE).containing(true);
EntityQuery<String> query = QueryBuilder.queryFor(String.class, EntityDescriptor.user()).with(restriction)
    .returningAtMost(100);
Iterable<String> usernames = crowdService.search(query);

The new CrowdService API will optimise your query if you are only retrieving strings, and many of the common membership-related queries are cached by Confluence.

[Gary Weaver]

Thanks for the info, Matt! Are there plans for implementing a Pager class similar to the old atlassian-user one in the embedded Crowd API? And perhaps something in AUI that allowed scrolling through a very large list of users that would automatically call CrowdService on the backend to page? I know that similar can be done by setting startIndex and maxResults on EntityQuery, but that makes the plugin have to keep track of index in session.

[Matt Ryall]

The Pager interface and implementation, despite its name, doesn't properly page results. All user management queries in 3.4 and earlier load the entire result set and cause performance problems.

So our recommendation is to do your own pagination via the startingAt() and returningAtMost() methods on the QueryBuilder. You should only be displayed a subset of users in the user interface of your plugins anyway.

[Gary Weaver]

Matt, thanks again. In earlier versions of Confluence (2.5.7 when we originally tested with a massive number of users), Pager was much faster than listing all users. What version of Confluence did that Pager issue come up in, so that I can tell users of the CSUM plugin? We have a UI in the CSUM plugin that pages through users in groups using Pager, so it is helpful to know that the Atlassian Pager API does not work properly. Again, appreciate your help.

[Matt Ryall]

The Pager has always been relatively slow, and loaded all the users if Atlassian-User caching was enabled (which it is by default). The difference with the "getUsersWithConfluenceAccess()"-style methods is that they also do permission checks and membership look-ups, in addition to retrieving all the users, so were even slower.

[CharlesA]

The short answer is: please don't. Confluence instances can have tens, even hundreds of thousands of users and listing them all is a very expensive operation.

If your plugin is only ever going to be installed on a Confluence instance with a small number of users, you'll want UserAccessor#getUserNamesWithConfluenceAccess if you're just after the usernames, or UserAccessor#getUsersWithConfluenceAccessAsList if you want the full User object for each user.

[Gary Weaver]

(Adding to Charles's, Stefan's, and everyone else's great answers)

Like Stefan said, check out UserAccessor.getUsers() that returns a Pager.

In the UserAndGroupManagementService class in the CSUM plugin (that link goes to v2.0.1, since as of 6/28/2011, the Confluence v3.5 version of the plugin is still under development (in trunk)), we do some paging, so you might take a look at that for an example.

The way I've been getting a Pager in CSUM to access users is via GroupManager's getMemberNames(Group). So another way would be to do this for the group "confluence-users", although maybe in future versions of Confluence that group may go away- not sure (seems like it should be a role/permission to use Confluence, not a group, and I thought I'd read something about that, but maybe I'm making that up).

There is also UserManager in versions of Confluence before v3.5 that you could call getUserNames() on. Then you can page through the result set.

In Confluence v3.5+, (in addition to using GroupManager) instead of using UserManager, you use CrowdService which is part of embedded Crowd. I could have sworn that I had seen that some part of the API let you specify start and end index on users or similar, but I can't find that part of the API at the moment. If someone finds it, let me know, and I'll update this answer.

Although I don't think that it matters for what you are doing, if you run into permissions issues using UserAccessor, try the manager or service classes which don't check permissions.

[Stefan Kohler]

Actually since Confluence 3.5.1 both methods are deprecated because they are very slow. That also counts for the userlister macro ;-)

Only methods available are userAccessor.getUsers() and userAccessor.getUserNames(). Those methods probably don't check if someone is also allowed to access Confluence of whatsoever. That could improve the speed a bit of course.

[Karola Schaeuble]

I would be careful using 'confluence-users' for this like suggested by Gary.

Just yesterday we had a discussion about how the group is defined and I found this useful definition by Confluence: http://confluence.atlassian.com/display/DOC/Users+and+Groups

It states that 'confluence-users' is the default group for NEW users. I read it that way, that users do not have to stay in this group. That means a user does not necessarily have to be in 'confluence-users' to have access to Confluence but must be in a group that has the 'can use' permission.

Please correct me if I'm wrong, that would be an important information.

[Jeremy Largman]

The userlister macro does this. The svn is here. Look at UserLister.java, I think it's a good start.

A tip on how I found that - if you check out Confluence's source, there's a shell script called checkout-bundled-plugins.sh in the confluence-project/confluence-bundled-plugins folder. It has the basic macros, advanced macros, and all the bundled plugins.

[Matt Ryall]

The UserLister plugin is one of the oldest Confluence plugins and its methods of looking up and displaying users shouldn't really be used as a reference. See Charles's and my replies above for the relevant API links.

[BG]

.

[Jason Skrzypek]

I usually use the usergroups macro and select relevent user group

{userlister:groups=confluence users} or {userlister:groups=*} for all groups