JQL ile Jira’da sorgu yazmak ve filtre olarak kaydetmek

JQL nedir, neden öğrenilir?

JQL (Jira Query Language), Jira'da iş öğelerini (issue) arayıp süzmek için kullanılan sorgu dilidir. Temel arama kutuları proje, durum, atanan kişi gibi alanlarda seçim yapmanıza izin verir; JQL ise aynı aramayı yazı ile ifade ederek çok daha ayrıntılı koşullar kurmanıza imkân tanır: "benim üzerimdeki, öncelik orta ve üstü, durumu henüz bitmemiş işler, eskiden yeniye sıralı" gibi.

Neden öğrenmeye değer? Çünkü Jira'da neredeyse her toplu görünüm bir aramanın üzerine kuruludur. Kaydedilmiş bir arama filtre olur; filtreler panolarda gösterge olarak (gadget), raporlarda ve e-posta aboneliklerinde kullanılır. Atlassian'ın belgelerine göre arama sonucu bir filtre olarak kaydedilince meslektaşlarla paylaşılabilir, e-postayla gönderilebilir, favorilere eklenebilir, belirlediğiniz programla e-postanıza gelebilir ve bir gösterge panosunda görüntülenebilir. Yani doğru yazılmış tek bir sorgu, yönetici raporundan günlük toplantıya kadar birçok yerde tekrar tekrar kullanılır.

JQL'in öğrenilmesi kolaydır çünkü yapısı tutarlıdır: alan, işleç, değer. Karmaşık görünen sorgular bu üçlünün birbirine bağlanmasından ibarettir.

Bir JQL cümlesinin anatomisi

Bir JQL koşulu (clause) şu parçalardan oluşur: bir alan (project, status, assignee gibi), bir işleç (=, !=, IN, ~, > gibi) ve bir ya da daha fazla değer ya da işlev. Atlassian belgelerindeki temel örnek project = "TEST" koşuludur: TEST projesindeki tüm iş öğelerini bulur.

Birden çok koşul AND ve OR anahtar sözcükleriyle bağlanır, NOT ise bir koşulu tersine çevirir. Sonuçların sırası ORDER BY ile belirlenir. Örnek:

project = "MUS" AND assignee = currentUser() ORDER BY created

Bu sorgu MUS projesinde, giriş yapmış kişiye atanmış tüm işleri oluşturulma tarihine göre sıralar. currentUser() sorguyu kimin çalıştırdığına göre değişen bir işlevdir; paylaşılan bir filtrede herkes kendi işlerini görür.

Sorguyu soldan sağa değil, soru sırasıyla kurmak kolaylık sağlar. Önce kapsamı daraltın (proje), sonra durum, kişi ve öncelik gibi süzgeçleri ekleyin, en sonda sıralayın. Her eklemeden sonra sonucu çalıştırıp bakmak, hatayı ilk yaptığınız yerde yakalamanızı sağlar.

İşleçler: eşitlik, liste, metin ve karşılaştırma

Sık kullanılan işleçler şöyle özetlenebilir:

• = ve !=: tam eşleşme ya da eşit olmama. status = "In Progress".
• IN: bir listeden herhangi bir değer. project IN (MUS, SAT). OR ile birden çok eşitlik yazmaktan kısa ve okunurdur.
• ~ ve !~: metin içerir ve içermez. summary ~ "fatura" gibi. Atlassian belgeleri, != işlecinin metin alanlarında kullanılamadığını ve bu iş için !~ gerektiğini söyler.
• >, >=, <, <=: sıralı alanlarda karşılaştırma, örneğin öncelik ya da tarih.
• IS EMPTY ve IS NOT EMPTY: alanın boş ya da dolu olması. assignee IS EMPTY, kimseye atanmamış işleri bulur.

Çok sözcüklü değerler tırnak içine alınır: status = "In Progress". Tek sözcükler çoğu zaman tırnaksız yazılabilir, ama alışkanlık olarak tırnak kullanmak hata riskini azaltır.

Alan adları ve değerler Jira kurulumunuza göre değişebilir. Durum adları, öncelik adları ve özel alanlar yöneticinin yaptığı tanımlara bağlıdır; bir sorgu bir projede çalışırken diğerinde sonuç vermiyorsa ilk kontrol edilecek şey bu adların birebir aynı olup olmadığıdır.

En sık tuzaklar: boş alanlar ve parantez

JQL'de bazı hatalar hata mesajı vermeden sonucu bozar.

İlki, != ile boş alanların sonuçta kaybolmasıdır. Atlassian belgeleri, != işlecinin boş alanları eşleştirmediğini söyler. component != fred sorgusu "bileşeni fred olmayan tüm işleri" getirmez, yalnızca bileşeni dolu olup fred olmayanları getirir. Bileşeni boş işleri de istiyorsanız component != fred OR component IS EMPTY yazmak gerekir. Aynı mantık atanan kişi, sürüm ve etiket gibi boş olabilen tüm alanlar için geçerlidir.

