1. Basic Folder Creation

Basic Folder Creation

This scenario demonstrates how to create folders and organize documents within the Circularo platform. Folders provide a hierarchical structure for organizing your documents, making them easier to find, manage, and share.

Key features:

Create folders to organize your documents
Control access with shared or private folders
Place documents in specific folders during creation
Build hierarchical document structures

Prerequisites

Before working with folders, you need:

A valid authentication token (see the "Authentication & Security" section for details)
Appropriate permissions to create folders in your Circularo instance
For document creation within folders, a file to upload and appropriate metadata definition

Folders in Circularo can be either shared (accessible to multiple users) or private (accessible only to the creator). This access control setting affects all documents placed within the folder.

Step 1 - Create a folder

This endpoint creates a new folder at the root level of the folder hierarchy. Folders provide a way to organize documents into logical groups for easier management and access control.

The name parameter defines the display name of the folder
The isShared parameter determines whether the folder is accessible to multiple users
The parentFolderId parameter specifies where in the hierarchy to create the folder (null for root level)

Endpoint

CODE

POST /folders

Request

JSON

POST /folders?token=LUapHjmp7LWeAIegZbWFOpFGj3LA0z5n7pv4Ej9uZkftQg0Xz4wiQxTIRPWSsPA8

Content-Type: application/json

{
  "name": "Project Documents",  //Display name of the folder
  "isShared": true,  //Whether the folder is shared (true) or private (false)
  "parentFolderId": null  //Parent folder ID (null for root level)
}

Response

JSON

{
  "id": "1103b911-f211-44a8-b7b0-3fe7769d6ed7"
}

The response contains the following important properties:

folderId - Located at id in the response.
- The unique identifier for the newly created folder. Use this ID for all subsequent operations involving this folder.
- Example value: 1103b911-f211-44a8-b7b0-3fe7769d6ed7

The folder has been successfully created at the root level of the folder hierarchy.

The response includes the folder ID which will be used to reference this folder
The folder is created with the shared access setting, making it accessible to other users with appropriate permissions
This folder can now be used to organize documents and create nested folder structures

Access control is inherited in the folder hierarchy. All nested folders created within a shared folder must also be shared (and vice versa) to maintain consistent access control.

Step 2 - Upload a PDF file

Before creating a document in the folder, you need to upload the PDF file that will serve as the document content. This step uploads and stores a PDF file in the Circularo system.

The file is uploaded as a multipart/form-data request
The response includes the file ID that will be used in the document creation step
The response also includes storage quota information to help manage available space

The file upload is a separate step from document creation. The file itself is not automatically associated with any folder until a document is created referencing both the file and folder.

Endpoint

CODE

POST /files/saveFile

Request

JSON

POST /files/saveFile?token=LUapHjmp7LWeAIegZbWFOpFGj3LA0z5n7pv4Ej9uZkftQg0Xz4wiQxTIRPWSsPA8

Content-Type: multipart/form-data

{
  "file": "blob",
  "fileName": "My PDF file"
}

Response

JSON

{
  "file": {
    "id": "9nKSb4xXSVv2oskxWrsslqie8170PgHnMGZMVfR42tVAWWMhCus7TwJG2Phl91kl",
    "documentname": "My PDF file",
    "mimetype": "application/pdf",
    "size": 125840,
    ...
  },
  "storage": {
    "used": 2458732,
    "limit": 10737418240,
    ...
  },
  ...
}

The response contains the following important properties:

fileId - Located at file.id in the response.
- Example value: 9nKSb4xXSVv2oskxWrsslqie8170PgHnMGZMVfR42tVAWWMhCus7TwJG2Phl91kl

The PDF file has been successfully uploaded and stored in the system. The response includes the file ID that will be used in the next step to create a document based on this file.

The file.id is the unique identifier for the uploaded file
This ID will be used in the document creation step to reference this file
The storage information shows your current usage and available quota

Store the file ID for use in the next step. This ID is required to create a document based on this file.

Step 3 - Create a document inside the folder

This endpoint creates a new document in the Circularo system and places it within the previously created folder. The folder association is specified in the optionalData section of the request.

The documentType parameter specifies which metadata definition to use
The workflow parameter defines the workflow that will be applied to the document
The pdfFile.content parameter references the file ID from the previous step
The optionalData.folder parameter specifies which folder should contain the document

You must have appropriate permissions for both the folder and the document type to successfully create a document within a folder.

Endpoint

CODE

POST /documents

Request

