跳到正文

Jira

JiraToolSpec #

Bases: BaseToolSpec

Atlassian Jira 工具规范。

源代码位于 llama-index-integrations/tools/llama-index-tools-jira/llama_index/tools/jira/base.py 
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
class JiraToolSpec(BaseToolSpec):
    """Atlassian Jira Tool Spec."""

    spec_functions = [
        "jira_issues_query",
        "jira_issue_query",
        "jira_comments_query",
        "jira_all_projects",
    ]

    def __init__(
        self,
        email: Optional[str] = None,
        api_token: Optional[str] = None,
        server_url: Optional[str] = None,
    ) -> None:
        """Initialize the Atlassian Jira tool spec."""
        from jira import JIRA

        if email and api_token and server_url:
            self.jira = JIRA(
                basic_auth=(email, api_token),
                server=server_url,
            )
        else:
            raise Exception("Error: Please provide Jira api credentials to continue")

    def jira_all_projects(self) -> dict:
        """
        Retrieve all projects from the Atlassian Jira account.

        This method fetches a list of projects from Jira and returns them in a structured
        format, including the project ID, key, and name. If an error occurs during
        retrieval, an error message is returned.

        Returns:
            dict: A dictionary containing:
                - 'error' (bool): Indicates whether the request was successful.
                - 'message' (str): A description of the result.
                - 'projects' (list, optional): A list of projects with their details
                  (ID, key, name) if retrieval is successful.

        """
        try:
            projects = self.jira.projects()

            if projects:
                return {
                    "error": False,
                    "message": "All Projects from the account",
                    "projects": [
                        {"id": project.id, "key": project.key, "name": project.name}
                        for project in projects
                    ],
                }
        except Exception:
            pass

        return {"error": True, "message": "Unable to fetch projects"}

    def jira_comments_query(
        self, issue_key: str, author_email: Optional[str] = None
    ) -> dict:
        """
        Retrieve all comments for a given Jira issue, optionally filtering by the author's email.

        This function fetches comments from a specified Jira issue and returns them as a structured
        JSON response. If an `author_email` is provided, only comments from that specific author
        will be included.

        Args:
            issue_key (str): The Jira issue key for which to retrieve comments.
            author_email (str, Optional): filters comments by the author's email.

        Returns:
            dict: A dictionary containing:
                - 'error' (bool): Indicates whether the request was successful.
                - 'message' (str): A descriptive message about the result.
                - 'comments' (list, optional): A list of comments, where each comment includes:
                    - 'id' (str): The unique identifier of the comment.
                    - 'author' (str): The display name of the comment's author.
                    - 'author_email' (str): The author's email address.
                    - 'body' (str): The content of the comment.
                    - 'created_at' (str): The timestamp when the comment was created.
                    - 'updated_at' (str): The timestamp when the comment was last updated.

        """
        error = False

        try:
            issue = self.jira.issue(issue_key)

            all_comments = list(issue.fields.comment.comments)
            filtered_results = []

            for comment in all_comments:
                if (
                    author_email is not None
                    and author_email not in comment.author.emailAddress
                ):
                    continue

                filtered_results.append(
                    {
                        "id": comment.id,
                        "author": comment.author.displayName,
                        "author_email": comment.author.emailAddress,
                        "body": comment.body,
                        "created_at": comment.created,
                        "updated_at": comment.updated,
                    }
                )

            message = f'All the comments in the issue key "{issue_key}"'
        except Exception:
            error = True
            message = "Unable to fetch comments due to some error"

        response = {"error": error, "message": message}

        if error is False:
            response["comments"] = filtered_results

        return response

    def jira_issue_query(
        self, issue_key: str, just_payload: bool = False
    ) -> Union[None, dict]:
        """
        Retrieves detailed information about a specific Jira issue.

        This method fetches issue details such as summary, description, type, project, priority, status,
        reporter, assignee, labels, and timestamps. The response structure can be adjusted using the
        `just_payload` flag.

        Args:
            issue_key (str): The unique key or ticket number of the Jira issue.
            just_payload (bool, optional): If True, returns only the issue payload without the response
                                           metadata. Defaults to False.

        Returns:
            Union[None, dict]: A dictionary containing issue details if found, or an error response if the issue
                               cannot be retrieved.

        Example:
            > jira_client.load_issue("JIRA-123", just_payload=True)
            {
                'key': 'JIRA-123',
                'summary': 'Fix login bug',
                'description': 'Users unable to log in under certain conditions...',
                'type': 'Bug',
                'project_name': 'Web App',
                'priority': 'High',
                'status': 'In Progress',
                'reporter': 'John Doe',
                'reporter_email': '[email protected]',
                'labels': ['authentication', 'urgent'],
                'created_at': '2024-02-01T10:15:30.000Z',
                'updated_at': '2024-02-02T12:20:45.000Z',
                'assignee': 'Jane Smith',
                'assignee_email': '[email protected]'
            }

        """
        error = False
        try:
            issue = self.jira.issue(issue_key)

            payload = {
                "key": issue.key,
                "summary": issue.fields.summary,
                "description": issue.fields.description,
                "type": issue.fields.issuetype.name,
                "project_name": issue.fields.project.name,
                "priority": issue.fields.priority.name,
                "status": issue.fields.status.name,
                "reporter": issue.fields.reporter.displayName
                if issue.fields.reporter
                else None,
                "reporter_email": issue.fields.reporter.emailAddress
                if issue.fields.reporter
                else None,
                "labels": issue.fields.labels,
                "created_at": issue.fields.created,
                "updated_at": issue.fields.updated,
                "assignee": issue.fields.assignee.displayName
                if issue.fields.assignee
                else None,
                "assignee_email": issue.fields.assignee.emailAddress
                if issue.fields.assignee
                else None,
            }

            message = f"Details of the issue: {issue.key}"

        except Exception:
            error = True
            message = "Unable to fetch issue due to some error"

        if error is False and just_payload:
            return payload

        response = {"error": error, "message": message}

        if error is False:
            response["result"] = payload

        return response

    def jira_issues_query(self, keyword: str, max_results: int = 10) -> dict:
        """
        Search for Jira issues containing a specific keyword.

        This function searches for Jira issues where the specified `keyword` appears in the summary, description, or comments.
        The results are sorted by creation date in descending order.

        Args:
            keyword (str): The keyword to search for within issue summaries, descriptions, or comments.
            max_results (int, optional): The maximum number of issues to return. Defaults to 10. If set higher than 100, it will be limited to 100.

        Returns:
            dict: A dictionary with the following structure:
                - 'error' (bool): Indicates if an error occurred during the fetch operation.
                - 'message' (str): Describes the outcome of the operation.
                - 'results' (list, optional): A list of issues matching the search criteria, present only if no error occurred.

        """
        error = False

        max_results = min(max_results, 100)

        # if custom_query is not None:
        #     jql = custom_query
        # else:
        jql = f'summary ~ "{keyword}" or description ~ "{keyword}" or text ~ "{keyword}" order by created desc'

        try:
            issues = [
                self.jira_issue_query(issue.key, just_payload=True)
                for issue in self.jira.search_issues(jql, maxResults=max_results)
            ]

            message = "All the issues with specific matching conditions"
        except Exception:
            error = True
            message = "Unable to fetch issue due to some error"

        response = {"error": error, "message": message}

        if error is False:
            response["results"] = issues

        return response

