Cari tiket Jira dengan Tindakan Khusus

Jira bukan integrasi bawaan Quickchat AI. Halaman ini merupakan contoh lengkap pembuatan Tindakan API Khusus untuk REST API pihak ketiga, dan pola yang sama berlaku untuk API lainnya.

Dalam tulisan ini, saya akan menunjukkan cara menghubungkan Agen AI Anda ke Jira. Kita akan menggunakan:

• akun Jira (gratis)
• Agen AI Quickchat (daftar di sini dan gunakan gratis)

Dengan penyiapan ini, Agen Quickchat AI dapat:

• mencari tiket Jira Anda, dan
• menjawab pertanyaan berdasarkan tiket tersebut secara cerdas

Kita akan menggunakan Tindakan AI Quickchat (tindakan HTTP khusus) agar Agen dapat memanggil endpoint Enhanced search for issues dari API Jira (Atlassian).

Buat Agen AI yang kreatif dalam menafsirkan masukan pengguna

Pemeriksaan contoh opsional

• Pratinjau permintaan Tindakan API. Render templat permintaan yang diberikan dengan nilai contoh sintetis tanpa mengirimkannya. Jangan sertakan header kredensial.

• Pratinjau kecocokan JSONPath. Periksa jalur root, bidang, indeks array, dan wildcard terhadap JSON yang diberikan. Pemeriksaan ini tidak menjalankan Tindakan atau menyimpan memori percakapan.

Di browser yang kompatibel, pemeriksaan ini juga tersedia sebagai tool situs. Tautannya membuka formulir standar.

Tonton Video

Play

Cara kerjanya

Berikut cara Agen AI bekerja selama percakapan:

1. Pengguna mengajukan pertanyaan seperti “bagaimana kabar isu yang berkaitan dengan mercury?”
2. Agen AI mengambil informasi relevan dari API Jira menggunakan kueri seperti “mercury”
3. Agen AI membalas pengguna berdasarkan informasi yang diambil dari API

Ikuti langkah-langkah di bawah. Seluruh penyiapan seharusnya tidak lebih dari 10 menit!

Langkah 0 - buat akun dan proyek Jira

1. Buka id.atlassian.com/signup, buat dan verifikasi akun Anda.
2. Tambahkan Jira ke aplikasi Atlassian Anda (paket gratis cukup untuk memulai).
3. Siapkan proyek pertama dan buat tiket seperti contoh di bawah.

Contoh papan dengan isu Jira

Langkah 1 - token autentikasi API Jira

Buka id.atlassian.com/manage-profile/security/api-tokens dan buat token API Anda, yang akan terlihat seperti ini:

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

Agar dapat menggunakan token API Atlassian dalam Tindakan AI Quickchat, Anda perlu mengodekannya dalam base64 bersama alamat email:

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

Pastikan menyertakan alamat email yang sama persis dengan yang digunakan untuk membuat akun Atlassian

Anda dapat menggunakan tool online sederhana seperti base64encode.org.

Pastikan menggunakan Live mode yang menjamin pengodean dilakukan sepenuhnya di browser Anda.

Anda dapat menggunakan tool online gratis untuk mengodekan token API

Atau, berikut cara melakukannya di komputer Anda menggunakan skrip python sederhana:

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

Skrip di atas memberikan header siap pakai dengan token yang telah dikodekan, seperti berikut:

Basic eW91cl9lbWFpbEBleGFtcGxlLmNvbTpBVEFUVDN4RmZHRjAxc0tVbDBIRVcyLV8tdTl1bWZMU3o3amVibG1lTHpFSFoxRExjZExiS2VWRjEzN2lUSEdrS2hQdU5NU0tYOG1rYndMcEhYVDQtcVhFbi14TkVuZmlLOF9YRFZXNlhYdkdkX1NCVjNIRDRrSkluR05qZmcyX3lFb0pGTjZ1d3k0TlJxZXVoVjJ0am15enhvekxCUm4zNU9oWGtEQTZRR2ZMRnZmMl9QS3VOdEE9OERBNzA0RTQ=

Langkah 2 - buat Tindakan Quickchat AI

Di aplikasi Quickchat AI, buka Tindakan & MCP dan tambahkan tindakan:

Halaman Tindakan AI

Berikan nama yang sesuai untuk Tindakan AI:

Nama: Search Jira issues

Masukkan nama Tindakan AI

Langkah 3 - atur parameter masukan

Tugas utama Agen AI adalah menerjemahkan pertanyaan pengguna menjadi kueri tepat untuk mencari isu Jira. Untuk pencarian isu, Jira baru-baru ini beralih sepenuhnya ke JQL (Jira Query Language) agar pencarian lebih kompleks dapat dilakukan. Ini membuat Agen AI jauh lebih mampu. Siapkan parameter masukan sebagai berikut:

Format	Nama	Deskripsi	Nilai default	Wajib
Text	jql	(lihat di bawah)	-	✅

