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
POST /export
Request
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.
// 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.