Posting ini mencakup cara melakukan operasi Mail Merge dalam dokumen MS Word menggunakan Java. Di akhir artikel ini, Anda akan mempelajari cara membuat template Mail Merge dan menjalankan Mail Merge secara terprogram.

Tentang Gabungan Surat

Mail Merge adalah cara mudah untuk menghasilkan surat, amplop, faktur, laporan, dan jenis dokumen lainnya secara dinamis. Menggunakan Gabungan Surat, Anda membuat file templat yang berisi bidang gabungan lalu mengisi bidang tersebut menggunakan data di sumber data. Misalkan Anda harus mengirim surat ke 20 orang yang berbeda dan Anda hanya perlu mengubah nama dan alamat penerima pada setiap salinan. Dalam hal ini, Anda dapat membuat template Gabungan Surat untuk surat tersebut dan kemudian menghasilkan 20 huruf dengan mengisi bidang nama dan alamat secara dinamis.

Java Mail Merge API - Unduhan Gratis

Aspose.Words for Java adalah API pengolah kata terkenal yang memungkinkan Anda membuat berbagai jenis dokumen dari awal. API menyediakan fitur Gabungan Surat bawaan yang memungkinkan Anda membuat dokumen secara dinamis menggunakan templat dan sumber data. Aspose.Words for Java dapat diunduh sebagai JAR atau diinstal dalam aplikasi berbasis Maven.

<repository>
    <id>AsposeJavaAPI</id>
    <name>Aspose Java API</name>
    <url>https://repository.aspose.com/repo/</url>
</repository>

<dependency>
    <groupId>com.aspose</groupId>
    <artifactId>aspose-words</artifactId>
    <version>20.11</version>
    <classifier>jdk17</classifier>
</dependency>

Sumber Data untuk Gabungan Surat

Data dalam Mail Merge dapat diambil dari sumber data apa pun seperti JSON, XML, spreadsheet, atau database.

Buat Template untuk Mail Merge di MS Word

Template yang digunakan dalam Mail Merge dapat berupa dokumen Word sederhana (yaitu DOCX) dan tidak perlu dalam format template. Dokumen template berisi kolom gabungan yang diisi dengan data saat Mail Merge dijalankan. Berikut langkah-langkah cara membuat template Mail Merge menggunakan MS Word.

  • Buat dokumen baru di MS Word.
  • Tempatkan kursor di tempat Anda ingin menambahkan bidang gabungan.
  • Dari menu Insert pilih opsi Field.
  • Dari daftar Nama bidang, pilih MergeField.
  • Masukkan nama untuk bidang gabungan di Nama bidang dan tekan OK.
  • Simpan dokumen sebagai DOCX.

Berikut adalah screenshot dari dokumen contoh template.

templat kata gabungan surat

Buat Template Gabungan Surat menggunakan Java

Anda juga dapat membuat template Mail Merge secara terprogram. Berikut ini adalah langkah-langkah untuk itu.

Contoh kode berikut menunjukkan cara membuat template Mail Merge menggunakan Java.

// Buat pembuat dokumen
DocumentBuilder builder = new DocumentBuilder();

// Sisipkan bidang input teks, nama unik bidang ini adalah "Halo", parameter lainnya ditentukan
// jenis FormField apa, format teks, hasil bidang dan panjang teks maksimum (0 = tidak ada batas)
builder.insertTextInput("TextInput", TextFormFieldType.REGULAR, "", "Hello", 0);
builder.insertField("MERGEFIELD CustomerFirstName \\* MERGEFORMAT");

builder.insertTextInput("TextInput1", TextFormFieldType.REGULAR, "", " ", 0);
builder.insertField("MERGEFIELD CustomerLastName \\* MERGEFORMAT");

builder.insertTextInput("TextInput1", TextFormFieldType.REGULAR, "", " , ", 0);

// Masukkan jeda paragraf ke dalam dokumen
builder.insertParagraph();

// Sisipkan badan surat
builder.insertTextInput("TextInput", TextFormFieldType.REGULAR, "", "Thanks for purchasing our ", 0);
builder.insertField("MERGEFIELD ProductName \\* MERGEFORMAT");

builder.insertTextInput("TextInput", TextFormFieldType.REGULAR, "", ", please download your Invoice at ",
	0);
builder.insertField("MERGEFIELD InvoiceURL \\* MERGEFORMAT");

builder.insertTextInput("TextInput", TextFormFieldType.REGULAR, "",
	". If you have any questions please call ", 0);
builder.insertField("MERGEFIELD Supportphone \\* MERGEFORMAT");

