Özel Eylem ile Jira kayıtlarında arama

Jira, yerleşik bir Quickchat AI entegrasyonu değildir. Bu sayfa, üçüncü taraf REST API’si için Özel API Eylemi oluşturmanın uygulamalı bir örneğidir; aynı yöntem diğer API’ler için de kullanılabilir.

Bu yazıda AI Temsilcinizi Jira’ya nasıl bağlayacağınızı göstereceğim. Şunları kullanacağız:

• bir Jira hesabı (ücretsiz)
• bir Quickchat AI Temsilcisi (buradan kaydolun ve ücretsiz kullanın)

Böylece Quickchat AI Temsilciniz:

• Jira kayıtlarınızda arama yapabilecek ve
• bu kayıtlara dayalı soruları akıllıca yanıtlayabilecektir

Temsilcinizin Jira (Atlassian) API’sinin Enhanced search for issues uç noktasını çağırmasını sağlamak için Quickchat AI Eylemlerini (özel HTTP eylemleri) kullanacağız.

Kullanıcı girdilerini yaratıcı biçimde yorumlayan bir AI Temsilcisi oluşturun

İsteğe bağlı örnek kontroller

• API Eylemi isteğini önizleyin. Sağlanan istek şablonunu, isteği göndermeden sentetik örnek değerlerle oluşturun. Kimlik bilgisi başlıklarını eklemeyin.

• JSONPath eşleşmelerini önizleyin. Sağlanan JSON üzerinde kök, alan, dizi dizini ve joker karakter yollarını kontrol edin. Bu işlem Eylem çalıştırmaz veya konuşma belleğine kayıt yapmaz.

Uyumlu tarayıcılarda bu kontroller site araçları olarak da kullanılabilir. Bağlantılar standart formları açar.

Videoyu izleyin

Play

Nasıl çalışır

AI Temsilciniz konuşmalar sırasında şöyle çalışır:

1. Kullanıcı “mercury ile ilgili kayıtlarda neler oluyor?” gibi bir soru sorar
2. AI Temsilcisi “mercury” gibi bir sorgu kullanarak Jira API’sinden ilgili bilgileri alır
3. AI Temsilcisi API’den alınan bilgilere dayanarak kullanıcıyı yanıtlar

Aşağıdaki adımları izleyin. Kurulumun tamamı 10 dakikadan fazla sürmemelidir!

Adım 0 - Jira hesabı ve proje oluşturun

1. id.atlassian.com/signup adresine gidin, hesabınızı oluşturun ve doğrulayın.
2. Atlassian uygulamalarınıza Jira’yı ekleyin (başlangıç için ücretsiz plan yeterlidir).
3. İlk projenizi oluşturun ve aşağıdaki örnekteki gibi kayıtlar ekleyin.

Jira kayıtları içeren örnek pano

Adım 1 - Jira API kimlik doğrulama belirteci

id.atlassian.com/manage-profile/security/api-tokens adresine gidin ve aşağıdakine benzer bir API belirteci oluşturun:

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

Atlassian API belirtecinizi Quickchat AI Eylemlerinde kullanabilmek için e-posta adresinizle birlikte base64 biçiminde kodlamanız gerekir:

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

Atlassian hesabınızı oluştururken kullandığınız e-posta adresini aynen eklediğinizden emin olun

base64encode.org gibi basit bir çevrimiçi araç kullanabilirsiniz.

Kodlamanın tamamen tarayıcınızda gerçekleşmesini sağlayan Live mode seçeneğini kullanın.

API belirtecinizi kodlamak için ücretsiz bir çevrimiçi araç kullanabilirsiniz

Alternatif olarak, bilgisayarınızda basit bir Python betiği ile şöyle yapabilirsiniz:

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

Yukarıdaki betik, kodlanmış belirteci içeren ve aşağıdakine benzeyen kullanıma hazır bir başlık verir:

