SAP bağlantısı, fonksiyon inceleme ve RFC çağrıları

Lunex’in SAP JCo bileşeni bir SAP sistemindeki RFC/BAPI fonksiyonunu çağırır. İstek gövdesi native JCo JSON biçimindedir; yanıt JSON metni mesajın yeni gövdesi olur. Aynı projedeki akışlar adlandırılmış bir SAP destination bean’ini paylaşabilir.

Bu rehber önce bağlantıyı ve fonksiyon sözleşmesini hazırlar, ardından kontrollü bir çağrı yaptırır. İş verisi yazan BAPI’lerde ayrıca açık transaction ve hata politikası gerekir.

Kurulum önkoşulları

JCo SDK Lunex ile dağıtılmaz. Özgün JAR veya uygun native kitaplık yoksa yalnız katalogda SAP seçmek RFC çalıştırmaz. Container Linux ise SDK da container’ın Linux mimarisiyle eşleşmelidir. Yerel işletim sisteminizin kitaplığını container’a vermek yeterli değildir.

SAP JCo ve SAP JCo Session, SAP desteği etkin kurulumlarda yeni adım seçicisinde görünür. Görünmüyorsa yöneticiniz runtime/SDK ve worker hazırlığını tamamlamalıdır. SAP gateway veya SAProuter gerekiyorsa yöneticiden doğru bağlantı bilgilerini alın; Lunex bu servisleri oluşturmaz.

Projeye SAP SDK’sını bağlayın

Kurulumda SAP’nin etkin olması bir projeye SAP eklemez. SAP kullanan her proje, kurulumun lunex-sap-sdk claim’ini kendi deployment.jkube.yaml dosyasında salt okunur olarak /opt/sapjco yoluna bağlar. Claim, node’daki SDK dizinini gösterir. Lunex runtime’ı bu mount’u görünce SAP desteğini yükler. Mount yoksa Run podu başlar, ancak destination bean’i oluşturulurken io.etzel.lunex.sap.SapJcoDestination sınıfı bulunamaz.

Fonksiyon arama ve inceleme metadata worker üzerinden çalışır; bu mount’a ihtiyaç duymaz. Mount, akışı Run veya Build ile çalıştırmak için gerekir.

1. Projede Source → deployment.jkube.yaml açın.
2. Mevcut metadata ve proje etiketlerini koruyun. Aşağıdaki alanları spec.template.spec altına birleştirin:

spec:
  template:
    spec:
      containers:
        - name: integration
          volumeMounts:
            - name: sap-sdk
              mountPath: /opt/sapjco
              readOnly: true
      volumes:
        - name: sap-sdk
          persistentVolumeClaim:
            claimName: lunex-sap-sdk
            readOnly: true

3. Kaydedin. Proje çalışıyorsa Kubernetes ortamında Delete container ile geliştirme runtime’ını kaldırın, ardından Run seçin. Run, kayıtlı dosyayı yalnız podu oluştururken okur.
4. Paketlenmiş sürüm için dosyayı commit edip gönderin ve Build çalıştırın. Build mount’u commit edilmiş dosyadan okur; yalnız kaydedilmiş bir değişiklik Build’e ulaşmaz.

Şablonla oluşturulan dosyada konteyner tanımı yoktur; örnekteki integration adı olduğu gibi kullanılabilir. Dosyanızda zaten bir konteyner varsa mount’u ilk konteynere ekleyin ve onun adını koruyun; Lunex yalnız ilk konteynerin /opt/sapjco mount’unu dikkate alır. Dosyada zaten spec, template, containers veya volumes varsa ikinci bir aynı adlı YAML anahtarı eklemeyin; mevcut yapıya birleştirin.

SDK’nın node’daki yolunu kurulum belirler; her ortamın lunex-sap-sdk claim’i kendi yolunu gösterir, bu yüzden aynı dosya geliştirme ve üretim ortamında değişmeden çalışır. Projeler hostPath volume kullanamaz: entegrasyon namespace’i Kubernetes Pod Security baseline düzeyini uygular ve hostPath, privileged gibi node’a erişen ayarları içeren podları reddeder. Birden fazla node’lu kurulumda SDK, podun çalışabileceği her node’da bulunmalıdır. Dizin node’da yoksa Kubernetes volume’u bağlayamaz ve pod başlamaz; bu durumda platform yöneticisine başvurun. SDK’yı projeye bağımlılık olarak eklemeyin. application.properties içindeki camel.jbang.dependencies alanında io.etzel.lunex:lunex-sap bulunursa Run ve Build bu bağımlılığı kaldırmanızı ister; SAP modülünü runtime imajı sağlar.

Destination oluşturun

Önkoşul: Geliştirme projesi düzenleme yetkisi ve kullanılacak SAP teknik kullanıcısı.

