SAP Integration Suite'de Content Modifier ile Mesaj Dönüşümü: Kapsamlı Rehber

SAP Integration Suite entegrasyon akışlarında mesajlar nadiren kaynak sistemden geldiği biçimiyle hedef sisteme iletilebilir. Content Modifier adımı, bu boşluğu kapatmanın en pratik ve güçlü yoludur. Bu rehberde Content Modifier’ın ne işe yaradığını, hangi sekmelerin hangi senaryolarda kullanıldığını, exchange property ile header arasındaki kritik farkı ve gerçek dünya örnekleriyle adım adım yapılandırmayı öğreneceksiniz. Rehberin sonunda Content Modifier’ı güvenle uygulayabilir, yaygın hatalardan kaçınabilir ve entegrasyon akışlarınızı daha bakımı kolay hâle getirebileceksiniz.

Content Modifier Nedir ve Neden Kullanılır?

Content Modifier, SAP Integration Suite (eski adıyla SAP Cloud Platform Integration – SAP CPI) içinde bir entegrasyon akışında mesaj içeriğini, başlıklarını (headers) ve değişken özelliklerini (exchange properties) dönüştürmek için kullanılan temel bir adımdır. Kaynak sistemden gelen bir mesajı doğrudan hedefe iletmek yerine bu adım sayesinde mesajı zenginleştirebilir, yeniden şekillendirebilir veya filtreleyebilirsiniz.

SAP belgelerine göre Content Modifier, Message Header, Exchange Property ve Message Body olmak üzere üç farklı katmanda değişiklik yapmanıza olanak tanır. Bu esneklik, aracı tek bir bileşenle hem routing kararları için değer taşıma hem de payload şekillendirme gibi birden fazla amaca hizmet eder.

İlgili konular için SAP Integration Suite’te Header, Property ve Exchange yazımızı inceleyebilirsiniz. Ayrıca SAP Integration Suite Monitoring: PO’dan Geçişte 7 Zor Nokta yazımız da entegrasyon akışlarını anlamak için faydalı bir kaynak olacaktır.

Ne Zaman Content Modifier Kullanmalısınız?

• Kaynak mesajın gövdesini tamamen değiştirmeniz gerektiğinde
• Downstream adımlarda kullanılacak geçici değerleri (örn. OrderID, tarih) saklamanız gerektiğinde
• HTTP adapter veya SOAP adapter’a özel başlıklar (headers) eklemeniz gerektiğinde
• Sabit ya da dinamik içerikle yeni bir mesaj oluşturmanız gerektiğinde
• Hata yönetimi akışlarında okunabilir bir mesaj üretmeniz gerektiğinde

Content Modifier’ı Anlamak: Üç Temel Sekme

Content Modifier bileşeni açıldığında üç sekme karşınıza çıkar. Her sekmenin farklı bir kapsamı ve kullanım amacı vardır. Bu ayrımı kavramak, hem hatasız akış tasarımı hem de kolay bakım için kritiktir.

Message Header Sekmesi

Bu sekme, mesaja HTTP ya da SOAP başlığı eklemenizi veya mevcut başlıkları değiştirmenizi sağlar. Özellikle HTTP adapter kullanırken Content-Type veya Authorization gibi başlıkları buradan ayarlarsınız.

Önemli uyarı: Header değerleri mesaj tamamlanana kadar bellekte tutulur; ancak bazı adapter’lar akıştan çıkarken başlıkları siler. Bu nedenle kritik değerleri aynı zamanda Exchange Property olarak da saklamak iyi bir pratiktir.

Exchange Property Sekmesi

Exchange Property, SAP Integration Suite’in en güçlü değişken mekanizmalarından biridir. Burada tanımladığınız değerler tüm akış boyunca erişilebilir kalır ve birden fazla adım arasında veri taşımanızı kolaylaştırır.

Bir değeri property olarak kaydetmek için Expression Type sütununu XPath, Constant veya ${header.xxx} gibi seçeneklerden birine ayarlayıp Value alanına ilgili ifadeyi yazmanız yeterlidir.

