Skip to main content
Skip table of contents

5. Folder Content Export

Folder Content Export

This scenario demonstrates how to export the contents of a folder as a zip file in the Circularo platform. Folder export functionality allows you to download multiple documents at once, preserving the folder structure and document metadata.

Key features:

  • Export entire folder contents as a single zip file

  • Preserve folder structure in the exported archive

  • Download multiple documents in a single operation

  • Efficiently archive and share document collections

Prerequisites

Before exporting folder contents, you need:

  • A valid authentication token (see the "Authentication & Security" section for details)

  • The folder ID of the folder you want to export

  • Appropriate permissions to access the folder and its contents

  • Sufficient network bandwidth to download potentially large zip files

Folder export is particularly useful for archiving projects, sharing document collections, or creating offline backups of important document sets.

Step 1 - Export folder contents as a zip file

This endpoint exports the contents of a folder as a zip file. The export includes all documents within the specified folder, preserving the folder structure and document metadata.

  • The exporterName parameter specifies the type of export to perform

  • The documentIds array contains the folder ID to export

  • The response is the binary content of the zip file containing all folder documents

  • For folders with many documents, the export may be processed as a background job

The folder export includes all documents the user has access to within the specified folder. Documents that the user cannot access will not be included in the export.

Endpoint

CODE
POST /export

Request

JSON
POST /export?token=cxuRRRhQ8CLqI6gQQ4wE0xM7UYX4MvFEnY5APCzEAfG2ozHn4VBoNJMys7gvIxQb

Content-Type: application/json

{
  "exporterName": "folder",  //Specifies that we want to export a folder
  "options": {
    "documentIds": [
      "14d4faff-c898-499b-ac3f-d7057f25b169"  //Folder ID that we want to export
    ]
  },
  "query": {}
}

The folder contents have been successfully exported as a zip file.

  • The response contains the binary content of the zip file

  • The zip file includes all documents within the specified folder

  • The folder structure is preserved in the zip file

  • Document metadata is included in the export

For folders containing a large number of documents, the export may not return immediately. Instead, the system will create a background job to process the export.


Folder Export Summary

You have successfully learned how to export folder contents as a zip file in the Circularo system.

Key Concepts

  • Folder Export: Download all documents within a folder as a single zip file

  • Background Processing: Large exports are handled asynchronously to prevent timeouts

  • Folder Structure: The hierarchical organization of documents is preserved in the export

  • Bulk Download: Efficient retrieval of multiple documents in a single operation

Background Processing for Large Folders

When exporting folders with a large number of documents, the system may process the export as a background job:

  • Instead of returning the zip file directly, the response will include a jobId property

  • The system creates a corresponding entry in the user's backgroundJobs array

  • You need to periodically check the user data and look for the job with item.id === jobId

  • Monitor the job's status property until it becomes "success"

  • Once complete, the job will contain a fileHash property

  • Use this file hash with the standard file download endpoint to retrieve the zip file

Example Implementation

See our OpenAPI documentation to learn about the full set of API endpoints and parameters.

Please use proper exception handling and function decomposition in your own code. The code is provided for illustrative purposes only and is not intended for production use.

JAVASCRIPT
// Folder export example
const URL = "https://sandbox.circularo.com";
const API_PATH = "/api/v1";
const TOKEN = "YOUR_AUTH_TOKEN"; // Obtained from login or API key
const FOLDER_ID = "YOUR_FOLDER_ID"; // ID of the folder you want to export

async function exportFolder() {
    try {
        // Request folder export
        const exportResponse = await fetch(`${URL}${API_PATH}/export?token=${TOKEN}`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
                exporterName: "folder",
                options: {
                    documentIds: [FOLDER_ID]
                },
                query: {}
            })
        });

        // Check if the response is a direct file download or a background job
        const contentType = exportResponse.headers.get('content-type');

        if (contentType && contentType.includes('application/json')) {
            // This is a background job response
            const jobData = await exportResponse.json();
            const jobId = jobData.jobId;

            console.log(`Export started as background job with ID: ${jobId}`);
            console.log('Checking job status periodically...');

            // Poll for job completion
            let completed = false;
            while (!completed) {
                // Wait a few seconds between checks
                await new Promise(resolve => setTimeout(resolve, 5000));

                // Check user data for job status
                const userDataResponse = await fetch(`${URL}${API_PATH}/login?token=${TOKEN}`);
                const userData = await userDataResponse.json();

                // Find our job in the background jobs array
                const job = userData.user.backgroundJobs.find(job => job.id === jobId);

                if (job) {
                    console.log(`Job status: ${job.status}`);

                    if (job.status === 'success' && job.fileHash) {
                        // Job completed, download the file
                        const fileResponse = await fetch(
                            `${URL}${API_PATH}/files/loadFile/hash/${job.fileHash}?token=${TOKEN}`
                        );
                        if (!fileResponse.ok) {
                            throw new Error(`File download failed: ${fileResponse.status}`);
                        }

                        // Save the zip file
                        const blob = await fileResponse.blob();
                        const downloadLink = document.createElement('a');
                        downloadLink.href = URL.createObjectURL(blob);
                        downloadLink.download = 'folder_export.zip';
                        downloadLink.click();

                        console.log('Folder export completed and downloaded successfully');
                        completed = true;
                    } else if (job.status === 'error') {
                        throw new Error(`Export job failed: ${job.error || 'Unknown error'}`);
                    }
                }
            }
        } else {

            // Direct file download (small folders)
            if (!exportResponse.ok) {
                throw new Error(`Export failed: ${exportResponse.status} ${exportResponse.statusText}`);
            }

            // Save the zip file
            const blob = await exportResponse.blob();
            const downloadLink = document.createElement('a');
            downloadLink.href = URL.createObjectURL(blob);
            downloadLink.download = 'folder_export.zip';
            downloadLink.click();

            console.log('Folder export downloaded successfully');
        }
    } catch (error) {
        console.error('Error exporting folder:', error.message);
    }
}

Exporting very large folders may take significant time to process. Design your application to handle the asynchronous nature of background jobs appropriately.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.