Jira-tickets doorzoeken met een aangepaste actie

Jira is geen ingebouwde Quickchat AI-integratie. Deze pagina werkt een voorbeeld uit van een aangepaste API-actie voor een externe REST API. Hetzelfde patroon werkt voor elke andere API.

In deze handleiding laat ik zien hoe je je AI-agent met Jira verbindt. We gebruiken:

• een Jira-account (gratis)
• een AI-agent van Quickchat (meld je hier aan en gebruik deze gratis)

Hiermee kan je Quickchat AI-agent:

• je Jira-tickets doorzoeken en
• slim vragen beantwoorden op basis van die tickets

We gebruiken AI-acties van Quickchat (aangepaste HTTP-acties) om je agent het endpoint Enhanced search for issues van de Jira-API (Atlassian) te laten aanroepen.

Maak een AI-agent die gebruikersinvoer creatief interpreteert

Optionele voorbeeldcontroles

• Bekijk een voorbeeld van een API-actieverzoek. Vul een opgegeven verzoeksjabloon in met synthetische voorbeeldwaarden zonder het te versturen. Laat authenticatieheaders weg.

• Bekijk JSONPath-resultaten. Controleer paden naar de root, velden, array-indexen en wildcards in opgegeven JSON. Dit voert geen actie uit en slaat niets op in het gespreksgeheugen.

In een compatibele browser zijn deze controles ook beschikbaar als websitetools. De links openen de standaardformulieren.

Bekijk de video

Play

Hoe het werkt

Zo zal je AI-agent tijdens gesprekken werken:

1. De gebruiker stelt een vraag zoals “hoe staat het met de issues over mercurius?”
2. De AI-agent haalt relevante informatie op uit de Jira-API met een zoekopdracht zoals “mercury”
3. De AI-agent antwoordt op basis van de informatie uit de API

Volg de onderstaande stappen. De volledige configuratie zou niet langer dan 10 minuten moeten duren!

Stap 0 - Een Jira-account en project aanmaken

1. Ga naar id.atlassian.com/signup, maak een account aan en verifieer het.
2. Voeg Jira toe aan je Atlassian-apps (het gratis abonnement is voldoende om te beginnen).
3. Stel je eerste project in en maak tickets aan zoals in het voorbeeld hieronder.

Een voorbeeldbord met Jira-issues

Stap 1 - Een authenticatietoken voor de Jira-API

Ga naar id.atlassian.com/manage-profile/security/api-tokens en maak een API-token aan dat er ongeveer zo uitziet:

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

Om je Atlassian-API-token in Quickchat AI-acties te kunnen gebruiken, moet je het met base64 coderen, samen met je e-mailadres:

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

Gebruik precies het e-mailadres waarmee je je Atlassian-account hebt aangemaakt

Je kunt een eenvoudige online tool zoals base64encode.org gebruiken.

Gebruik Live mode, zodat de codering volledig in je browser plaatsvindt.

Je kunt een gratis online tool gebruiken om je API-token te coderen

Je kunt het ook op je eigen computer doen met dit eenvoudige Python-script:

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}")

Het bovenstaande script geeft je een gebruiksklare header met het gecodeerde token, die er ongeveer zo uitziet:

Basic eW91cl9lbWFpbEBleGFtcGxlLmNvbTpBVEFUVDN4RmZHRjAxc0tVbDBIRVcyLV8tdTl1bWZMU3o3amVibG1lTHpFSFoxRExjZExiS2VWRjEzN2lUSEdrS2hQdU5NU0tYOG1rYndMcEhYVDQtcVhFbi14TkVuZmlLOF9YRFZXNlhYdkdkX1NCVjNIRDRrSkluR05qZmcyX3lFb0pGTjZ1d3k0TlJxZXVoVjJ0am15enhvekxCUm4zNU9oWGtEQTZRR2ZMRnZmMl9QS3VOdEE9OERBNzA0RTQ=

Stap 2 - Een Quickchat AI-actie aanmaken

