atlassian-modules 1.2.1

Modules for interacting with Atlassian cloud products.

Important notes

• What happened to the older releases?
  • On November 11, 2024, while working on potential improvements for older releases, I unintentionally deleted the entire repository. This was due to a mistake made during the deletion of the older releases, which led to the module being absent from Python for approximately 30 minutes.
• How did I recover it?
  • To recover from this incident, I incremented the version to 6.0.2 and re-released the entire module back to the public.
• What if you have older versions in place?
  • I recommend upgrading to the latest version, which is now 1.0.2. This version includes all bug fixes and improvements with separate functions for each functionality. This design helps modify only the particular function without requiring the deletion of any releases in the future.

The GitHub repository is now public at github.com/python-codelover/atlassian-modules for all of us to improve this module together. Please feel free to contact me at the email address provided in my profile, and I will quickly reach out to you. Thank you for understanding.

---

---

The best way to interact with Atlassian Jira/Confluence API.

Note: This module is useful for the Atlassian Cloud
Your URL should look like this https://domain.atlassian.net

Prerequisites

from atlassian_modules import JiraHelper # for Jira
from atlassian_modules import WikiHelper # for Wiki

Getting Started

Connectivity to Atlassian Jira

To initialize a connection to Jira, instantiate the JiraHelper class with your Jira URL, email, and API token:

jira_helper = JiraHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)
wiki_helper = WikiHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

---

---

Atlassian Jira

---

---

1. Create a Jira Ticket

• You can create a new Jira ticket using the create_ticket method:

jira_helper = JiraHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

ticket_url = jira_helper.create_ticket("PRJ", "Issue Summary", "Detailed issue description.", "Bug")
if ticket_url:
    print(f"Ticket created: {ticket_url}")
else:
    print("Failed to create ticket.")

Parameters:

• project_key (str): Key of the project where the new ticket will be created. This is usually a short, capitalized identifier for a project in JIRA.
• summary (str): Summary of the new ticket. This is a concise overview of the issue or task.
• description (str): Detailed description of the new ticket. This field is used to provide all necessary details about the issue or task.
• issue_type (str): Type of the issue (e.g., Bug, Task, Story). This specifies what kind of ticket is being created.

Output:

• The function outputs informational messages about the process of creating a ticket, including preparing issue data, sending a request to create the ticket, and the result of that request.

Return:

• URL of the created ticket (str): If the ticket creation is successful, the function returns the URL to access the newly created ticket directly.
• False: If the ticket creation fails (for example, due to incorrect input parameters or server errors), the function returns False.

---

2. Create a custom Jira Ticket

• You can create a new custom Jira ticket using the create_custom_ticket method:

jira_helper = JiraHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

# Define additional fields if necessary
additional_fields = {
    "customfield_12345": "Custom value",
    "labels": ["label1", "label2"]
}

ticket_url = jira_helper.create_custom_ticket("PRJ", "Issue Summary", "Detailed issue description.", "Bug", additional_fields)
if ticket_url:
    print(f"Ticket created: {ticket_url}")
else:
    print("Failed to create ticket.")

Parameters:

• project_key (str): The key of the project where the new ticket will be created. This is typically a short, capitalized identifier specific to a project in Jira.
• summary (str): A concise overview of the issue or task that the new ticket will represent.
• description (str): A detailed description of the issue or task, providing all necessary details for understanding and addressing it.
• issue_type (str): Specifies the type of issue being created (e.g., Bug, Task, Story), determining how the issue is categorized within Jira.
• additional_fields (dict, optional): A dictionary of additional fields that are required for ticket creation. This parameter allows for the inclusion of project-specific or issue-specific information that is not covered by the standard fields.

Output:

• The function provides informational messages throughout the process of creating a ticket.
• These messages include details on preparing the issue data, sending a request to create the ticket, and the outcome of that request.

Return:

• URL of the created ticket (str): If the ticket creation is successful, the function returns the URL to access the newly created ticket directly. This allows for immediate navigation to the ticket for review or further action.
• False: If the ticket creation process fails, whether due to incorrect input parameters, server errors, or issues with the additional fields, the function returns False. This indicates that the ticket was not created and provides an opportunity to address any issues before retrying.

---

3. Update the Jira ticket with inbuilt and custom fields

• You can update any custom field of Jira ticket using the update_ticket_with_fields method:

jira_helper = JiraHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

# Define the additional fields you want to update
additional_fields = {
    "customfield_12345": "New custom value",
    "labels": ["newlabel1", "newlabel2"]
}

ticket_id = "PRJ-123"  # Example ticket ID to be updated