Message Body Sekmesi

Bu sekme, mesajın gövdesini (payload) değiştirmenize olanak tanır. Sabit bir XML veya JSON içeriği girmek ya da Groovy/XSLT ile üretilmiş dinamik içeriği yerleştirmek için kullanılır. Özellikle downstream sisteme gönderilecek mesajın önceden şablonlandırılmış olduğu senaryolarda değerlidir.

Content Modifier’ı Adım Adım Yapılandırma

Aşağıdaki örnek senaryo, bir satış siparişi entegrasyonunda kullanılan Content Modifier konfigürasyonunu gerçek dünya yaklaşımıyla açıklamaktadır. SAP S/4HANA’dan gelen bir sipariş mesajının OrderID değeri property olarak saklanacak, ardından mesaj body’si zenginleştirilecektir.

Adım 1 – Integration Flow’a Content Modifier Ekleyin

• SAP Integration Suite Web IDE’yi açın ve ilgili entegrasyon akışını düzenleyin.
• Palette’ten Transformation > Content Modifier adımını sürükleyip akış üzerinde uygun konuma bırakın.
• Adımı tıklayarak sağ panelde özelliklerini açın.

Adım 2 – Exchange Property Tanımlayın

• Exchange Properties sekmesine geçin.
• Add butonuna tıklayın.
• Name alanına orderID yazın.
• Type olarak XPath seçin.
• Value alanına /Order/OrderID XPath ifadesini girin.
• Data Type alanını java.lang.String olarak bırakın.

Pratik Not – XPath Kullanımı: XPath ifadeleri, gelen mesajın XML yapısına göre değişir. Mesajın namespace içerdiği durumlarda namespace-uri() fonksiyonunu kullanmayı veya local-name() ile namespace’i devre dışı bırakmayı tercih edin.

//*[local-name()='OrderID']

Adım 3 – Message Body’yi Şekillendirin

• Message Body sekmesine geçin.
• Type alanını Constant olarak ayarlayın.
• Aşağıdaki gibi bir şablon girin:

<EnrichedOrder>
  <ID>${property.orderID}</ID>
  <ProcessedAt>${date:now:yyyy-MM-dd}</ProcessedAt>
</EnrichedOrder>

• Değişikliklerinizi kaydedin ve akışı deploy edin.

Adım 4 – Akışı Test Edin

SAP Integration Suite’in Monitoring ekranından ya da bir REST istemcisi (örn. Postman) üzerinden test mesajı gönderin. Message Processing Log bölümünde her adımın girdi ve çıktı payload’ını inceleyerek Content Modifier’ın beklediğiniz dönüşümü gerçekleştirip gerçekleştirmediğini doğrulayın.

Header mı, Exchange Property mi? Kritik Fark

SAP CPI öğrenme sürecinin en sık kafa karıştıran noktalarından biri, Message Header ile Exchange Property’nin ne zaman kullanılacağını bilmektir. Her ikisi de akış boyunca değer taşır; ancak kapsamları ve davranışları önemli ölçüde farklıdır.

Bu konuyu daha ayrıntılı anlamak için SAP Integration Suite’te Header, Property ve Exchange Nedir? yazımızı okumanızı öneririz.

Kural olarak: Bir değeri sadece akış içinde kullanacaksanız Exchange Property tercih edin. Değerin bir adapter tarafından okunması ya da hedef sisteme başlık olarak iletilmesi gerekiyorsa Message Header kullanın.

Yaygın Kullanım Senaryoları ve Örnekler

Senaryo 1 – Dinamik Routing için Değer Saklama

Bir Router adımından önce gelen mesajdaki müşteri tipi değerini (örn. PREMIUM veya STANDARD) property olarak saklayabilir, sonra Router koşulunda bu property’yi kullanabilirsiniz.

• Property adı: customerType
• Tip: XPath
• Değer: /Customer/Type