Ga in de Quickchat AI-app naar Acties en MCP’s en voeg een actie toe:

De pagina voor AI-acties

Geef je AI-actie een passende naam:

Naam: Search Jira issues

Vul de naam van de AI-actie in

Stap 3 - Invoerparameters instellen

De belangrijkste taak van je AI-agent is om de vraag van de gebruiker om te zetten in een exacte zoekopdracht voor Jira-issues. Jira is voor het zoeken naar issues onlangs volledig overgestapt op JQL (Jira Query Language), waarmee complexere zoekopdrachten mogelijk zijn. Dit maakt je AI-agent veel krachtiger. Stel de invoerparameters als volgt in:

Formaat	Naam	Beschrijving	Standaardwaarde	Verplicht
Text	jql	(zie hieronder)	-	✅

Een zorgvuldig geformuleerde beschrijving is bijzonder belangrijk voor goede prestaties van je AI-agent:

Beschrijving:

A single valid JQL (Jira Query Language) string built per the description. Favor recall: prefer `(text ~ "term1" OR text ~ "term2")` over chaining with AND, and use parentheses for grouping. For "not started / in progress / done" questions, filter on `statusCategory` ("To Do", "In Progress", "Done"), which is stable across projects; use `status = "..."` only when the user names a specific status that exists on the board. Avoid custom fields. Examples: `statusCategory = "In Progress" AND (text ~ "mercury" OR text ~ "venus")`, `(text ~ "planet*" OR text ~ "integration")`, `project = "Solar System" AND statusCategory = "To Do"`.

Een zorgvuldig geformuleerde parameterbeschrijving is essentieel voor de prestaties van de AI-agent

Een opmerking over Jira-statussen

Jira maakt onderscheid tussen de naam en categorie van een status, en JQL behandelt deze verschillend:

• De statusnaam is wat op het bord wordt weergegeven. Het ene project gebruikt To Do / In Progress / Done, het andere Open / In Review / Closed.
• De statuscategorie is een van drie vaste groepen waaraan elke status is gekoppeld: To Do, In Progress, Done.

status = "To Do" filtert op naam en geeft dus niets terug op een bord waarvan de eerste kolom Open heet. Dit is een veelvoorkomende reden waarom een agent vol vertrouwen meldt dat er “geen openstaande tickets” zijn terwijl het bord er vol mee staat. Filter voor vragen over “wat nog niet is gestart”, “wat in uitvoering is” en “wat klaar is” op de categorie:

statusCategory = "To Do"
statusCategory = "In Progress"
statusCategory = "Done"

Gebruik status = "..." wanneer de gebruiker een specifieke status noemt waarvan je weet dat die op het bord bestaat. Je kunt ook de werkelijke statusnamen van je bord in de actiebeschrijving opnemen (stap 7), zodat de agent een verzoek als “klaar voor QA” aan de juiste status koppelt.

Stap 4 - De API-endpoint-URL instellen

1. Kies GET als methode voor het API-verzoek
2. Stel de endpoint-URL in op het Jira-endpoint /rest/api/3/search/jql

Stel je API-endpoint-URL in

Gebruik je eigen Atlassian-domeinnaam. Je vindt deze in de URL van je Jira-bord.

Je Atlassian-domeinnaam

Stap 5 - Headers voor het API-verzoek instellen

Definieer de headers voor je API-verzoek als volgt:

Accept	Autorization
application/json	Basic cGlvdHJAcXVpY2tjaGF0LmFpOkFUQVRUM3hGZkdGMGlQOVNacEhVZ1o5YUJfWGhmQjZJWjJId3MyaHlsMzEtTlNpYW90Z2tZVzRxQXEwQ3R4UVY1OXFTZkpWWVZNcXlxem42MWRkR0VobmJWNzdzaWtrb19ZWkhtLUgwazFOZGh4WlpQMnltYmZ1SzhBRmlFMnJEUmdqd182N1hkSFFUelFQY2I2U1lrNUFPRlRuVnZvaGxkZUd3djVpM2VrcEFyMVJ4QnJWRncyYz04MEZGQTcyMA==

