Skip to main content

​
Overview

DriveManager handles the automated creation and management of the Drive folder hierarchy for SGD-MCS entities. It creates organized folder structures based on entity type, year/cohort, and entity identifiers. Source: ~/workspace/source/Backend/services/DriveManager.js
This service handles both folder management and file operations for the Drive integration.

​
Folder Structure

The system creates this hierarchy: 
SGD_DATABASE_ROOT/
├── Estudiantes/
│   ├── 2024-1/
│   │   ├── EST0001 - Juan Pérez/
│   │   └── EST0002 - María González/
│   └── 2024-2/
├── Docentes/
│   └── 2024/
│       └── DOC0001 - Dr. López/
├── Tesis/
│   └── 2024/
│       └── TES0001 - Machine Learning Research/
├── Eventos/
│   └── 2024/
├── Externos/
│   └── 2024/
└── _Plantillas/

​
getSystemRootFolder

Obtains the root folder for the entire system.
​
folder
Folder
required
Google Drive Folder object (not serializable)

​
Behavior

  1. Tries to get folder by ROOT_FOLDER_ID from Config.js
  2. Falls back to creating “SGD_DATABASE_ROOT” in user’s Drive root
  3. Uses getOrCreateFolder() to ensure folder exists
This function is used internally. To get folder information from the frontend, use getSystemRootFolderId().

​
getSystemRootFolderId

Gets the root folder ID and metadata (frontend-compatible).
​
success
boolean
required
Whether the operation succeeded
​
id
string
Folder ID in Google Drive
​
name
string
Folder name
​
url
string
Direct URL to folder in Drive

​
Example

google.script.run
  .withSuccessHandler((response) => {
    console.log('Root folder:', response.name);
    console.log('Open at:', response.url);
    // Use response.id for creating subfolders
  })
  .getSystemRootFolderId();

// Response:
// {
//   success: true,
//   id: '1a2b3c4d5e6f7g8h9i0j',
//   name: 'SGD_DATABASE_ROOT',
//   url: 'https://drive.google.com/drive/folders/1a2b3c4d5e6f7g8h9i0j'
// }

​
createEntityFolder

Creates the folder structure for a new entity.
​
type
string
required
Entity type: estudiante, docente, externo, evento, or tesis
​
data
object
required
Entity data object containing ID and naming fields
Estudiante:
  • ID_Estudiante: Student ID
  • Nombre1, Apellido1: Name for folder
  • Cohorte_Ingreso: Cohort (e.g., “2024-1”) for organization
Docente:
  • ID_Docente: Teacher ID
  • Nombre1, Apellido1: Name
Tesis:
  • ID_Tesis: Thesis ID
  • Titulo_Investigacion: Title
  • Año: Year for organization
Evento:
  • ID_Evento: Event ID
  • Nombre_Evento: Event name
Externo:
  • ID_Externo: External ID
  • Nombre1, Apellido1: Name
​
id
string
required
Created folder’s Drive ID
​
url
string
required
Direct URL to the folder

​
Example

// Usually called internally by EntityManager.createItem()
// But can be called directly:

const folderInfo = createEntityFolder('estudiante', {
  ID_Estudiante: 'EST0001',
  Nombre1: 'Juan',
  Apellido1: 'Pérez',
  Cohorte_Ingreso: '2024-1'
});

console.log(folderInfo);
// {
//   id: '1a2b3c4d5e6f7g8h9i0j',
//   url: 'https://drive.google.com/drive/folders/1a2b3c4d5e6f7g8h9i0j'
// }

// Creates: Root/Estudiantes/2024-1/EST0001 - Juan Pérez/
Cohort Handling (Students):
  • Accepts ISO date strings: “2023-01-01T05:00:00.000Z” → extracted to “2023-1”
  • Accepts direct format: “2024-1”
  • Month 1-6 = semester 1, Month 7-12 = semester 2

​
syncEntityFolder

Creates or verifies the Drive folder for an existing entity.
​
type
string
required
Entity type: estudiante, docente, externo, evento, or tesis
​
id
string
required
Entity ID (e.g., “EST0001”)
​
success
boolean
required
Whether the operation succeeded
​
id
string
Folder ID in Drive
​
url
string
Direct URL to folder
​
message
string
required
Description of what happened