Untuk kinerja Agen AI yang baik, deskripsi yang disusun dengan baik sangat penting:

Deskripsi:

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

Deskripsi parameter yang baik adalah kunci kinerja Agen AI

Catatan tentang status Jira

Jira memisahkan nama status dari kategorinya, dan JQL memperlakukannya berbeda:

• Nama status adalah yang ditampilkan papan. Satu proyek menggunakan To Do / In Progress / Done, proyek lain menggunakan Open / In Review / Closed.
• Kategori status adalah salah satu dari tiga kelompok tetap yang memetakan setiap status: To Do, In Progress, Done.

status = "To Do" memfilter berdasarkan nama, sehingga tidak mengembalikan apa pun pada papan yang kolom pertamanya bernama Open. Ini sering menjadi alasan agen dengan yakin melaporkan “tidak ada tiket yang harus dikerjakan” padahal papan penuh dengan tiket. Untuk pertanyaan “apa yang belum dimulai”, “apa yang sedang dikerjakan”, dan “apa yang sudah selesai”, filter berdasarkan kategori:

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

Pertahankan status = "..." ketika pengguna menyebut status tertentu yang Anda ketahui ada di papan. Anda juga dapat mencantumkan nama status sebenarnya dalam deskripsi Tindakan (Langkah 7) agar agen memetakan permintaan seperti “siap untuk QA” ke status yang benar.

Langkah 4 - atur URL endpoint API

1. Pilih GET sebagai metode permintaan API
2. Atur URL endpoint ke endpoint Jira /rest/api/3/search/jql

Atur URL endpoint API Anda

Pastikan menggunakan nama domain Atlassian Anda. Anda dapat menemukannya dalam URL papan Jira.

Nama domain Atlassian Anda

Langkah 5 - atur header permintaan API

Tentukan header permintaan API sebagai berikut:

Accept	Autorization
application/json	Basic cGlvdHJAcXVpY2tjaGF0LmFpOkFUQVRUM3hGZkdGMGlQOVNacEhVZ1o5YUJfWGhmQjZJWjJId3MyaHlsMzEtTlNpYW90Z2tZVzRxQXEwQ3R4UVY1OXFTZkpWWVZNcXlxem42MWRkR0VobmJWNzdzaWtrb19ZWkhtLUgwazFOZGh4WlpQMnltYmZ1SzhBRmlFMnJEUmdqd182N1hkSFFUelFQY2I2U1lrNUFPRlRuVnZvaGxkZUd3djVpM2VrcEFyMVJ4QnJWRncyYz04MEZGQTcyMA==

Perhatikan format header Authorization dengan benar: Basic <base64-encoded email:api token>

Atur header permintaan API Anda

Langkah 6 - atur parameter kueri permintaan API

Atur dua parameter kueri untuk permintaan AI:

• jql mengambil nilai dinamis yang ditentukan sebelumnya di bagian Apa yang harus ditanyakan kepada pengguna terlebih dahulu. Tugas Agen AI adalah mengisi nilai parameter ini berdasarkan ucapan pengguna dalam percakapan.
• fields mengambil nilai tetap. Untuk setiap isu Jira, kita hanya tertarik pada ringkasan, deskripsi, dan status.

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

Atur parameter kueri permintaan API Anda

Pastikan parameter jql mengarah dengan benar ke nilai yang ditentukan sebelumnya. Anda dapat memilihnya dari menu dropdown Tambah Data AI.

Pilih parameter dinamis jql dari menu dropdown

Langkah 7 - atur deskripsi Tindakan API

Unsur penting terakhir untuk Tindakan AI yang disiapkan dengan baik adalah deskripsinya. Meskipun Agen AI memahami endpoint API dari URL dan parameternya, mengoptimalkan perilaku untuk kasus penggunaan Anda tetap penting.

Tiga aspek terpenting dalam prompt adalah:

• kapan memanggil tindakan: cantumkan setiap ungkapan yang mungkin dipilih pengguna (temukan / cari / carikan, serta jelaskan / ceritakan tentang / uraikan / apa itu / bagaimana status) agar agen tidak melewatkan panggilan ketika pengguna tidak mengatakan “cari”
• saran penggunaan sintaks JQL lanjutan saat mencari isu Jira
• cara menangani hasil kosong: agen harus menyatakannya secara jelas, bukan menolak akses

Berikut Deskripsi Tindakan API yang dihasilkan:

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.

Langkah 8 - uji Tindakan API

Sebelum menguji Tindakan AI dalam percakapan, kita dapat menguji cara API dipanggil melalui tab Uji Respons. Mari lakukan pengujian pertama dengan kueri berikut yang seharusnya mengembalikan semua isu dalam proyek: project = "Solar System"

Mencari semua isu dalam proyek Solar System

Berikut respons pengujiannya. Sesuai harapan, respons mencantumkan bidang ringkasan, deskripsi, dan status untuk keenam isu pada papan Jira.