builder.insertTextInput("TextInput", TextFormFieldType.REGULAR, "", ", or email us at ", 0);
builder.insertField("MERGEFIELD SupportEmail \\* MERGEFORMAT");

builder.insertTextInput("TextInput", TextFormFieldType.REGULAR, "", ".", 0);

builder.insertParagraph();

// Sisipkan akhiran surat
builder.insertTextInput("TextInput", TextFormFieldType.REGULAR, "", "Best regards,", 0);
builder.insertBreak(BreakType.LINE_BREAK);
builder.insertField("MERGEFIELD EmployeeFullname \\* MERGEFORMAT");

builder.insertTextInput("TextInput1", TextFormFieldType.REGULAR, "", " ", 0);
builder.insertField("MERGEFIELD EmployeeDepartment \\* MERGEFORMAT");

// Simpan dokumen
builder.getDocument().save("document.docx");

Lakukan Mail Merge di Dokumen Word menggunakan Java

Setelah templat siap, Anda dapat mengisi kolom gabungan dengan data. Berikut adalah langkah-langkah melakukan Mail Merge pada template Word.

Contoh kode berikut menunjukkan cara melakukan gabungan surat dalam dokumen Word menggunakan Java.

// Sertakan kode untuk template kita
Document doc = new Document();

// Berikan dokumen ke pembuat dokumen
DocumentBuilder builder = new DocumentBuilder(doc);

// Buat Bidang Gabungan
builder.insertField(" MERGEFIELD CustomerName ");
builder.insertParagraph();
builder.insertField(" MERGEFIELD Item ");
builder.insertParagraph();
builder.insertField(" MERGEFIELD Quantity ");

// Simpan templatnya
builder.getDocument().save("MailMerge.TestTemplate.docx");

// Isi kolom dalam dokumen dengan data pengguna
doc.getMailMerge().execute(new String[] { "CustomerName", "Item", "Quantity" },
		new Object[] { "John Doe", "Hawaiian", "2" });

// Simpan dokumen 
builder.getDocument().save("MailMerge.Simple.docx");

Templat

gabungan surat sederhana di java

Keluaran

gabungan surat sederhana

Lakukan Penggabungan Surat menggunakan Sumber Data XML

Pada contoh sebelumnya, kami melakukan Mail Merge menggunakan objek Java. Namun, di sebagian besar kasus, sumber data digunakan untuk mengisi kolom gabungan. Untuk demonstrasi, mari lihat cara menggunakan sumber data XML di Mail Merge. Berikut ini adalah langkah-langkah untuk itu.

  • Muat sumber data XML menggunakan kelas DataSet.
  • Muat template Mail Merge menggunakan kelas Document.
  • Gunakan fungsi eksekusi untuk mengisi kolom gabungan menggunakan tabel data yang diinginkan di sumber data.
  • Simpan dokumen Word yang dihasilkan menggunakan metode Document.save(String).

Berikut ini adalah sumber data XML yang digunakan dalam contoh ini.

<?xml version="1.0" encoding="utf-8"?>
<customers>
	 <customer Name="John Ben Jan" ID="1" Domain="History" City="Boston"/>
 	<customer Name="Lisa Lane" ID="2" Domain="Chemistry" City="LA"/>
	 <customer Name="Dagomir Zits" ID="3" Domain="Heraldry" City="Milwaukee"/>
 	<customer Name="Sara Careira Santy" ID="4" Domain="IT" City="Miami"/>
</customers>

Contoh kode berikut menunjukkan cara mengisi template Mail Merge menggunakan tabel data Pelanggan di sumber data XML yang disediakan.

// Buat Dataset dan baca XML
DataSet customersDs = new DataSet();
customersDs.readXml("Customers.xml");

// Buka dokumen templat
Document doc = new Document("TestFile XML.docx");

// Jalankan penggabungan surat untuk mengisi template dengan data dari XML menggunakan DataTable.
// Perhatikan bahwa kelas ini juga berfungsi dengan satu wilayah berulang (dan semua wilayah bersarang).
// Untuk menggabungkan beberapa wilayah sekaligus dari satu sumber data XML, gunakan kelas XmlMailMergeDataSet.
// misalnya doc.getMailMerge().executeWithRegions(new XmlMailMergeDataSet(xmlData));
doc.getMailMerge().execute(customersDs.getTables().get("Customer"));

// Simpan dokumen keluaran
doc.save("generated-document.docx");

Templat

gabungan surat dengan XML

Keluaran

gabungan surat xml

Mail Merge dengan Wilayah di Jawa

