API Controller

APIController

class APIController(configuration: jiratui.config.ApplicationConfiguration | None = None)

A controller for the JirAPI to provide some additional functionality and integration of multiple endpoints.

Initialization

async get_project(key: str) → jiratui.api_controller.controller.APIControllerResponse

Retrieves the details of a project by key.

Parameters:

key – the case-sensitive key of the project.

Returns:

An instance of APIControllerResponse with the details of the project in the result key; `success=False and the detail of the error if the project can not be retrieved.

async search_projects(query: str | None = None, order_by: str | None = None, keys: list[str] = None) → jiratui.api_controller.controller.APIControllerResponse

Searches for projects using different filters.

This method implements pagination in order to retrieve all the projects that satisfy the search criteria in a single operation. If an exception occurs while fetching any of the pages then the method will return the list of projects found so far with an additional error message.

Parameters:

  • query – filter the results using a literal string. Projects with a matching key or name are returned (case-insensitive).

  • order_by – sort the results by a field: key (default), category, issueCount, lastIssueUpdatedTime, name, owner, archivedDate, deletedDate.

  • keys – the project keys to filter the results by.

Returns:

An instance of APIControllerResponse with the list of Project instances. If an error occurs an instance of APIControllerResponse with the error message.

async get_project_statuses(project_key: str) → jiratui.api_controller.controller.APIControllerResponse

Retrieves the statues applicable to issues of a project.

Parameters:

project_key – the case-sensitive key of a project.

Returns:

An instance of APIControllerResponse with the statuses grouped by type of issues. If an error occurs an instance of APIControllerResponse with the error message and success = False.

async find_groups(offset: int = 0, limit: int = RECORDS_PER_PAGE_LIST_GROUPS, groups_ids: list[str] | None = None, groups_names: list[str] | None = None) → jiratui.api_controller.controller.APIControllerResponse

Finds Jira users groups that match the given criteria.

Parameters:

  • offset – the index of the first item to return in a page of results (page offset).

  • limit – the maximum number of items to return per page (number should be between 1 and 50).

  • groups_ids – retrieve the groups with these IDs only.

  • groups_names – retrieve the groups with these names only.

Returns:

An instance of APIControllerResponse with the list of JiraUserGroup instances. If an error occurs an instance of APIControllerResponse with the error message and success = False.

async count_users_in_group(group_id: str) → jiratui.api_controller.controller.APIControllerResponse

Counts the number of users in a Jira users group.

Parameters:

group_id – the ID of the Jira users group.

Returns:

The total number of users i the group.

async list_all_active_users_in_group(group_id: str) → jiratui.api_controller.controller.APIControllerResponse

Retrieves all the active users in a group.

If an exception occurs while fetching any of the pages then the method will return the list of users found so far with an additional error message.

Parameters:

group_id – the ID of the Jira users group.

Returns:

An instance of APIControllerResponse with the list of JiraUser instances.

async get_issue_types_for_project(project_key: str) → jiratui.api_controller.controller.APIControllerResponse

Retrieves the types of issues associated to a project.

Parameters:

project_key – the ID or (case-sensitive) key of the project whose issue types we want to retrieve.

Returns:

An instance of APIControllerResponse with the list of IssueType instances. If an error occurs an instance of APIControllerResponse with the error message.

async get_issue_types() → jiratui.api_controller.controller.APIControllerResponse

Retrieves all the types of issues relevant for any project.

Warning: this may contain multiple issue types with the same name (different IDs though).

Returns:

An instance of APIControllerResponse with the list of IssueType instances. If an error occurs an instance of APIControllerResponse with the error message.

async search_users(email_or_name: str) → jiratui.api_controller.controller.APIControllerResponse

Searches users by email or name.

Parameters:

email_or_name – the email or name to filter users

Returns:

An instance of APIControllerResponse with the list of JiraUser instances. If an error occurs an instance of APIControllerResponse with the error message.

async find_users_for_picker(query: str) → jiratui.api_controller.controller.APIControllerResponse

Searches users whose attributes match the query term.

This is useful for building widgets that allow the user to pick users.

Parameters:

query – string that is matched against user attributes, such as displayName, and emailAddress, to find relevant users.

Returns:

An instance of APIControllerResponse with the list of JiraUser instances. If an error occurs an instance of APIControllerResponse with the error message.

async search_users_assignable_to_issue(issue_key: str | None = None, query: str | None = None, account_id: str | None = None, active: bool | None = True, project_id_or_key: str | None = None) → jiratui.api_controller.controller.APIControllerResponse

Retrieves the users that can be assigned to a work item.

Parameters:

  • issue_key – the key (case-sensitive) of a work item.

  • query – a string that is matched against user attributes, such as displayName, and emailAddress, to find relevant users. The string can match the prefix of the attribute’s value. For example, query=john matches a user with a displayName of John Smith and a user with an emailAddress of johnson@example.com.

  • active – if set to True (default) it will retrieve active users only.

  • project_id_or_key – the project ID or project key (case sensitive).

  • account_id

Returns:

An instance of APIControllerResponse with the list of JiraUser instances. If an error occurs an instance of APIControllerResponse with the error message.

async search_users_assignable_to_projects(project_keys: list[str], query: str | None = None, active: bool | None = True) → jiratui.api_controller.controller.APIControllerResponse

Retrieves the users that can be assigned to work items in multiple projects.

Parameters:

  • project_keys – a list of project keys (case-sensitive).

  • query – a string that is matched against user attributes, such as displayName, and emailAddress, to find relevant users. The string can match the prefix of the attribute’s value. For example, query=john matches a user with a displayName of John Smith and a user with an emailAddress of johnson@example.com.

  • active – if set to True (default) it will retrieve active users only.

Returns:

An instance of APIFacadeResponse with a list of JiraUser and success = True. If an error occurs then success = False and the error message in the error key.

async get_user(account_id: str) → jiratui.api_controller.controller.APIControllerResponse

Retrieves the details of a single user.

Parameters:

account_id – the account ID of the user, which uniquely identifies the user across all Atlassian products. For example, 5b10ac8d82e05b22cc7d4ef5.

Returns:

A dictionary with the details of the user

async delete_work_item(issue_id_or_key: str) → jiratui.api_controller.controller.APIControllerResponse

Deletes a work item.

Parameters:

issue_id_or_key – the id of the work item we want to delete.

Returns:

An instance of APIControllerResponse with success = True if the item was deleted successfully; success = False and the error message in the error key if the issue could not be deleted.

async get_issue(issue_id_or_key: str, fields: list[str] | None = None, properties: str | None = None) → jiratui.api_controller.controller.APIControllerResponse

Retrieves a work item (aka. Jira issue) by its key or id.

Parameters:

  • issue_id_or_key – the ID or case-sensitive key of the work item to retrieve.

  • fields – a list of fields to return for the issue. This parameter accepts a comma-separated list. Use it to retrieve a subset of fields. Allowed values: - *all: Returns all fields. - *navigable: Returns navigable fields. - Any issue field, prefixed with a minus to exclude.

  • properties – a list of issue properties to return for the issue. This parameter accepts a comma-separated list. Allowed values: - *all Returns all issue properties. - Any issue property key, prefixed with a minus to exclude.

Returns:

An instance of APIFacadeResponse with the issue and success = True. If an error occurs then success = False and the error message in the error key.

async issue_picker(query: str, project_id: str | None = None, show_sub_tasks: bool = True, current_issue_key: str | None = None) → jiratui.api_controller.controller.APIControllerResponse

Retrieves lists of issues matching a query string. Use this resource to provide auto-completion suggestions when the user is looking for an issue using a word or string.

Parameters:

  • query – a string to match against text fields in the issue such as title, description, or comments.

  • project_id – the ID of a project that suggested issues must belong to.

  • show_sub_tasks – indicate whether to include subtasks in the suggestions list. The default is True.

  • current_issue_key – the key of an issue to exclude from search results. For example, the issue the user is viewing when they perform this query.

Returns:

An instance of APIControllerResponse with a list of JiraIssuePickerSuggestion if the request is successful; APIControllerResponse with success = False and an error message otherwise.

async search_issues(project_key: str | None = None, created_from: datetime.date | None = None, created_until: datetime.date | None = None, status: int | None = None, assignee: str | None = None, issue_type: int | None = None, search_in_active_sprint: bool = False, jql_query: str | None = None, next_page_token: str | None = None, limit: int | None = None, order_by: jiratui.models.WorkItemsSearchOrderBy | None = None, fields: list[str] | None = None) → jiratui.api_controller.controller.APIControllerResponse

Searches for issues matching specified JQL query and other criteria.

Parameters:

  • project_key – the case-sensitive key of the project whose work items we want to search.

  • created_from – search work items created from this date forward (inclusive).

  • created_until – search work items created until this date (inclusive).

  • status – search work items with this status.

  • assignee – search work items assigned to this user’s account ID.

  • issue_type – search work items of this type.

  • search_in_active_sprint – if True only work items that belong to the currently active sprint will be retrieved.

  • jql_query – search work items using this (additional) JQL query.

  • next_page_token – the token that identifies the next page of results. This helps implements pagination of results.

  • limit – the maximum number of items to retrieve.

  • order_by – an instance of WorkItemsSearchOrderBy to sort the results.

  • fields – the fields to retrieve for every work item. It defaults to: ‘id’, ‘key’, ‘status’, ‘summary’, ‘issuetype’

Returns:

An instance of APIControllerResponse with the work items found or, en error if the search can not be performed.

async search_issues_by_page_number(project_key: str | None = None, created_from: datetime.date | None = None, created_until: datetime.date | None = None, status: int | None = None, assignee: str | None = None, issue_type: int | None = None, search_in_active_sprint: bool = False, jql_query: str | None = None, page: int | None = None, limit: int | None = None, order_by: jiratui.models.WorkItemsSearchOrderBy | None = None, fields: list[str] | None = None) → jiratui.api_controller.controller.APIControllerResponse

Searches for issues matching specified JQL query and other criteria.

This method implements issue search for the Jira Data Center Platform API. In contrast with the API offered by the Jira Cloud Platform the former does not use the concept of next_page_token to fetch pages of results. Instead, pagination is implemented using offset and limit variables. To address this difference the controller provides this method that fetches results based on a page number.

Parameters:

  • project_key – the case-sensitive key of the project whose work items we want to search.

  • created_from – search work items created from this date forward (inclusive).

  • created_until – search work items created until this date (inclusive).

  • status – search work items with this status.

  • assignee – search work items assigned to this user’s account ID.

  • issue_type – search work items of this type.

  • search_in_active_sprint – if True only work items that belong to the currently active sprint will be retrieved.

  • jql_query – search work items using this (additional) JQL query.

  • page – the page of results to retrieve.

  • limit – the maximum number of items to retrieve.

  • order_by – an instance of WorkItemsSearchOrderBy to sort the results.

  • fields – the fields to retrieve for every work item. It defaults to: ‘id’, ‘key’, ‘status’, ‘summary’, ‘issuetype’

Returns:

An instance of APIControllerResponse with the work items found or, en error if the search can not be performed.

async count_issues(project_key: str | None = None, created_from: datetime.date | None = None, created_until: datetime.date | None = None, status: int | None = None, assignee: str | None = None, issue_type: int | None = None, jql_query: str | None = None) → jiratui.api_controller.controller.APIControllerResponse

Estimates the number of work items yield by a search.

Parameters:

  • project_key – the case-sensitive key of the project whose work items we want to search.

  • created_from – search work items created from this date forward (inclusive).

  • created_until – search work items created until this date (inclusive).

  • status – search work items with this status.

  • assignee – search work items assigned to this user’s account ID.

  • issue_type – search work items of this type.

  • jql_query – search work items using this (additional) JQL query.

Returns:

An instance of APIControllerResponse with the count of work items or, en error if the estimation can not be calculated.

Retrieves the web links of a work item.

Parameters:

  • issue_key_or_id – the ID or case-sensitive key of a work item whose web links we want to retrieve.

  • global_id – an optional global ID that identifies a Web Link.

Returns:

An instance of APIControllerResponse with the list of IssueRemoteLink or, success = False with an error key if there is an error.

Deletes a web link associated to a work item.

Parameters:

  • issue_key_or_id – the (case-sensitive) key of the work item.

  • link_id – the ID of the link we want to delete.

Returns:

An instance of APIControllerResponse(success=True) if the link was deleted; APIControllerResponse(success=False) otherwise.

async global_settings() → jiratui.api_controller.controller.APIControllerResponse

Retrieves the global settings of the Jira instance.

Returns:

An instance of APIControllerResponse(success=True) with the details or, APIControllerResponse(success=False) if there is an error fetching the details.

async server_info() → jiratui.api_controller.controller.APIControllerResponse

Retrieves details of the Jira server instance.

Returns:

An instance of APIControllerResponse(success=True) with the details or, APIControllerResponse(success=False) if there is an error fetching the details.

async myself() → jiratui.api_controller.controller.APIControllerResponse

Retrieves details of the Jira user connecting to the API.

Returns:

An instance of APIControllerResponse(success=True) with the details or, APIControllerResponse(success=False) if there is an error fetching the details.

async get_edit_metadata_for_issue(issue_key_or_id: str) → dict

Retrieves the metadata relevant for editing a work item.

Parameters:

issue_key_or_id – the (case-sensitive) key of the work item.

Returns:

A dictionary with the relevant metadata or, {} if there is an error fetching the data.

async update_issue(issue: jiratui.models.JiraIssue, updates: dict) → jiratui.api_controller.controller.APIControllerResponse

Updates a work item.

This method supports updating the following fields:

  • Summary

  • Assignee

  • Priority

  • Due Date

  • Labels

  • Parent

  • Components

  • Reporter

  • Environment

  • Description

  • (Some) Custom and System fields types

Parameters:

  • issue – the work item we want to update.

  • updates – a dictionary with the Jira fields that we want to update and their corresponding values.

Returns:

An instance of APIControllerResponse with the result of the update, which may include a list of fields that were updated.

Raises:

  • UpdateWorkItemException – if the work item’s edit metadata is missing.

  • UpdateWorkItemException – if the work item’s edit metadata does not include details of the fields that can be updated.

  • UpdateWorkItemException – When any of the fields that we want to update do not support updates.

  • ValidationError – If the summary field is empty.

async transitions(issue_id_or_key: str) → jiratui.api_controller.controller.APIControllerResponse

Retrieves the applicable (status) transitions of a work item.

Parameters:

issue_id_or_key – the (case-sensitive) key of the work item.

Returns:

An instance of APIControllerResponse(success=True) with the list of IssueTransition instances or, APIControllerResponse(success=False) if there is an error fetching the data.

async transition_issue_status(issue_id_or_key: str, status_id: str) → jiratui.api_controller.controller.APIControllerResponse

Transitions a work item to a new status.

Parameters:

  • issue_id_or_key – the (case-sensitive) key of the work item.

  • status_id – the ID of the new status.

Returns:

An instance of APIControllerResponse(success=True) if the work item was transitioned; APIControllerResponse(success=False) if there is an error.

async get_comment(issue_key_or_id: str, comment_id: str) → jiratui.api_controller.controller.APIControllerResponse

Retrieves the details of a comment.

Parameters:

  • issue_key_or_id – the case-sensitive key or id of a work item.

  • comment_id – the id of the comment.

Returns:

An instance of APIControllerResponse with the IssueComment instance in the result key; `success=False and the detail of the error if one occurs.