Let goed op de juiste opmaak van je Authorization-header: Basic <base64-encoded email:api token>

Stel de headers voor je API-verzoek in

Stap 6 - Queryparameters voor het API-verzoek instellen

Stel twee queryparameters voor je API-verzoek in:

• jql krijgt een dynamische waarde die eerder in het onderdeel Wat je eerst aan de gebruiker vraagt is gedefinieerd. De AI-agent vult de waarde van deze parameter in op basis van wat de gebruiker heeft gezegd in het gesprek.
• fields krijgt een vaste waarde. Voor elke Jira-issue zijn we alleen geïnteresseerd in de samenvatting, beschrijving en status.

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

Stel de queryparameters voor je API-verzoek in

Zorg dat de parameter jql correct verwijst naar de eerder gedefinieerde waarde. Je kunt deze selecteren via de keuzelijst AI-gegevens toevoegen.

Selecteer de dynamische parameter jql in de keuzelijst

Stap 7 - De beschrijving van de API-actie instellen

De laatste essentiële bouwsteen van een goed ingestelde AI-actie is de beschrijving. Hoewel de AI-agent je API-endpoint al redelijk begrijpt op basis van de URL en parameters, is het belangrijk zijn gedrag te optimaliseren voor jouw toepassing.

De drie belangrijkste aspecten in de prompt zijn:

• wanneer de actie moet worden aangeroepen: vermeld alle mogelijke formuleringen van gebruikers (vinden / zoeken / opzoeken, maar ook uitleggen / vertellen over / beschrijven / wat is / wat is de status van), zodat de agent de aanroep niet overslaat wanneer de gebruiker niet “zoeken” zegt
• suggesties voor het gebruik van geavanceerde JQL-syntaxis bij het zoeken naar Jira-issues
• hoe lege resultaten moeten worden afgehandeld: de agent moet expliciet melden dat er geen resultaten zijn, in plaats van toegang te weigeren

Dit is de resulterende Beschrijving van API-actie:

Use this action whenever the user asks anything that could be answered by data in their Jira — projects, issues, statuses, sprints, test cycles, descriptions, owners, comments — regardless of how they phrase the request (find / search / look for / explain / tell me about / describe / what is / how is the status of, etc.). Do not refuse access; query Jira first.

Construct a JQL that prioritises recall over precision: prefer `(text ~ "term1" OR text ~ "term2")` over chaining with AND, and use parentheses for grouping. For lifecycle questions (not started, in progress, done) filter on `statusCategory` ("To Do" / "In Progress" / "Done") rather than `status`, because status names vary by board; use `status = "..."` only when the user names a specific status. Avoid custom fields.

If Jira returns no matches, say so explicitly to the user and suggest a refined query.

Stap 8 - De API-actie testen

Voordat we de AI-actie in een gesprek testen, kunnen we op het tabblad Antwoord testen controleren hoe de API wordt aangeroepen. We testen eerst deze zoekopdracht, die alle issues in het project zou moeten teruggeven: project = "Solar System"

Zoeken naar alle issues in het project Solar System

Hieronder staat het antwoord dat we ontvangen. Zoals verwacht bevat het de samenvatting, beschrijving en status van alle 6 issues op ons Jira-bord.

Het antwoord bevat alle issues in het project Solar System

Laten we nog een zoekopdracht proberen. Deze keer zoeken we alle issues waarin “mercury” wordt genoemd: text ~ "mercury"

Zoeken naar issues waarin mercury wordt genoemd

We hebben nu gecontroleerd dat de AI-actie ons API-endpoint correct aanroept. We kunnen verdergaan met het testen van volledige gesprekken met de AI-agent!

Stap 9 - De AI-agent in gesprekken testen

Ga terug naar de Quickchat AI-app en test je AI-agent in de gespreksvoorvertoning.

Gesprek #1

De AI-agent geeft een samenvatting van alle issues in het project