jira_all_projects #

jira_all_projects() -> dict

从 Atlassian Jira 账户检索所有项目。

此方法从 Jira 获取项目列表，并以结构化格式返回，包括项目 ID、key 和名称。如果在检索过程中发生错误，将返回错误消息。

返回值

名称 类型 描述
dict dict

包含以下内容的字典： - 'error' (bool): 指示请求是否成功。 - 'message' (str): 结果的描述。 - 'projects' (list, 可选): 如果检索成功，则为包含项目详情（ID、key、名称）的列表。
源代码位于 llama-index-integrations/tools/llama-index-tools-jira/llama_index/tools/jira/base.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
def jira_all_projects(self) -> dict:
    """
    Retrieve all projects from the Atlassian Jira account.

    This method fetches a list of projects from Jira and returns them in a structured
    format, including the project ID, key, and name. If an error occurs during
    retrieval, an error message is returned.

    Returns:
        dict: A dictionary containing:
            - 'error' (bool): Indicates whether the request was successful.
            - 'message' (str): A description of the result.
            - 'projects' (list, optional): A list of projects with their details
              (ID, key, name) if retrieval is successful.

    """
    try:
        projects = self.jira.projects()

        if projects:
            return {
                "error": False,
                "message": "All Projects from the account",
                "projects": [
                    {"id": project.id, "key": project.key, "name": project.name}
                    for project in projects
                ],
            }
    except Exception:
        pass

    return {"error": True, "message": "Unable to fetch projects"}

jira_comments_query #

jira_comments_query(issue_key: str, author_email: Optional[str] = None) -> dict