Sonraki hata, parantezsiz AND ve OR karışımıdır. Belgelere göre parantez yoksa ifade soldan sağa değerlendirilir; yani yazdığınız mantık sizin düşündüğünüzden farklı gruplanabilir. status = "To Do" OR status = "In Progress" AND assignee = currentUser() sorgusunda niyet, kişiye atanmış ve bu durumlardan birindeki işleri bulmak olabilir; ama soldan sağa değerlendirme sonucu farklı gruplar. Karşıt koşulları açıkça gruplayın: (status = "To Do" OR status = "In Progress") AND assignee = currentUser(). Daha da iyisi, durumları IN ile listeleyip parantez gereğini ortadan kaldırmaktır.

Bu tuzaklar, bir panoda sessizce yanlış sayı gösteren filtrelerin en yaygın nedenidir. Önemli bir filtreyi paylaşmadan önce sonuç listesinden birkaç iş öğesini elle açıp koşula uyduklarını doğrulayın.

Gerçek işte kullanılan sorgu örnekleri

Şu örnekler gündelik ihtiyaçları karşılar. Proje anahtarı MUS örnek olarak seçilmiştir; kendi proje anahtarınızla değiştirin.

Bana atanmış, bitmemiş işler: project = "MUS" AND assignee = currentUser() AND status IN ("To Do", "In Progress") ORDER BY created

Henüz kimseye atanmamış, bekleyen işler: project = "MUS" AND assignee IS EMPTY AND status = "To Do"

Önceliği orta ve üzeri olan açık işler: project = "MUS" AND status IN ("To Do", "In Progress") AND priority >= Medium ORDER BY priority

Özetinde belirli bir sözcük geçen işler: project = "MUS" AND summary ~ "fatura"

Bir ekip toplantısı için bu sorguların birkaçı kaydedilir ve her biri bir pano göstergesine bağlanır. Böylece "atanmamış işler" ve "yüksek öncelikli açık işler" tek bakışta görünür.

Sorgu yazarken bir iş sorusu olarak başlamak faydalıdır: "Bugün kime dönmem gerekiyor?", "Hangi iş sahipsiz?", "Sprint'te riskli olan ne?" Soruyu önce cümleyle yazın, sonra alanlara çevirin. Sorgu çalışmıyorsa genellikle hata JQL sözdiziminde değil, sorunun belirsizliğindedir.

Aramayı filtre olarak kaydetmek ve sürdürmek

Doğru sonucu veren bir sorgu, yalnızca bir kez kullanılacaksa gerekli değildir ama tekrar kullanılacaksa kaydedilmelidir. Atlassian belgeleri kaydedilmiş aramanın birkaç şey sağladığını söyler: meslektaşlarınızla paylaşmak, favori listesi oluşturmak, sonuçları belirlediğiniz programla e-postayla almak, sonuçları dışa aktarmak, rapor biçiminde göstermek ve gösterge panosunda göstermek.

Filtre kaydederken şu alışkanlıklar işinizi kolaylaştırır: • Anlamlı ve açıklayıcı bir ad verin: "MUS - atanmamış açık işler". "Filtre kopya" adı kimseye bir şey söylemez. • Kim görebilecek ve kim değiştirebilecek, bunu bilinçli belirleyin. Paylaşılan bir filtreyi düzenleyen herkes, onu kullanan panoları da etkiler. • Filtreyi sorgudaki alan adı ya da durum değiştiğinde güncelleyin. Bir iş akışı durumu yeniden adlandırıldığında, o durumu adıyla süzen filtreler sessizce boş sonuç döndürmeye başlar. • Filtreyi bir kişiye bağımlı bırakmayın. Sahibi ekipten ayrıldığında filtreler ve onlara bağlı panolar sorun çıkarabilir.

Filtreler panolarda ve panolar da toplantılarda kullanıldığı için, bir filtre değişikliğinin etkisini önceden düşünmek gerekir. Değişiklikten sonra bağlı panoya bakıp sayıların beklendiği gibi olduğunu doğrulayın.

Sık yapılan hatalar ve nereden başlanır?

Görülen başlıca hatalar: • Sorguyu bir seferde uzun uzun yazıp hata çıkınca nerede olduğunu bulamamak; koşulları tek tek eklemek daha güvenlidir. • Boş alanları hesaba katmamak (!= tuzağı). • Parantezsiz karma AND/OR. • Durum ve alan adlarını kurulumdaki gibi yazmamak. • Filtreleri ayrıntılı adlandırmadan kaydedip panoların bağımlı olduğu mantığı kaybetmek.

Başlamak için Jira'nın temel arama kutusuyla bir arama yapın, ardından bunu JQL görünümüne çevirip sorguyu okuyun. Atlassian belgelerine göre çoğu temel arama JQL'e çevrilebilir; bu çeviriyi gözlemlemek, sözdizimini öğrenmenin en hızlı yoludur. Sonra elle küçük değişiklikler yapın.

Mindset kataloğunda Jira Eğitimi: Temel ve İleri Uygulama, Gerçek Zamanlı İzleme ve Raporlama ile Jira'yı Diğer Araçlarla Entegrasyon ve İleri Özellikler modül başlıklarını içerir; Jira ile Proje Yönetimi Eğitimi ise Raporlama, Gösterge Panoları ve Analitik İzleme modülünü kapsar. İzleme ve raporlama işlerinin çekirdeğinde filtreler bulunduğu için bu başlıklar proje yöneticilerinin, ürün sahiplerinin ve ekip liderlerinin JQL ile karşılaştığı konu alanlarıdır.