In dit eenvoudige gesprek geeft de AI-agent een overzicht van alle issues in het project. Achter de schermen zien we dat de exacte zoekopdracht naar het API-endpoint was: project = "Solar System"

Gesprek #2

De AI-agent beantwoordt vragen over specifieke issues en statussen

In dit geval kreeg de AI-agent vragen over twee afzonderlijke onderwerpen: een specifieke issue en lopende issues in het algemeen. Achter de schermen zien we dat de agent ervoor koos de Jira-API in twee stappen te gebruiken:

1. Controleren of pluto in uitvoering is:

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

2. Controleren wat er verder in uitvoering is:

status = "In Progress"

Gesprek #3

De AI-agent beantwoordt een creatieve vraag 😉

In dit geval wilde ik de AI-agent uitdagen met een vraag die enige creativiteit vereist om correct te interpreteren. Zo werd die omgezet in een JQL-zoekopdracht:

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

Probeer deze formuleringen

Om zeker te weten dat de AI-actie wordt aangeroepen ongeacht hoe eindgebruikers hun verzoek formuleren, probeer je elk van de onderstaande prompts in je testscenario. De agent moet bij elke prompt Jira raadplegen, niet alleen bij expliciete zoekvragen:

• “vind alle openstaande issues over live uitslagen”
• “zoek naar issues met mercury”
• “leg het Solar System-project uit”
• “vertel me over de openstaande issues in deze sprint”
• “beschrijf wat momenteel in uitvoering is”
• “wat is de status van pluto?”

Als een van deze formuleringen de AI-actie niet aanroept, controleer je of de beschrijving van je API-actie (stap 7) deze werkwoorden expliciet vermeldt.

Wat je kunt verwachten als Jira geen passende issues heeft

Wanneer Jira geen resultaten teruggeeft, moet je AI-agent dat expliciet zeggen, bijvoorbeeld: “Ik heb Jira gecontroleerd en geen passende issues gevonden voor je zoekopdracht. Probeer een bredere formulering of verwijder het statusfilter.”

Als de agent in plaats daarvan antwoordt met “Ik heb geen directe toegang tot je Jira”, is de AI-actie helemaal niet uitgevoerd. Controleer de beschrijving uit stap 7 opnieuw en zorg dat deze werkwoorden bevat die niet rechtstreeks naar zoeken verwijzen (explain, tell me about, describe, what is).

Samenvatting

In deze handleiding lieten we zien hoe je een AI-agent kunt instellen om een specifiek API-endpoint creatief in gesprekken te gebruiken. De juiste configuratie werkt niet vanzelf: je moet gedetailleerde informatie geven over de specifieke toepassing die je voor ogen hebt. Gebruik de prompts en beschrijvingen uit deze handleiding gerust voor je eigen vergelijkbare AI-agents!

Liever een uitgebreide uitleg met toelichting? Dezelfde configuratie staat ook in een blogartikel op quickchat.ai. Deze documentatiepagina is de officiële referentie die voortdurend wordt bijgewerkt.

Verder gaan

Een Jira-actie hoeft niet uit één vast verzoek te bestaan. Je kunt ingebouwde gespreksvariabelen en opgeslagen metadata (zoals de taal van de bezoeker of eerder vastgelegde waarden) in elk veld invoegen. Je kunt ook meerdere acties toevoegen, zodat de agent per vraag de juiste kiest. Bekijk de actiereferentie voor alle mogelijkheden.

🎁  BONUS

Deze handleiding is geschreven door een mens (ondergetekende), maar had net zo goed door AI kunnen zijn geschreven. Bijvoorbeeld door een prompt als deze in ChatGPT te plakken:

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)

Misschien wil je in de toekomst, in plaats van Jira-tickets doorzoeken:

• berichten naar een Slack-kanaal sturen?
• informatie van een Notion-pagina ophalen?
• een actie via Zapier uitvoeren?

Vermeld dat in de eerste zin en voer de prompt opnieuw uit! Je krijgt dan prima instructies om precies de AI-actie toe te voegen die je nodig hebt!