Jira Entegrasyonu

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ı yapılandırabilir. Portal ile Jira arasında güvenli bir entegrasyon kurar, talepleri standart bir issue tipi altında etiketleyerek açar ve gerektiğinde portal bilgilerini Jira issue alanlarına taşı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:

JIRA Entegrasyon Ayarları

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

​

Entegrasyon Ayarları

#	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 **	Ç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.	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.	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.	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, Customer 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.	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.	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.

Not: Jira’da custom field oluşturma ve ID’lerini bulma hakkında detaylı bilgi için Atlassian Custom Fields Dokümanını inceleyebilirsiniz.

​

Adım Adım Jira Entegrasyonu Kurulum Rehberi

1. Adım 1: Ön Hazırlık (Jira Tarafı)

   • Entegrasyon için kullanacağınız Atlassian hesabını belirleyin (mümkünse servis hesabı).
   • Bu kullanıcıya ilgili Jira projesinde Create Issues ve gerekli custom field’ları düzenleme yetkisi verildiğinden emin olun.
   • Atlassian API token sayfasından yeni token oluşturun ve güvenli şekilde saklayın.
   • Kullanılacak Jira projesinin Project Key değerini ve kullanılacak issue tipini not alın.
2. Adım 2: Portal Jira Config Sayfasına Giriş

   • Apinizer Manager’da Portal Management → Portal Jira Config menüsüne gidin.
   • Sayfa açıldığında mevcut konfigürasyon varsa yüklenir; ilk kurulumda alanlar boş gelir.
