Inbox Mesajları ve Zamanlanmış Sorgular

İçindekiler

Inbox Mesajları ve Zamanlanmış Sorgular

Genel Bakış

MMX Notificator, iki temel yöntemle bildirim gönderir:

Anlık bildirim: Bir olay tetiklendiğinde (örn. sipariş oluşturulması) sistem doğrudan mesaj gönderir.
Zamanlanmış bildirim: Belirli aralıklarla çalıştırılan bir SQL sorgusu, ilgili kayıtları bulur ve bunları Inbox Mesajı olarak kuyruğa ekler. Kuyruk işleyici arka planda mesajları okuyup gönderir.

Bu dokümanda ikinci yöntem (zamanlanmış bildirim) ve Inbox Mesajı kavramı ayrıntılı olarak açıklanmaktadır.

Arayüz Sayfaları

Aşağıdaki tabloda sistemin yönetim arayüzüne ait sayfa adresleri yer almaktadır.

Sayfa	URL	Açıklama
Sağlayıcı Listesi	`/Providers`	E-posta sağlayıcılarını listeler ve yönetir
Şablon Listesi	`/Template`	Mesaj şablonlarını listeler ve yönetir
Zamanlanmış Sorgu Listesi	`/ScheduledInboxQuery`	Zamanlanmış sorgu tanımlarını listeler
Zamanlanmış Sorgu Oluştur	`/ScheduledInboxQuery/Create`	Yeni bir zamanlanmış sorgu tanımı oluşturur
Zamanlanmış Sorgu Düzenle	`/ScheduledInboxQuery/Edit`	Mevcut bir zamanlanmış sorgu tanımını düzenler

Mesaj Şablonları ve Parametreler

Her bildirim bir Mesaj Şablonu (MessageTemplate) üzerine kuruludur. Şablon şu bilgileri içerir:

Alan	Açıklama
Kod	Şablonu tanımlayan benzersiz kısa ad
Açıklama	Şablonun ne için kullanıldığının açıklaması
Konu	E-posta konusu; içinde yer tutucu kullanılabilir
Gövde	E-posta gövdesi; içinde yer tutucu kullanılabilir
Sağlayıcı	Mesajın hangi e-posta sunucusu üzerinden gönderileceği
Alıcı Yapılandırması	Mesajın kime gönderileceği (kullanıcı, personel, özel SQL vs.)
Parametreler	Şablonda kullanılan dinamik değerlerin tanımları

Parametreler

Bir şablona bağlı her parametre şunları içerir:

Code: Şablon metninde kullanılacak anahtar (örn. SiparisNo).
Script: Veritabanında çalıştırılacak SQL ifadesi. Bu sorgu çalışma zamanında değerlendirilir ve dönen değer şablondaki yer tutucunun yerine yazılır.

Inbox Mesajı Nedir?

Inbox Mesajı (InboxMessage), bir bildirim gönderim talebinin veritabanına yazılmış halidir. Sistemde bir "kuyruk" görevi görür. Anlık gönderim yerine önce veritabanına kaydedilir; ardından arka plan işleyicisi (ProcessInboxMessagesJob) bu mesajları okuyarak gerçek gönderimi gerçekleştirir.

Her InboxMessage şu bilgileri tutar:

Alan	Açıklama
`TemplateId`	Kullanılacak mesaj şablonunun kimliği
`QueryId`	SQL sorgusundan dönen kaydın `Id` değeri (örn. sipariş ID'si)
`ParameterValues`	Şablondaki yer tutucuları dolduracak anahtar-değer çiftleri
`IsProcessed`	Mesajın başarıyla işlenip işlenmediği
`RetryCount`	Kaç kez yeniden deneme yapıldığı
`MaxRetries`	İzin verilen maksimum yeniden deneme sayısı
`ProcessError`	Hata durumunda hata detayı

Mesaj Gövdesinin Parametrelerle Doldurulması

Şablon gövdesi ve konusunda yer tutucu değerler ${ParametreAdi} söz dizimiyle tanımlanır. Örnek:

Sayın ${AdSoyad},

${SiparisNo} numaralı siparişiniz ${SiparisTarihi} tarihinde oluşturulmuştur.
Toplam tutar: ${ToplamTutar} TL

Mesaj gönderimi sırasında sistem ParameterValues sözlüğündeki değerleri kullanarak her ${...} yer tutucusunu karşılık gelen değerle değiştirir.

Örnek ParameterValues:

{
  "AdSoyad": "Ahmet Yılmaz",
  "SiparisNo": "SP-2024-001",
  "SiparisTarihi": "12.06.2026",
  "ToplamTutar": "1.250,00"
}

Oluşan mesaj:

Sayın Ahmet Yılmaz,

SP-2024-001 numaralı siparişiniz 12.06.2026 tarihinde oluşturulmuştur.
Toplam tutar: 1.250,00 TL

Önemli: Yer tutucu adları büyük/küçük harf duyarlıdır. ${siparisNo} ile ${SiparisNo} farklı yer tutuculardır.

Zamanlanmış Sorgu (ScheduledInboxQuery) Sistemi

ScheduledInboxQuery, belirli aralıklarla çalışan ve veritabanından kayıt çekip bunları inbox mesajı olarak kuyruğa ekleyen bir tanımdır.

Tanım Alanları

Alan	Açıklama
Ad	Zamanlanmış sorgunun tanımlayıcı adı
Açıklama	Opsiyonel açıklama metni
SQL	Çalıştırılacak SQL sorgusu (mutlaka `Id` sütunu içermelidir)
Şablon	Oluşturulacak inbox mesajlarına bağlanacak mesaj şablonu
Cron İfadesi	Quartz formatında çalışma zamanlaması
Maks. Yeniden Deneme	Bir inbox mesajı için izin verilen maksimum yeniden deneme (varsayılan: 3)
Durum	Aktif / Pasif

Sistem Nasıl Çalışır?

┌─────────────────────────────────────────────────────────────────────┐
│  Uygulama Başlangıcı                                                │
│  ScheduledInboxQueryManager → Aktif tanımları yükler               │
│  → Her tanım için Quartz Job zamanlar                               │
└───────────────────────────────┬─────────────────────────────────────┘
                                │ Cron tetikler
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│  PopulateInboxMessagesJob                                           │
│  1. ScheduledInboxQuery tanımını yükler                             │
│  2. Tanımdaki SQL'i çalıştırır                                      │
│  3. Her satır için InboxMessage oluşturur ve veritabanına ekler     │
└───────────────────────────────┬─────────────────────────────────────┘
                                │ ProcessInboxMessagesJob (ayrı job)
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│  ProcessInboxMessagesJob                                            │
│  1. İşlenmemiş ve yeniden deneme hakkı olan mesajları çeker        │
│  2. Her mesaj için şablonu yükler                                   │
│  3. NotificationDispatchService ile e-posta gönderir               │
│  4. Mesajı işlenmiş olarak işaretler ya da hata kaydeder           │
└─────────────────────────────────────────────────────────────────────┘

SQL Sorgusunu Yazmak

ScheduledInboxQuery tanımında girilen SQL sorgusu, gönderilecek mesajları belirler. Sorgu yazarken dikkat edilmesi gereken kurallar:

Zorunlu Kural: `Id` Sütunu

SQL sorgusu mutlaka Id adında bir sütun döndürmelidir. Bu sütun, hangi kaydın işlendiğini takip etmek için kullanılır (örn. sipariş ID, fatura ID). Id sütunu olmayan sorgular kayıt sırasında reddedilir.

Ek Sütunlar = Parametre Değerleri

Id dışındaki tüm sütunlar otomatik olarak o inbox mesajının ParameterValues sözlüğüne eklenir. Sütun adı parametre anahtarı, sütun değeri ise parametre değeri olur.

Örnek

Gecikmiş siparişleri bildiren bir şablon için:

SELECT
    s.Id,
    m.AdSoyad,
    s.SiparisNo,
    CAST(s.OlusturmaTarihi AS VARCHAR) AS SiparisTarihi,
    CAST(s.ToplamTutar AS VARCHAR)     AS ToplamTutar
FROM Siparisler s
JOIN Musteriler m ON m.Id = s.MusteriId
WHERE s.Durum = 'Beklemede'
  AND s.OlusturmaTarihi < NOW() - INTERVAL '2 days'
  AND s.BildirimGonderildi = FALSE

Bu sorgu çalıştığında sistem şuna benzer ParameterValues oluşturur:

{
  "AdSoyad": "Ahmet Yılmaz",
  "SiparisNo": "SP-2024-001",
  "SiparisTarihi": "2026-06-10 08:30:00",
  "ToplamTutar": "1250.00"
}

Ve bu değerler bağlı şablondaki ${AdSoyad}, ${SiparisNo}, ${SiparisTarihi}, ${ToplamTutar} yer tutucularını doldurur.

Cron İfadesi

Sistem Quartz formatında cron ifadesi kullanır. Bu format standart Unix cron'dan farklı olarak saniye alanı içerir (7 alan).

Örnek	Açıklama
`0 0 8 * * ?`	Her gün sabah 08:00'de
`0 0/30 * * * ?`	Her 30 dakikada bir
`0 0 9 ? * MON-FRI`	Hafta içi her gün saat 09:00'da
`0 0 8 1 * ?`	Her ayın 1'inde saat 08:00'de

Cron ifadesi kaydedilmeden önce sistem tarafından doğrulanır. Geçersiz bir ifade girildiğinde kayıt reddedilir.

Aktivasyon ve Deaktivasyon

Yeni oluşturulan zamanlanmış sorgular pasif durumda başlar. Çalışmaya başlaması için arayüzden ya da API üzerinden aktifleştirilmesi gerekir.

Aktifleştirme

Zamanlanmış sorgu, IsActive = true olarak güncellenir.
Quartz içinde ilgili job otomatik olarak zamanlanır.
Uygulama yeniden başlatıldığında tüm aktif tanımlar otomatik olarak geri yüklenir.

Pasifleştirme

Zamanlanmış sorgu, IsActive = false olarak güncellenir.
Quartz içindeki job silinir; bir sonraki tetiklenme iptal edilmiş olur.
Halihazırda kuyruğa eklenmiş inbox mesajları etkilenmez, işlenmeye devam eder.

İşlem Akışı Özeti

Tanım Oluştur
     │
     ▼
Aktifleştir ──► Quartz Job Zamanlanır
                     │
                     │  (Cron ifadesine göre)
                     ▼
             PopulateInboxMessagesJob çalışır
                     │
                     │  SQL sorgusu çalıştırılır
                     │  Her satır → InboxMessage
                     ▼
             Veritabanı (InboxMessages tablosu)
                     │
                     │  (ProcessInboxMessagesJob - ayrı çizelge)
                     ▼
             Şablon + ParameterValues birleştirilir
             E-posta gönderilir
             MessagingTransaction kaydedilir

Sık Karşılaşılan Hatalar

Hata	Olası Neden	Çözüm
`SQL sorgusu geçersiz veya 'Id' sütunu içermiyor`	SQL'de `Id` sütunu yok veya söz dizimi hatalı	Sorgunun döndürdüğü sütunlardan birinin adının `Id` olduğundan emin olun
`Template X not found`	Bağlı şablon silinmiş	Tanımı güncelleyerek geçerli bir şablon seçin
`Provider or mail configuration not found`	Şablonun sağlayıcısı yapılandırılmamış	Şablona bağlı e-posta sağlayıcısını kontrol edin
Mesaj tekrar tekrar gönderiliyor	SQL sorgusunda filtre koşulu yok	Sorgunun zaten işlenmiş kayıtları döndürmemesi için uygun filtre ekleyin
Mesaj `MaxRetries` aşıldıktan sonra durdu	Kalıcı bir gönderim hatası var	`ProcessError` alanındaki hata detayını inceleyip problemi giderin

İçindekiler​

Genel Bakış​

Arayüz Sayfaları​

Mesaj Şablonları ve Parametreler​

Parametreler​

Inbox Mesajı Nedir?​

Mesaj Gövdesinin Parametrelerle Doldurulması​

Zamanlanmış Sorgu (ScheduledInboxQuery) Sistemi​

Tanım Alanları​

Sistem Nasıl Çalışır?​

SQL Sorgusunu Yazmak​

Zorunlu Kural: Id Sütunu​

Ek Sütunlar = Parametre Değerleri​

Örnek​

Cron İfadesi​

Aktivasyon ve Deaktivasyon​

Aktifleştirme​

Pasifleştirme​

İşlem Akışı Özeti​

Sık Karşılaşılan Hatalar​