检索指定 Jira 问题的所有评论，可选择按作者邮箱过滤。

此函数从指定的 Jira 问题获取评论，并将其作为结构化的 JSON 响应返回。如果提供了 author_email，则仅包含该特定作者的评论。

参数

名称 类型 描述 默认值
issue_key str

要检索评论的 Jira 问题 key。

 必需
author_email (str, 可选)

按作者邮箱过滤评论。

 None

返回值

名称 类型 描述
dict dict

包含以下内容的字典： - 'error' (bool): 指示请求是否成功。 - 'message' (str): 结果的描述性消息。 - 'comments' (list, 可选): 评论列表，其中每条评论包括： - 'id' (str): 评论的唯一标识符。 - 'author' (str): 评论作者的显示名称。 - 'author_email' (str): 作者的邮箱地址。 - 'body' (str): 评论内容。 - 'created_at' (str): 评论创建时间戳。 - 'updated_at' (str): 评论上次更新时间戳。
源代码位于 llama-index-integrations/tools/llama-index-tools-jira/llama_index/tools/jira/base.py 
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
def jira_comments_query(
    self, issue_key: str, author_email: Optional[str] = None
) -> dict:
    """
    Retrieve all comments for a given Jira issue, optionally filtering by the author's email.

    This function fetches comments from a specified Jira issue and returns them as a structured
    JSON response. If an `author_email` is provided, only comments from that specific author
    will be included.

    Args:
        issue_key (str): The Jira issue key for which to retrieve comments.
        author_email (str, Optional): filters comments by the author's email.

    Returns:
        dict: A dictionary containing:
            - 'error' (bool): Indicates whether the request was successful.
            - 'message' (str): A descriptive message about the result.
            - 'comments' (list, optional): A list of comments, where each comment includes:
                - 'id' (str): The unique identifier of the comment.
                - 'author' (str): The display name of the comment's author.
                - 'author_email' (str): The author's email address.
                - 'body' (str): The content of the comment.
                - 'created_at' (str): The timestamp when the comment was created.
                - 'updated_at' (str): The timestamp when the comment was last updated.

    """
    error = False

    try:
        issue = self.jira.issue(issue_key)

        all_comments = list(issue.fields.comment.comments)
        filtered_results = []

        for comment in all_comments:
            if (
                author_email is not None
                and author_email not in comment.author.emailAddress
            ):
                continue

            filtered_results.append(
                {
                    "id": comment.id,
                    "author": comment.author.displayName,
                    "author_email": comment.author.emailAddress,
                    "body": comment.body,
                    "created_at": comment.created,
                    "updated_at": comment.updated,
                }
            )

        message = f'All the comments in the issue key "{issue_key}"'
    except Exception:
        error = True
        message = "Unable to fetch comments due to some error"

    response = {"error": error, "message": message}

    if error is False:
        response["comments"] = filtered_results

    return response

jira_issue_query #

jira_issue_query(issue_key: str, just_payload: bool = False) -> Union[None, dict]

检索特定 Jira 问题的详细信息。

此方法获取问题详情，如摘要、描述、类型、项目、优先级、状态、报告人、经办人、标签和时间戳。可以使用 just_payload 标志调整响应结构。

参数

名称 类型 描述 默认值
issue_key str

Jira 问题的唯一 key 或工单号。

 必需
just_payload bool

如果为 True，则仅返回问题 payload，不包含响应元数据。默认为 False。

 False

返回值

类型 描述
Union[None, dict]

Union[None, dict]: 如果找到问题，则为包含问题详情的字典；如果无法检索问题，则为错误响应。
示例

jira_client.load_issue("JIRA-123", just_payload=True) { 'key': 'JIRA-123', 'summary': '修复登录 bug', 'description': '用户在某些条件下无法登录...', 'type': 'Bug', 'project_name': 'Web App', 'priority': '高', 'status': '进行中', 'reporter': 'John Doe', 'reporter_email': '[email protected]', 'labels': ['认证', '紧急'], 'created_at': '2024-02-01T10:15:30.000Z', 'updated_at': '2024-02-02T12:20:45.000Z', 'assignee': 'Jane Smith', 'assignee_email': '[email protected]' }