3. Adım 3: Temel Bağlantı Bilgilerini Girin

   • Jira URL alanına instance adresini yazın (örn: https://company.atlassian.net).
   • Username alanına token oluşturduğunuz Atlassian e-postasını girin.
   • API Token alanına oluşturduğunuz token’ı yapıştırın.
   • Project Key ve Issue Type alanlarını doldurun.
4. Adım 4: Opsiyonel Alanları Konfigüre Edin

   • Jira issue’larına kategori, API ürün veya endpoint bilgisi taşımak istiyorsanız ilgili custom field ID alanlarını doldurun.
   • Otomatik etiket gereksiniminiz varsa Label List alanına bir veya birden fazla label ekleyin.
   • İç ekipleriniz için açıklama gerekiyorsa Description alanını kullanın.
5. Adım 5: Entegrasyonu Aktifleştirin

   • İsterseniz önce Status toggle’ını pasifte bırakıp kaydedebilirsiniz. Tüm alanlar hazır olduğunda toggle’ı Active konumuna getirerek entegrasyonu devreye alın.
6. Adım 6: Kaydedin ve Test Edin

   • Sağ üstteki Save butonuna basın.
   • Başarılı kayıt sonrası portal üzerinde Jira entegrasyonunu kullanan bir formdan test talebi oluşturun.
   • Jira’da ilgili projeye giderek yeni issue’nun doğru şekilde açıldığını doğrulayın.
7. Adım 7: Sorun Giderme

   • Hata alırsanız portal loglarını ve tarayıcı konsolunu inceleyin.
   • Gerekirse yeni token oluşturup tekrar kaydedin veya proje yetkilerini güncelleyin.

​

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

Hata	Olası Nedenler	Çözüm
401 Unauthorized Hatası	Hatalı kullanıcı adı, süresi dolmuş/iptal edilmiş API token, Atlassian hesabının gerekli projeye erişim yetkisi olmaması.	1. Atlassian hesap ayarından yeni token üretin. 2. Portal konfigürasyonunda Username alanının token ile aynı kullanıcıya ait olduğundan emin olun. 3. Jira projesinde ilgili kullanıcıya “Create Issues” izni verildiğini doğrulayın.
404 Project Does Not Exist	Yanlış Project Key veya kullanıcı projenin erişim yetkisine sahip değil.	1. Jira’da projenin Key değerini Project settings → Details ekranından kontrol edin. 2. Portal ayarındaki Project Key’i güncelleyin. 3. Yetki sorunu varsa Atlassian tarafında kullanıcıya proje erişimi verin.
400 Issue Type Is Not Valid	Girilen issue tipi, seçili projede geçerli değil veya yanlış yazıldı.	1. Jira’da GET /rest/api/3/issuetype ile veya UI üzerinden proje için izin verilen issue tiplerini listeleyin. 2. Portal ayarında Issue Type alanını bu listeden biriyle güncelleyin.
Label Bilgisi Jira’ya Düşmüyor	Label listesi boş, Portal kaydından sonra issue güncellenmiyor, Jira workflow’u label eklemeye izin vermiyor.	1. Portalda label listesine en az bir değer girildiğinden emin olun. 2. Jira issue detayında labels alanının düzenlenebilir olduğunu kontrol edin. 3. Automation veya workflow kısıtı varsa gerekli izinleri sağlayın.

​

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ü

Portal Destek Talepleri Liste Görünümü

• 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 Destek Talebi Oluşturma Formu

1. Adım 1: New butonuna tıklanır

   Liste sayfasındaki New butonuna basın.

2. Adım 2: Açılan Formdaki Alanlar doldurulur

   • Label (Etiket): Talebin tipini seçin (ör. Bug, Enhancement). Sistem yöneticisi hangi etiketlerin gerektiğini önceden tanımlar.
   • Summary (Özet): Sorunu veya isteği kısa ve net biçimde yazın.
   • Description (Açıklama): Detayları, yeniden nasıl üretilebileceğini veya beklentinizi belirtin.
   • Category (Kategori): Talebin hangi alana ait olduğunu seçin. “Diğer Talep” seçerseniz ürün alanı kapanır.
   • API Product ve Endpoint: Eğer konu belirli bir API ürününe ilişkin ise ürün ve ilgili endpoint’i seçin. İlginç bir sorun hangi endpoint’te yaşandıysa belirtmek çözüm sürecini hızlandırır.
   • Attachment (Ek dosya): Ekran görüntüsü, log veya belge eklemek isteyen kullanıcılar burada dosya yükleyebilir.
3. Adım 3: Kaydetme

   Formu tamamladığınızda Send butonuna basın. İşlem birkaç saniye sürebilir; oluşturulan talep otomatik olarak listeye eklenir.

​

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ışı

1. 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:

   Portal Form Alanı	Açıklama	JIRA’daki Karşılığı
   Label (Etiket)	Talep tipi (Bug, Enhancement, Question vb.)	JIRA issue’nun labels alanına eklenir
   Summary (Özet)	Talebin kısa açıklaması	JIRA issue’nun summary alanı
   Description (Açıklama)	Talebin detaylı açıklaması	JIRA issue’nun description alanı
   Category (Kategori)	Talep kategorisi (Payment, Customer, Other Request vb.)	Manager’da tanımlanan Category Custom Field ID’ye yazılır
   API Product	İlgili API ürünü adı	Manager’da tanımlanan API Product Custom Field ID’ye yazılır
   Endpoint	İlgili API endpoint yolu	Manager’da tanımlanan API Product Endpoint Custom Field ID’ye yazılır
   Attachment (Ek Dosya)	Ekran görüntüsü, log dosyası vb.	JIRA issue’ya attachment olarak eklenir

2. 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
3. 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
4. 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
5. 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

Talebim nereye gidiyor?

Gönderdiğiniz talep JIRA üzerinde ilgili projeye oluşturulur. Destek ekibi buradan takip eder.

Durum ne zaman güncellenir?

Destek ekibi talebinizi JIRA’da güncellediğinde, portal listesindeki durum da kısa süre içinde yenilenir.

Bir talebi düzenleyebilir veya silebilir miyim?

Portal, yalnızca yeni talep gönderme ve mevcut talepleri görüntüleme imkânı sunar. Güncelleme/kapama işlemleri destek ekibi tarafından yapılır.

Ek dosya eklemek zorunlu mu?

Hayır, ancak sorun tespiti için yardımcı olabilecek ekran görüntüsü veya logları eklemek süreci hızlandırır.

Portal'da Talep Oluşturuldu Ama JIRA'da Issue Yok neden?

Olası Nedenler:

1. Manager’da Status “Passive” durumda
2. JIRA URL hatalı
3. Network bağlantı sorunu
4. API Token süresi dolmuş

Çözüm Adımları:

1. Manager → Portal Jira Config → Status toggle’ını kontrol edin (“Active” olmalı)
2. Manager’daki logları inceleyin
3. JIRA URL’e tarayıcıdan erişebildiğinizi doğrulayın
4. Atlassian’da yeni API token oluşturup Manager’da güncelleyin
5. Portal’dan test talebi gönderin ve logları takip edin

JIRA'da Issue Oluşuyor Ama Custom Field'lar Boş

Olası Nedenler:

1. Manager’da Custom Field ID’ler yanlış girilmiş
2. JIRA’da custom field’lar mevcut değil
3. Custom field’ların veri tipi uyumsuz

Çözüm Adımları:

1. JIRA’da ilgili issue’yu açın
2. Ayarlar (•••) → View Screen’e tıklayın
3. Custom field’ların görünür olduğunu kontrol edin
4. JIRA Admin → Issues → Custom Fields’den field ID’leri doğrulayın:
   • Edit butonuna basın
   • URL’de customfield_XXXXX ifadesini kopyalayın
5. Manager’da Custom Field ID’leri güncelleyin
6. Yeni test talebi gönderin

​

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.