Senaryo 2 – HTTP Adapter’a Özel Başlık Ekleme

Bir REST servisi çağırırken Authorization başlığını Content Modifier ile eklemek, bu değeri akışın geri kalanından izole tutar ve adapter konfigürasyonunu temiz bırakır.

• Header adı: Authorization
• Tip: Constant
• Değer: Bearer eyJhbGciOiJSUzI1NiJ9...

Senaryo 3 – Hata Mesajı Üretimi

Exception subprocess içinde Content Modifier kullanarak insan tarafından okunabilir bir hata mesajı body’si oluşturabilirsiniz. Bu yaklaşım, hata bildirim e-postalarını ya da alert mesajlarını standartlaştırmak için idealdir.

Hata: ${exception.message} – Zaman: ${date:now:HH:mm:ss}

Senaryo 4 – Sabit Statik Mesaj Üretme

Downstream sisteme her zaman aynı acknowledgment mesajını göndermeniz gerekiyorsa Message Body sekmesinde sabit bir XML veya JSON içeriği tanımlayabilirsiniz. Bu, gereksiz mapping adımlarını ortadan kaldırır ve akışı sadeleştirir.

En İyi Pratikler ve Yaygın Hatalar

Yapmanız Önerilen Pratikler

• Property adlarını tutarlı bir isimlendirme kuralıyla belirleyin (örn. prop_orderID, prop_customerType). Büyük akışlarda bu alışkanlık bakım süresini yarıya indirir.
• Mümkün olduğunda sabit (Constant) değer yerine Expression kullanın; bu sayede değişen iş kurallarına uyum sağlamak kolaylaşır.
• Aynı değeri hem header hem property olarak kaydedin; adapter geçişlerinde header silinse bile property’den erişebilirsiniz.
• Content Modifier adımlarına açıklayıcı isimler verin (örn. “Set OrderID Property”). Monitoring ekranında hata ayıklamayı kolaylaştırır.
• Test aşamasında Message Processing Log > Trace modunu etkinleştirerek her adımın girdi/çıktısını karşılaştırın.

Kaçınılması Gereken Yaygın Hatalar

• Yanlış XPath ifadesi: Namespace içeren XML mesajlarında düz XPath çalışmaz. local-name() kullanmayı ihmal etmeyin.
• Boş değer kontrolü yapmamak: XPath sonucu boş dönebilir. Downstream adımlarda null-check eksikliği NPE hatalarına yol açar.
• Header’ı property yerine kullanmak: Akış içi geçici değerler için header kullanmak, adapter geçişlerinde değerin kaybolmasına neden olur.
• Aynı adımda fazla değişiklik yapmak: Tek bir Content Modifier’a çok fazla property/header yüklemek okunabilirliği düşürür. Sorumlulukları bölün.

SAP Integration Suite ile Bütünleşik Dönüşüm Mimarisi

MDP Group olarak gerçekleştirdiğimiz B2B entegrasyon projelerinde Content Modifier’ın doğru konumlandırılmasının akış kararlılığını ve bakım kolaylığını doğrudan etkilediğini gözlemledik. Content Modifier tek başına güçlü bir araç olsa da asıl değerini SAP Integration Suite’in diğer bileşenleriyle birlikte kullanıldığında ortaya çıkar.

Tipik bir B2B entegrasyonunda Content Modifier şu şekilde konumlandırılır:

1. Sender Adapter (SFTP/HTTPS) → Mesajı alır
2. Content Modifier #1 → Anahtar alanları Exchange Property olarak saklar
3. Router → Property değerine göre akışı yönlendirir
4. Message Mapping / XSLT → Payload dönüşümü
5. Content Modifier #2 → Hedef adapter için başlıkları ayarlar
6. Receiver Adapter (HTTP/OData) → Mesajı hedefe iletir
7. Exception Subprocess → Content Modifier #3 ile hata mesajı üretir