update_success = jira_helper.update_ticket_with_fields(ticket_id, additional_fields)
if update_success:
    print(f"Ticket {ticket_id} updated successfully.")
else:
    print(f"Failed to update ticket {ticket_id}.")

Parameters:

• ticket_id (str): ID (also known as the key) of the ticket to be updated. This identifier is typically a combination of the project key and a sequence number, like PRJ-123.
• additional_fields (dict): A dictionary of fields to update the ticket with. This parameter allows specifying values for any standard or custom field in the ticket that supports updates.

Output:

• The function prints messages about the process of updating the ticket, including preparing the update data, making the request to update the ticket, and the result of that request.

Return:

• True if the update was successful. This indicates that the server accepted the update request and applied the changes to the ticket.
• False otherwise. If the ticket update fails (for example, due to incorrect ticket ID, fields that cannot be updated, or server errors), the function returns False, and additional error information is printed to help diagnose the issue.

---

4. Delete a Jira Ticket

• To delete a ticket, use the delete_ticket method:

jira_helper = JiraHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

ticket_key = "PRJ-123"  # Example ticket key
if jira_helper.delete_ticket(ticket_key):
    print("Ticket deleted successfully.")
else:
    print("Failed to delete ticket or ticket does not exist.")

Parameters:

• ticket_key (str): The unique identifier for the ticket you wish to delete. This key is usually a combination of the project key and a number (e.g., "PRJ-123").

Output:

• The function itself does not print any output, but it performs a DELETE request to the JIRA REST API to delete the specified ticket.

Return:

• True: If the ticket is successfully deleted. This is indicated by a 204 HTTP status code from the JIRA API, meaning "No Content" but signifying successful deletion.
• False: If the deletion fails, which can occur if the ticket does not exist or if there's an issue with the API request (e.g., permissions, invalid ticket key). This is communicated by returning False.

---

5. Get Transition ID

jira_helper = JiraHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

ticket_key = "PRJ-123"  # Example ticket key
transition_name = "Close"
transition_id = jira_helper.get_transitions(ticket_key, transition_name)
if transition_id:
    print(f"Transition ID for '{transition_name}' is {transition_id}.")
else:
    print(f"Transition '{transition_name}' not found for ticket {ticket_key} or failed to fetch transitions.")

Parameters:

• ticket_key (str): The key of the ticket for which transitions are being fetched. This is typically a unique identifier like "PRJ-123".
• transition_to (str): The name of the desired transition to look for. This is the human-readable name of the transition (e.g., "Close", "Resolve").

Output:

• The function prints messages about the process of fetching transitions for the ticket, including whether the transitions were successfully fetched, if the specific transition was found, and any errors encountered during the request.

Return:

• Transition ID (str): If the specified transition is found for the given ticket, the function returns the transition's ID, which can be used for further actions like transitioning the ticket to another status.
• False: If the specified transition is not found for the ticket, or if there is any failure in fetching transitions (e.g., due to an invalid ticket key, network issues, or server errors), the function returns False.

---

6. Transition a Jira Ticket

• To transition a ticket to a different status, use the transition_ticket method:

jira_helper = JiraHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

ticket_key = "PRJ-123"  # Example ticket key
transition_input = "Done"  # Can be a transition name like 'Done' or an ID like '31'
if jira_helper.transition_ticket(ticket_key, transition_input):
    print("Ticket transitioned successfully.")
else:
    print("Failed to transition ticket.")

Parameters:

• ticket_key (str): The key of the ticket you want to transition. This is a unique identifier for the ticket within JIRA.
• transition_input (str or int): The desired transition for the ticket. This can be specified as either the name of the transition (e.g., "Done") or the transition ID (e.g., 31).

Output:

• The function outputs informational messages regarding the transition process, including attempts to find the transition ID if a name is provided, and the result of the transition attempt.

Return:

• True: If the ticket transition is successful. This is indicated by a 204 HTTP status code, which means "No Content" but signifies that the operation completed successfully.
• False: If the ticket transition fails. This could be due to various reasons, such as an invalid ticket key, an unrecognized transition name or ID, or a failure in the HTTP request itself.

---

7. Check if a Jira Ticket exists

• To check if a ticket exists, use the if_ticket_exist method:

jira_helper = JiraHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

ticket_key = "PRJ-123"  # Example ticket key
if jira_helper.if_ticket_exist(ticket_key):
    print("The ticket exists.")
else:
    print("The ticket does not exist.")

Parameters:

• ticket_key (str): The key of the ticket you want to check. This is a unique identifier for the ticket within JIRA.

Output:

• The function outputs messages that indicate whether it is checking for the existence of the specified ticket and the result of that check.

Return:

• True: If the ticket exists. This is confirmed by a 200 HTTP status code, indicating that the ticket was found.
• False: If the ticket does not exist or if there was an error in checking. A 404 HTTP status code indicates the ticket does not exist. Other status codes indicate a failure in the request to check the ticket.

---

8. Comment on a Jira ticket

• To comment on the ticket, use the comment_ticket method:

jira_helper = JiraHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

ticket_key = "PRJ-123"  # Example ticket key
comment_text = "This is an example comment."
comment_url = jira_helper.comment_ticket(ticket_key, comment_text)
if comment_url:
    print(f"Comment added successfully: {comment_url}")
else:
    print("Failed to add comment to the ticket.")

Parameters:

• ticket_key (str): The key of the ticket to which you want to add a comment. This is a unique identifier for the ticket within JIRA.
• comment_text (str): The text of the comment you wish to add to the ticket.

Output:

• The function outputs messages that indicate the process of adding a comment to the specified ticket, including checking if the ticket exists and attempting to add the comment.

Return:

• URL of the created comment (str): If adding the comment is successful, the function returns the URL to access the newly created comment directly. This is indicated by a 201 HTTP status code, meaning "Created".
• False: If adding the comment fails. This could be because the ticket does not exist, the comment text is invalid, or there was an error in the request itself. In such cases, the function returns False.

---

9. Pass the JQL and get the ticket array

• To query tickets using JQL, use the jql_ticket method:

jira_helper = JiraHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

jql_query = "project = PRJ AND status = 'Open'"
max_results = 100  # Optional
ticket_keys = jira_helper.jql_ticket(jql_query, max_results)
if ticket_keys:
    print(f"Found tickets: {', '.join(ticket_keys)}")
else:
    print("Failed to retrieve tickets based on the JQL query.")

Parameters:

• jql_query (str): The Jira Query Language query string used to retrieve tickets. This string specifies the criteria that the returned tickets must meet.
• max_results (int, optional): The maximum number of tickets to retrieve. If not specified, the method attempts to fetch all tickets that match the query.

Output:

• The function outputs messages that detail the execution of the JQL query, including the number of tickets fetched in each batch and the total number of requested tickets.

Return:

• List of ticket keys (list): If successful, the function returns a list containing the keys of the tickets that match the JQL query criteria. Each key is a unique identifier for a ticket within JIRA.
• False: If the retrieval fails. This could be due to an issue with the JQL query, a problem with the request to JIRA, or if the JIRA server returns an unexpected status code. In such cases, the function returns False.

---

10. Get the subject of a Jira Ticket

• To get the subject of a Jira ticket, use the get_ticket_subject method:

jira_helper = JiraHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

ticket_key = "PRJ-123"  # Example ticket key
subject = jira_helper.get_ticket_subject(ticket_key)
if subject:
    print(f"Subject of the ticket: {subject}")
else:
    print("Failed to retrieve the subject of the ticket.")

Parameters:

• ticket_key (str): The key of the ticket for which you want to retrieve the subject. This is a unique identifier for the ticket within JIRA.

Output:

• The function prints the subject of the specified ticket if it is successfully retrieved.

Return:

• Subject of the ticket (str): If the subject is successfully retrieved, the function returns the subject of the ticket.
• None: If the retrieval fails, the function returns None.

---

11. Attach a file to a Jira ticket

• To attach a file to a JIRA ticket, use the attach_file_to_ticket method:

jira_helper = JiraHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

ticket_id = "PRJ-123"
file_path = "/path/to/your/file.txt"

success = jira_helper.attach_file_to_ticket(ticket_id, file_path)
if success:
    print("File attached successfully!")
else:
    print("Failed to attach file.")

Parameters:

• ticket_id (str): The ID of the ticket to which the file will be attached.
• file_path (str): The path to the file that will be attached.

Return:

• True: If the file was successfully attached.
• False: If the attachment failed (e.g., file not found, network error, or permission issue).

---

12. Get full ticket details

• To get comprehensive details of a ticket, use the get_ticket_details method:

jira_helper = JiraHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

ticket_key = "PRJ-123"
details = jira_helper.get_ticket_details(ticket_key)
if details:
    print(f"Status: {details['status']}")
    print(f"Assignee: {details['assignee']}")
    print(f"Priority: {details['priority']}")
    print(f"Labels: {details['labels']}")
else:
    print("Failed to fetch ticket details.")

Parameters:

• ticket_key (str): Key of the ticket (e.g., 'PRJ-123').

Return:

• Dictionary with keys: key, summary, status, assignee, reporter, priority, labels, issue_type, created, updated, project, url.
• None: If the retrieval fails.