JSON

POST /documents?token=LUapHjmp7LWeAIegZbWFOpFGj3LA0z5n7pv4Ej9uZkftQg0Xz4wiQxTIRPWSsPA8

Content-Type: application/json

{
  "body": {
    "documentType": "d_default",
    "documentTitle": "Sample Document",
    "pdfFile": {
      "content": "9nKSb4xXSVv2oskxWrsslqie8170PgHnMGZMVfR42tVAWWMhCus7TwJG2Phl91kl"
    }
  },
  "optionalData": {
    "folder": "1103b911-f211-44a8-b7b0-3fe7769d6ed7"  //ID of the folder where the document should be placed
  },
  "definitionType": "ext",
  "workflow": "wf_archive"
}

Response

JSON

{
  "results": [
    {
      "documentId": "c95e9490-ddb7-43f8-b7fa-acdfc7259f1d",
      "documentTitle": "Sample Document",
      "documentType": "d_default",
      "folder": {
        "global": {
          "level": 1,
          "parentFolderId": "1103b911-f211-44a8-b7b0-3fe7769d6ed7",
          "name": "Project Documents",
          ...
        },
        ...
      },
      "workflow": {
        "workflowType": "wf_archive",
        ...
      },
      ...
    }
  ],
  ...
}

The response contains the following important properties:

documentId - Located at results[0].documentId in the response.
- The unique identifier for the newly created document. Use this ID for all subsequent operations on this document.
- Example value: c95e9490-ddb7-43f8-b7fa-acdfc7259f1d

The document has been successfully created and placed within the specified folder.

The response includes the document ID which can be used for subsequent operations
The document is created with the specified metadata definition and workflow
The document is placed in the specified folder, as indicated in the folder information in the response
The folder hierarchy information is included in the response, showing the document's location

Folder Creation Summary

You have successfully learned how to create folders and organize documents within the Circularo system.

Key Concepts

Folders: Hierarchical containers for organizing documents
Access Control: Folders can be shared or private, affecting access to contained documents
Folder Hierarchy: Folders can be nested to create complex organizational structures
Document Placement: Documents can be placed in specific folders during creation

Next Steps

With your folder structure created, you can now:

Create nested folders for more complex organization
Move existing documents into folders
Share folders with other users or groups
Search for documents within specific folders

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 creation and document organization example
const URL = "https://sandbox.circularo.com";
const API_PATH = "/api/v1";
const TOKEN = "YOUR_AUTH_TOKEN"; // Obtained from login or API key

try {
    // Step 1: Create a folder
    const createFolderResponse = await fetch(`${URL}${API_PATH}/folders?token=${TOKEN}`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            name: "Project Documents",
            isShared: true,
            parentFolderId: null
        })
    });
    if (!createFolderResponse.ok) {
        throw new Error(`Folder creation failed: ${createFolderResponse.status} ${createFolderResponse.statusText}`);
    }

    const folderData = await createFolderResponse.json();
    const folderId = folderData.id;
    console.log(`Folder created with ID: ${folderId}`);

    // Step 2: Upload a PDF file
    const formData = new FormData();
    formData.append('fileName', 'Project Proposal');
    formData.append('file', fs.createReadStream('path/to/document.pdf'));   // Using Node.js fs module

    const uploadResponse = await fetch(`${URL}${API_PATH}/files/saveFile?token=${TOKEN}`, {
        method: 'POST',
        body: formData
    });
    if (!uploadResponse.ok) {
        throw new Error(`File upload failed: ${uploadResponse.status} ${uploadResponse.statusText}`);
    }

    const uploadData = await uploadResponse.json();
    const fileId = uploadData.file.id;

    // Step 3: Create a document in the folder
    const createDocumentResponse = await fetch(`${URL}${API_PATH}/documents?token=${TOKEN}`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            body: {
                documentType: "d_default",
                documentTitle: "Project Proposal",
                pdfFile: {
                    content: fileId
                }
            },
            optionalData: {
                folder: folderId
            },
            definitionType: "ext",
            workflow: "wf_archive"
        })
    });
    if (!createDocumentResponse.ok) {
        throw new Error(`Document creation failed: ${createDocumentResponse.status} ${createDocumentResponse.statusText}`);
    }

    const documentData = await createDocumentResponse.json();
    const documentId = documentData.results[0].documentId;

    console.log(`Document created in folder with ID: ${documentId}`);

} catch (error) {
    console.error('Error in folder and document creation:', error.message);
}