源代码位于 llama-index-integrations/tools/llama-index-tools-jira/llama_index/tools/jira/base.py 
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
def jira_issue_query(
    self, issue_key: str, just_payload: bool = False
) -> Union[None, dict]:
    """
    Retrieves detailed information about a specific Jira issue.

    This method fetches issue details such as summary, description, type, project, priority, status,
    reporter, assignee, labels, and timestamps. The response structure can be adjusted using the
    `just_payload` flag.

    Args:
        issue_key (str): The unique key or ticket number of the Jira issue.
        just_payload (bool, optional): If True, returns only the issue payload without the response
                                       metadata. Defaults to False.

    Returns:
        Union[None, dict]: A dictionary containing issue details if found, or an error response if the issue
                           cannot be retrieved.

    Example:
        > jira_client.load_issue("JIRA-123", just_payload=True)
        {
            'key': 'JIRA-123',
            'summary': 'Fix login bug',
            'description': 'Users unable to log in under certain conditions...',
            'type': 'Bug',
            'project_name': 'Web App',
            'priority': 'High',
            'status': 'In Progress',
            'reporter': 'John Doe',
            'reporter_email': '[email protected]',
            'labels': ['authentication', 'urgent'],
            'created_at': '2024-02-01T10:15:30.000Z',
            'updated_at': '2024-02-02T12:20:45.000Z',
            'assignee': 'Jane Smith',
            'assignee_email': '[email protected]'
        }

    """
    error = False
    try:
        issue = self.jira.issue(issue_key)

        payload = {
            "key": issue.key,
            "summary": issue.fields.summary,
            "description": issue.fields.description,
            "type": issue.fields.issuetype.name,
            "project_name": issue.fields.project.name,
            "priority": issue.fields.priority.name,
            "status": issue.fields.status.name,
            "reporter": issue.fields.reporter.displayName
            if issue.fields.reporter
            else None,
            "reporter_email": issue.fields.reporter.emailAddress
            if issue.fields.reporter
            else None,
            "labels": issue.fields.labels,
            "created_at": issue.fields.created,
            "updated_at": issue.fields.updated,
            "assignee": issue.fields.assignee.displayName
            if issue.fields.assignee
            else None,
            "assignee_email": issue.fields.assignee.emailAddress
            if issue.fields.assignee
            else None,
        }

        message = f"Details of the issue: {issue.key}"

    except Exception:
        error = True
        message = "Unable to fetch issue due to some error"

    if error is False and just_payload:
        return payload

    response = {"error": error, "message": message}

    if error is False:
        response["result"] = payload

    return response

jira_issues_query #

jira_issues_query(keyword: str, max_results: int = 10) -> dict

搜索包含特定关键词的 Jira 问题。

此函数搜索 keyword 出现在摘要、描述或评论中的 Jira 问题。结果按创建日期降序排序。

参数

名称 类型 描述 默认值
keyword str

在问题摘要、描述或评论中搜索的关键词。

 必需
max_results int

要返回的最大问题数。默认为 10。如果设置高于 100，将限制为 100。

 10

返回值

名称 类型 描述
dict dict

结构如下的字典： - 'error' (bool): 指示获取操作期间是否发生错误。 - 'message' (str): 描述操作结果。 - 'results' (list, 可选): 匹配搜索条件的问题列表，仅在未发生错误时存在。
源代码位于 llama-index-integrations/tools/llama-index-tools-jira/llama_index/tools/jira/base.py 
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
def jira_issues_query(self, keyword: str, max_results: int = 10) -> dict:
    """
    Search for Jira issues containing a specific keyword.

    This function searches for Jira issues where the specified `keyword` appears in the summary, description, or comments.
    The results are sorted by creation date in descending order.

    Args:
        keyword (str): The keyword to search for within issue summaries, descriptions, or comments.
        max_results (int, optional): The maximum number of issues to return. Defaults to 10. If set higher than 100, it will be limited to 100.

    Returns:
        dict: A dictionary with the following structure:
            - 'error' (bool): Indicates if an error occurred during the fetch operation.
            - 'message' (str): Describes the outcome of the operation.
            - 'results' (list, optional): A list of issues matching the search criteria, present only if no error occurred.

    """
    error = False

    max_results = min(max_results, 100)

    # if custom_query is not None:
    #     jql = custom_query
    # else:
    jql = f'summary ~ "{keyword}" or description ~ "{keyword}" or text ~ "{keyword}" order by created desc'

    try:
        issues = [
            self.jira_issue_query(issue.key, just_payload=True)
            for issue in self.jira.search_issues(jql, maxResults=max_results)
        ]

        message = "All the issues with specific matching conditions"
    except Exception:
        error = True
        message = "Unable to fetch issue due to some error"

    response = {"error": error, "message": message}

    if error is False:
        response["results"] = issues

    return response