---

13. Get ticket status

• To quickly check the current status of a ticket, use the get_ticket_status method:

jira_helper = JiraHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

ticket_key = "PRJ-123"
status = jira_helper.get_ticket_status(ticket_key)
if status:
    print(f"Current status: {status}")
else:
    print("Failed to get ticket status.")

Parameters:

• ticket_key (str): Key of the ticket (e.g., 'PRJ-123').

Return:

• Status name (str): The current status of the ticket (e.g., 'In Progress', 'Done').
• None: If the retrieval fails.

---

14. Assign a ticket

• To assign a ticket to a user, use the assign_ticket method:

jira_helper = JiraHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

ticket_key = "PRJ-123"
account_id = "5b10ac8d82e05b22cc7d4ef5"  # Atlassian account ID of the assignee

if jira_helper.assign_ticket(ticket_key, account_id):
    print("Ticket assigned successfully.")
else:
    print("Failed to assign ticket.")

Parameters:

• ticket_key (str): Key of the ticket to assign.
• account_id (str): The Atlassian account ID of the user to assign. Use None to unassign.

Return:

• True: If the assignment was successful.
• False: If the assignment failed.

---

15. Add labels to a ticket

• To add labels to a ticket, use the add_label method:

jira_helper = JiraHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

ticket_key = "PRJ-123"
labels = ["urgent", "backend", "sprint-5"]

if jira_helper.add_label(ticket_key, labels):
    print("Labels added successfully.")
else:
    print("Failed to add labels.")

Parameters:

• ticket_key (str): Key of the ticket.
• labels (list or str): A list of label strings to add, or a single label string.

Return:

• True: If labels were added successfully.
• False: If the operation failed.

---

16. Link two tickets

• To create a link between two tickets, use the link_tickets method:

jira_helper = JiraHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

if jira_helper.link_tickets("PRJ-100", "PRJ-200", "Blocks"):
    print("Tickets linked successfully.")
else:
    print("Failed to link tickets.")

Parameters:

• inward_key (str): Key of the inward ticket.
• outward_key (str): Key of the outward ticket.
• link_type (str): Type of link (e.g., 'Blocks', 'Relates', 'Duplicate', 'Cloners').

Return:

• True: If the link was created successfully.
• False: If the operation failed.

---

17. Bulk transition tickets

• To transition multiple tickets at once, use the bulk_transition method:

jira_helper = JiraHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

ticket_keys = ["PRJ-101", "PRJ-102", "PRJ-103"]
results = jira_helper.bulk_transition(ticket_keys, "Done")
for ticket, success in results.items():
    print(f"{ticket}: {'✓' if success else '✗'}")

Parameters:

• ticket_keys (list): List of ticket keys to transition.
• transition_input (str or int): Desired transition name or ID.

Return:

• Dictionary: Keys are ticket keys, values are True/False indicating success or failure for each ticket.

---

---

Atlassian Wiki

---

---

1. Creating a wiki page

• To create a wiki page, use the create_wiki_page method:

wiki_helper = WikiHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

space_key = "DEV"
title = "API Documentation"
content = "<p>This is the API documentation for our project.</p>"
parent_page_id = 123456  # Optional
page_url = wiki_helper.create_wiki_page(space_key, title, content, parent_page_id)
if page_url:
    print(f"Wiki page created successfully: {page_url}")
else:
    print("Failed to create wiki page.")

Parameters:

• space_key (str): The key of the Confluence space where the new page will be created. Confluence spaces are containers for related content.
• title (str): The title of the new page. Titles are used to identify pages within Confluence.
• content (str): The content of the new page. This is usually HTML or Confluence storage format markup that defines the page's body.
• parent_page_id (int, optional): The ID of a parent page if the new page is to be a child page. This parameter is optional; if not provided, the page will be created at the root of the specified space.

Output:

• The function outputs messages detailing the process of creating the Confluence page, including the attempt to create the page and the result of that attempt.

Return:

• URL of the created Confluence page (str): If the page creation is successful, the function returns the URL to access the newly created page.
• None: If the page creation fails due to invalid input parameters, permissions problems, or server errors.

---

2. Duplicate a wiki page

• To duplicate a wiki page, use the duplicate_wiki_page method:

wiki_helper = WikiHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

source_page_id = "12345"  # Example source page ID
target_space_key = "TGT"  # Example target space key
target_title = "Duplicated Page Title"  # New title for the duplicated page
target_parent_page_id = "67890"  # Optional parent page ID for the new page

duplicated_page_url = wiki_helper.duplicate_wiki_page(source_page_id, target_space_key, target_title, target_parent_page_id)
if duplicated_page_url:
    print(f"Duplicated page successfully. View at: {duplicated_page_url}")
