Yeni müşteriler için kırk karşılama mektubu, her katılımcı için bir sertifika, her sipariş için bir fatura: aynı belge, her seferinde farklı bir kayıt. GroupDocs.Assembly.Mcp yerel olarak çalışırken (dnx GroupDocs.Assembly.Mcp --yes), Claude Desktop, Cursor veya Copilot bunu tek bir araç çağrısı, assemble_per_record ile yapar; bu, Word şablonunuzu JSON dizisinin her öğesi için bir kez doldurur, her sonucu seçtiğiniz bir alanla adlandırılmış kendi PDF’si olarak kaydeder ve başarısız olan kayıtları, ilkinde durmak yerine raporlar:

Her müşteri için customers.json dosyasındaki bir karşılama mektubu PDF’si oluştur ve her dosyayı müşteri adına adlandır.

Adım adım yapılandırma ve sorun giderme sürümü belgelerde bulunabilir: How to generate one document per record (mail merge) with an AI agent.

Neden aracı döngüye bırakmıyoruz?

Bunu yapabilir ve beş kayıt için bu sorun yaratmaz. Ancak kırk araç çağrısı içeren bir döngü, ajanın saymayı kaybetmesi, bağlam uzunlaştığında bir kaydı atlaması ya da “yardımcı” bir şekilde bir mektubu yeniden ifade etmesi için kırk fırsat demektir. Kayıt başına bir araç döngüyü sunucuya taşır: tek bir çağrı, tek bir şablon, dizi üzerinde tek bir geçiş ve kaç dosyanın yazıldığını ve hangi kayıtların başarısız olduğunu tam olarak belirten bir rapor. Ajana düşen görev şablonu, veri dosyasını ve adlandırma alanını seçmek, ardından raporu size geri okumaktır.

Ajan önce neyi kontrol eder?

İki şey: verinin nasıl göründüğü ve şablonun ne okuduğu. Testimizde customers.json içinde beş müşteri ve tek sayfalık bir karşılama mektubu vardı:

-> get_document_info {"file":{"filePath":"customers.json"}}
<- { "dataKind": "json",
     "data": { "root": "array", "length": 5, "keys": null } }

-> get_template_fields {"template":{"filePath":"welcome-letter.docx"}}
<- { "dataSourceNames": [ "customer" ],
     "fields": [ "customer.Contact", "customer.Plan", "customer.Name",
                 "customer.Manager", "customer.FirstInvoice" ] }

Şablon bir kayıt customer olarak çağrılır; sunucu bunu kendiliğinden çözer, bu yüzden ajanın dataSourceName geçmesine gerek yoktur.

Tek çağrı, beş kayıt, bir hata

-> assemble_per_record {"template":{"filePath":"welcome-letter.docx"},
     "data":{"filePath":"customers.json"},"fileNameField":"Name",
     "format":"pdf"}
<- Assembled 4 of 5 document(s) from 'welcome-letter.docx' with
   'customers.json', one per record (each record as 'customer'), as PDF.
   Saved to:
   .../Contoso Pharma.pdf
   .../Fabrikam Logistics.pdf
   .../Tailspin Toys.pdf
   .../Litware Labs.pdf
   1 record(s) failed:
   record 4: InvalidOperationException: ... Can not get the value of
   member 'FirstInvoice' on type 'System.Data.DataRow'. The template
   reads 'FirstInvoice', which the data does not have. ...

Kayıt 4, Wingtip Travel, veride bir ilk-fatura tarihi içermiyordu. Diğer dört mektup yazıldı, her biri müşterinin adıyla adlandırıldı ve hata, kayıt numarası ve eksik alanla geri döndü. Bir ajan bunu şu şekilde raporlar: “dört mektup tamamlandı; Wingtip Travel’ın ilk-fatura tarihi yok, satırı boş bırakmamı mı yoksa tarihi beklememi mi istersiniz?”. Bu, kırk dosya ve hangisinin yanlış olduğunu bilmediğiniz bir durumdan çok istediğiniz konuşmadır.

Fan‑out nasıl çalışır

customers.json  [ {Name:"Contoso Pharma",...}, {Name:"Fabrikam ..."},
                  ... 5 records ]
        |
assemble_per_record {"template":{"filePath":"welcome-letter.docx"},
                     "data":{"filePath":"customers.json"},
                     "fileNameField":"Name","format":"pdf"}
        |
        +--> Contoso Pharma.pdf
        +--> Fabrikam Logistics.pdf     ... 2 more
        '--> "4 of 5 ... 1 record(s) failed: record 4 ..."