Dalam kasus tertentu, Anda mungkin perlu mengulangi bagian tertentu dalam dokumen. Misalnya, Anda ingin menampilkan pesanan yang dilakukan oleh setiap pelanggan di tabel terpisah. Dalam kasus seperti itu, Anda dapat memanfaatkan wilayah Gabungan Surat. Untuk membuat region, Anda dapat menentukan awal dan akhir region. Akibatnya, wilayah tersebut akan diulangi untuk setiap instance data selama eksekusi Mail Merge.

Screenshot berikut menampilkan template yang wilayahnya terdiri dari tabel. Dimulai dengan «TableStart:Pelanggan» dan berakhir di «TableEnd:Pelanggan».

templat wilayah gabungan surat

Contoh kode berikut menunjukkan cara membuat template dengan region dan mengisinya dengan data.

// Buat dokumen
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// Titik awal gabungan surat dengan wilayah kumpulan data.
builder.insertField(" MERGEFIELD TableStart:Customers");
// Data dari baris kolom "NamaPelanggan" dari tabel "Pelanggan" akan masuk
// di MERGEFIELD ini.
builder.write("Orders for ");
builder.insertField(" MERGEFIELD CustomerName");
builder.write(":");

// Buat tajuk kolom
builder.startTable();
builder.insertCell();
builder.write("Item");
builder.insertCell();
builder.write("Quantity");
builder.endRow();

// Kami memiliki tabel data kedua yang disebut "Pesanan", yang memiliki banyak-ke-satu
// hubungan dengan "Pelanggan"
// mengambil baris dengan nilai CustomerID yang sama.
builder.insertCell();
builder.insertField(" MERGEFIELD TableStart:Orders");
builder.insertField(" MERGEFIELD ItemName");
builder.insertCell();
builder.insertField(" MERGEFIELD Quantity");
builder.insertField(" MERGEFIELD TableEnd:Orders");
builder.endTable();

// Titik akhir gabungan surat dengan wilayah.
builder.insertField(" MERGEFIELD TableEnd:Customers");

// Lewati kumpulan data kami untuk melakukan gabungan surat dengan wilayah.
DataSet customersAndOrders = CreateDataSet();
doc.getMailMerge().executeWithRegions(customersAndOrders);

// Simpan hasilnya
doc.save("MailMerge.ExecuteWithRegions.docx");

Keluaran

wilayah gabungan surat

Buat Wilayah Gabungan Surat Bersarang menggunakan Java

Skenario populer lainnya di Mail Merge adalah saat Anda memiliki wilayah bersarang. Misalnya, ketika Anda harus membuat daftar pesanan dan item di setiap pesanan, Anda dapat menggunakan wilayah bersarang. Gambar berikut membuat gambar lebih jelas tentang wilayah bersarang.

Pada gambar di atas, kita memiliki tabel Orders dan tabel Items dimana setiap record di Items ditautkan ke record di Orders. Oleh karena itu, ada hubungan satu-ke-banyak antara kedua tabel ini. Dalam kasus seperti itu, Aspose.Words mengeksekusi Mail Merge untuk menjaga hubungan yang ditentukan dalam Kumpulan Data. Misalnya, jika kita memiliki sumber data XML maka Aspose.Words akan menggunakan informasi skema atau struktur XML untuk mengetahui hubungannya. Dengan demikian, Anda tidak perlu menanganinya sendiri secara manual dan metode Document.getMailMerge().executeWithRegions(DataSet) akan bekerja untuk Anda (seperti contoh sebelumnya).

Terapkan Pemformatan Kustom pada Bidang Gabungan

Untuk memberi Anda lebih banyak kontrol atas Penggabungan Surat, Aspose.Words for Java memungkinkan Anda menyesuaikan bidang gabungan selama eksekusi Penggabungan Surat. Metode setFieldMergingCallback(IFieldMergingCallback) menerima kelas yang mengimplementasikan metode fieldMerging(FieldMergingArgs) dan imageFieldMerging(ImageFieldMergingArgs) untuk kontrol kustom atas proses Mail Merge. Peristiwa fieldMerging(FieldMergingArgs) terjadi saat bidang gabungan ditemui selama eksekusi Mail Merge.

Berikut ini adalah contoh kode lengkap tentang cara menyesuaikan operasi Mail Merge dan menerapkan pemformatan ke sel.

public class ApplyCustomFormattingDuringMailMerge {

    private static final String dataDir = Utils.getSharedDataDir(ApplyCustomFormattingDuringMailMerge.class) + "MailMerge/";