else:
    print("Failed to duplicate the page.")

Parameters:

• source_page_id (str): ID of the Confluence page you wish to duplicate.
• target_space_key (str): Key of the Confluence space where the duplicated page will reside.
• target_title (str): Title of the duplicated page.
• target_parent_page_id (str, optional): ID of the parent page if the duplicated page is to be a child within the hierarchy. If not specified, the page will be created at the top level of the specified space.

Output:

• The method outputs messages detailing the process of duplicating a page, including fetching content from the source page and creating a new page with this content in the target space.

Return:

• URL of the duplicated Confluence page (str): If the duplication is successful, the method returns the URL to access the newly created duplicated page.
• None: If the duplication fails at any point (e.g., retrieving content from the source page, creating the new page), the method returns None.

---

3. Create a wiki page from template

• To create a wiki page from a template, use the create_page_from_template method:

wiki_helper = WikiHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

template_id = "12345"  # Example template ID
space_key = "TGT"  # Example space key
title = "New Page from Template"  # Title for the new page
parent_page_id = "67890"  # Optional parent page ID

created_page = wiki_helper.create_page_from_template(template_id, space_key, title, parent_page_id)
if created_page:
    print(f"New page created successfully.")
else:
    print("Failed to create the new page from template.")

Parameters:

• template_id (str): ID of the Confluence template you wish to use for creating the new page.
• space_key (str): Key of the Confluence space where the new page will be created.
• title (str): Title of the new page.
• parent_page_id (str, optional): ID of the parent page if the new page is to be a child within the space hierarchy. If not specified, the page will be created at the top level of the specified space.

Output:

• The function outputs messages that detail the process of creating a new page from a template, including checking for duplicate titles in the target space, retrieving content from the specified template, and the creation of the new page.

Return:

• Page object (dict): If the page creation is successful, the function returns the Confluence page object (JSON response).
• None: If the page creation fails due to template retrieval failure, duplicate title, or any error in the creation process.

---

4. Move wiki page from one location to another

• To move a wiki page from one location to another without changing its title, use the move_wiki_page method:

wiki_helper = WikiHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

page_id = "12345"  # Example page ID to be moved
target_space_key = "NEWSPACE"  # Target space key
target_position = "append"  # Position relative to the parent page ('append', 'before', 'after')
target_parent_page_id = "67890"  # Optional new parent page ID

moved_page = wiki_helper.move_wiki_page(page_id, target_space_key, target_position, target_parent_page_id)
if moved_page:
    print(f"Page moved successfully.")
else:
    print("Failed to move the page.")

Parameters:

• page_id (str): ID of the Confluence page you wish to move.
• target_space_key (str): Key of the Confluence space where the page will be moved to.
• target_position (str): Position to place the moved page relative to the parent page. Default is 'append', but 'before' and 'after' are also valid options.
• target_parent_page_id (str, optional): ID of the parent page if the moved page is to be nested under another page. If not specified, the page will be moved to the top level of the target space.

Output:

• The function outputs messages detailing the process of moving the page, including retrieving the current page title, preparing the move operation, and executing the move.

Return:

• Page object (dict): If the move operation is successful, the function returns the Confluence page object (JSON response).
• None: If the move operation fails due to an error retrieving page details or executing the move.

---

5. Check if wiki page exists

• To check if a wiki page exists, use the wiki_page_exists method:

wiki_helper = WikiHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

title = "Example Page Title"  # Title of the Confluence wiki page to check
space_key = "EX"  # Key of the Confluence space

if wiki_helper.wiki_page_exists(title, space_key):
    print(f"The page '{title}' exists in space '{space_key}'.")
else:
    print(f"The page '{title}' does not exist in space '{space_key}'.")

Parameters:

• title (str): Title of the Confluence wiki page to check for existence.
• space_key (str): Key of the Confluence space where the page might reside.

Output:

• The function outputs a message indicating the start of the check process and then reports whether the specified page exists in the given space based on the title.

Return:

• True: If the page exists. This is determined by the presence of results matching the specified title in the specified space.
• False: If the page does not exist or if there was an error during the request.

---

6. Retrieve all child pages

• Recursively retrieve all descendant pages of a given parent page ID.

wiki_helper = WikiHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

parent_id = "12345"  # Example parent page ID
child_pages = wiki_helper.get_child_pages_recursive(parent_id)
if child_pages:
    print("Child pages found:")
    for page in child_pages:
        print(f"Title: {page['title']}, ID: {page['id']}")
else:
    print("No child pages found or failed to fetch.")

