JIRA Entegrasyonu

JIRA ile API Portal arasında bağlantı ayarları bu ekrandan yönetilir. Bu sayfa üzerinden JIRA bağlantı bilgilerinizi, API erişim anahtarınızı ve talep türlerinizi tanımlayabilirsiniz.

İçindekiler

Genel Bakış

Portal Jira Config ekranı, API Portal kullanıcılarının oluşturduğu destek taleplerinin Jira Service/Software projelerine otomatik olarak açılabilmesi için gerekli bağlantı ayarlarının yapıldığı yönetim sayfasıdır. Burada tanımlanan bilgiler sayesinde portal ile Jira arasında güvenli bir entegrasyon kurulur, talepler standart bir issue tipi altında etiketlenerek açılır ve gerektiğinde portal bilgilerinin Jira issue alanlarına taşınması sağlanır.

Önemli Not: Jira entegrasyonunu aktifleştirmeden önce Atlassian hesabınızda API token oluşturmuş, kullanacağınız Jira projesinin anahtarını (Project Key) ve gerekli custom field ID değerlerini biliyor olmanız gerekir.

JIRA Entegrasyon Ayarları ekranına ait detaylar aşağıdaki görselde yer verilmiştir:

Sayfadaki Jira Entegrasyonu için kullanılan alanlar aşağıdaki tabloda görülmektedir.