async get_comments(issue_key_or_id: str, offset: int | None = None, limit: int | None = None) → jiratui.api_controller.controller.APIControllerResponse

Retrieves the comments of a work item.

Parameters:

  • issue_key_or_id – the case-sensitive key or id of a work item.

  • offset – the index of the first item to return in a page of results (page offset).

  • limit – the maximum number of items to return per page.

Returns:

An instance of APIControllerResponse with the list of IssueComment instances in the result key; `success=False and the detail of the error if one occurs.

async add_comment(issue_key_or_id: str, message: str) → jiratui.api_controller.controller.APIControllerResponse

Adds a comment to a work item.

Parameters:

  • issue_key_or_id – the case-sensitive key or id of a work item.

  • message – the text of the comment.

Returns:

An instance of APIControllerResponse with the result of the operation.

async delete_comment(issue_key_or_id: str, comment_id: str) → jiratui.api_controller.controller.APIControllerResponse

Deletes a comment from a work item.

Parameters:

  • issue_key_or_id – the case-sensitive key or id of a work item.

  • comment_id – the id of a comment.

Returns:

An instance of APIControllerResponse with the result of the operation.

Creates a link between 2 work items.

Parameters:

  • left_issue_key – the (case-sensitive) key of the work item.

  • right_issue_key – the (case-sensitive) key of the work item.

  • link_type – the type of link to create.

  • link_type_id – the ID of the type of link.

Returns:

An instance of APIControllerResponse(success=True) if the work items were linked successfully; APIControllerResponse(success=False) if there is an error.

Deletes the link between 2 work items.

Parameters:

link_id – the ID of the link to delete.

Returns:

An instance of APIControllerResponse(success=True) if the work items were unlinked successfully; APIControllerResponse(success=False) if there is an error.

Retrieves the types of links that can be created between 2 work items.

Returns:

An instance of APIControllerResponse(success=True) with the list of LinkIssueType instances; APIControllerResponse(success=False) if there is an error.

async get_issue_create_metadata(project_id_or_key: str, issue_type_id: str) → jiratui.api_controller.controller.APIControllerResponse

Retrieves the metadata relevant for creating work items of a project and of a certain type.

Parameters:

  • project_id_or_key – the (case-sensitive) key of the project.

  • issue_type_id – the ID of the type of work item.

Returns:

An instance of APIControllerResponse(success=True) with the metadata; APIControllerResponse(success=False) if there is an error.

async get_required_fields_for_issue_type(project_key: str, issue_type_id: str) → jiratui.api_controller.controller.APIControllerResponse

Retrieves required fields for a project and issue type combination.

Note

Results are cached in memory for the lifetime of the APIController instance. The cache uses {project_key}:{issue_type_id} as the key and has no explicit invalidation mechanism.

Parameters:

  • project_key – The case-sensitive key of the project.

  • issue_type_id – The ID of the issue type.

Returns:

An instance of APIControllerResponse with a list of required field keys in the result; APIControllerResponse(success=False) if there is an error.

async create_work_item(data: dict, **dynamic_fields) → jiratui.api_controller.controller.APIControllerResponse

Creates a work item.

The description field of a work item may be an ADF document or, if API v2 is used then a simple string. This method generates the proposer payload format for the description field based on the api version in use.

The current version of this method does not implement support for setting the value of the environment field. If we want to change this then we would need to take care of the difference in the format of the environment field for API v2 (does nto support ADF) and v3 (supports ADF).

Parameters:

data – the data that includes the fields and values to create the work item.

Returns:

An instance of APIControllerResponse with an instance of JiraBaseIssue as the result. This includes the item id and key. If an error occurs then APIControllerResponse.success == False and APIControllerResponse.error indicates the error.

add_attachment(issue_key_or_id: str, filename: str) → jiratui.api_controller.controller.APIControllerResponse

Adds a file attachment to a work item.

Parameters:

  • issue_key_or_id – the case-sensitive key or id of a work item.

  • filename – the name of the file to attach.

Returns:

An instance of APIControllerResponse with the details of the attachment in the result key; `success=False and the detail of the error if the file can not be attached.