1. System → Secrets içinde örneğin sap-erp Secret’ını oluşturun; username ve password anahtarlarını ekleyin.
2. Projede Architecture → More create options → Bean açın.
3. Type → ERP, Template → SAP seçin.
4. Properties adımında Name değerini erp gibi benzersiz bir isim yapın.
5. Host, system number, client ve kimlik bilgisi referanslarını doldurun.
6. File adımında sap-connection.camel.yaml dosyasına kaydedin.

Örnek:

- beans:
    - name: erp
      type: '#class:io.etzel.lunex.sap.SapJcoDestination'
      properties:
        ashost: '{{sap.host}}'
        sysnr: '{{sap.sysnr}}'
        client: '{{sap.client}}'
        user: '{{secret:sap-erp/username}}'
        passwd: '{{secret:sap-erp/password}}'
        lang: EN

application.properties dosyasındaki hassas olmayan değerler:

sap.host=sap-dev.example.test
sap.sysnr=00
sap.client=100

Bu değerleri kendi SAP sisteminizle değiştirin. Message server üzerinden yük dağıtımı kullanılıyorsa uygun mshost, r3name, group; SAProuter için saprouter özellikleri kullanılabilir. Bağlantı havuzundaki poolCapacity boşta tutulan bağlantıları, peakLimit etkin bağlantı üst sınırını, maxGetTime bağlantı bekleme süresini yönetir. SAP sisteminin kapasitesine göre ayarlayın.

Bean adı aynı projede benzersiz olmalıdır. Başka bir projede aynı erp adı bulunması aynı JCo destination nesnesini paylaşmaz.

Fonksiyonu arayın ve inceleyin

Proje çalışmıyorken de fonksiyon metadata’sını inceleyebilirsiniz. Bu işlem seçtiğiniz iş fonksiyonunu çağırmaz.

1. Route’a bir SAP JCo çıkış adımı ekleyin.
2. Destination alanında erp bağlantısını seçin.
3. Bilinen adı Function alanına yazın veya Search SAP functions açın.
4. Aramada Function name pattern alanına örneğin BAPI_MATERIAL_* yazıp Search SAP kullanın. Buradaki * SAP fonksiyon adı aramasının jokeridir.
5. Sonuçları Filter returned functions ile daraltın, bir fonksiyon seçip Select and inspect kullanın. Elle yazdıysanız Inspect function açın.
6. Request ve Response sekmelerinde ad, yön, native tip, uzunluk, ondalık ve iç içe alan yollarını inceleyin.

Request import/changing/table girdilerini; Response export/changing/table çıktılarını gösterir. Beklenen sonuç, seçili destination ve fonksiyonun SAP’den alınan güncel sözleşmesidir. Inspect function, gerekli proje dosyalarının kaydını bekler; kaydetme hatası varsa eski kaynakla incelemeye devam etmez.

Arama kayıtlı bağlantı üzerinden çalışır. Salt okunur projede arama/inceleme yapılabilir, ancak seçim kaynak dosyasına yazılamaz. İki dosyada aynı destination adı varsa Duplicate connection name hatasını adları benzersiz yaparak giderin.

Örnek istek, yanıt ve şema üretin

1. Inspect function penceresinde Generate project files seçin.
2. Dosya önekini ve dört hedef adı kontrol edin:
   • <prefix>.request.json
   • <prefix>.response.json
   • <prefix>.request.schema.json
   • <prefix>.response.schema.json
3. Mevcut dosyalarda Keep existing file veya yalnız değiştirmek istediklerinizde Replace existing file seçin.
4. Generate files kullanın; kaydedilen, korunan ve başarısız dosyaların sonuçlarını ayrı kontrol edin.
5. Source listesinden request dosyasını açıp işinize ait örnek değerleri girin.

Açık editördeki dosya değiştirme için korunur; düzenlemesini bitirip kapattıktan sonra yeniden deneyin. Dosyalar tek tek kaydedilir; biri başarısız olduğunda daha önce kaydedilenler kalır. Bu işlem Git commit oluşturmaz.

Üretilen response dosyası bir örnektir; gerçek çağrı sonucu değildir ve her çağrıda üzerine yazılmaz. Şemalar sözleşmeyi anlamaya yardımcı olur; route’a otomatik runtime doğrulaması eklemez. Büyük sayılar ve ondalıklar için native JSON metnini koruyun; gereksiz ara JSON dönüşümleriyle sayısal hassasiyeti kaybetmeyin.

Kontrollü bir RFC çağrısı yapın

SAP yöneticinizin test için izin verdiği, iş verisi yazmayan bir fonksiyonla başlayın. Örneğin sisteminizde mevcut ve izinliyse STFC_CONNECTION, REQUTEXT girdisini kullanabilir.

erp bean’inin bulunduğu proje içinde:

- route:
    id: sap-connection-check
    from:
      uri: timer:sap-connection-check
      parameters:
        repeatCount: 1
      steps:
        - setBody:
            constant: '{"REQUTEXT":"Lunex connection check"}'
        - to:
            uri: sap-jco:STFC_CONNECTION
            parameters:
              destination: '#bean:erp'
        - bean:
            ref: lunexMonitor
            method: "appendAttachment('sap-response.json','application/json',${body})"