Üç parametre işi halleder. fileNameField, çıktıyı kaydın kendisindeki bir alanla adlandırır: burada Name ya da her kaydın bir nesne içerdiği durumlarda order.Number gibi noktalı bir yol. Düz kayıtlar üzerinde customer.Name her zaman başarısız olur (“kaydın dosyasını adlandıracak ‘customer.Name’ alanı yok”). Bu parametre olmadan dosyalar artan bir sayı alır ve aynı ada sahip bir dosya asla üzerine yazılmaz: yeni dosya (1) alır. recordsPath, JSON bir nesne içinde dizi barındırıyorsa (ör. "customers" veya "batch.items"), bu diziye işaret eder. maxDocuments ise fren görevi görür.

Kontrolsüz bir toplu işin önüne ne geçer?

maxDocuments, varsayılan olarak 100 ve en fazla 1000 olabilir. Herhangi bir şey yazılmadan önce sunucu kayıtları sayar; limitten fazla ise reddeder. Beş müşterimiz için sınırı 3 olarak ayarladık:

-> assemble_per_record {..., "maxDocuments":3}
<- Per-record assembly failed for 'welcome-letter.docx': there are 5
   records, more than maxDocuments=3. Raise 'maxDocuments' (up to 1000)
   or pass fewer records.

Hiçbir şey yazılmadı. Gerçek kişilere gönderilecek bir posta için bu doğru varsayılandır: bütün CRM dışa aktarımına yanlışlıkla işaret eden bir komut, on bin PDF yerine bir soru ile geri döner.

Verilerim bir elektronik tablo, JSON değil

Kayıt‑başına üretim yalnızca JSON okur: nesneler dizisi ya da bir nesne içinde tutulan bir dizi. Liste bir CSV ya da çalışma sayfasında ise ajan önce satırları JSON’a dönüştürür; bu, ajanların iyi yaptığı bir işlemdir ve dosyayı depolama klasörüne yazar. Eğer amacınız her satırı listeleyen tek bir belge (fiyat listesi ya da kayıt defteri gibi) ise, bu assemble_document ile şablondaki <<foreach>> kullanılarak yapılır ve CSV ile elektronik tablolar doğrudan okunur.

Dürüst sınırlamalar

  • Kayıt‑başına birleştirme yalnızca JSON okur; CSV ve elektronik tablo verileri önce dönüştürülmelidir.
  • Değerlendirme modu: oluşturulan her dosya “Evaluation Only. Created with GroupDocs.Assembly 26.7…” satırıyla başlar ve e‑posta şablonları yalnızca düz metin gövdesini tutar. Gerçek bir posta göndermeden önce sunucuyu lisanslayın.
  • Eksik bir alan o kaydı başarısız kılar. allowMissingMembers: true ayarı, satırı boş bırakarak dosyayı yazar; hangisini istediğinize karar verin.
  • Tarihler: 2026-12-01T00:00:00 biçiminde yazın ve şablonda biçimlendirin; mektubumuzda <<[customer.FirstInvoice]:"d MMMM yyyy">> kullanılmıştır. Testimizde UTC+2 makinede bir gün kaydırılmış bir tarih‑sadece dizeydi.
  • Sunucu dosyaları yazar; göndermez. Teslimat ayrı bir adımdır.

SSS

Claude ile müşteri listesini yüklemeden toplu birleştirme yapabilir miyim?
Evet. Sunucu yerel olarak çalışır ve customers.json dosyasını depolama klasörünüzden okur; oluşturulan PDF’ler de aynı klasöre yazılır.

Çıktı dosyaları nasıl adlandırılır?
fileNameField olarak belirttiğiniz kayıt alanına göre, burada müşteri adı, yani Contoso Pharma.pdf. Bu alan belirtilmezse artan bir sayı kullanılır.

Her belge PDF yerine bir e‑posta olabilir mi?
Evet, şablon bir e‑posta ise: EML veya MSG şablonu eml, emlx ya da msg olarak kaydedilir, kayıt başına bir mesaj olur. Bu mektup gibi bir Word şablonu e‑posta olarak kaydedilemez; sunucu “a WordProcessing template cannot be saved as ’eml’” hatası verir. Değerlendirme modunda bir e‑posta’nın HTML gövdesi değerlendirme satırıyla değiştirilir; lisanslı bir ortamda e‑posta çıktısını test edin.

Daha derine inin