async delete_attachment(attachment_id: str) → jiratui.api_controller.controller.APIControllerResponse

Deletes an attachment.

Parameters:

attachment_id – the id of the attachment to delete.

Returns:

An instance of APIControllerResponse with the result of the operation.

async get_attachment_content(attachment_id: str) → jiratui.api_controller.controller.APIControllerResponse

Downloads the content of an attachment.

Parameters:

attachment_id – the ID of the attachment

Returns:

An instance of APIControllerResponse with the bytes representation of the attached file or, an error if the file can not be downloaded.

async get_work_item_worklog(issue_key_or_id: str, offset: int | None = None, limit: int | None = None) → jiratui.api_controller.controller.APIControllerResponse

Retrieves the work log of a work item.

Important

The author and update author information depends on whether the toll uses Jira DC API, Jira Cloud API v2 or v3.

Parameters:

  • issue_key_or_id – the case-sensitive key or id of a work item.

  • offset – the index of the first item to return in a page of results (page offset).

  • limit – the maximum number of items to return per page.

Returns:

An instance of APIControllerResponse(success=True) with the JiraWorklog entries; APIControllerResponse(success=False) if there is an error.

async add_work_item_worklog(issue_key_or_id: str, started: datetime.datetime, time_spent: str, time_remaining: str | None = None, comment: str | None = None, current_remaining_estimate: str | None = None) → jiratui.api_controller.controller.APIControllerResponse

