tessl/pypi-atlassian-python-api
Python Atlassian REST API Wrapper providing comprehensive access to Jira, Confluence, Bitbucket, and other Atlassian products
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
service-management.mddocs/
Service Management
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.
Initialization
class ServiceDesk(AtlassianRestAPI):
def __init__(self, url: str, username: str = None, password: str = None,
token: str = None, cloud: bool = None, **kwargs):
"""
Initialize Service Desk client.
Parameters:
- url (str): Base URL of Jira Service Management instance
- username (str, optional): Username for authentication
- password (str, optional): Password or API token
- token (str, optional): Bearer token for authentication
- cloud (bool, optional): True for Cloud, False for Server/DC
"""Capabilities
Service Desk Operations
Core service desk management and configuration for organizing support services and request types.
def get_service_desks(self) -> List[dict]:
"""
Get all service desks.
Returns:
List[dict]: Service desks with IDs, names, and project keys
"""
def get_service_desk_by_id(self, service_desk_id: str) -> T_resp_json:
"""
Get service desk details.
Parameters:
- service_desk_id: Service desk ID
Returns:
dict: Service desk information with request types and queues
"""
def get_service_desk_queues(self, service_desk_id: str,
include_count: bool = False,
start: int = 0, limit: int = 50) -> T_resp_json:
"""
Get service desk queues.
Parameters:
- service_desk_id: Service desk ID
- include_count: Include issue counts in queues
- start: Starting index
- limit: Maximum results
Returns:
dict: Queue list with filters and counts
"""Customer Management
Customer account creation, management, and relationship handling for service desk interactions.
def create_customer(self, email: str, display_name: str) -> T_resp_json:
"""
Create customer account.
Parameters:
- email: Customer email address
- display_name: Customer display name
Returns:
dict: Created customer data with account ID
"""
def get_customer(self, customer_id: str) -> T_resp_json:
"""
Get customer details.
Parameters:
- customer_id: Customer account ID
Returns:
dict: Customer profile information
"""
def get_customers(self, service_desk_id: str, query: Optional[str] = None,
start: int = 0, limit: int = 50) -> T_resp_json:
"""
Get service desk customers.
Parameters:
- service_desk_id: Service desk ID
- query: Search query for customer filtering
- start: Starting index
- limit: Maximum results
Returns:
dict: Customers list with pagination
"""
def add_customers_to_service_desk(self, service_desk_id: str,
customer_ids: List[str]) -> T_resp_json:
"""
Add customers to service desk.
Parameters:
- service_desk_id: Service desk ID
- customer_ids: List of customer account IDs
Returns:
dict: Operation results
"""
def remove_customers_from_service_desk(self, service_desk_id: str,
customer_ids: List[str]) -> T_resp_json:
"""
Remove customers from service desk.
Parameters:
- service_desk_id: Service desk ID
- customer_ids: List of customer account IDs
Returns:
dict: Operation results
"""Customer Request Management
Comprehensive request lifecycle management including creation, updates, transitions, and resolution.
def create_customer_request(self, service_desk_id: str, request_type_id: str,
summary: str, description: str = "",
customer_id: Optional[str] = None,
channel: str = "api") -> T_resp_json:
"""
Create customer request.
Parameters:
- service_desk_id: Service desk ID
- request_type_id: Request type ID
- summary: Request summary/title
- description: Detailed description
- customer_id: Customer account ID (uses current user if not specified)
- channel: Request channel ("api", "email", "portal")
Returns:
dict: Created request with issue key and URL
"""
def get_customer_request(self, issue_id_or_key: str,
expand: Optional[str] = None) -> T_resp_json:
"""
Get customer request details.
Parameters:
- issue_id_or_key: Request issue key or ID
- expand: Additional data to expand (participants, sla, status)
Returns:
dict: Request information with customer and service desk data
"""
def get_customer_requests(self, service_desk_id: str,
request_status: Optional[str] = None,
request_type_id: Optional[str] = None,
customer_id: Optional[str] = None,
start: int = 0, limit: int = 50) -> T_resp_json:
"""
Get customer requests with filtering.
Parameters:
- service_desk_id: Service desk ID
- request_status: Filter by status ("OPEN", "CLOSED", "ALL")
- request_type_id: Filter by request type
- customer_id: Filter by customer
- start: Starting index
- limit: Maximum results
Returns:
dict: Filtered requests list
"""
def get_my_customer_requests(self, service_desk_id: Optional[str] = None,
request_status: Optional[str] = None,
start: int = 0, limit: int = 50) -> T_resp_json:
"""
Get current user's customer requests.
Parameters:
- service_desk_id: Filter by service desk
- request_status: Filter by status
- start: Starting index
- limit: Maximum results
Returns:
dict: User's requests list
"""
def transition_customer_request(self, issue_id_or_key: str,
transition_id: str,
comment: Optional[str] = None) -> T_resp_json:
"""
Transition customer request status.
Parameters:
- issue_id_or_key: Request issue key or ID
- transition_id: Transition ID to execute
- comment: Optional comment for transition
Returns:
dict: Transition result
"""Request Types and Configuration
Management of service desk request types, fields, and approval processes.
def get_request_types(self, service_desk_id: str,
group_id: Optional[int] = None,
expand: Optional[str] = None,
start: int = 0, limit: int = 50) -> T_resp_json:
"""
Get service desk request types.
Parameters:
- service_desk_id: Service desk ID
- group_id: Filter by request type group
- expand: Additional data to expand (field, practice)
- start: Starting index
- limit: Maximum results
Returns:
dict: Request types with fields and configurations
"""
def get_request_type_by_id(self, service_desk_id: str,
request_type_id: str) -> T_resp_json:
"""
Get request type details.
Parameters:
- service_desk_id: Service desk ID
- request_type_id: Request type ID
Returns:
dict: Request type configuration and fields
"""
def get_request_type_fields(self, service_desk_id: str,
request_type_id: str) -> T_resp_json:
"""
Get request type fields.
Parameters:
- service_desk_id: Service desk ID
- request_type_id: Request type ID
Returns:
dict: Field definitions and validation rules
"""Comments and Communication
Customer communication management including public and internal comments.
def create_request_comment(self, issue_id_or_key: str, body: str,
public: bool = True,
internal: bool = False) -> T_resp_json:
"""
Add comment to customer request.
Parameters:
- issue_id_or_key: Request issue key or ID
- body: Comment text
- public: Visible to customers
- internal: Internal agent comment
Returns:
dict: Created comment data
"""
def get_request_comments(self, issue_id_or_key: str, public: bool = True,
internal: bool = True, start: int = 0,
limit: int = 50) -> T_resp_json:
"""
Get request comments.
Parameters:
- issue_id_or_key: Request issue key or ID
- public: Include public comments
- internal: Include internal comments
- start: Starting index
- limit: Maximum results
Returns:
dict: Comments list with visibility and authors
"""
def get_request_comment_by_id(self, issue_id_or_key: str,
comment_id: str,
expand: Optional[str] = None) -> T_resp_json:
"""
Get specific request comment.
Parameters:
- issue_id_or_key: Request issue key or ID
- comment_id: Comment ID
- expand: Additional data to expand
Returns:
dict: Comment details
"""Organizations
Customer organization management for grouping customers and managing permissions.
def get_organisations(self, service_desk_id: Optional[str] = None,
start: int = 0, limit: int = 50) -> T_resp_json:
"""
Get organizations.
Parameters:
- service_desk_id: Filter by service desk
- start: Starting index
- limit: Maximum results
Returns:
dict: Organizations list
"""
def create_organization(self, name: str) -> T_resp_json:
"""
Create organization.
Parameters:
- name: Organization name
Returns:
dict: Created organization data
"""
def get_organization(self, organization_id: str) -> T_resp_json:
"""
Get organization details.
Parameters:
- organization_id: Organization ID
Returns:
dict: Organization information
"""
def add_customers_to_organization(self, organization_id: str,
customer_ids: List[str]) -> T_resp_json:
"""
Add customers to organization.
Parameters:
- organization_id: Organization ID
- customer_ids: List of customer account IDs
Returns:
dict: Operation results
"""
def remove_customers_from_organization(self, organization_id: str,
customer_ids: List[str]) -> T_resp_json:
"""
Remove customers from organization.
Parameters:
- organization_id: Organization ID
- customer_ids: List of customer account IDs
Returns:
dict: Operation results
"""SLA Management
Service Level Agreement monitoring, tracking, and reporting for performance management.
def get_sla_information(self, issue_id_or_key: str) -> T_resp_json:
"""
Get SLA information for request.
Parameters:
- issue_id_or_key: Request issue key or ID
Returns:
dict: SLA metrics with time tracking and breach status
"""
def get_sla_information_by_request_key(self, request_key: str) -> T_resp_json:
"""
Get SLA information by request key.
Parameters:
- request_key: Request issue key
Returns:
dict: SLA status and time remaining
"""Attachments
File attachment management for customer requests and internal documentation.
def create_attachment(self, issue_id_or_key: str, filename: str,
public: bool = True) -> T_resp_json:
"""
Add attachment to request.
Parameters:
- issue_id_or_key: Request issue key or ID
- filename: Path to file to attach
- public: Make attachment visible to customers
Returns:
dict: Attachment metadata
"""
def get_request_attachments(self, issue_id_or_key: str,
start: int = 0, limit: int = 50) -> T_resp_json:
"""
Get request attachments.
Parameters:
- issue_id_or_key: Request issue key or ID
- start: Starting index
- limit: Maximum results
Returns:
dict: Attachments list with download URLs
"""Usage Examples
Service Desk Setup
from atlassian import ServiceDesk
service_desk = ServiceDesk(
url="https://your-domain.atlassian.net",
username="email@example.com",
password="api-token"
)
# Get all service desks
service_desks = service_desk.get_service_desks()
# Get specific service desk
sd_info = service_desk.get_service_desk_by_id("1")
# Get request types
request_types = service_desk.get_request_types("1")Customer Management
# Create customer
customer = service_desk.create_customer(
email="customer@example.com",
display_name="John Customer"
)
# Get customers
customers = service_desk.get_customers(
service_desk_id="1",
query="john"
)
# Add customers to service desk
service_desk.add_customers_to_service_desk(
service_desk_id="1",
customer_ids=[customer["accountId"]]
)Request Lifecycle
# Create customer request
request = service_desk.create_customer_request(
service_desk_id="1",
request_type_id="101",
summary="Password reset request",
description="User cannot log into the system",
customer_id="customer-account-id"
)
# Get request details
request_details = service_desk.get_customer_request(
request["issueKey"],
expand="participants,sla,status"
)
# Add comment
comment = service_desk.create_request_comment(
request["issueKey"],
"We are investigating this issue",
public=True
)
# Transition request
service_desk.transition_customer_request(
request["issueKey"],
transition_id="11", # "In Progress"
comment="Working on password reset"
)Organization Management
# Create organization
org = service_desk.create_organization("Acme Corporation")
# Add customers to organization
service_desk.add_customers_to_organization(
org["id"],
["customer-id-1", "customer-id-2"]
)
# Get organization details
org_details = service_desk.get_organization(org["id"])SLA Monitoring
# Get SLA information
sla_info = service_desk.get_sla_information("DESK-123")
# Check SLA status
for sla in sla_info["values"]:
print(f"SLA: {sla['name']}")
print(f"Status: {sla['completedCycles'][0]['breached']}")
print(f"Time remaining: {sla['ongoingCycle']['remainingTime']}")Bulk Operations
# Get all requests for analysis
all_requests = []
start = 0
while True:
batch = service_desk.get_customer_requests(
service_desk_id="1",
start=start,
limit=50
)
all_requests.extend(batch["values"])
if batch["isLastPage"]:
break
start += 50
# Process requests
for request in all_requests:
if request["requestStatus"]["status"] == "OPEN":
# Add follow-up comment to open requests
service_desk.create_request_comment(
request["issueKey"],
"This is an automated follow-up on your request.",
public=True
)Error Handling
from atlassian.errors import ApiNotFoundError, ApiPermissionError
try:
request = service_desk.get_customer_request("INVALID-123")
except ApiNotFoundError:
print("Request not found")
except ApiPermissionError:
print("Access denied")Types
from atlassian.typehints import T_id, T_resp_json
from typing import List, Dict, Optional
# Common parameter types
ServiceDeskId = str
RequestTypeId = str
CustomerId = str
RequestStatus = str # "OPEN", "CLOSED", "ALL"
RequestChannel = str # "api", "email", "portal"Install with Tessl CLI
npx tessl i tessl/pypi-atlassian-python-api