0
# Administration & Utilities
1
2
Administrative functions, server information, utility operations, and system maintenance tasks. These operations typically require administrative permissions in JIRA.
3
4
## Capabilities
5
6
### Server Information
7
8
Operations for retrieving server and system information.
9
10
```python { .api }
11
def server_info(self) -> dict:
12
"""
13
Get JIRA server information including version and build details.
14
15
Returns:
16
Dictionary containing server information
17
"""
18
19
def myself(self) -> User:
20
"""
21
Get information about the current authenticated user.
22
23
Returns:
24
User object representing the current user
25
"""
26
27
def client_info(self) -> dict:
28
"""
29
Get client connection information.
30
31
Returns:
32
Dictionary containing client connection details
33
"""
34
35
def current_user(self) -> User:
36
"""
37
Get current user information (alias for myself).
38
39
Returns:
40
User object representing the current user
41
"""
42
```
43
44
Usage examples:
45
```python
46
# Get server information
47
server_info = jira.server_info()
48
print(f"JIRA Version: {server_info['version']}")
49
print(f"Build Number: {server_info['buildNumber']}")
50
print(f"Build Date: {server_info['buildDate']}")
51
print(f"Server ID: {server_info['serverId']}")
52
print(f"Server Title: {server_info['serverTitle']}")
53
54
# Get current user information
55
current_user = jira.myself()
56
print(f"Current User: {current_user.displayName}")
57
print(f"Username: {current_user.name}")
58
print(f"Email: {current_user.emailAddress}")
59
print(f"Time Zone: {current_user.timeZone}")
60
61
# Get client connection info
62
client_info = jira.client_info()
63
print(f"Client info: {client_info}")
64
```
65
66
### System Administration
67
68
Administrative operations for system maintenance and configuration.
69
70
```python { .api }
71
def reindex(self, force: bool = False, background: bool = True) -> dict:
72
"""
73
Trigger a re-index of JIRA.
74
75
Parameters:
76
- force: Force re-index even if one is already running
77
- background: Run re-index in background
78
79
Returns:
80
Re-index operation status dictionary
81
"""
82
83
def backup(self, filename: str = 'backup.zip', attachments: bool = False) -> dict:
84
"""
85
Create a backup of JIRA.
86
87
Parameters:
88
- filename: Backup file name
89
- attachments: Include attachments in backup
90
91
Returns:
92
Backup operation status dictionary
93
"""
94
95
def backup_progress(self) -> dict:
96
"""
97
Get backup progress information.
98
99
Returns:
100
Backup progress dictionary
101
"""
102
103
def backup_complete(self) -> bool:
104
"""
105
Check if backup is complete.
106
107
Returns:
108
Boolean indicating backup completion status
109
"""
110
111
def backup_download(self, filename: str = None) -> bytes:
112
"""
113
Download backup file.
114
115
Parameters:
116
- filename: Backup filename to download
117
118
Returns:
119
Backup file content as bytes
120
"""
121
```
122
123
Usage examples:
124
```python
125
# Trigger system re-index
126
reindex_status = jira.reindex(background=True)
127
print(f"Re-index started: {reindex_status}")
128
129
# Create system backup
130
backup_status = jira.backup(
131
filename='jira_backup_20240315.zip',
132
attachments=True
133
)
134
print(f"Backup started: {backup_status}")
135
136
# Monitor backup progress
137
import time
138
while not jira.backup_complete():
139
progress = jira.backup_progress()
140
print(f"Backup progress: {progress}")
141
time.sleep(10)
142
143
print("Backup completed successfully")
144
145
# Download backup file
146
backup_data = jira.backup_download('jira_backup_20240315.zip')
147
with open('local_backup.zip', 'wb') as f:
148
f.write(backup_data)
149
print("Backup downloaded successfully")
150
```
151
152
### Application Properties
153
154
Manage JIRA application properties and configuration settings.
155
156
```python { .api }
157
def application_properties(self, key: str = None) -> dict:
158
"""
159
Get application properties.
160
161
Parameters:
162
- key: Specific property key to retrieve
163
164
Returns:
165
Application properties dictionary
166
"""
167
168
def set_application_property(self, key: str, value: str) -> dict:
169
"""
170
Set an application property.
171
172
Parameters:
173
- key: Property key
174
- value: Property value
175
176
Returns:
177
Updated property dictionary
178
"""
179
180
def applicationlinks(self, cached: bool = True) -> list[dict]:
181
"""
182
Get application links.
183
184
Parameters:
185
- cached: Use cached results
186
187
Returns:
188
List of application link dictionaries
189
"""
190
```
191
192
Usage examples:
193
```python
194
# Get all application properties
195
properties = jira.application_properties()
196
for prop in properties:
197
print(f"{prop['id']}: {prop['value']}")
198
199
# Get specific property
200
base_url = jira.application_properties(key='jira.baseurl')
201
print(f"Base URL: {base_url}")
202
203
# Set application property
204
jira.set_application_property(
205
key='jira.title',
206
value='Company JIRA Instance'
207
)
208
209
# Get application links
210
links = jira.applicationlinks()
211
for link in links:
212
print(f"Application: {link['name']} -> {link['displayUrl']}")
213
```
214
215
### Dashboard Management
216
217
Operations for managing and retrieving dashboards.
218
219
```python { .api }
220
def dashboards(
221
self,
222
filter: str = None,
223
startAt: int = 0,
224
maxResults: int = 20
225
) -> list[dict]:
226
"""
227
Get list of dashboards.
228
229
Parameters:
230
- filter: Dashboard name filter
231
- startAt: Starting index for pagination
232
- maxResults: Maximum number of results
233
234
Returns:
235
List of dashboard dictionaries
236
"""
237
238
def dashboard(self, id: str) -> dict:
239
"""
240
Get dashboard by ID.
241
242
Parameters:
243
- id: Dashboard ID
244
245
Returns:
246
Dashboard dictionary
247
"""
248
```
249
250
Usage examples:
251
```python
252
# Get all dashboards
253
dashboards = jira.dashboards()
254
for dashboard in dashboards:
255
print(f"Dashboard: {dashboard['name']}")
256
print(f"Owner: {dashboard['owner']['displayName']}")
257
258
# Search dashboards by name
259
dev_dashboards = jira.dashboards(filter='Development')
260
261
# Get specific dashboard
262
dashboard = jira.dashboard('10000')
263
print(f"Dashboard: {dashboard['name']}")
264
print(f"Description: {dashboard['description']}")
265
```
266
267
### Filter Management
268
269
Operations for managing saved filters.
270
271
```python { .api }
272
def filter(self, id: str) -> dict:
273
"""
274
Get filter by ID.
275
276
Parameters:
277
- id: Filter ID
278
279
Returns:
280
Filter dictionary
281
"""
282
283
def favourite_filters(self) -> list[dict]:
284
"""
285
Get user's favorite filters.
286
287
Returns:
288
List of favorite filter dictionaries
289
"""
290
291
def create_filter(
292
self,
293
name: str = None,
294
description: str = None,
295
jql: str = None,
296
favourite: bool = None
297
) -> dict:
298
"""
299
Create a new filter.
300
301
Parameters:
302
- name: Filter name
303
- description: Filter description
304
- jql: JQL query string
305
- favourite: Mark as favorite
306
307
Returns:
308
Created filter dictionary
309
"""
310
311
def update_filter(
312
self,
313
filter_id: str,
314
name: str = None,
315
description: str = None,
316
jql: str = None,
317
favourite: bool = None
318
) -> dict:
319
"""
320
Update an existing filter.
321
322
Parameters:
323
- filter_id: Filter ID to update
324
- name: New filter name
325
- description: New filter description
326
- jql: New JQL query string
327
- favourite: Mark as favorite
328
329
Returns:
330
Updated filter dictionary
331
"""
332
```
333
334
Usage examples:
335
```python
336
# Get favorite filters
337
favorites = jira.favourite_filters()
338
for filter in favorites:
339
print(f"Favorite: {filter['name']} - {filter['jql']}")
340
341
# Create new filter
342
new_filter = jira.create_filter(
343
name='My Open Issues',
344
description='Issues assigned to me that are not resolved',
345
jql='assignee = currentUser() AND resolution = Unresolved',
346
favourite=True
347
)
348
print(f"Created filter: {new_filter['name']}")
349
350
# Update filter
351
updated_filter = jira.update_filter(
352
filter_id=new_filter['id'],
353
name='My Active Issues',
354
jql='assignee = currentUser() AND status in ("To Do", "In Progress")'
355
)
356
357
# Get specific filter
358
filter = jira.filter(new_filter['id'])
359
print(f"Filter JQL: {filter['jql']}")
360
```
361
362
### Utility Operations
363
364
Various utility functions for system operations and data management.
365
366
```python { .api }
367
def find(self, resource_format: str, ids: list[str] = None) -> dict:
368
"""
369
Find generic resource by format and IDs.
370
371
Parameters:
372
- resource_format: Resource format string
373
- ids: List of resource IDs
374
375
Returns:
376
Resource dictionary
377
"""
378
379
def async_do(self, size: int = 10) -> dict:
380
"""
381
Execute queued asynchronous operations.
382
383
Parameters:
384
- size: Batch size for async operations
385
386
Returns:
387
Async operation results dictionary
388
"""
389
390
def get_igrid(self, issueid: str, customfield: str, schemeid: str) -> dict:
391
"""
392
Get iDalko Grid data (specialized function for iDalko Grid plugin).
393
394
Parameters:
395
- issueid: Issue ID
396
- customfield: Custom field ID
397
- schemeid: Scheme ID
398
399
Returns:
400
Grid data dictionary
401
"""
402
```
403
404
Usage examples:
405
```python
406
# Execute async operations
407
async_results = jira.async_do(size=20)
408
print(f"Async operations completed: {async_results}")
409
410
# Find resources by format
411
resources = jira.find('issue/{0}', ids=['PROJ-123', 'PROJ-124'])
412
print(f"Found resources: {resources}")
413
414
# Get specialized plugin data (if iDalko Grid is installed)
415
try:
416
grid_data = jira.get_igrid('PROJ-123', 'customfield_10001', 'scheme1')
417
print(f"Grid data: {grid_data}")
418
except Exception as e:
419
print(f"iDalko Grid not available: {e}")
420
```
421
422
## System Monitoring
423
424
Monitor system health and performance:
425
426
```python
427
def system_health_check():
428
"""Perform comprehensive system health check."""
429
430
print("=== JIRA System Health Check ===")
431
432
# Server information
433
server_info = jira.server_info()
434
print(f"JIRA Version: {server_info['version']}")
435
print(f"Build: {server_info['buildNumber']}")
436
437
# Current user info
438
current_user = jira.myself()
439
print(f"Connected as: {current_user.displayName}")
440
441
# Test basic operations
442
try:
443
# Test project access
444
projects = jira.projects()
445
print(f"Accessible projects: {len(projects)}")
446
447
# Test issue search
448
recent_issues = jira.search_issues(
449
'created >= -7d',
450
maxResults=10
451
)
452
print(f"Recent issues (7 days): {len(recent_issues)}")
453
454
# Test user search
455
users = jira.search_users('a', maxResults=5)
456
print(f"User search working: {len(users)} users found")
457
458
except Exception as e:
459
print(f"Health check failed: {e}")
460
461
print("=== Health Check Complete ===")
462
463
# Run health check
464
system_health_check()
465
```
466
467
## Batch Operations
468
469
Perform administrative tasks in batch:
470
471
```python
472
def cleanup_old_filters(days_old=365):
473
"""Clean up old unused filters."""
474
475
from datetime import datetime, timedelta
476
477
# This is a conceptual example - actual implementation would
478
# require additional API endpoints for filter usage data
479
480
favorites = jira.favourite_filters()
481
print(f"Found {len(favorites)} favorite filters")
482
483
# In practice, you would need to check filter usage dates
484
# and remove filters that haven't been used recently
485
486
old_filters = []
487
for filter in favorites:
488
# Check if filter is old and unused
489
# This would require additional logic to determine usage
490
pass
491
492
print(f"Would clean up {len(old_filters)} old filters")
493
494
def backup_and_cleanup():
495
"""Automated backup and cleanup routine."""
496
497
# Create backup
498
backup_filename = f"jira_backup_{datetime.now().strftime('%Y%m%d')}.zip"
499
500
print("Starting backup...")
501
backup_status = jira.backup(filename=backup_filename, attachments=False)
502
503
# Wait for backup completion
504
while not jira.backup_complete():
505
time.sleep(30)
506
progress = jira.backup_progress()
507
print(f"Backup progress: {progress}")
508
509
print("Backup completed")
510
511
# Perform maintenance tasks
512
print("Starting re-index...")
513
jira.reindex(background=True)
514
515
print("Maintenance routine completed")
516
517
# Run automated maintenance (uncomment to execute)
518
# backup_and_cleanup()
519
```
520
521
## Configuration Management
522
523
Manage JIRA configuration programmatically:
524
525
```python
526
def export_configuration():
527
"""Export key JIRA configuration settings."""
528
529
config = {}
530
531
# Application properties
532
properties = jira.application_properties()
533
config['properties'] = {prop['id']: prop['value'] for prop in properties}
534
535
# Projects
536
projects = jira.projects()
537
config['projects'] = [
538
{
539
'key': p.key,
540
'name': p.name,
541
'lead': p.lead.name if p.lead else None
542
}
543
for p in projects
544
]
545
546
# Issue types
547
issue_types = jira.issue_types()
548
config['issue_types'] = [
549
{'name': it['name'], 'description': it['description']}
550
for it in issue_types
551
]
552
553
# Export to file
554
import json
555
with open('jira_config.json', 'w') as f:
556
json.dump(config, f, indent=2)
557
558
print("Configuration exported to jira_config.json")
559
return config
560
561
# Export current configuration
562
# config = export_configuration()
563
```