Bu mimari, SAP Integration Suite’in Cloud Integration katmanında yaygın olarak kullanılmaktadır. Özellikle SAP S/4HANA, SAP SuccessFactors ve üçüncü taraf sistemler arasındaki entegrasyonlarda Content Modifier, tutarlı bir veri akışı sağlamanın temel taşlarından biridir.

Daha ileri düzey dönüşümler için Content Modifier’ı Groovy Script veya XSLT Mapping adımlarıyla birleştirmeyi değerlendirin. Scheduler ve polling gibi zamanlama konularını öğrenmek için SAP Integration Suite Scheduler Polling Nedir? yazımızı inceleyebilirsiniz.

Sınırlama ve Uyarı: Bu rehberde anlatılan yöntemler SAP Integration Suite Cloud Integration bileşeni kapsamındadır. SAP Process Orchestration (PO) veya eski CPI sürümlerinde bazı özellikler farklı çalışabilir. Üretim ortamına geçmeden önce tüm konfigürasyonları sandbox ortamında test etmenizi öneririz.

Sık Sorulan Sorular (SSS)

Content Modifier ile Message Transformer arasındaki fark nedir?

Content Modifier, body, header ve property’yi aynı anda yönetebilen çok amaçlı bir adımdır. Message Transformer ise yalnızca mesaj gövdesinin formatını (örn. XML’den JSON’a) değiştirmek için kullanılır. Basit değer atamalarında Content Modifier tercih edilmeli, format dönüşümlerinde ise Message Transformer veya Mapping adımları kullanılmalıdır.

Exchange Property değerlerine akış dışından erişilebilir mi?

Hayır. Exchange Property yalnızca mevcut entegrasyon akışının çalışma zamanında geçerlidir. Akış tamamlandığında tüm property değerleri bellekten silinir ve dışarıya taşınmaz. Kalıcı veri saklamak için Data Store veya Variables kullanılmalıdır.

Birden fazla Content Modifier adımı kullanmak performansı etkiler mi?

Content Modifier son derece hafif bir adımdır ve performans üzerindeki etkisi ihmal edilebilir düzeydedir. Okunabilirlik ve bakım kolaylığı adına sorumlulukları birden fazla Content Modifier adımına bölmek, tek bir adıma çok fazla işlem yüklemekten daha iyi bir yaklaşımdır. SAP’nin resmi tasarım kılavuzları da bu yaklaşımı destekler.

Özet

Bu rehberde SAP Integration Suite’de Content Modifier bileşeninin kapsamlı bir incelemesini yaptık. Content Modifier; Message Header, Exchange Property ve Message Body olmak üzere üç katmanda çalışır. Exchange Property akış içi geçici değerleri saklamak için en güvenli yoldur. Message Header ise adapter’a özgü metadata taşımak için kullanılmalıdır. XPath, Constant ve Expression tipleriyle dinamik ya da statik değerler tanımlanabilir.

SAP Integration Suite ile entegrasyon geliştirme konusunda daha fazla içerik için SAP PI/PO’dan SAP Integration Suite’e Geçiş ve SAP Integration Suite ile Event-Driven Architecture Nedir? yazılarımızı inceleyebilirsiniz.

Referanslar

• SAP Help Portal – Content Modifier
• SAP Community Blog – Understanding Exchange Properties vs Headers in SAP CPI
• SAP Integration Suite Official Documentation – Integration Flow Design Guidelines
• SAP Learning – SAP Integration Suite for Developers
• SAP API Business Hub – SAP Integration Suite Samples

Gamze Yücel Kurtkapan

SAP PI/PO/CPI Danışmanı
Gamze Yücel Kurtkapan, SAP PI/PO/CPI ve Microsoft Azure Logic App alanında deneyime sahip bir entegrasyon danışmanıdır. Farklı sektörlerde birçok entegrasyon projesinde görev alan Gamze; SAP ve SAP dışı sistemlerin entegrasyonu, uçtan uca entegrasyon geliştirme ve modern bulut entegrasyon çözümleri üzerine uzmanlaşmıştır.