    public static void main(String[] args) throws Exception {
        Document doc = new Document(dataDir + "MailMerge.AlternatingRows.doc");

        // Tambahkan handler untuk acara MergeField.
        doc.getMailMerge().setFieldMergingCallback(new HandleMergeFieldAlternatingRows());

        // Jalankan gabungan surat dengan wilayah.
        DataTable dataTable = getSuppliersDataTable();
        doc.getMailMerge().executeWithRegions(dataTable);

        doc.save(dataDir + "MailMerge.AlternatingRows Out.doc");
    }

    /**
     * Mengembalikan true jika nilainya ganjil; salah jika nilainya genap.
     */
    public static boolean isOdd(int value) throws Exception {
        return (value % 2 != 0);
    }

    /**
     * Buat DataTable dan isi dengan data. Dalam kehidupan nyata DataTable ini
     * harus diisi dari database.
     */
    private static DataTable getSuppliersDataTable() throws Exception {
        java.sql.ResultSet resultSet = createCachedRowSet(new String[]{"CompanyName", "ContactName"});

       for (int i = 0; i < 10; i++)
            addRow(resultSet, new String[]{"Company " + Integer.toString(i), "Contact " + Integer.toString(i)});

        return new DataTable(resultSet, "Suppliers");
    }

    /**
     * Metode pembantu yang membuat ResultSet terputus dengan Java kosong
     * kolom yang ditentukan.
     */
    private static ResultSet createCachedRowSet(String[] columnNames) throws Exception {
        RowSetMetaDataImpl metaData = new RowSetMetaDataImpl();
        metaData.setColumnCount(columnNames.length);
       for (int i = 0; i < columnNames.length; i++) {
            metaData.setColumnName(i + 1, columnNames[i]);
            metaData.setColumnType(i + 1, java.sql.Types.VARCHAR);
        }

        CachedRowSet rowSet = RowSetProvider.newFactory().createCachedRowSet();
        ;
        rowSet.setMetaData(metaData);

        return rowSet;
    }

    /**
     * Metode pembantu yang menambahkan baris baru dengan nilai yang ditentukan ke a
     * ResultSet yang terputus.
     */
    private static void addRow(ResultSet resultSet, String[] values) throws Exception {
        resultSet.moveToInsertRow();

       for (int i = 0; i < values.length; i++)
            resultSet.updateString(i + 1, values[i]);

        resultSet.insertRow();

        // "Tarian" ini diperlukan untuk menambahkan baris ke akhir set hasil dengan benar.
        // Jika saya melakukan sesuatu yang lain maka baris ditambahkan di depan atau hasilnya
        // set melontarkan pengecualian tentang baris yang dihapus selama penggabungan surat.
        resultSet.moveToCurrentRow();
        resultSet.last();
    }
}

class HandleMergeFieldAlternatingRows implements IFieldMergingCallback {
    /**
     * Dipanggil untuk setiap bidang gabungan yang ditemui dalam dokumen. Kita juga bisa
     * kembalikan beberapa data ke mesin gabungan surat atau lakukan sesuatu yang lain dengan
     * dokumen. Dalam hal ini kami memodifikasi pemformatan sel.
     */
    public void fieldMerging(FieldMergingArgs e) throws Exception {
        if (mBuilder == null)
            mBuilder = new DocumentBuilder(e.getDocument());

        // Dengan cara ini kami menangkap awal dari baris baru.
        if (e.getFieldName().equals("CompanyName")) {
            // Pilih warna tergantung pada apakah nomor barisnya genap atau ganjil.
            Color rowColor;
            if (ApplyCustomFormattingDuringMailMerge.isOdd(mRowIdx))
                rowColor = new Color(213, 227, 235);
            else
                rowColor = new Color(242, 242, 242);

            // Tidak ada cara untuk menyetel properti sel untuk seluruh baris saat ini,
            // jadi kita harus mengulangi semua sel di baris.
           for (int colIdx = 0; colIdx < 4; colIdx++) {
                mBuilder.moveToCell(0, mRowIdx, colIdx, 0);
                mBuilder.getCellFormat().getShading().setBackgroundPatternColor(rowColor);
            }

            mRowIdx++;
        }
    }

    public void imageFieldMerging(ImageFieldMergingArgs args) throws Exception {
        // Tidak melakukan apapun.
    }

    private DocumentBuilder mBuilder;
    private int mRowIdx;
}

Kesimpulan

Mail Merge memberi Anda berbagai fitur untuk menghasilkan dokumen MS Word secara dinamis. Anda dapat membuat laporan sederhana maupun kompleks berdasarkan data di database atau sumber data lainnya. Pada artikel ini, Anda telah melihat bagaimana mengimplementasikan fitur Mail Merge secara terprogram menggunakan Java. Anda dapat mempelajari lebih lanjut tentang Java Mail Merge API menggunakan dokumentasi.

Lihat juga