1. Fonksiyonun Request sözleşmesini kontrol edin.
2. Örnek route’u kaydedin. Projenin deployment.jkube.yaml dosyasında SDK mount’unun bulunduğunu doğrulayın (Projeye SAP SDK’sını bağlayın).
3. Run kullanın. Timer her runtime başlangıcında bir kez çağrı yapar.
4. Log ve Message Monitor sonucunu kontrol edin. Info veya daha ayrıntılı kayıt seviyesinde, ilgili run’ın Attachments bölümündeki sap-response.json ekini açın.
5. Bu test fonksiyonunun gerçek yanıtını beklenen native JSON alanlarıyla karşılaştırın. Gerçek iş fonksiyonlarında teşhis ekine hangi verilerin yazılacağını ayrıca belirleyin.

Bir request dosyasını gövdeye yüklemek için önceki Set Body yerine şunu kullanabilirsiniz:

- setBody:
    constant: resource:classpath:my-function.request.json

Kaynağı değiştirdikten sonra akışı yeniden başlatın; constant resource başlangıçta yüklenir. İstek dosyası veridir, çalıştırılacak bir jq programı değildir. Dönüşüm adımlarınız da aynı native request JSON biçimini üretmelidir.

İş hatası ve teknik hata farklıdır

Bağlantı veya RFC yürütme hatası normal route hata yönetimine gider. Ancak BAPI, Java exception atmadan RETURN alanında iş hatası döndürebilir. Bileşen bu alanı otomatik yorumlamaz; fonksiyonun sözleşmesine göre dönüşü kontrol edip başarı, hata yanıtı veya exception üreten route adımlarını ekleyin.

Message Monitor → Completed, route’un tamamlandığını gösterir. RETURN içindeki iş hatasını kontrol etmediyseniz bu durum iş belgesinin başarıyla oluştuğu anlamına gelmez. Bir REST API arkasından çağırıyorsanız dış API hata kodu ve response body eşlemesini de açıkça tasarlayın.

Yazma işlemlerinde açık transaction

Session açmadan yapılan normal sap-jco çağrıları stateless çalışır. Bir SAP logical unit of work içinde birden fazla BAPI ve commit gerekiyorsa aynı destination ile aşağıdaki sırayı tasarlayın:

İş çağrısının yanıtına commit sonrasında ihtiyacınız varsa commit’ten önce bir exchange property’de saklayın. Rollback’i yalnız session’ın açıldığı hata kapsamına yerleştirin; başarısız bir begin sonrasında açık session varmış gibi rollback çağırmayın. Beklenmeyen hata sonrası kapanış fallback’i vardır, ancak bu fallback otomatik iş rollback veya commit yapmaz.

wait=true native yüksek öncelikli update işinin beklenmesini ister. wait=false, kalıcılığın dönüş anında tamamlandığını garanti etmez. İki destination kullanmak tek atomik dağıtık transaction oluşturmaz.

Açık session’ı paralel split/multicast, fire-and-forget kuyruk veya eşzamanlı işler arasında paylaşmayın. Sıralı thread geçişleri ve sonucu tamamen beklenen SEDA geçişleri desteklenebilir; bağımsız tüketici kendi session’ını açmalıdır. Native Camel yeniden denemesi başarısız adımdan devam edebilir; bütün LUW’yu otomatik yeniden oynatmaz.

Belirsiz bağlantı hatasından sonra yazma fonksiyonunu tekrar çağırmadan önce SAP’deki iş durumunu kontrol edin. Tekrar güvenliği, iş anahtarı ve BAPI sözleşmesiyle çözülmelidir.

SAP arayüzü değiştiğinde

1. Inspect function penceresindeki Refresh kullanın. Bu işlem metadata önbelleğini yeniler; mevcut request dosyanızı değiştirmez.
2. Yeni iç içe alanları Request / Response sekmelerinde kontrol edin.
3. Gerekiyorsa dosyaları ayrı bir Generate project files işlemiyle ve bilinçli değiştirme seçimiyle güncelleyin.
4. Çalışan projenin JVM’ini yeniden başlatın. Tasarım worker’ını yenilemek çalışan projenin native metadata önbelleğini yenilemez; yalnız route reload yeterli olmayabilir.

Destek kapsamı ve sorun giderme

Bu SAP bileşeni outbound RFC/BAPI producer’ıdır. Gelen RFC server/gateway kaydı, IDoc consumer/producer, tRFC/qRFC ve TID yönetimi bu endpoint’in sunulan işlemleri değildir. SAP’nin HTTP/OData/SOAP servisleri varsa uygun genel HTTP/SOAP bileşeniyle ayrı bir sözleşme üzerinden bağlanabilir; bu servislerin SAP tarafında hazır olması gerekir.