Parameters:

• parent_id (str): ID of the parent Confluence wiki page from which to start retrieving descendant pages.

Output:

• The method recursively fetches and lists all child pages beneath a given parent page. It handles pagination automatically to ensure all children are returned (not just the first 25).

Return:

• List of child pages (list): Returns a list of page objects, each containing the title and id of each descendant page found.
• Empty list []: If no child pages are found or if the input is invalid.

---

7. Get wiki page ID

• Retrieve the ID of a Confluence wiki page by its title.

wiki_helper = WikiHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

title = "Example Page"  # Title of the Confluence wiki page to search for
space_key = "EX"  # Key of the Confluence space

page_id = wiki_helper.get_page_id(title, space_key)
if page_id:
    print(f"Found page '{title}' with ID: {page_id} in space '{space_key}'.")
else:
    print(f"No page found with the title '{title}' in space '{space_key}'.")

Parameters:

• title (str): Title of the Confluence wiki page you're looking for.
• space_key (str): Key of the Confluence space where you're searching for the page.

Output:

• The function outputs a message indicating the process of searching for the page by its title within the specified space and then reports the outcome of the search.

Return:

• ID of the page (str): If a page with the specified title is found in the given space, the function returns the ID of the page.
• None: If no page is found with the given title in the specified space, or if there was an error during the request.

---

8. Replace word in wiki

• Replace all occurrences of a string in a Confluence wiki page.

wiki_helper = WikiHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

page_id = "123456"  # Example page ID
from_string = "old text"  # Text to be replaced
to_string = "new text"  # Replacement text

if wiki_helper.replace_in_page(page_id, from_string, to_string):
    print(f"Replaced all occurrences of '{from_string}' with '{to_string}' in page ID: {page_id}.")
else:
    print("Failed to replace text in the page.")

Parameters:

• page_id (str): ID of the Confluence wiki page where the replacement will be made.
• from_string (str): The string to be replaced in the page's content.
• to_string (str): The string to use as a replacement.

Output:

• The function outputs messages detailing the process of fetching the page content, performing the replacement, and updating the page with the new content.

Return:

• True: If the replacement operation was successful, whether replacements were made or not (including the case where the from_string was not found).
• False: If there was a failure at any point during the process, such as an error fetching the page content, or updating the page with the new content.

---

9. Fetch tables from wiki

• Fetch all tables from a Confluence wiki page.

wiki_helper = WikiHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

page_id = "123456"  # Example page ID

tables_json = wiki_helper.get_tables_from_page(page_id)
if tables_json:
    print("Found tables on the page:")
    print(tables_json)
else:
    print("Failed to fetch tables or no tables found on the page.")

Parameters:

• page_id (str): ID of the Confluence wiki page from which to fetch tables.

Output:

• The function initiates by fetching the content of the specified Confluence wiki page. It then parses the HTML content of the page to find and extract data from all tables present on the page.

Return:

• JSON string: Returns a JSON string that represents all the tables found on the page. Each table is structured with keys representing the table headers and values representing the row data. Multiple tables are indexed as table1, table2, etc.
• None: If the fetching fails or no tables are found on the page.

---

10. Replace the whole wiki page

• Replace the entire Confluence wiki page with new content.

wiki_helper = WikiHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

page_id = "12345"  # Example page ID
new_content = "<p>This is the new content for the page.</p>"  # HTML content

if wiki_helper.update_wiki_page(page_id, new_content):
    print(f"Page ID: {page_id} was updated successfully.")
else:
    print(f"Failed to update the page ID: {page_id}.")

Parameters:

• page_id (str): The ID of the Confluence wiki page that you want to update.
• new_content (str): The new content to replace the existing content of the page. This content is typically in HTML format.

Output:

• The method prints messages to inform the user about the process steps, including fetching current page data and attempting to update the page with new content.

Return:

• True: If the page content update is successful.
• False: If the update fails due to an invalid page ID, issues with the Confluence server, or improper formatting of the new content.

---

11. Get parent page ID

• Retrieve the parent ID of a Confluence wiki page by its page ID.

wiki_helper = WikiHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

page_id = "123456"  # Example page ID

parent_id = wiki_helper.get_parent_page_id(page_id)
if parent_id:
    print(f"Parent page ID for page ID {page_id}: {parent_id}")
else:
    print(f"No parent page found for page ID {page_id}, or failed to fetch.")

Parameters:

• page_id (str): The ID of the Confluence wiki page for which you want to find the parent page.

Output:

• The method outputs a message indicating it is fetching the parent page ID for the specified page.

Return:

• ID of the parent page (str): If the specified page has a parent page, the method returns the ID of the parent page.
• None: If no parent page exists for the specified page or if there was an error in the fetch operation.

---

12. Add Table of Content (TOC) in wiki page

• Add a Table of Contents (TOC) to a Confluence wiki page if it doesn't already have one.

wiki_helper = WikiHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

page_id = "123456"  # Example page ID

result_message = wiki_helper.add_toc_to_page(page_id)
print(result_message)

Parameters:

• page_id (str): The ID of the Confluence wiki page where you want to add a Table of Contents.

Return:

• A message string indicating the operation's result: confirmation that the TOC was added successfully, a message stating that the TOC already exists, or an error message if the operation failed.

---

13. Add row to an existing table in wiki page

• Pass the headers to identify the table and then add the row to that identified table.

wiki_helper = WikiHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

page_id = "123456"  # Example page ID
headers = ["Header1", "Header2", "Header3"]  # The headers of the table you're targeting
row_data = ["Data1", "Data2", "Data3"]  # The data for the new row

result_message = wiki_helper.add_row_to_table(page_id, headers, row_data)
print(result_message)

Parameters:

• page_id (str): The ID of the Confluence page you're modifying.
• headers (list of str): A list of headers representing the columns of the table. This ensures that the data is added to the correct table.
• row_data (list of str): A list of values corresponding to each header, forming the new row.

Return:

• A message string indicating the result of the operation — either confirmation of successful row addition, or an error message detailing why the operation failed.

---

14. Update or add row to an existing table in wiki page

• Pass the headers to identify the table and then update an existing row (matched by first column) or add a new row if no match is found.

wiki_helper = WikiHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

page_id = "123456"  # Example page ID
headers = ["Cluster Name", "Component Name", "Next Version"]  # The headers of your table
new_row_data = ["Cluster1", "ComponentA", "v2.0"]  # Data for the new or updated row

result_message = wiki_helper.update_or_add_table_row(page_id, headers, new_row_data)
print(result_message)

Parameters:

• page_id (str): The ID of the Confluence page containing the table.
• headers (list of str): A list of headers representing the columns of the table.
• new_row_data (list of str): The values for the new or updated row, aligned with the headers order. The first value is used as the key to match existing rows.

Output and Return:

• A message string indicating the result: "Row updated successfully." if an existing row was matched and updated, "Row added successfully." if a new row was appended, or an error message if the operation failed.

---

15. Get page content

• Fetch the storage format content of a Confluence page.

wiki_helper = WikiHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

page_id = "123456"  # Example page ID
content = wiki_helper.get_page_content(page_id)
if content:
    print(f"Page content: {content}")
else:
    print("Failed to fetch page content.")

Parameters:

• page_id (str): The ID of the Confluence page.

Return:

• Content (str): The storage format (HTML) content of the page if successful.
• None: If the request fails.

---

16. Update page content

• Update the content of a Confluence page (handles version incrementing automatically).

wiki_helper = WikiHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

page_id = "123456"  # Example page ID
new_content = "<p>Updated content here</p>"

if wiki_helper.update_page_content(page_id, new_content):
    print("Page content updated successfully.")
else:
    print("Failed to update page content.")

Parameters:

• page_id (str): The ID of the Confluence page to be updated.
• new_content (str): The new content in storage format (HTML).

Return:

• True: If the update was successful.
• False: If the update failed.

---

17. Delete a wiki page

• To delete a wiki page, use the delete_wiki_page method:

wiki_helper = WikiHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

page_id = "123456"

if wiki_helper.delete_wiki_page(page_id):
    print("Page deleted successfully.")
else:
    print("Failed to delete the page.")

Parameters:

• page_id (str): The ID of the Confluence page to delete.

Return:

• True: If the page was successfully deleted.
• False: If the deletion failed.

---

18. Get full page metadata

• To get full page metadata (title, space, version, etc.) without the body content, use the get_page_by_id method:

wiki_helper = WikiHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

page_id = "123456"
page_info = wiki_helper.get_page_by_id(page_id)
if page_info:
    print(f"Title: {page_info['title']}")
    print(f"Version: {page_info['version']}")
    print(f"Parent ID: {page_info['parent_id']}")
else:
    print("Failed to fetch page metadata.")

Parameters:

• page_id (str): The ID of the Confluence page.

Return:

• Dictionary with keys: id, title, status, space_id, parent_id, version, created_at, author_id.
• None: If the retrieval fails.

---

19. Add labels to a wiki page

• To add labels to a wiki page, use the add_label_to_page method:

wiki_helper = WikiHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

page_id = "123456"
labels = ["documentation", "api", "v2"]

if wiki_helper.add_label_to_page(page_id, labels):
    print("Labels added successfully.")