​
Example

// Sync folder for an existing student
google.script.run
  .withSuccessHandler((response) => {
    if (response.success) {
      console.log(response.message);
      // Either: "Carpeta creada y vinculada"
      // Or: "La carpeta ya existe y está vinculada"
      window.open(response.url, '_blank');
    }
  })
  .syncEntityFolder('estudiante', 'EST0001');

​
Behavior

  1. Searches for entity by ID in the corresponding Sheet
  2. Checks if ID_Carpeta_Drive column has a value
  3. If folder exists and not trashed: returns existing folder info
  4. If folder missing or trashed: creates new folder and updates Sheet
  5. Logs audit trail for folder creation
This function is automatically called by updateItem() if an entity has no folder.

​
getEntityFiles

Retrieves all files within an entity’s Drive folder.
​
folderId
string
required
Drive folder ID
​
files
array
required
Array of file objects (empty array if error)

​
File Object Structure

​
id
string
File ID in Drive
​
name
string
File name
​
mimeType
string
MIME type (e.g., “application/pdf”, “image/jpeg”)
​
url
string
Direct URL to file
​
size
number
File size in bytes
​
lastUpdated
string
ISO timestamp of last modification

​
Example

google.script.run
  .withSuccessHandler((files) => {
    console.log(`Found ${files.length} files`);
    files.forEach(file => {
      console.log(`- ${file.name} (${formatBytes(file.size)})`);
    });
  })
  .getEntityFiles('1a2b3c4d5e6f7g8h9i0j');

// Response:
// [
//   {
//     id: '1abc...',
//     name: 'Cedula.pdf',
//     mimeType: 'application/pdf',
//     url: 'https://drive.google.com/file/d/1abc.../view',
//     size: 245632,
//     lastUpdated: '2024-06-15T10:30:00.000Z'
//   },
//   ...
// ]
This function only returns files, not subfolders. Use getFolderStructure() from DriveFileManager for folder hierarchies.

​
deleteEntityFolder

Moves an entity’s folder to Drive trash.
​
folderId
string
required
Drive folder ID to delete
​
success
boolean
required
Whether the operation succeeded
​
message
string
required
Result message

​
Example

// Usually called internally by EntityManager.deleteItem()
// But can be called directly:

google.script.run
  .withSuccessHandler((response) => {
    if (response.success) {
      console.log('Folder moved to trash');
    }
  })
  .deleteEntityFolder('1a2b3c4d5e6f7g8h9i0j');
The folder is moved to trash, not permanently deleted. Users can recover it from Drive trash within 30 days.

​
getOrCreateFolder

Utility function that gets or creates a folder by name.
​
parentFolder
Folder
required
Parent Google Drive Folder object
​
folderName
string
required
Name of the folder to get or create
​
folder
Folder
required
Google Drive Folder object

​
Behavior

  1. Searches for existing folder with exact name match
  2. Returns existing folder if found
  3. Creates new folder if not found
  4. Idempotent - safe to call multiple times
This is a helper function used internally by other DriveManager functions. It’s not typically called from the frontend.

​
getSubfolderNameByType

Maps entity type to its container folder name.
​
type
string
required
Entity type
​
folderName
string
required
Folder name for that entity type

​
Mapping Table

TypeFolder Name
estudianteEstudiantes
docenteDocentes
tesisTesis
eventoEventos
externoExternos
(other)Otros

​
Implementation Notes

​
Folder Organization

From DriveManager.js:73-110:
  • Students: Organized by cohort (“2024-1”, “2024-2”)
  • Thesis: Organized by year
  • Other entities: Organized by current year

​
Error Handling

All functions handle Drive API errors gracefully:
  • Invalid folder IDs return empty/error responses
  • Trashed folders are detected and recreated
  • Missing permissions log errors but don’t crash

​
Audit Integration

From DriveManager.js:188-197: All folder operations are logged via logDocumentAction() with:
  • Action type (SYNC_FOLDER, DELETE_ENTITY_FOLDER)
  • Folder ID and name
  • Associated entity information
  • Contextual details

Build docs developers (and LLMs) love

Get started for freeTalk to us