0
# User & Group Management
1

2
User administration including user creation, group management, permissions, avatar management, and user search functionality. These operations typically require administrative permissions in JIRA.
3

4
## Capabilities
5

6
### User Operations
7

8
Core user management functions for retrieving, creating, and managing JIRA users.
9

10
```python { .api }
11
def user(self, id: str, expand: str = None) -> User:
12
    """
13
    Get user information by username or user ID.
14
    
15
    Parameters:
16
    - id: Username or user ID
17
    - expand: Properties to expand (groups, applicationRoles)
18
    
19
    Returns:
20
    User object
21
    """
22

23
def search_users(
24
    self,
25
    user: str,
26
    startAt: int = 0,
27
    maxResults: int = 50,
28
    includeActive: bool = True,
29
    includeInactive: bool = False
30
) -> list[User]:
31
    """
32
    Search for users by username or display name.
33
    
34
    Parameters:
35
    - user: Username or display name search term
36
    - startAt: Starting index for pagination
37
    - maxResults: Maximum number of results
38
    - includeActive: Include active users
39
    - includeInactive: Include inactive users
40
    
41
    Returns:
42
    List of matching User objects
43
    """
44

45
def add_user(
46
    self,
47
    username: str,
48
    email: str,
49
    directoryId: int = 1,
50
    password: str = None,
51
    fullname: str = None,
52
    notify: bool = False,
53
    active: bool = True,
54
    ignore_existing: bool = False,
55
    application_keys: list = None
56
) -> User:
57
    """
58
    Create a new user.
59
    
60
    Parameters:
61
    - username: Username (must be unique)
62
    - email: Email address
63
    - directoryId: Directory ID for user creation
64
    - password: User password (auto-generated if not provided)
65
    - fullname: Full display name
66
    - notify: Send notification email to user
67
    - active: Whether user is active
68
    - ignore_existing: Don't fail if user already exists
69
    - application_keys: List of application keys for access
70
    
71
    Returns:
72
    Created User object
73
    """
74

75
def rename_user(self, old_user: str, new_user: str) -> None:
76
    """
77
    Rename a user.
78
    
79
    Parameters:
80
    - old_user: Current username
81
    - new_user: New username
82
    """
83

84
def delete_user(self, username: str) -> None:
85
    """Delete a user account."""
86

87
def deactivate_user(self, username: str) -> None:
88
    """Deactivate a user account."""
89
```
90

91
Usage examples:
92
```python
93
# Get user information
94
user = jira.user('john.doe')
95
print(f"Name: {user.displayName}")
96
print(f"Email: {user.emailAddress}")
97
print(f"Active: {user.active}")
98

99
# Get user with expanded groups
100
user = jira.user('john.doe', expand='groups')
101
groups = [group['name'] for group in user.groups['items']]
102
print(f"User groups: {groups}")
103

104
# Search for users
105
users = jira.search_users('john', maxResults=10)
106
for user in users:
107
    print(f"{user.name}: {user.displayName}")
108

109
# Create new user
110
new_user = jira.add_user(
111
    username='jane.smith',
112
    email='jane.smith@company.com',
113
    fullname='Jane Smith',
114
    password='temporary123',
115
    notify=True
116
)
117
print(f"Created user: {new_user.displayName}")
118

119
# Rename user
120
jira.rename_user('old.username', 'new.username')
121

122
# Deactivate user
123
jira.deactivate_user('inactive.user')
124
```
125

126
### User Search for Assignment
127

128
Specialized user search functions for finding users who can be assigned to issues or projects.
129