Respons mencantumkan semua isu dalam proyek Solar System

Mari coba satu kueri lagi. Kali ini kita mencari semua isu yang menyebut “mercury”: text ~ "mercury"

Mencari isu yang menyebut mercury

Kini kita telah memvalidasi bahwa Tindakan AI memanggil endpoint API dengan benar. Kita dapat beralih ke pengujian percakapan lengkap dengan Agen AI!

Langkah 9 - uji Agen AI dalam percakapan

Kembali ke aplikasi Quickchat AI dan uji Agen AI dalam pratinjau percakapan.

Percakapan #1

Agen AI memberikan ringkasan semua isu dalam proyek

Dalam percakapan sederhana ini, Agen AI memberi gambaran semua isu dalam proyek. Pemeriksaan di balik layar menunjukkan kueri tepat yang dijalankan terhadap endpoint API: project = "Solar System"

Percakapan #2

Agen AI menjawab pertanyaan tentang isu dan status tertentu

Dalam kasus ini, Agen AI ditanya tentang dua aspek terpisah: satu isu tertentu dan isu yang sedang berlangsung secara umum. Pemeriksaan di balik layar menunjukkan agen memilih menggunakan API Jira dalam dua langkah:

1. Periksa apakah pluto sedang berlangsung:

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

2. Periksa apa lagi yang sedang berlangsung:

status = "In Progress"

Percakapan #3

Agen AI menjawab kueri kreatif 😉

Dalam kasus ini, saya ingin memberikan tantangan kepada Agen AI dengan pertanyaan yang membutuhkan kreativitas untuk ditafsirkan dengan benar. Berikut cara pertanyaan diterjemahkan menjadi kueri JQL:

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

Coba ungkapan berikut

Untuk memastikan Tindakan AI berjalan apa pun cara pengguna akhir menyampaikan permintaan, jalankan setiap prompt berikut pada skenario uji Anda. Agen harus mengueri Jira untuk semuanya, bukan hanya ungkapan pencarian:

• “temukan semua isu terbuka tentang skor langsung”
• “cari isu dengan mercury”
• “jelaskan proyek Solar System”
• “ceritakan tentang isu terbuka dalam sprint ini”
• “uraikan apa yang sedang dikerjakan”
• “bagaimana status pluto?”

Jika ada ungkapan yang tidak memanggil Tindakan AI, periksa kembali bahwa deskripsi Tindakan API (Langkah 7) secara jelas mencantumkan kata kerja tersebut.

Yang diharapkan ketika Jira tidak menemukan isu yang cocok

Ketika Jira mengembalikan nol hasil, Agen AI harus menyatakannya secara jelas, misalnya “Saya sudah memeriksa Jira dan tidak menemukan isu yang cocok dengan kueri Anda. Coba ungkapan yang lebih luas atau hapus filter status.”

Jika agen justru menjawab “Saya tidak memiliki akses langsung ke Jira Anda”, Tindakan AI sama sekali tidak berjalan. Periksa kembali deskripsi dari Langkah 7 dan pastikan kata kerja selain pencarian dicantumkan secara jelas (explain, tell me about, describe, what is).

Ringkasan

Dalam tulisan ini, kami menunjukkan cara menyiapkan Agen AI untuk menggunakan endpoint API tertentu secara kreatif dalam percakapan. Penyiapan yang tepat tidak tersedia begitu saja; diperlukan informasi tambahan yang terperinci tentang kasus penggunaan yang dimaksud. Silakan gunakan kembali prompt dan deskripsi dalam tulisan ini untuk membuat Agen AI serupa!

Lebih suka panduan panjang dengan penjelasan naratif? Penyiapan yang sama juga dibahas sebagai artikel blog di quickchat.ai. Halaman dokumentasi ini adalah referensi utama yang terus diperbarui.

Langkah lanjutan

Tindakan Jira tidak harus berupa satu permintaan tetap. Anda dapat memasukkan variabel percakapan bawaan dan metadata tersimpan (seperti bahasa pengunjung atau nilai yang diperoleh sebelumnya dalam percakapan) ke bidang mana pun, dan menambahkan beberapa tindakan agar agen memilih yang tepat untuk setiap pertanyaan. Lihat referensi Tindakan untuk seluruh opsi.

🎁  BONUS

Tulisan di atas dibuat oleh manusia (saya sendiri), tetapi bisa juga ditulis AI. Misalnya, dengan menempelkan prompt seperti ini ke ChatGPT:

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)

Di masa mendatang, mungkin alih-alih mencari tiket Jira, Anda ingin:

• mengirim pesan ke kanal Slack?
• mengambil informasi dari halaman Notion?
• melakukan tindakan melalui Zapier?

Sebutkan dalam kalimat pertama dan jalankan prompt lagi! Anda akan mendapatkan petunjuk yang baik untuk menambahkan Tindakan AI yang dibutuhkan!