Adds a worklog to an item.

Important

The author and update author information depends on whether the toll uses Jira DC API, Jira Cloud API v2 or v3.

Parameters:

  • issue_key_or_id – the case-sensitive key or id of a work item.

  • current_remaining_estimate – the issue’s current remaining time estimate, as days (#d), hours (#h), or minutes (#m or #). For example, 2d.

  • started – the datetime on which the worklog effort was started. Required when creating a worklog. Optional when updating a worklog.

  • time_spent – the time spent working on the issue as days (#d), hours (#h), or minutes (#m or #). E.g. 2d 1h

  • time_remaining – the value to set as the issue’s remaining time estimate, as days (#d), hours (#h), or minutes (#m or #). For example, 2d.

  • comment – a comment about the worklog.

Returns:

An instance of APIControllerResponse(success=True) with the JiraWorklog entries; APIControllerResponse(success=False) if there is an error.

async remove_worklog(issue_id_or_key: str, worklog_id: str) → jiratui.api_controller.controller.APIControllerResponse

Deletes a worklog from an issue.

Parameters:

  • issue_id_or_key – the ID or key of the issue.

  • worklog_id – the ID of the worklog.

Returns:

APIControllerResponse(success=True) if the operation was successful; APIControllerResponse(success=False) if there is an error.

async get_fields(field_name: str | None = None) → jiratui.api_controller.controller.APIControllerResponse

Retrieves system and custom issue fields.

Returns:

APIControllerResponse(success=True, result=fields) if the operation was successful; APIControllerResponse(success=False) if there is an error.

async update_issue_flagged_status(issue_id_or_key: str, add_flag: bool = True, note: str | None = None) → jiratui.api_controller.controller.APIControllerResponse

Adds or removes a flag to/from a work item.

Optionally, it creates a comment with a note.

The status of a flag is stored in a custom field. The key/ID depends on the configuration of the target Jira platform. In order to support a dynamic feature that doesn’t require the user to specify what is the key/id of the field used for flagging I decided to use an endpoint to extract the necessary configuration of the supported fields.

As a result, this method implements the following logic:

        sequenceDiagram
    actor User
    User->>UI: flag work item
    UI->>Controller: update the flag status of the work item
    Controller->>API: get field configuration for field "flagged"
    API->>Controller: APIControllerResponse with field configuration
    alt field configuration not found or field key is not set
        API->>UI: "Unable to flag the item. Missing fields configuration"
        UI->>User: "Unable to flag the item"
    else
        Controller->>API: update issue
        API->>Controller: update response
        alt the update failed
            Controller->>UI: Failed to update the item's flag
            UI->>User: "Unable to flag the item"
        else
            alt the user wants to add a note
                Controller->>Controller: add comment to the issue
            end
            Controller->>UI: Item flagged successfully
            UI->>User: "Item flagged!"
        end
    end

Important

To update the work item’s flag field we can’t use the id of the option that represents the value of the field (aka. “Impediment”) because we don’t always have edit metadata for the field. If the field is not part of an edit screen the issue’s edit metadata will not contain the metadata; this is why we rely on the fields configuration endpoint.

param issue_id_or_key:

the id or key of the work item that we want to flag.

param add_flag:

if True then a flag is added to the item; otherwise the flag is removed.

param note:

an optional message to create a comment; useful to explain why the issue is flagged.

Returns:

APIControllerResponse(success=True) if a flag was added/removed. APIControllerResponse(success=False) if there was an error.

async get_jql_autocomplete_suggestions(field_name: str | None = None, field_value: str | None = None, predicate_name: str | None = None, predicate_value: str | None = None) → jiratui.api_controller.controller.APIControllerResponse

Retrieves suggestions for a field.

Parameters:
Returns:

An instance of APIControllerResponse with a list of suggestions and success = True. If an error occurs then success = False and the error message in the error key.

APIControllerResponse

class APIControllerResponse

Bases: jiratui.models.BaseModel

The response that the API controller returns on every method.

as_dict()