else:
    print("Failed to add labels.")

Parameters:

• page_id (str): The ID of the Confluence page.
• labels (list or str): A list of label strings to add, or a single label string.

Return:

• True: If labels were added successfully.
• False: If the operation failed.

---

20. Get page labels

• To get all labels on a wiki page, use the get_page_labels method:

wiki_helper = WikiHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

page_id = "123456"
labels = wiki_helper.get_page_labels(page_id)
if labels:
    print(f"Labels: {', '.join(labels)}")
else:
    print("No labels found or failed to fetch.")

Parameters:

• page_id (str): The ID of the Confluence page.

Return:

• List of label names (list): If successful.
• None: If the retrieval fails.

---

21. Search pages

• To search for pages by text content, use the search_pages method:

wiki_helper = WikiHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

# Search across all spaces
results = wiki_helper.search_pages("deployment guide")

# Search within a specific space
results = wiki_helper.search_pages("API documentation", space_key="DEV")

if results:
    for page in results:
        print(f"{page['title']} - {page['url']}")
else:
    print("No pages found.")

Parameters:

• query (str): Text to search for in page content/titles.
• space_key (str, optional): Limit search to a specific space.
• limit (int, optional): Maximum number of results (default 25).

Return:

• List of dictionaries: Each with id, title, and url.
• None: If the search fails.

---

22. Get all pages in a space

• To list all pages in a space, use the get_all_pages_in_space method:

wiki_helper = WikiHelper(ATLASSIAN_URL, EMAIL, API_TOKEN)

pages = wiki_helper.get_all_pages_in_space("DEV")
if pages:
    print(f"Found {len(pages)} pages in space DEV:")
    for page in pages:
        print(f"  - {page['title']} (ID: {page['id']})")
else:
    print("No pages found or failed to fetch.")

Parameters:

• space_key (str): Key of the Confluence space.
• limit (int, optional): Maximum number of pages to return (default 250). Use None for all.

Return:

• List of dictionaries: Each with id, title, status, and parent_id.
• None: If the retrieval fails.

---

Data Privacy Note

🔒 We respect your privacy: This module does not store any of your data anywhere. It simply interacts with the Atlassian Jira API to perform the requested operations. Ensure you manage your connection details securely.

Release Notes

Latest Release: 1.2.0 (June 2025)

• New Jira Functions:
  • get_ticket_details — Get full ticket info (status, assignee, priority, labels, etc.)
  • get_ticket_status — Quick status check for a ticket
  • assign_ticket — Assign/unassign a ticket to a user
  • add_label — Add labels to a ticket
  • link_tickets — Create links between tickets (Blocks, Relates, etc.)
  • bulk_transition — Transition multiple tickets at once
• New Wiki Functions:
  • delete_wiki_page — Delete a wiki page
  • get_page_by_id — Get full page metadata
  • add_label_to_page — Add labels to a wiki page
  • get_page_labels — Get all labels on a page
  • search_pages — Search pages by text content
  • get_all_pages_in_space — List all pages in a space

Previous Releases:

• 1.1.0 (June 2025)
• Migrated all Jira endpoints from REST API v2 to v3
  • jql_ticket now uses /rest/api/3/search/jql (old /rest/api/2/search was removed May 2025)
  • create_ticket and create_custom_ticket now use v3 with automatic ADF conversion (users still pass plain text)
  • All other Jira functions moved to /rest/api/3/issue
• Migrated all Wiki endpoints from REST API v1 to v2
  • All functions now use /wiki/api/v2/pages endpoints
  • Cursor-based pagination for child page retrieval
  • Space key automatically resolved to space ID internally
  • Exceptions: move_wiki_page and template retrieval stay on v1 (no v2 equivalent)
• No breaking changes — all function signatures and return types unchanged

Previous Releases:

• 1.0.2 (June 2025)
  • Fixed file handle leak in attach_file_to_ticket
  • Added network error handling across all functions
  • Fixed pagination in get_child_pages_recursive
  • Fixed CQL injection risk in wiki_page_exists
  • Fixed update_or_add_table_row logic bug
  • Added input validation to all functions
• 1.0.1 (04 Feb 2025)
  • Minor bug fixed for jql_ticket function
• 1.0.0 (19 Nov 2024)
  • Addressing many minor bugs
  • Restructured the entire release to improve the user experience
  • Added Important Notes section to highlight critical information
• 0.6.2 (11 Nov 2024)
  • Dummy release to recover the incident happened on 11 Nov 2024
  • Please review the Important Notes section for more details

Deleted Releases:

• 0.6.1 and earlier — see git history for details