Documentation for writePdf Logic

Overview

The writePdf logic component in Vantage is designed for converting tabular data into a formatted PDF document, or for uploading existing PDF binary content to OneDrive. This functionality is particularly valuable for users needing to generate reports or export data in a visually appealing format for sharing or archival purposes.

Purpose

The primary purpose of writePdf is to:

• Convert an array of objects (tabular data) into a structured PDF containing formatted tables.
• Upload an existing PDF file, provided either in base64 format or as a Buffer, to a specified location in OneDrive.

Expected Input Data

writePdf expects one of the following types of input:

• An array of objects representing the dataset.
• A base64-encoded string of a PDF document.
• A Buffer containing raw PDF binary data.

If the data provided is neither of these formats, the operation will fail.

Settings

1. fileName

• Input Type: String
• Description: Specifies the name of the PDF file to be created. The component will append a timestamp to this filename to ensure uniqueness. If not provided, it defaults to 'document.pdf'.
• Default Value: 'document.pdf'

2. subfolder

• Input Type: String (optional)
• Description: Indicates the subfolder under which the PDF file will be saved in OneDrive. If the folder does not exist, it attempts to create it.
• Default Value: None (if not specified, the file will be saved in the main directory).

3. mode

• Input Type: Dropdown (options: 'auto', 'create', 'overwrite')
• Description: Defines how to handle existing files with the same name in the target directory:
  • 'auto': Default mode; the system will automatically decide based on existing files.
  • 'create': Will create a new file even if a file with the same name exists (potentially appending a timestamp).
  • 'overwrite': Will replace the existing file with the same name.
• Default Value: 'auto'

4. title

• Input Type: String (optional)
• Description: Specifies the title to be displayed at the top of the PDF document. If not set, the title will default to be the filename (excluding the extension).
• Default Value: None (if not specified).

How It Works

1. Input Handling: writePdf retrieves the input data. It can handle nested data structures and unwrap them to obtain an array of objects.
2. Configuration: The file name, optional subfolder, mode (overwrite or create), and title for the document are retrieved from the configuration.
3. Timestamp Generation: A timestamp is generated in ISO format to append to the filename to ensure that each file is uniquely named.
4. Integration with OneDrive:
   • The function ensures that the OneDrive integration is configured properly and retrieves the necessary clientId.
   • It checks for the existence of specified subfolders and creates them if needed.
5. PDF Generation:
   • If no valid data is provided, an error is returned.
   • If data is provided, it checks the format (Buffer, string, or array) and proceeds to generate a PDF using the generatePdfFromData function, which uses the pdfkit library.
6. File Upload: Finally, the generated or provided PDF is uploaded to OneDrive, and relevant metadata is returned.

Integration with AI Features

The current implementation does not specify any direct integration with AI functionalities. However, users can potentially enhance their data visualizations and report insights using various AI-driven analytics provided by Vantage.

Billing Impact

Using the writePdf logic may incur costs associated with:

• Storage space used in OneDrive for storing generated PDFs.
• API calls made during the creation of folders and uploading files to OneDrive, which may be subject to rate limits or fees.

Use Cases & Examples

Use Case 1: Business Reporting

A marketing team needs to generate monthly performance reports in PDF format to share with stakeholders. By using writePdf, they can automate the process of generating these reports from their analytics data stored in Vantage.

Use Case 2: Data Export for Compliance

A finance department requires exporting transaction data into PDF reports for compliance audits. writePdf allows them to pull the relevant data and format it neatly for submission.

Use Case 3: Dynamic PDF Generation

An application that allows users to create custom reports can utilize writePdf to let users generate on-demand PDFs from any customizable data inputs through the application interface.

Detailed Example Configuration

For a marketing team generating a report:

{
    "inputs": {
        "input1": [
            {"date": "2023-10-01", "campaign": "Campaign A", "impressions": 1000, "clicks": 100},
            {"date": "2023-10-02", "campaign": "Campaign B", "impressions": 1500, "clicks": 150}
        ]
    },
    "config": {
        "fileName": "Marketing_Report",
        "subfolder": "Monthly Reports",
        "mode": "create",
        "title": "October 2023 Marketing Performance Overview"
    },
    "context": {
        "clientId": "your-client-id"
    }
}

In this example, the marketing team defines the input dataset as an array of campaign performance metrics. They choose to save the file in the "Monthly Reports" subfolder of OneDrive, create a unique filename for each report based on the month's performance, and set a meaningful title for clarity.