Basic eW91cl9lbWFpbEBleGFtcGxlLmNvbTpBVEFUVDN4RmZHRjAxc0tVbDBIRVcyLV8tdTl1bWZMU3o3amVibG1lTHpFSFoxRExjZExiS2VWRjEzN2lUSEdrS2hQdU5NU0tYOG1rYndMcEhYVDQtcVhFbi14TkVuZmlLOF9YRFZXNlhYdkdkX1NCVjNIRDRrSkluR05qZmcyX3lFb0pGTjZ1d3k0TlJxZXVoVjJ0am15enhvekxCUm4zNU9oWGtEQTZRR2ZMRnZmMl9QS3VOdEE9OERBNzA0RTQ=

Adım 2 - Quickchat AI Eylemi oluşturun

Quickchat AI uygulamasında Eylemler ve MCP’ler bölümüne gidin ve bir eylem ekleyin:

AI Eylemi sayfası

AI Eyleminize uygun bir ad verin:

Ad: Search Jira issues

AI Eylemi adını girin

Adım 3 - Girdi parametrelerini ayarlayın

AI Temsilcinizin temel görevi, kullanıcının sorusunu Jira kayıtlarını aramak için kullanılacak kesin bir sorguya dönüştürmektir. Jira, daha karmaşık aramalara olanak tanımak için kayıt aramasını yakın zamanda tamamen JQL (Jira Query Language) sistemine geçirdi. Bu, AI Temsilcinizi çok daha güçlü kılar. Girdi parametrelerini şöyle ayarlayın:

Biçim	Ad	Açıklama	Varsayılan değer	Gerekli
Text	jql	(aşağıya bakın)	-	✅

AI Temsilcinizin iyi performans göstermesi için özenle hazırlanmış bir açıklama çok önemlidir:

Açıklama:

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"`.

Özenle hazırlanmış bir parametre açıklaması, AI Temsilcisi performansının anahtarıdır

Jira durumları hakkında not

Jira, durumun adını ve kategorisini ayırır; JQL bunları farklı şekilde işler:

• Durum adı, panoda gösterilen addır. Bir projede To Do / In Progress / Done, diğerinde Open / In Review / Closed kullanılır.
• Durum kategorisi, her durumun eşlendiği üç sabit gruptan biridir: To Do, In Progress, Done.

status = "To Do" ada göre filtreler; bu nedenle ilk sütununun adı Open olan panoda sonuç döndürmez. Pano kayıtlarla doluyken temsilcinin kendinden emin şekilde “yapılacak kayıt yok” demesinin yaygın nedenlerinden biri budur. “Neye başlanmadı”, “ne devam ediyor” ve “ne tamamlandı” sorularında bunun yerine kategoriye göre filtreleyin:

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

Kullanıcının panoda bulunduğunu bildiğiniz belirli bir durum adını söylediği durumlarda status = "..." kullanın. Temsilcinin “QA için hazır” gibi bir isteği doğru durumla eşleştirmesi için panonuzun gerçek durum adlarını Eylem açıklamasına (Adım 7) da ekleyebilirsiniz.

Adım 4 - API uç nokta URL’sini ayarlayın

1. API istek yöntemi olarak GET seçin
2. Uç nokta URL’sini Jira /rest/api/3/search/jql uç noktasına ayarlayın

API uç nokta URL’nizi ayarlayın

Kendi Atlassian alan adınızı kullanın. Bunu Jira panonuzun URL’sinde bulabilirsiniz.

Atlassian alan adınız

Adım 5 - API istek başlıklarını ayarlayın

API istek başlıklarını şöyle tanımlayın:

Accept	Autorization
application/json	Basic cGlvdHJAcXVpY2tjaGF0LmFpOkFUQVRUM3hGZkdGMGlQOVNacEhVZ1o5YUJfWGhmQjZJWjJId3MyaHlsMzEtTlNpYW90Z2tZVzRxQXEwQ3R4UVY1OXFTZkpWWVZNcXlxem42MWRkR0VobmJWNzdzaWtrb19ZWkhtLUgwazFOZGh4WlpQMnltYmZ1SzhBRmlFMnJEUmdqd182N1hkSFFUelFQY2I2U1lrNUFPRlRuVnZvaGxkZUd3djVpM2VrcEFyMVJ4QnJWRncyYz04MEZGQTcyMA==

