Combining files

You can combine multiple files into a single document using the Documents plugin.

This guide provides step-by-step instructions on how to combine multiple files into a single PDF document, such as when a user needs to merge several related documents into one file.

Prerequisites

1. Access Permissions: Ensure that you have the necessary permissions to use the Documents Plugin. The user account used for these operations should have the required access rights.

2. Kafka Configuration: Verify that the Kafka messaging system is properly configured and accessible. The Documents Plugin relies on Kafka for communication between nodes.

   • Kafka Topics: Familiarize yourself with the Kafka topics used for these operations (later in this section)

3. Before initiating the combining process, ensure you have the unique IDs of all files you want to combine in the storage solution. This ensures that the combination is performed on already uploaded files.

Ensure that all files to be combined are PDF documents. The combine operation merges multiple PDF files into a single PDF.

You have two options to obtain file IDs:

• Extract the file ID from a Response Message of an upload file request. For more details, refer to the upload process documentation.

• Extract the file ID from a Response Message of a generate from template request. For more details, refer to the document generation reply documentation.

In the following example, we will combine two documents using their fileId values obtained from previous upload operations.

File 1:

{
  "customId": "119501",
  "fileId": "0b453429-6807-4439-9a14-46222d70620c",
  "documentType": "APPLICATION_FORM",
  "documentLabel": null,
  "minioPath": "flowx-dev-process-id-119501/119501/470_APPLICATION_FORM.pdf",
  "downloadPath": "internal/files/0b453429-6807-4439-9a14-46222d70620c/download",
  "noOfPages": 12,
  "error": null
}

File 2:

{
  "customId": "119501",
  "fileId": "0da982f6-e167-4e4b-9c71-459e3fca429b",
  "documentType": "APPENDIX",
  "documentLabel": null,
  "minioPath": "flowx-dev-process-id-119501/119501/471_APPENDIX.pdf",
  "downloadPath": "internal/files/0da982f6-e167-4e4b-9c71-459e3fca429b/download",
  "noOfPages": 3,
  "error": null
}

Configuring the combining process

To create a process that combines multiple files into a single document, follow these steps:

1. Create a process that includes a Send Message Task (Kafka) node and a Receive Message Task (Kafka) node:

• Use the Send Message Task node to send the combine request.
• Use the Receive Message Task node to receive the combine reply.

2. Configure the first node (Send Message Task) by adding a Kafka Send Action.

3. Specify the Kafka topic where you want to send the combine request.

To identify your defined topics in your current environment, follow the next steps:

1. From the FLOWX.AI main screen, navigate to the Platform Status menu at the bottom of the left sidebar.
2. In the FLOWX Components list, scroll to the document-plugin-mngt line and press the eye icon on the right side.
3. In the details screen, expand the KafkaTopicsHealthCheckIndicator line and then details → configuration → topic → file → combine. Here you will find the in and out topics for combining files.

4. Fill in the body of the message request.

Message request example

{
  "combineFiles": [
    {
      "documentType": "CONTRACT",
      "customId": "119501",
      "files": [
        {
          "fileId": "0b453429-6807-4439-9a14-46222d70620c",
          "startPage": 0,
          "endPage": 11,
          "order": 0
        },
        {
          "fileId": "0da982f6-e167-4e4b-9c71-459e3fca429b",
          "startPage": 0,
          "endPage": 2,
          "order": 1
        }
      ],
      "shouldOverride": true
    }
  ]
}

• combineFiles: An array of combine operations. Each operation creates one combined document.
  • documentType: The document type to assign to the combined file.
  • customId: The unique identifier for the combined document (it could be for example the ID of a client or process instance).
  • files: An array of files to include in the combined document:
    • fileId: The unique identifier of the file to include.
    • startPage: Starting page number (0-indexed). Use 0 for the first page.
    • endPage: Ending page number (0-indexed). Use 0 to include only the first page, or specify a higher number to include a range.
    • order: The order in which files should be combined. Files are merged in ascending order based on this value.
  • shouldOverride: A boolean value indicating whether to override an existing document if one with the same name already exists.

Page numbering is 0-indexed. Setting both startPage: 0 and endPage: 0 will include only the first page of that file. To include all pages from a 12-page document, use startPage: 0 and endPage: 11.

You can combine specific page ranges from different documents. For example, you could take pages 1-3 from document A and pages 5-10 from document B.

5. Configure the second node (Receive Message Task) by adding a Data stream topic:

The response will be sent to the ..out Kafka topic configured for file combination.

Receiving the reply

The following values are expected in the reply body:

• customId: The unique identifier for your document (matching the name of the folder in the storage solution where the document is uploaded).
• fileId: The ID of the newly created combined file.
• documentType: The document type.
• documentLabel: The document label (if available).
• minioPath: The storage path for the combined document.
• downloadPath: The download path for the combined document.
• noOfPages: The total number of pages in the combined document.
• error: Any error message in case of an error during the combining process.

Message response example

{
  "customId": "119501",
  "fileId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "documentType": "CONTRACT",
  "documentLabel": null,
  "minioPath": "flowx-dev-process-id-119501/119501/472_CONTRACT.pdf",
  "downloadPath": "internal/files/c3d4e5f6-a7b8-9012-cdef-345678901234/download",
  "noOfPages": 15,
  "error": null
}

The combined file is now available in the storage solution and can be downloaded. The total page count reflects the sum of included pages from all source documents based on your specified page ranges.

Note that the actual values in the response will depend on the specific combine request and the documents being combined.