Jira

In diesem Artikel zeige ich Ihnen, wie Sie Ihren AI Agent mit Jira verbinden. Wir verwenden:

• ein Jira-Konto (kostenlos)
• einen Quickchat AI Agent (hier registrieren und kostenlos nutzen)

Dadurch kann Ihr Quickchat AI Agent:

• Ihre Jira-Tickets durchsuchen und
• smart auf Fragen auf deren Grundlage antworten

Wir verwenden die AI Actions von Quickchat (benutzerdefinierte HTTP-Aktionen), damit Ihr Agent den Endpunkt Enhanced search for issues der Jira (Atlassian) API aufrufen kann.

Einen AI Agent gestalten, der Benutzereingaben kreativ interpretiert

Video ansehen

Play

So funktioniert es

So arbeitet Ihr AI Agent während Unterhaltungen:

1. Nutzer stellt eine Frage wie “Was ist mit den Issues zu Merkur?”
2. AI Agent holt relevante Informationen aus der Jira API mittels einer Abfrage wie “mercury”
3. AI Agent antwortet dem Nutzer basierend auf den vom API geholten Informationen

Bitte folgen Sie den Schritten unten. Die gesamte Einrichtung sollte nicht länger als 10 Minuten dauern!

Schritt 0 – Jira-Konto und Projekt erstellen

1. Gehen Sie zu id.atlassian.com/signup, erstellen und verifizieren Sie Ihr Konto.
2. Fügen Sie Jira zu Ihren Atlassian-Apps hinzu (der kostenlose Plan reicht für den Anfang).
3. Richten Sie Ihr erstes Projekt ein und erstellen Sie Tickets wie im Beispiel unten.

Beispiel-Board mit Jira-Issues

Schritt 1 – Jira API-Authentifizierungstoken

Gehen Sie zu id.atlassian.com/manage-profile/security/api-tokens und erstellen Sie Ihr API-Token, das etwa so aussieht:

ATATT3xFfGF01sKUl0HEW2-_-u9umfLSz7jeblmeLzEHZ1DLcdLbKeVF137iTHGkKhPuNMSKX8mkbwLpHXT4-qXEn-xNEnfiK8_XDVW6XXvGd_SBV3HD4kJInGNjfg2_yEoJFN6uwy4NRqeuhV2tjmyzxozLBRn35OhXkDA6QGfLFvf2_PKuNtA=8DA704E4

Damit Sie Ihr Atlassian API-Token in Quickchat AI Actions verwenden können, müssen Sie es zusammen mit Ihrer E-Mail-Adresse base64-codieren:

your_email@example.com:ATATT3xFfGF01sKUl0HEW2-_-u9umfLSz7jeblmeLzEHZ1DLcdLbKeVF137iTHGkKhPuNMSKX8mkbwLpHXT4-qXEn-xNEnfiK8_XDVW6XXvGd_SBV3HD4kJInGNjfg2_yEoJFN6uwy4NRqeuhV2tjmyzxozLBRn35OhXkDA6QGfLFvf2_PKuNtA=8DA704E4

Achten Sie darauf, die exakt gleiche E-Mail-Adresse zu verwenden, mit der Sie Ihr Atlassian-Konto eingerichtet haben.

Sie können ein einfaches Online-Tool wie base64encode.org verwenden.

Verwenden Sie den Live mode, der garantiert, dass die Kodierung vollständig in Ihrem Browser erfolgt.

Kostenloses Online-Tool zum Kodieren Ihres API-Tokens

Alternativ können Sie es auf Ihrem Rechner mit einem einfachen Python-Skript machen:

import base64

email = "your_email@example.com"
api_token = "ATATT3xFfGF01sKUl0HEW2-_-u9umfLSz7jeblmeLzEHZ1DLcdLbKeVF137iTHGkKhPuNMSKX8mkbwLpHXT4-qXEn-xNEnfiK8_XDVW6XXvGd_SBV3HD4kJInGNjfg2_yEoJFN6uwy4NRqeuhV2tjmyzxozLBRn35OhXkDA6QGfLFvf2_PKuNtA=8DA704E4"

credentials = f"{email}:{api_token}"
b64_credentials = base64.b64encode(credentials.encode("utf-8")).decode("utf-8")

print(f"Basic {b64_credentials}")

Das obige Skript gibt Ihnen einen einsatzbereiten Header mit dem kodierten Token aus, der etwa so aussieht:

Basic eW91cl9lbWFpbEBleGFtcGxlLmNvbTpBVEFUVDN4RmZHRjAxc0tVbDBIRVcyLV8tdTl1bWZMU3o3amVibG1lTHpFSFoxRExjZExiS2VWRjEzN2lUSEdrS2hQdU5NU0tYOG1rYndMcEhYVDQtcVhFbi14TkVuZmlLOF9YRFZXNlhYdkdkX1NCVjNIRDRrSkluR05qZmcyX3lFb0pGTjZ1d3k0TlJxZXVoVjJ0am15enhvekxCUm4zNU9oWGtEQTZRR2ZMRnZmMl9QS3VOdEE9OERBNzA0RTQ=