#	Alan	Portalda Görüldüğü Yer	Nasıl Doldurulmalı	Jira Üzerindeki Etkisi
1	Jira Entegrasyon Durumu (Status)	Sayfanın üst bölümündeki toggle. Aktif/Pasif bilgisi yanında yeşil/kırmızı etiketi gösterir.	Toggle açık olduğunda (Active) portal talepleri Jira'ya gönderilir. Toggle kapalı ise (Passive) kullanıcılar portalda ticket oluşturduğunda Jira'ya kayıt açılmaz. Portal içi kayıt devam edebilir ancak Jira senkronu durur.	status=true ise portal ticket formundan gelen kayıtlar Jira'ya REST çağrısı ile iletilir, false ise hiçbir REST çağrısı yapılmaz; portal sadece kendi içinde kaydeder.
2	Jira URL	Zorunlu metin alanı. Form validasyonu URL boş bırakılırsa kırmızı uyarı gösterir.	Atlassian Cloud kullanan müşteriler için https://<organization>.atlassian.net formatında olmalıdır. Self-hosted Jira sunucusu kullanıyorsanız tam adresi girin (örn: https://jira.company.com). Sonunda / olmadan yazın.	REST çağrılarında temel domain olarak kullanılır (https://.../rest/api/3/*). Hatalı girilirse NOTFOUND veya 404 hatası döner, issue oluşmaz.
3	Açıklama (Description)	Çok satırlı açıklama alanı. Yöneticiler için bilgi notu kartlarında görünür.	İç ekibinize not bırakmak, hangi projeye yönlendirildiğini anlatmak veya Atlassian tarafındaki özel kuralları belirtmek için kullanın. Maksimum 1000 karakter önerilir.	Jira ile doğrudan senkronize edilmez; yalnızca portal yönetim arayüzünde referans olarak saklanır.
4	Kullanıcı Adı (Username)	Zorunlu metin alanı. Değer girilmezse entity.validation.required uyarısı verir.	Atlassian hesabına giriş yapıp https://id.atlassian.com/manage-profile/security/api-tokens adresinden yeni token üretin. Token'ı sadece bir kez görebileceğinizi unutmayın; portal ayarlarını kaydederken güvenli bir şekilde kopyalayın. Kullanıcı adı alanına token'ı oluşturan hesabın e-posta adresini yazın.	Jira REST çağrısında Basic Auth kullanıcı adı olarak kullanılır (genellikle Atlassian e-posta adresi). Yanlışsa 401 Unauthorized alınır.
5	API Token	Zorunlu parola alanı. Değer girilmezse hata mesajı verir.		Basic Auth şifresi olarak kullanılır. Token hatalıysa Jira 401 döner ve issue oluşturulamaz.
6	Project Key	Zorunlu metin alanı.	Jira projesinin sağ üst köşesinde veya Project settings → Details sayfasında bulunur. Yanlış girilirse talepler oluşturulamaz; hata loglarında Project does not exist mesajı gözlenir.	project alanına yazılır; Jira 404 dönerse “Project does not exist” hatası alınır. Başarılı olduğunda tüm Jira ticket'ları bu projede açılır.
7	Issue Type	Zorunlu metin alanı, placeholder ile örnek değer gösterir.	Projenizde tanımlı issue tiplerinden biri olmalıdır. Atlassian Cloud için REST endpoint: GET /rest/api/3/issuetype ile mevcut tipleri doğrulayabilirsiniz.	issuetype alanına yazılır. Tip geçersizse Jira 400 Bad Request döner; portal kaydetme işlemini tamamlar ama issue oluşturma başarısız olur.
8	Kategori Custom Field ID	Opsiyonel metin alanı.	Portal isteği ile Jira issue'ları arasındaki veri eşleştirmesini özelleştirmek için kullanılır. Jira'da custom field ID değerini öğrenmek için ilgili alanı düzenlerken URL'de customfield_XXXXX ifadesini bulun. Alan boş bırakılırsa eşleştirme yapılmaz; portal isteği temel bilgiler ile açılır. Jira'da oluşturduğunuz kategori alanının kimliğini girin (örn: customfield_10070). Bu alan Payment, Customer gibi kategori bilgilerini içerir. ⚠️ **Not:** Jira'da custom field oluşturma ve ID'lerini bulma hakkında detaylı bilgi için [Atlassian Custom Fields Dokümanını](https://confluence.atlassian.com/adminjiraserver/adding-custom-fields-1047552713.html) inceleyebilirsiniz.	Portal kategorisi Jira issue JSON'unda fields[customfield_xxxxx] olarak gönderilir. Alan boşsa gönderim yapılmaz.
9	API Product Custom Field ID	Opsiyonel metin alanı.	Jira'da oluşturduğunuz API ürün adı alanının ID'sini girin (örn: customfield_10071). Bu alan Payment API'si, Custormer API'si gibi ürün adlarını depolar Alan boş bırakılırsa eşleştirme yapılmaz; portal isteği temel bilgiler ile açılır. ⚠️ **Not:** Jira'da custom field oluşturma ve ID'lerini bulma hakkında detaylı bilgi için [Atlassian Custom Fields Dokümanını](https://confluence.atlassian.com/adminjiraserver/adding-custom-fields-1047552713.html) inceleyebilirsiniz.	Portalda seçilen API ürün adı aynı şekilde ilgili custom field'a set edilir. Boş bırakılırsa atlanır.
10	API Product Endpoint Custom Field ID	Opsiyonel metin alanı.	Jira'da oluşturduğunuz uç nokta alanının kimliğini girin (örn.: customfield_10072). Bu alan /api/v1/payment gibi uç nokta yollarını depolar Alan boş bırakılırsa eşleştirme yapılmaz; portal isteği temel bilgiler ile açılır. ⚠️ **Not:** Jira'da custom field oluşturma ve ID'lerini bulma hakkında detaylı bilgi için [Atlassian Custom Fields Dokümanını](https://confluence.atlassian.com/adminjiraserver/adding-custom-fields-1047552713.html) inceleyebilirsiniz.	Portal endpoint bilgisi Jira issue'suna custom field olarak yazılır; örn. /payments/v1.
11	Label List	Input + tablo bileşeni. Liste boşsa “No labels found” mesajı gösterilir.	Input alanına label yazıp Enter tuşuna bastığınızda listeye eklenir. Tablo üzerinden çöp kutusu ikonuna tıklayarak label'ı silebilirsiniz.	Her label Jira issue labels listesine eklenir. Var olan issue'larda otomasyon ya da filtreleme için kullanılabilir.

Adım Adım Jira Entegrasyonu Kurulum Rehberi

Sık Karşılaşılan Senaryolar ve Çözüm Adımları

Portal Destek Talepleri ve JIRA Entegrasyonu 

Genel Bakış

Apinizer Manager'da yapılandırılan JIRA entegrasyonu, Portal kullanıcılarının oluşturduğu destek taleplerinin otomatik olarak JIRA'ya aktarılmasını sağlar. Bu bölümde, Manager'daki konfigürasyon ile Portal'daki destek talepleri arasındaki ilişki ve veri akışı detaylı olarak açıklanmaktadır.

• Portal kullanıcılarının karşılaştıkları sorunları, geliştirme isteklerini veya önerilerini destek ekibine iletmesini sağlar.
• Gönderilen talepler JIRA üzerinde ticket olarak oluşturulur ve durumları bu ekranda takip edilebilir.
• Kullanıcılar geçmiş taleplerini filtreleyip durumlarını inceleyebilir.
• Portal hesabına giriş yapmış tüm kullanıcılar bu sayfaya erişebilir.
• Menü yolu: Portal → Support Requests.
• Talep gönderebilmek için zorunlu alanların (etiket, özet, açıklama) doldurulması gerekir.

Liste Görünümü

Liste Görünümü içeren görsele aşağıda yer verilmiştir:

• Sayfa açıldığında mevcut talepler tablo halinde listelenir.
• Üstte yer alan arama kutularıyla Issue ID veya Özet (Summary) alanında hızlı arama yapabilirsiniz.
• “New” butonuna tıklayarak yeni talep oluşturma formuna geçebilirsiniz.
• Issue ID bağlantısına tıklamak, ilgili talebin detay sayfasını açar.
• Tablo sütunlarında;
  • Talebin kodu (Issue ID)
  • Özet metni
  • Durum, etiket ve kategori bilgileri
  • İlişkili API ürünü ve endpoint adı (varsa)
  • Son güncellenme tarihi bilgileri yer alır.

Yeni Talep Oluşturma

Yeni talep oluşturma ekranı aşağıda belirtilmiştir.

Talep Detayı Nasıl Görüntülenir?

• Liste ekranında issue ID üzerine tıklayın.
• Açılan sayfada:
  • Talebin kodu, etiketi, durumu ve raporlayan kişi bilgisi yer alır.
  • Hangi kategoriye, hangi API ürününe ve endpoint’e bağlı olduğu görülür.
  • Özet ve açıklama metinleri tam haliyle görünür.
  • Ek dosya varsa “Download” butonuyla indirebilirsiniz.
  • “Comments” bölümünde destek ekiplerinin bıraktığı notlar ve tarihçesi listelenir.
  • “Back” butonuyla listeye geri dönebilirsiniz.

API Manager ile Bağlantı

• Bu portal ekranı, kullanıcı talebini toplar ve arka planda JIRA üzerinde ticket oluşturur.
• Talep formundaki API Product seçimi, API Manager’da yayınlanmış ürünlere dayalıdır. Böylece destek ekibi sorunun hangi ürünle ilgili olduğunu kolayca anlar.
• Talep süreçlerinin yönetimi (durum değişiklikleri, yorumlar, çözüm) JIRA üzerinden yapılır; portal yalnızca görüntüleme sağlar.

Manager JIRA Konfigürasyonu ve Portal Arasındaki Bağlantı

1. Konfigürasyon Kaynağı

Portal'daki destek talepleri sistemi, doğrudan Manager'da tanımlanan JIRA entegrasyon ayarlarını kullanır.

• Manager → Portal Management → Portal Jira Config ekranında yapılan tüm ayarlar, Portal arayüzündeki Support Requests sayfası için geçerlidir.
• Portal'ın kendi içinde ayrı bir JIRA konfigürasyonu bulunmaz; tüm bağlantı bilgileri Manager üzerinden merkezi olarak yönetilir.
• Manager'da yapılan her değişiklik (URL, token, project key, custom field ID'ler vb.) Portal'a otomatik olarak yansır.

2. Entegrasyon Durumu ve Portal'a Etkisi

Manager'daki Jira Entegrasyon Durumu (Status) toggle'ı Portal destek talepleri için kritik rol oynar:

Active (Etkin) Durumda:

• Portal kullanıcıları Support Requests sayfasından yeni talep oluşturduğunda:
  • Talep bilgileri Portal API'sine gönderilir
  • Portal API, Manager'daki JIRA konfigürasyonunu kullanarak JIRA REST API'sine istek atar
  • JIRA'da otomatik olarak yeni issue oluşturulur
  • Oluşturulan issue'nun Issue Key (örn: SUP-123) Portal'a döner
  • Portal'daki talep bu issue key ile ilişkilendirilir
  • Kullanıcı Portal'da talep listesinde JIRA issue key'ini görebilir

Passive (Pasif) Durumda:

• Portal kullanıcıları destek talebi oluşturabilir
• Ancak JIRA'ya hiçbir istek gönderilmez
• Talep sadece Portal veritabanında saklanır
• JIRA tarafında hiçbir issue oluşturulmaz
• Bu mod, entegrasyon test edilirken veya geçici olarak devre dışı bırakılmak istendiğinde kullanılır

Portal Support Requests Sayfası ve JIRA Entegrasyonu Veri Akışı

Adım 1: Kullanıcı Portal'da Yeni Talep Oluşturur

Portal kullanıcısı Portal → Support Requests → New butonuna tıklayarak talep oluşturma formunu açar ve aşağıdaki alanları doldurur:

Adım 2: Portal API'si Manager Konfigürasyonunu Çeker

Kullanıcı Send butonuna bastığında:

1. Portal frontend, form verilerini Portal backend API'sine POST eder
2. Portal backend:
   • Manager API'sinden JIRA entegrasyon ayarlarını çeker
   • Entegrasyon durumunu kontrol eder (Active/Passive)
   • Eğer Active ise, JIRA bağlantı bilgilerini alır

Adım 3: JIRA REST API Çağrısı Yapılır

Portal backend, Manager'dan aldığı bilgilerle JIRA'ya REST çağrısı gönderir

Kimlik Doğrulama (Authentication):

• Username: Manager'da tanımlanan Atlassian hesap e-posta adresi
• API Token: Manager'da güvenli olarak saklanan token
• Basic Auth: Base64 kodlanmış username:token formatında gönderilir

Custom Field Eşlemeleri:

• Manager'da tanımlanan Category Custom Field ID (örn: customfield_10070) Portal'daki kategori bilgisini taşır
• API Product Custom Field ID (örn: customfield_10071) seçilen API ürün adını içerir
• API Product Endpoint Custom Field ID (örn: customfield_10072) endpoint yolunu depolar
• Bu alanlar Manager'da boş bırakılırsa, Portal sadece temel alanları (summary, description, labels) gönderir

Adım 4: JIRA Yanıtı İşlenir

JIRA başarılı şekilde issue oluşturduğunda;

Portal backend:

1. JIRA'dan dönen Issue Key'i (SUP-123) alır
2. Bu key'i Portal veritabanındaki talep kaydıyla ilişkilendirir
3. Kullanıcıya başarı mesajı gösterir
4. Liste sayfası yenilendiğinde, Issue ID sütununda SUP-123 görünür

Adım 5: Talep Portal Listesinde Görüntülenir

Portal'daki Support Requests liste sayfasında:

• Her satırda JIRA Issue Key (SUP-123) clickable link olarak gösterilir
• Link'e tıklandığında Portal'daki detay sayfası açılır (JIRA'ya yönlendirme yapılmaz)
• Durum bilgisi JIRA'dan periyodik olarak senkronize edilir
• Kullanıcı, talebinin JIRA'daki durumunu Portal üzerinden takip edebilir

Sık Sorulan Sorular

Sonuç

Manager'da yapılan JIRA entegrasyon konfigürasyonu, Portal kullanıcılarının destek taleplerini JIRA'ya otomatik olarak iletmek için kritik öneme sahiptir. Bu entegrasyon sayesinde:

1. Merkezi Yönetim: Tüm JIRA ayarları tek noktadan (Manager) kontrol edilir
2. Otomatik Senkronizasyon: Portal talepleri anında JIRA issue'larına dönüşür
3. Veri Tutarlılığı: Custom field eşlemeleri sayesinde Portal ve JIRA verileri senkronize kalır
4. Kolay Takip: Kullanıcılar Portal üzerinden JIRA issue durumlarını görüntüleyebilir
5. Verimli Destek: Destek ekipleri JIRA'da tüm talepleri merkezi olarak yönetir

Bu dokümanda açıklanan tüm adımları takip ederek, Portal ve JIRA arasında sorunsuz bir entegrasyon kurabilir ve kullanıcı deneyimini maksimize edebilirsiniz.