130
```python { .api }
131
def search_assignable_users_for_projects(
132
    self,
133
    username: str,
134
    projectKeys: list[str],
135
    startAt: int = 0,
136
    maxResults: int = 50
137
) -> list[User]:
138
    """
139
    Search for users who can be assigned to issues in specific projects.
140
    
141
    Parameters:
142
    - username: Username search term
143
    - projectKeys: List of project keys to check assignment permissions
144
    - startAt: Starting index for pagination
145
    - maxResults: Maximum number of results
146
    
147
    Returns:
148
    List of assignable User objects
149
    """
150

151
def search_assignable_users_for_issues(
152
    self,
153
    username: str,
154
    project: str = None,
155
    issueKey: str = None,
156
    expand: str = None,
157
    startAt: int = 0,
158
    maxResults: int = 50
159
) -> list[User]:
160
    """
161
    Search for users who can be assigned to specific issues.
162
    
163
    Parameters:
164
    - username: Username search term
165
    - project: Project key to check assignment permissions
166
    - issueKey: Specific issue key to check assignment permissions
167
    - expand: Properties to expand
168
    - startAt: Starting index for pagination
169
    - maxResults: Maximum number of results
170
    
171
    Returns:
172
    List of assignable User objects
173
    """
174

175
def search_allowed_users_for_issue(
176
    self,
177
    user: str,
178
    issueKey: str = None,
179
    projectKey: str = None,
180
    startAt: int = 0,
181
    maxResults: int = 50
182
) -> list[User]:
183
    """
184
    Search for users who have permissions for specific issues.
185
    
186
    Parameters:
187
    - user: Username search term
188
    - issueKey: Issue key to check permissions
189
    - projectKey: Project key to check permissions
190
    - startAt: Starting index for pagination
191
    - maxResults: Maximum number of results
192
    
193
    Returns:
194
    List of allowed User objects
195
    """
196
```
197

198
Usage examples:
199
```python
200
# Find users who can be assigned in projects
201
assignable_users = jira.search_assignable_users_for_projects(
202
    username='john',
203
    projectKeys=['PROJ1', 'PROJ2']
204
)
205

206
# Find users who can be assigned to a specific issue
207
assignable_users = jira.search_assignable_users_for_issues(
208
    username='jane',
209
    issueKey='PROJ-123'
210
)
211

212
# Find users with permissions for an issue
213
allowed_users = jira.search_allowed_users_for_issue(
214
    user='smith',
215
    issueKey='PROJ-123'
216
)
217
```
218

219
### User Avatars
220

221
Manage user avatar images.
222

223
```python { .api }
224
def user_avatars(self, username: str) -> dict:
225
    """Get available avatars for a user."""
226

227
def create_temp_user_avatar(
228
    self,
229
    user: str,
230
    filename: str,
231
    size: int,
232
    avatar_img,
233
    contentType: str = None,
234
    auto_confirm: bool = False
235
) -> dict:
236
    """Create temporary user avatar."""
237

238
def confirm_user_avatar(self, user: str, cropping_properties: dict) -> dict:
239
    """Confirm and crop user avatar."""
240

241
def set_user_avatar(self, username: str, avatar: str) -> None:
242
    """Set user avatar."""
243

244
def delete_user_avatar(self, username: str, avatar: str) -> None:
245
    """Delete user avatar."""
246
```
247

248
Usage examples:
249
```python
250
# Get user avatars
251
avatars = jira.user_avatars('john.doe')
252
print(f"Available avatars: {len(avatars['system']) + len(avatars['custom'])}")
253

254
# Upload new avatar
255
with open('profile_pic.jpg', 'rb') as avatar_file:
256
    temp_avatar = jira.create_temp_user_avatar(
257
        user='john.doe',
258
        filename='profile_pic.jpg',
259
        size=avatar_file.tell(),
260
        avatar_img=avatar_file,
261
        contentType='image/jpeg'
262
    )
263

264
# Confirm avatar with cropping
265
cropping = {
266
    'cropperOffsetX': 10,
267
    'cropperOffsetY': 10,
268
    'cropperWidth': 100,
269
    'cropperHeight': 100
270
}
271
confirmed_avatar = jira.confirm_user_avatar('john.doe', cropping)
272
```
273

274
### Group Management
275

276
Manage JIRA groups and group memberships.
277

