0
# Service Management
1
2
Comprehensive Jira Service Management REST API client providing customer service, request management, and service desk operations. Enables automation of support workflows, customer communications, and service level agreement (SLA) management.
3
4
## Initialization
5
6
```python { .api }
7
class ServiceDesk(AtlassianRestAPI):
8
def __init__(self, url: str, username: str = None, password: str = None,
9
token: str = None, cloud: bool = None, **kwargs):
10
"""
11
Initialize Service Desk client.
12
13
Parameters:
14
- url (str): Base URL of Jira Service Management instance
15
- username (str, optional): Username for authentication
16
- password (str, optional): Password or API token
17
- token (str, optional): Bearer token for authentication
18
- cloud (bool, optional): True for Cloud, False for Server/DC
19
"""
20
```
21
22
## Capabilities
23
24
### Service Desk Operations
25
26
Core service desk management and configuration for organizing support services and request types.
27
28
```python { .api }
29
def get_service_desks(self) -> List[dict]:
30
"""
31
Get all service desks.
32
33
Returns:
34
List[dict]: Service desks with IDs, names, and project keys
35
"""
36
37
def get_service_desk_by_id(self, service_desk_id: str) -> T_resp_json:
38
"""
39
Get service desk details.
40
41
Parameters:
42
- service_desk_id: Service desk ID
43
44
Returns:
45
dict: Service desk information with request types and queues
46
"""
47
48
def get_service_desk_queues(self, service_desk_id: str,
49
include_count: bool = False,
50
start: int = 0, limit: int = 50) -> T_resp_json:
51
"""
52
Get service desk queues.
53
54
Parameters:
55
- service_desk_id: Service desk ID
56
- include_count: Include issue counts in queues
57
- start: Starting index
58
- limit: Maximum results
59
60
Returns:
61
dict: Queue list with filters and counts
62
"""
63
```
64
65
### Customer Management
66
67
Customer account creation, management, and relationship handling for service desk interactions.
68
69
```python { .api }
70
def create_customer(self, email: str, display_name: str) -> T_resp_json:
71
"""
72
Create customer account.
73
74
Parameters:
75
- email: Customer email address
76
- display_name: Customer display name
77
78
Returns:
79
dict: Created customer data with account ID
80
"""
81
82
def get_customer(self, customer_id: str) -> T_resp_json:
83
"""
84
Get customer details.
85
86
Parameters:
87
- customer_id: Customer account ID
88
89
Returns:
90
dict: Customer profile information
91
"""
92
93
def get_customers(self, service_desk_id: str, query: Optional[str] = None,
94
start: int = 0, limit: int = 50) -> T_resp_json:
95
"""
96
Get service desk customers.
97
98
Parameters:
99
- service_desk_id: Service desk ID
100
- query: Search query for customer filtering
101
- start: Starting index
102
- limit: Maximum results
103
104
Returns:
105
dict: Customers list with pagination
106
"""
107
108
def add_customers_to_service_desk(self, service_desk_id: str,
109
customer_ids: List[str]) -> T_resp_json:
110
"""
111
Add customers to service desk.
112
113
Parameters:
114
- service_desk_id: Service desk ID
115
- customer_ids: List of customer account IDs
116
117
Returns:
118
dict: Operation results
119
"""
120
121
def remove_customers_from_service_desk(self, service_desk_id: str,
122
customer_ids: List[str]) -> T_resp_json:
123
"""
124
Remove customers from service desk.
125
126
Parameters:
127
- service_desk_id: Service desk ID
128
- customer_ids: List of customer account IDs
129
130
Returns:
131
dict: Operation results
132
"""
133
```
134
135
### Customer Request Management
136
137
Comprehensive request lifecycle management including creation, updates, transitions, and resolution.
138
139
```python { .api }
140
def create_customer_request(self, service_desk_id: str, request_type_id: str,
141
summary: str, description: str = "",
142
customer_id: Optional[str] = None,
143
channel: str = "api") -> T_resp_json:
144
"""
145
Create customer request.
146
147
Parameters:
148
- service_desk_id: Service desk ID
149
- request_type_id: Request type ID
150
- summary: Request summary/title
151
- description: Detailed description
152
- customer_id: Customer account ID (uses current user if not specified)
153
- channel: Request channel ("api", "email", "portal")
154
155
Returns:
156
dict: Created request with issue key and URL
157
"""
158
159
def get_customer_request(self, issue_id_or_key: str,
160
expand: Optional[str] = None) -> T_resp_json:
161
"""
162
Get customer request details.
163
164
Parameters:
165
- issue_id_or_key: Request issue key or ID
166
- expand: Additional data to expand (participants, sla, status)
167
168
Returns:
169
dict: Request information with customer and service desk data
170
"""
171
172
def get_customer_requests(self, service_desk_id: str,
173
request_status: Optional[str] = None,
174
request_type_id: Optional[str] = None,
175
customer_id: Optional[str] = None,
176
start: int = 0, limit: int = 50) -> T_resp_json:
177
"""
178
Get customer requests with filtering.
179
180
Parameters:
181
- service_desk_id: Service desk ID
182
- request_status: Filter by status ("OPEN", "CLOSED", "ALL")
183
- request_type_id: Filter by request type
184
- customer_id: Filter by customer
185
- start: Starting index
186
- limit: Maximum results
187
188
Returns:
189
dict: Filtered requests list
190
"""
191
192
def get_my_customer_requests(self, service_desk_id: Optional[str] = None,
193
request_status: Optional[str] = None,
194
start: int = 0, limit: int = 50) -> T_resp_json:
195
"""
196
Get current user's customer requests.
197
198
Parameters:
199
- service_desk_id: Filter by service desk
200
- request_status: Filter by status
201
- start: Starting index
202
- limit: Maximum results
203
204
Returns:
205
dict: User's requests list
206
"""
207
208
def transition_customer_request(self, issue_id_or_key: str,
209
transition_id: str,
210
comment: Optional[str] = None) -> T_resp_json:
211
"""
212
Transition customer request status.
213
214
Parameters:
215
- issue_id_or_key: Request issue key or ID
216
- transition_id: Transition ID to execute
217
- comment: Optional comment for transition
218
219
Returns:
220
dict: Transition result
221
"""
222
```
223
224
### Request Types and Configuration
225
226
Management of service desk request types, fields, and approval processes.
227
228
```python { .api }
229
def get_request_types(self, service_desk_id: str,
230
group_id: Optional[int] = None,
231
expand: Optional[str] = None,
232
start: int = 0, limit: int = 50) -> T_resp_json:
233
"""
234
Get service desk request types.
235
236
Parameters:
237
- service_desk_id: Service desk ID
238
- group_id: Filter by request type group
239
- expand: Additional data to expand (field, practice)
240
- start: Starting index
241
- limit: Maximum results
242
243
Returns:
244
dict: Request types with fields and configurations
245
"""
246
247
def get_request_type_by_id(self, service_desk_id: str,
248
request_type_id: str) -> T_resp_json:
249
"""
250
Get request type details.
251
252
Parameters:
253
- service_desk_id: Service desk ID
254
- request_type_id: Request type ID
255
256
Returns:
257
dict: Request type configuration and fields
258
"""
259
260
def get_request_type_fields(self, service_desk_id: str,
261
request_type_id: str) -> T_resp_json:
262
"""
263
Get request type fields.
264
265
Parameters:
266
- service_desk_id: Service desk ID
267
- request_type_id: Request type ID
268
269
Returns:
270
dict: Field definitions and validation rules
271
"""
272
```
273
274
### Comments and Communication
275
276
Customer communication management including public and internal comments.
277
278
```python { .api }
279
def create_request_comment(self, issue_id_or_key: str, body: str,
280
public: bool = True,
281
internal: bool = False) -> T_resp_json:
282
"""
283
Add comment to customer request.
284
285
Parameters:
286
- issue_id_or_key: Request issue key or ID
287
- body: Comment text
288
- public: Visible to customers
289
- internal: Internal agent comment
290
291
Returns:
292
dict: Created comment data
293
"""
294
295
def get_request_comments(self, issue_id_or_key: str, public: bool = True,
296
internal: bool = True, start: int = 0,
297
limit: int = 50) -> T_resp_json:
298
"""
299
Get request comments.
300
301
Parameters:
302
- issue_id_or_key: Request issue key or ID
303
- public: Include public comments
304
- internal: Include internal comments
305
- start: Starting index
306
- limit: Maximum results
307
308
Returns:
309
dict: Comments list with visibility and authors
310
"""
311
312
def get_request_comment_by_id(self, issue_id_or_key: str,
313
comment_id: str,
314
expand: Optional[str] = None) -> T_resp_json:
315
"""
316
Get specific request comment.
317
318
Parameters:
319
- issue_id_or_key: Request issue key or ID
320
- comment_id: Comment ID
321
- expand: Additional data to expand
322
323
Returns:
324
dict: Comment details
325
"""
326
```
327
328
### Organizations
329
330
Customer organization management for grouping customers and managing permissions.
331
332
```python { .api }
333
def get_organisations(self, service_desk_id: Optional[str] = None,
334
start: int = 0, limit: int = 50) -> T_resp_json:
335
"""
336
Get organizations.
337
338
Parameters:
339
- service_desk_id: Filter by service desk
340
- start: Starting index
341
- limit: Maximum results
342
343
Returns:
344
dict: Organizations list
345
"""
346
347
def create_organization(self, name: str) -> T_resp_json:
348
"""
349
Create organization.
350
351
Parameters:
352
- name: Organization name
353
354
Returns:
355
dict: Created organization data
356
"""
357
358
def get_organization(self, organization_id: str) -> T_resp_json:
359
"""
360
Get organization details.
361
362
Parameters:
363
- organization_id: Organization ID
364
365
Returns:
366
dict: Organization information
367
"""
368
369
def add_customers_to_organization(self, organization_id: str,
370
customer_ids: List[str]) -> T_resp_json:
371
"""
372
Add customers to organization.
373
374
Parameters:
375
- organization_id: Organization ID
376
- customer_ids: List of customer account IDs
377
378
Returns:
379
dict: Operation results
380
"""
381
382
def remove_customers_from_organization(self, organization_id: str,
383
customer_ids: List[str]) -> T_resp_json:
384
"""
385
Remove customers from organization.
386
387
Parameters:
388
- organization_id: Organization ID
389
- customer_ids: List of customer account IDs
390
391
Returns:
392
dict: Operation results
393
"""
394
```
395
396
### SLA Management
397
398
Service Level Agreement monitoring, tracking, and reporting for performance management.
399
400
```python { .api }
401
def get_sla_information(self, issue_id_or_key: str) -> T_resp_json:
402
"""
403
Get SLA information for request.
404
405
Parameters:
406
- issue_id_or_key: Request issue key or ID
407
408
Returns:
409
dict: SLA metrics with time tracking and breach status
410
"""
411
412
def get_sla_information_by_request_key(self, request_key: str) -> T_resp_json:
413
"""
414
Get SLA information by request key.
415
416
Parameters:
417
- request_key: Request issue key
418
419
Returns:
420
dict: SLA status and time remaining
421
"""
422
```
423
424
### Attachments
425
426
File attachment management for customer requests and internal documentation.
427
428
```python { .api }
429
def create_attachment(self, issue_id_or_key: str, filename: str,
430
public: bool = True) -> T_resp_json:
431
"""
432
Add attachment to request.
433
434
Parameters:
435
- issue_id_or_key: Request issue key or ID
436
- filename: Path to file to attach
437
- public: Make attachment visible to customers
438
439
Returns:
440
dict: Attachment metadata
441
"""
442
443
def get_request_attachments(self, issue_id_or_key: str,
444
start: int = 0, limit: int = 50) -> T_resp_json:
445
"""
446
Get request attachments.
447
448
Parameters:
449
- issue_id_or_key: Request issue key or ID
450
- start: Starting index
451
- limit: Maximum results
452
453
Returns:
454
dict: Attachments list with download URLs
455
"""
456
```
457
458
## Usage Examples
459
460
### Service Desk Setup
461
462
```python
463
from atlassian import ServiceDesk
464
465
service_desk = ServiceDesk(
466
url="https://your-domain.atlassian.net",
467
username="email@example.com",
468
password="api-token"
469
)
470
471
# Get all service desks
472
service_desks = service_desk.get_service_desks()
473
474
# Get specific service desk
475
sd_info = service_desk.get_service_desk_by_id("1")
476
477
# Get request types
478
request_types = service_desk.get_request_types("1")
479
```
480
481
### Customer Management
482
483
```python
484
# Create customer
485
customer = service_desk.create_customer(
486
email="customer@example.com",
487
display_name="John Customer"
488
)
489
490
# Get customers
491
customers = service_desk.get_customers(
492
service_desk_id="1",
493
query="john"
494
)
495
496
# Add customers to service desk
497
service_desk.add_customers_to_service_desk(
498
service_desk_id="1",
499
customer_ids=[customer["accountId"]]
500
)
501
```
502
503
### Request Lifecycle
504
505
```python
506
# Create customer request
507
request = service_desk.create_customer_request(
508
service_desk_id="1",
509
request_type_id="101",
510
summary="Password reset request",
511
description="User cannot log into the system",
512
customer_id="customer-account-id"
513
)
514
515
# Get request details
516
request_details = service_desk.get_customer_request(
517
request["issueKey"],
518
expand="participants,sla,status"
519
)
520
521
# Add comment
522
comment = service_desk.create_request_comment(
523
request["issueKey"],
524
"We are investigating this issue",
525
public=True
526
)
527
528
# Transition request
529
service_desk.transition_customer_request(
530
request["issueKey"],
531
transition_id="11", # "In Progress"
532
comment="Working on password reset"
533
)
534
```
535
536
### Organization Management
537
538
```python
539
# Create organization
540
org = service_desk.create_organization("Acme Corporation")
541
542
# Add customers to organization
543
service_desk.add_customers_to_organization(
544
org["id"],
545
["customer-id-1", "customer-id-2"]
546
)
547
548
# Get organization details
549
org_details = service_desk.get_organization(org["id"])
550
```
551
552
### SLA Monitoring
553
554
```python
555
# Get SLA information
556
sla_info = service_desk.get_sla_information("DESK-123")
557
558
# Check SLA status
559
for sla in sla_info["values"]:
560
print(f"SLA: {sla['name']}")
561
print(f"Status: {sla['completedCycles'][0]['breached']}")
562
print(f"Time remaining: {sla['ongoingCycle']['remainingTime']}")
563
```
564
565
### Bulk Operations
566
567
```python
568
# Get all requests for analysis
569
all_requests = []
570
start = 0
571
while True:
572
batch = service_desk.get_customer_requests(
573
service_desk_id="1",
574
start=start,
575
limit=50
576
)
577
all_requests.extend(batch["values"])
578
579
if batch["isLastPage"]:
580
break
581
start += 50
582
583
# Process requests
584
for request in all_requests:
585
if request["requestStatus"]["status"] == "OPEN":
586
# Add follow-up comment to open requests
587
service_desk.create_request_comment(
588
request["issueKey"],
589
"This is an automated follow-up on your request.",
590
public=True
591
)
592
```
593
594
## Error Handling
595
596
```python
597
from atlassian.errors import ApiNotFoundError, ApiPermissionError
598
599
try:
600
request = service_desk.get_customer_request("INVALID-123")
601
except ApiNotFoundError:
602
print("Request not found")
603
except ApiPermissionError:
604
print("Access denied")
605
```
606
607
## Types
608
609
```python { .api }
610
from atlassian.typehints import T_id, T_resp_json
611
from typing import List, Dict, Optional
612
613
# Common parameter types
614
ServiceDeskId = str
615
RequestTypeId = str
616
CustomerId = str
617
RequestStatus = str # "OPEN", "CLOSED", "ALL"
618
RequestChannel = str # "api", "email", "portal"
619
```