Create batch import

Updated date: 29/10/2024
Updated by: VNPT eContract's team

---

Allow creating document batches based on templates with placeholder data. The process of creating a document batch includes the following steps:

• Step 1: Prepare a template file containing the necessary placeholders
• Step 2: Upload the template file and configure it
• Step 3: Prepare data for creating the document batch from the template
• Step 4: Call the API to create the document batch from the template
• Step 5: Initiate the signing process

Preparing a Template File with Placeholders

Prepare a template file (.docx format) with placeholder parameters. The variable naming convention is {{variable_name}}.
Example: a rental contract template with placeholders:

Uploading the Template File and Configuring

Log in to the VNPT eContract Web system and navigate to the document management screen /App/DocumentTemplate, then select “Create New” to upload the document template.

Once successfully added, proceed by selecting “Edit” to configure signature positions and parameters.

Choose "Add Signature Position" to add a signature box for the signer.

Place the signature boxes at the appropriate positions for signing; multiple signature boxes can be added. For example, adding two signature boxes at the bottom of the page, with box 1 for {{ben_a}} to sign and box 2 for {{ben_b}} to sign.

Preparing Data for Document Creation from the Template

Prepare the request data for the API call to create a document batch based on the template. The information required for creating the document batch includes:

• Document batch name name: used to distinguish between created document batches.
• Department departmentId: specifies the department to which the document belongs, aiding in reporting.
• Document type documentTypeId: identifies the type of document to create, aiding in reporting.
• Document template documentTemplateId: specifies the template information used to create the batch.
• Parameters parameters: specifies the list of necessary parameter names for creating placeholder documents.
• Data rows rows: contains data for each row corresponding to the declared placeholders; the number of rows represents the number of documents created.

Below is sample request data for creating a batch with 2 documents, each requiring signatures from 2 people.

{
    "name": "Lô chứng từ trình GĐ ký ngày 23/12/2022",
    "departmentId": 33,
    "documentTypeId": 47,
    "documentTemplateId": 1140,
    "parameters": [
        "{{D.FileName}}",
        "{{D.No}}",
        "{{D.Subject}}",
        "{{D.ExpiryDate}}",
        "{{D.Description}}",
        "{{D.IsOrder}}",
        "{{P.Code}}",
        "{{P.AccessPermission}}",
        "{{P.Code}}",
        "{{P.AccessPermission}}",
        "{{ben_a}}",
        "{{ben_b}}"
    ],
    "rows": [
        [
            "DOCUMENT_2",
            "CNCL_2",
            "Đơn đặt hàng 2",
            "",
            "Mô tả abc xyz",
            "Y",
            "baoth",
            "DR",
            "baoth",
            "D",
            "Nguyễn Văn A1",
            "Nguyễn Văn B1"
        ],
        [
            "DOCUMENT_3",
            "CNCL_3",
            "Đơn đặt hàng 3",
            "",
            "Mô tả abc xyz",
            "Y",
            "baoth",
            "DR",
            "baoth",
            "D",
            "Nguyễn Văn A2",
            "Nguyễn Văn B2"
        ]
    ]
}

The parameters parameter will have the first six mandatory parameters that must be provided with the correct names and in the correct order, including:

• {{D.FileName}}: File name, the created document will be named according to the declared file name.
• {{D.No}}: Document code, must be unique and is used for document lookup.
• {{D.Subject}}: Document title, displayed on the document list screen.
• {{D.ExpiryDate}}: Expiry date (format dd/MM/yyyy), the document will automatically be canceled if the processing expires.
• {{D.Description}}: Additional description, displayed when viewing the document.
• {{D.IsOrder}}: Sequential processing (Y/N), used to determine if the signing process is sequential. (required)

The next pair of parameters pertains to the signing process information {{P.Code}} and {{P.AccessPermission}}. Adding more pairs will create a document batch with that many handlers.

• {{P.Code}}: Recipient code, each user in the company has a unique code.
• {{P.AccessPermission}}: Access permission (V, D, DR, A). V for view-only, D for digital signature, DR for initialing, A for approval.

Lastly are the placeholders required on the document, with parameter names that must match the original variable naming convention and match the names of the parameters in the template file above. For instance, if the document template has a parameter named {{ben_a}}, the parameter name provided must exactly be {{ben_a}}.

Caution

• The parameters list cannot be changed and must follow the exact order and rules above: Basic information -> Signing process information -> Placeholder information.
• The rows data list: data must be provided in the same order as the parameters above.

Calling the API to Create a Document Batch from the Template

Use the API (/api/batch-imports/create-advance) to create a document batch from the prepared sample data. See details in the Advanced Batch Import API.

After successfully creating the document batch, you can check the result on the web at /App/BatchImport.

Select the “Send Process” button to view the detailed information of the created document batch.

Click on the details to view information on the created documents.

Verify the information in the created document, including signature boxes (if any). Documents that haven’t had the process sent will be in the “New Document” status. In this status, information can be updated and edited if there are any errors (update via APIs or on the web).

Sending the Signing Process

After successfully creating the document batch, the system will return the created batch ID, which is used to send the signing process. See details in the Batch Signing Process API.

Once the document batch has been sent, the documents can no longer be edited. So, ensure to check the information carefully before sending.

On the document list screen, the status of all sent documents will be visible. Select the search button to find the list of sent document batches.

The documents have been successfully sent to the recipients, who can process the received documents in batches (bulk processing).