278
```python { .api }
279
def groups(self, query: str = None, exclude: str = None, maxResults: int = 9999) -> list[dict]:
280
    """
281
    Get groups matching criteria.
282
    
283
    Parameters:
284
    - query: Group name search term
285
    - exclude: Group names to exclude from results
286
    - maxResults: Maximum number of results
287
    
288
    Returns:
289
    List of group dictionaries
290
    """
291

292
def group_members(self, group: str) -> list[User]:
293
    """
294
    Get members of a group.
295
    
296
    Parameters:
297
    - group: Group name
298
    
299
    Returns:
300
    List of User objects in the group
301
    """
302

303
def add_group(self, groupname: str) -> dict:
304
    """
305
    Create a new group.
306
    
307
    Parameters:
308
    - groupname: Name of the group to create
309
    
310
    Returns:
311
    Created group dictionary
312
    """
313

314
def remove_group(self, groupname: str) -> None:
315
    """
316
    Delete a group.
317
    
318
    Parameters:
319
    - groupname: Name of the group to delete
320
    """
321

322
def add_user_to_group(self, username: str, group: str) -> None:
323
    """
324
    Add a user to a group.
325
    
326
    Parameters:
327
    - username: Username to add
328
    - group: Group name
329
    """
330

331
def remove_user_from_group(self, username: str, groupname: str) -> None:
332
    """
333
    Remove a user from a group.
334
    
335
    Parameters:
336
    - username: Username to remove
337
    - groupname: Group name
338
    """
339
```
340

341
Usage examples:
342
```python
343
# Get all groups
344
groups = jira.groups()
345
for group in groups:
346
    print(f"Group: {group['name']}")
347

348
# Search for specific groups
349
dev_groups = jira.groups(query='developer')
350
for group in dev_groups:
351
    print(f"Dev group: {group['name']}")
352

353
# Get group members
354
members = jira.group_members('developers')
355
for member in members:
356
    print(f"Member: {member.displayName}")
357

358
# Create new group
359
new_group = jira.add_group('qa-team')
360
print(f"Created group: {new_group['name']}")
361

362
# Add user to group
363
jira.add_user_to_group('john.doe', 'developers')
364

365
# Remove user from group
366
jira.remove_user_from_group('jane.smith', 'old-team')
367

368
# Delete group
369
jira.remove_group('deprecated-group')
370
```
371

372
## User Properties
373

374
Common user properties available in User objects:
375

376
```python
377
user = jira.user('john.doe')
378

379
# Basic properties
380
print(f"Username: {user.name}")
381
print(f"Display Name: {user.displayName}")
382
print(f"Email: {user.emailAddress}")
383
print(f"Active: {user.active}")
384
print(f"Time Zone: {user.timeZone}")
385
print(f"Locale: {user.locale}")
386

387
# Avatar URLs
388
print(f"Avatar: {user.avatarUrls['48x48']}")
389

390
# With expanded groups
391
user = jira.user('john.doe', expand='groups')
392
groups = [group['name'] for group in user.groups['items']]
393
print(f"Groups: {', '.join(groups)}")
394
```
395

396
## Group Management Examples
397

398
Common group management patterns:
399

400
```python
401
# Bulk add users to group
402
usernames = ['user1', 'user2', 'user3']
403
group_name = 'project-team'
404

405
for username in usernames:
406
    try:
407
        jira.add_user_to_group(username, group_name)
408
        print(f"Added {username} to {group_name}")
409
    except Exception as e:
410
        print(f"Failed to add {username}: {e}")
411

412
# Move users from one group to another
413
old_group = 'old-team'
414
new_group = 'new-team'
415

416
old_members = jira.group_members(old_group)
417
for member in old_members:
418
    jira.add_user_to_group(member.name, new_group)
419
    jira.remove_user_from_group(member.name, old_group)
420
    print(f"Moved {member.displayName} from {old_group} to {new_group}")
421

422
# Find inactive users
423
all_users = jira.search_users('', includeInactive=True, maxResults=1000)
424
inactive_users = [user for user in all_users if not user.active]
425
print(f"Found {len(inactive_users)} inactive users")
426
```
427

428
## User Creation Best Practices
429

430
When creating users programmatically:
431

432
```python
433
# Create user with all recommended fields
434
new_user = jira.add_user(
435
    username='new.employee',
436
    email='new.employee@company.com',
437
    fullname='New Employee',
438
    notify=True,  # Send welcome email
439
    active=True,
440
    application_keys=['jira-software']  # Grant appropriate access
441
)
442

443
# Add to appropriate groups immediately
444
jira.add_user_to_group(new_user.name, 'employees')
445
jira.add_user_to_group(new_user.name, 'project-users')
446

447
print(f"Created and configured user: {new_user.displayName}")
448
```