Authorization başlığını doğru biçimlendirmeye özellikle dikkat edin: Basic <base64-encoded email:api token>

API istek başlıklarını ayarlayın

Adım 6 - API isteği sorgu parametrelerini ayarlayın

AI isteğiniz için iki sorgu parametresi ayarlayın:

• jql, daha önce Önce kullanıcıya ne sorulmalı bölümünde tanımlanan dinamik değeri alır. Bu parametrenin değerini konuşmada kullanıcının söylediklerine göre doldurmak AI Temsilcisinin görevidir.
• fields, sabit bir değer alır. Her Jira kaydı için yalnızca özet, açıklama ve durum ile ilgileniyoruz.

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

API isteği sorgu parametrelerini ayarlayın

jql parametresinin daha önce tanımlanan değeri doğru gösterdiğinden emin olun. Bunu AI verisi ekle açılır menüsünden seçebilirsiniz.

Açılır menüden dinamik jql parametresini seçin

Adım 7 - API Eylemi açıklamasını ayarlayın

İyi yapılandırılmış bir AI Eyleminin son önemli bileşeni açıklamasıdır. AI Temsilcisi API uç noktanızı yalnızca URL ve parametrelerinden bile iyi anlasa da davranışını kullanım durumunuza göre iyileştirmek önemlidir.

İstemde yer alan en önemli üç konu şunlardır:

• eylemin ne zaman çağrılacağı: kullanıcının seçebileceği tüm ifadeleri (bul / ara / arama yap ve açıkla / bana anlat / tarif et / nedir / durumu nasıl) sıralamak, kullanıcının “ara” demediği durumlarda temsilcinin çağrıyı atlamasını önler
• Jira kayıtlarını ararken gelişmiş JQL sözdiziminin kullanımına ilişkin öneriler
• boş sonuçların nasıl ele alınacağı: temsilci erişimi olmadığını söylemek yerine sonuç bulunmadığını açıkça belirtmelidir

Ortaya çıkan API Eylemi Açıklaması şöyledir:

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.

Adım 8 - API Eylemini test edin

AI Eylemini konuşmada test etmeden önce API’nin nasıl çağrıldığını Yanıtı test et sekmesinde sınayabiliriz. Projedeki tüm kayıtları döndürmesi gereken şu sorguyla ilk testi yapalım: project = "Solar System"

Solar System projesindeki tüm kayıtları arama

Aldığımız test yanıtı aşağıdadır. Beklendiği gibi, Jira panomuzdaki altı kaydın tamamı için özet, açıklama ve durum alanlarını listeler.

Yanıt, Solar System projesindeki tüm kayıtları listeler

Bir sorgu daha deneyelim. Bu kez “mercury” geçen tüm kayıtları arayalım: text ~ "mercury"

mercury geçen kayıtları arama

AI Eyleminin API uç noktamızı doğru çağırdığını doğruladık. Artık AI Temsilcisiyle tam konuşmaları test etmeye geçebiliriz!

Adım 9 - AI Temsilcisini konuşmalarda test edin

Quickchat AI uygulamasına dönün ve konuşma önizlemesinde AI Temsilcinizi test edin.

Konuşma #1

AI Temsilcisi projedeki tüm kayıtların özetini verir

Bu basit konuşmada AI Temsilcisi projedeki tüm kayıtlara genel bakış sunar. Arka planda API uç noktasına gönderdiği sorgunun tam olarak şu olduğunu görürüz: project = "Solar System"

Konuşma #2

AI Temsilcisi belirli kayıtlara ve durumlara ilişkin soruları yanıtlar

Bu örnekte AI Temsilcisine iki ayrı konu sorulmuştur: belirli bir kayıt ve genel olarak devam eden kayıtlar. Arka plana baktığımızda Jira API’sini iki adımda kullanmaya karar verdiğini görürüz:

1. pluto kaydının devam edip etmediğini kontrol et:

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

2. Başka nelerin devam ettiğini kontrol et:

status = "In Progress"

Konuşma #3

AI Temsilcisi yaratıcı bir sorguyu yanıtlar 😉

Bu örnekte AI Temsilcisini zorlamak istedim ve doğru yorumlamak için biraz yaratıcılık gerektiren bir soru sordum. Sorunun JQL sorgusuna dönüşümü şöyle oldu:

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

Bu ifadeleri deneyin

Son kullanıcılarınız isteklerini nasıl ifade ederse etsin AI Eyleminin çalıştığından emin olmak için aşağıdaki istemlerin her birini test senaryonuzda çalıştırın. Temsilci yalnızca arama biçimindeki sorularda değil, hepsinde Jira’yı sorgulamalıdır:

• “canlı skorlarla ilgili tüm açık kayıtları bul”
• “mercury içeren kayıtları ara”
• “Solar System projesini açıkla”
• “bu sprintteki açık kayıtları bana anlat”
• “şu anda nelerin devam ettiğini tarif et”
• “pluto’nun durumu nedir?”

Bu ifadelerden biri AI Eylemini çağırmıyorsa API Eylemi açıklamanızda (Adım 7) bu fiillerin açıkça yer aldığını kontrol edin.

What to expect when Jira has no matching issues

Jira sıfır sonuç döndürdüğünde AI Temsilciniz bunu açıkça belirtmelidir. Örneğin: “Jira’yı kontrol ettim ve sorgunuzla eşleşen kayıt bulamadım. Daha genel bir ifade deneyin veya durum filtresini kaldırın.”

Bunun yerine temsilcinin “Jira’nıza doğrudan erişimim yok” dediğini görüyorsanız AI Eylemi hiç çalışmamıştır. Adım 7’deki açıklamayı yeniden kontrol edin ve arama dışındaki fiilleri (explain, tell me about, describe, what is) açıkça listelediğini doğrulayın.

Özet

Bu yazıda, bir AI Temsilcisinin konuşmalarda belirli bir API uç noktasını yaratıcı biçimde kullanacak şekilde nasıl yapılandırılacağını gösterdik. Doğru kurulum kendiliğinden oluşmaz; hedeflediğimiz kullanım durumuna ilişkin ayrıntılı ek bilgi vermeyi gerektirir. Kendi benzer AI Temsilcilerinizi oluşturmak için bu yazıdaki istemleri ve açıklamaları yeniden kullanabilirsiniz!

Ayrıntılı, anlatımlı bir rehberi mi tercih edersiniz? Aynı kurulum quickchat.ai blog yazısında da ele alınır. Bu dokümantasyon sayfası sürekli güncellenen asıl başvuru kaynağıdır.

Daha ileri seçenekler

Bir Jira eyleminin tek bir sabit istek olması gerekmez. Herhangi bir alana yerleşik konuşma değişkenleri ve kaydedilmiş meta veriler (ziyaretçinin dili veya konuşmada daha önce alınmış değerler gibi) ekleyebilir, temsilcinin her soru için doğru olanı seçmesi amacıyla birden çok eylem tanımlayabilirsiniz. Tüm seçenekler için Eylemler başvurusuna bakın.

🎁  BONUS

Yukarıdaki yazıyı bir insan (yani ben) yazdı, ancak AI da yazabilirdi. Örneğin ChatGPT’ye şöyle bir istem yapıştırarak:

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)

Gelecekte Jira kayıtlarını aramak yerine şunları yapmak isteyebilirsiniz:

• Slack kanalına mesaj göndermek?
• Notion sayfasından bilgi almak?
• Zapier üzerinden bir eylem gerçekleştirmek?

Bunu ilk cümlede belirtin ve istemi tekrar çalıştırın! Tam olarak ihtiyaç duyduğunuz AI Eylemini eklemek için uygun talimatlar alacaksınız!