Schritt 2 – eine Quickchat AI Action erstellen

Gehen Sie in der Quickchat AI App zu Actions & MCPs und fügen Sie eine Action hinzu:

Seite der AI Action

Geben Sie Ihrer AI Action einen passenden Namen:

Name: Search Jira issues

AI Action Name einfügen

Schritt 3 – Eingabeparameter festlegen

Die Hauptaufgabe Ihres AI Agents besteht darin, das Anliegen des Nutzers in eine genaue Abfrage zu übersetzen, um Jira-Issues zu durchsuchen. Beim Suchen von Issues ist Jira kürzlich vollständig auf JQL (Jira Query Language) umgestiegen, um komplexere Suchen zu ermöglichen. Das macht Ihren AI Agent deutlich leistungsfähiger. Richten Sie Ihre Eingabeparameter wie folgt ein:

Format	Name	Beschreibung	Standardwert	Erforderlich
Text	jql	(siehe unten)	-	✅

Für eine starke Leistung Ihres AI Agents ist eine gut formulierte Beschreibung entscheidend:

Description:

A single valid JQL (Jira Query Language) string built per the description. Favor recall: prefer `(text ~ "term1" OR text ~ "term2")` over chaining with AND, add `status = "..."` only if requested, avoid custom fields, and use parentheses for grouping. Examples: `status = "In Progress" AND (text ~ "mercury" OR text ~ "venus")`, `(text ~ "planet*" OR text ~ "integration")`, `project = "Solar System" AND (text ~ "api" OR text ~ "integration")`.

Eine gut formulierte Parameterbeschreibung ist der Schlüssel zur Leistung des AI Agents

Schritt 4 – API-Endpunkt-URL festlegen

1. Wählen Sie GET als Action-Typ
2. Setzen Sie die Endpunkt-URL auf den Jira-Endpunkt /rest/api/3/search/jql

API-Endpunkt-URL festlegen

Achten Sie darauf, Ihre Atlassian-Domain zu verwenden. Sie finden diese in der URL Ihres Jira-Boards.

Ihre Atlassian-Domain

Schritt 5 – API-Request-Header festlegen

Definieren Sie Ihre Header wie folgt:

Accept	Autorization
application/json	Basic cGlvdHJAcXVpY2tjaGF0LmFpOkFUQVRUM3hGZkdGMGlQOVNacEhVZ1o5YUJfWGhmQjZJWjJId3MyaHlsMzEtTlNpYW90Z2tZVzRxQXEwQ3R4UVY1OXFTZkpWWVZNcXlxem42MWRkR0VobmJWNzdzaWtrb19ZWkhtLUgwazFOZGh4WlpQMnltYmZ1SzhBRmlFMnJEUmdqd182N1hkSFFUelFQY2I2U1lrNUFPRlRuVnZvaGxkZUd3djVpM2VrcEFyMVJ4QnJWRncyYz04MEZGQTcyMA==

Achten Sie besonders auf die korrekte Formatierung Ihres Authorization-Headers: Basic <base64-encoded email:api token>

API-Request-Header festlegen

Schritt 6 – API-Request-Query-Parameter festlegen

Setzen Sie zwei Query-Parameter für Ihren AI-Request:

• jql erhält einen dynamischen Wert, der zuvor im Abschnitt What to ask the user first definiert wurde. Es ist die Aufgabe des AI Agents, den Wert dieses Parameters basierend auf der Nutzereingabe zu füllen.
• fields erhält einen festen Wert. Für jedes Jira-Issue interessieren uns nur summary, description und status.

jql	fields
{{jql}}	summary,description,status

API-Request-Query-Parameter festlegen

Stellen Sie sicher, dass der Parameter jql korrekt auf den zuvor definierten Wert zeigt. Sie können ihn im Add AI Data-Dropdown auswählen.

Wählen Sie den dynamischen Parameter jql aus dem Dropdown

Schritt 7 – API Action-Beschreibung festlegen

Die letzte entscheidende Zutat einer gut eingerichteten AI Action ist ihre Beschreibung. Zwar versteht der AI Agent Ihren API-Endpunkt bereits gut anhand der URL und Parameter, dennoch ist es entscheidend, sein Verhalten für Ihren Anwendungsfall zu optimieren.

Die zwei wichtigsten Aspekte, die in der Prompt enthalten sind:

• Hinweise zur Nutzung der erweiterten JQL-Syntax beim Suchen nach Jira-Issues
• die Notwendigkeit, breit zu suchen, um Rückmeldungen ohne Ergebnisse zu vermeiden

Hier ist die resultierende API Action Description:

Infer the user’s intent and construct a single valid JQL that prioritizes recall over precision. Use `text ~ "..."` for contains (case-insensitive) domain / content terms (features, services, tasks, components, etc.). If multiple candidate terms exist, prefer OR and wrap in parentheses. Include `status = "..."` only when the user states a status. Never invent custom fields; only use standard fields like `text`, `status`, and `project` if explicitly mentioned. Keep queries short to avoid zero results. Use parentheses to make precedence explicit (AND binds tighter than OR). Example: `status = "In Progress" AND (text ~ "mercury" OR text ~ "venus")`.

Die Beschreibung muss präzise festhalten, wie der API-Request zu nutzen ist

Schritt 8 – die API Action testen

Bevor wir die AI Action in einer Unterhaltung testen, können wir prüfen, wie der API-Aufruf im Tab Test Response ausgeführt wird. Machen wir einen ersten Test mit der folgenden Abfrage, die alle Issues im Projekt zurückgeben sollte: project = "Solar System"

Suche nach allen Issues im Projekt Solar System

Unten sehen Sie die Testantwort. Wie erwartet listet sie die Felder summary, description und status für alle 6 Issues auf unserem Jira-Board auf.

Antwort listet alle Issues im Projekt Solar System

Probieren wir eine weitere Abfrage. Dieses Mal suchen wir nach allen Issues, die “mercury” erwähnen: text ~ "mercury"

Suche nach Issues, die mercury erwähnen

Wir haben nun validiert, dass die AI Action den API-Endpunkt korrekt aufruft. Jetzt können wir zu vollständigen Unterhaltungen mit dem AI Agent übergehen!

Schritt 9 – den AI Agent in Unterhaltungen testen

Gehen Sie zurück zur Quickchat AI App und testen Sie Ihren AI Agent in der Unterhaltungsvorschau.

Unterhaltung #1

AI Agent gibt eine Zusammenfassung aller Issues im Projekt

In dieser einfachen Unterhaltung gibt der AI Agent einen Überblick über alle Issues im Projekt. Ein Blick hinter die Kulissen zeigt, dass die exakte Abfrage gegen den API-Endpunkt war: project = "Solar System"

Unterhaltung #2

AI Agent beantwortet Fragen zu bestimmten Issues und Status

Hier wurde der AI Agent zu zwei Aspekten gefragt: einem spezifischen Issue und allgemein laufenden Issues. Ein Blick hinter die Kulissen zeigt, dass er die Jira API in zwei Schritten verwendet hat:

1. Prüfen, ob pluto in Arbeit ist:

status = "In Progress" AND (text ~ "pluto" OR text ~ "ongoing" OR text ~ "current" OR text ~ "active" OR text ~ "progress")

2. Prüfen, was sonst in Arbeit ist:

status = "In Progress"

Unterhaltung #3

AI Agent beantwortet eine kreative Anfrage 😉

Hier wollte ich den AI Agent herausfordern und stellte eine Frage, die etwas Kreativität erfordert. So wurde sie in eine JQL-Abfrage übersetzt:

(text ~ "planet" OR text ~ "upstream" OR text ~ "mercury" OR text ~ "venus")

Zusammenfassung

In diesem Artikel haben wir gezeigt, wie ein AI Agent so eingerichtet werden kann, dass er einen spezifischen API-Endpunkt kreativ in Unterhaltungen nutzt. Die korrekte Einrichtung ist nicht „out of the box“ – sie erfordert zusätzliche, detaillierte Informationen zu dem spezifischen Use Case. Sie können die in diesem Artikel gezeigten Prompts und Beschreibungen gerne wiederverwenden, um eigene, ähnliche AI Agents zu erstellen!

🎁  BONUS

Der obige Artikel wurde von einem Menschen (meiner Wenigkeit) geschrieben, könnte aber ebenso gut von AI verfasst worden sein. Zum Beispiel, indem Sie einen Prompt wie diesen in ChatGPT einfügen:

I need an API endpoint that allows me to search through my Jira tickets.

Guide me through the process step by step so that it is accessible to a moderately technical person:
- Provide links to documentation describing the endpoint
- Any necessary account creation and initial setup
- If any paid account is needed, indicate that clearly
- If any authentication such as API tokens is needed, guide me through the process of creating them and show me exactly every step needed to be able to use them as an HTTP request header. For example, if base64 encoding is needed, show a script or another way of achieving that.
- Show to me exactly what header keys and values I need for the HTTP request (show me header keys and values in a table)
- Show to me exactly what payload parameters I need for the HTTP request (show me payload parameter name and example values in a table)

Vielleicht möchten Sie in Zukunft nicht Jira-Tickets durchsuchen, sondern:

• Nachrichten in einen Slack-Kanal senden?
• Informationen aus einer Notion-Seite abrufen?
• Eine Aktion über Zapier ausführen?

Formulieren Sie das in dem ersten Satz und führen Sie den Prompt erneut aus! Sie erhalten hervorragende Anleitungen, um genau die AI Action hinzuzufügen, die Sie benötigen!