Skip to main content

​
Overview

EntityManager provides universal create, read, update, and delete operations for all entity types in the SGD-MCS system. It handles automatic ID generation, Drive folder creation, and audit logging. Source: ~/workspace/source/Backend/core/EntityManager.js

​
createItem

Creates a new entity record and optionally its Drive folder.
​
type
string
required
Entity type: estudiante, docente, externo, evento, or tesis
​
data
object
required
Entity data object with fields matching the Google Sheet columns
Estudiante (Student)
  • Nombre1, Nombre2: First and middle names
  • Apellido1, Apellido2: Last names
  • Cedula: ID number
  • Email: Email address
  • Cohorte_Ingreso: Cohort (e.g., “2024-1”)
  • Estado: Status
Docente (Teacher)
  • Nombre1, Apellido1: Name
  • Cedula: ID number
  • Email: Email address
  • Especialidad: Specialty area
Tesis (Thesis)
  • Titulo_Investigacion: Research title
  • Año: Year
  • ID_Estudiante: Associated student ID
  • Calificacion: Grade
Evento (Event)
  • Nombre_Evento: Event name
  • Fecha: Date
  • Tipo: Event type
Externo (External)
  • Nombre1, Apellido1: Name
  • Email: Email address
  • Institucion: Institution
​
data._createFolder
boolean
default:"true"
Set to false to skip automatic Drive folder creation
​
success
boolean
required
Whether the operation succeeded
​
message
string
required
Result message (“Creado correctamente” or error)
​
id
string
Auto-generated entity ID (e.g., “EST0001”)

​
Example

// Create a student with automatic ID and folder
google.script.run
  .withSuccessHandler((response) => {
    console.log('Student created:', response.id);
    // response = { success: true, message: 'Creado correctamente', id: 'EST0001' }
  })
  .createItem('estudiante', {
    Nombre1: 'María',
    Apellido1: 'González',
    Cedula: '1234567890',
    Email: '[email protected]',
    Cohorte_Ingreso: '2024-1',
    Estado: 'Activo'
  });

// Create without Drive folder
google.script.run
  .withSuccessHandler((response) => {
    console.log('Event created:', response.id);
  })
  .createItem('evento', {
    Nombre_Evento: 'Defensa de Tesis',
    Fecha: '15/06/2024',
    Tipo: 'Academico',
    _createFolder: false  // Skip folder creation
  });
Automatic Features:
  • ID generation using prefix + counter (EST0001, DOC0042, etc.)
  • Drive folder created at: Root/[EntityType]/[Year or Cohort]/[ID - Name]
  • Audit fields populated: Fecha_Registro, Usuario_Registro
  • All actions logged to audit trail

​
updateItem

Updates an existing entity record.
​
type
string
required
Entity type: estudiante, docente, externo, evento, or tesis
​
id
string
required
Entity ID to update (e.g., “EST0001”)
​
data
object
required
Object containing only the fields to update
​
success
boolean
required
Whether the operation succeeded
​
message
string
required
Result message (“Actualizado correctamente” or error)

​
Example

// Update student email and status
google.script.run
  .withSuccessHandler((response) => {
    if (response.success) {
      console.log('Student updated successfully');
    }
  })
  .updateItem('estudiante', 'EST0001', {
    Email: '[email protected]',
    Estado: 'Graduado'
  });

// Update thesis grade
google.script.run
  .withSuccessHandler((response) => {
    console.log(response.message);
  })
  .updateItem('tesis', 'TES0001', {
    Calificacion: 4.5,
    Estado: 'Aprobada'
  });
Automatic Updates:
  • Ultima_Actualizacion timestamp updated automatically
  • Ultimo_Usuario set to current user’s email
  • If entity has no Drive folder, syncEntityFolder() is called automatically
  • All updates logged to audit trail

​
deleteItem

Deletes an entity record and moves its Drive folder to trash.
​
type
string
required
Entity type: estudiante, docente, externo, evento, or tesis
​
id
string
required
Entity ID to delete (e.g., “EST0001”)
​
success
boolean
required
Whether the operation succeeded
​
message
string
required
Result message (“Eliminado correctamente” or “ID no encontrado”)

​
Example

// Delete a student
google.script.run
  .withSuccessHandler((response) => {
    if (response.success) {
      console.log('Student and folder deleted');
    } else {
      alert('Error: ' + response.message);
    }
  })
  .deleteItem('estudiante', 'EST0001');
Destructive Operation:
  • Permanently removes the row from the Google Sheet
  • Moves associated Drive folder to trash (can be recovered from Drive trash)
  • This operation cannot be undone from the application

​
bulkUpdateItems

Updates multiple entities at once with the same data.
​
type
string
required
Entity type: estudiante, docente, externo, evento, or tesis
​
ids
string[]
required
Array of entity IDs to update
​
updates
object
required
Object containing fields to update on all entities
​
success
boolean
required
Always returns true
​
message
string
required
Count of successfully updated records

​
Example

// Update status for multiple students
google.script.run
  .withSuccessHandler((response) => {
    console.log(response.message);
    // Output: "Se actualizaron 3 registros."
  })
  .bulkUpdateItems('estudiante', 
    ['EST0001', 'EST0002', 'EST0003'],
    { Estado: 'Inactivo' }
  );

// Assign cohort to multiple students
google.script.run
  .withSuccessHandler((response) => {
    console.log(response.message);
  })
  .bulkUpdateItems('estudiante',
    ['EST0010', 'EST0011', 'EST0012', 'EST0013'],
    { Cohorte_Ingreso: '2024-2' }
  );

​
bulkDeleteItems

Deletes multiple entities at once.
​
type
string
required
Entity type: estudiante, docente, externo, evento, or tesis
​
ids
string[]
required
Array of entity IDs to delete
​
success
boolean
required
Always returns true
​
message
string
required
Count of successfully deleted records

​
Example

// Delete multiple events
google.script.run
  .withSuccessHandler((response) => {
    console.log(response.message);
    // Output: "Se eliminaron 2 registros."
  })
  .bulkDeleteItems('evento', ['EVE0001', 'EVE0002']);
Bulk deletion is destructive and affects multiple records. Ensure you have confirmation before calling this function.

​
Implementation Details

​
ID Generation

From EntityManager.js:26-34:
  • IDs use 3-letter prefix + zero-padded counter
  • Counter stored in Config sheet: Siguiente_ID_[EntityType]
  • Format: EST0001, DOC0042, TES0123, etc.
  • IDs are unique per entity type

​
Drive Folder Naming

From EntityManager.js:114-118:
  • Format: [ID] - [Name] (e.g., “EST0001 - Juan Pérez”)
  • Truncated to 100 characters maximum
  • Uses Titulo_Investigacion for thesis, Nombre_Evento for events

​
Data Normalization

The normalizeData() function ensures consistent data formats before saving to Sheets.

​
Error Handling

All functions are wrapped in try-catch blocks. Common errors:
  • “Tipo no válido”: Invalid entity type parameter
  • “Hoja [name] no encontrada”: Sheet not found in database
  • “ID no encontrado”: Entity ID doesn’t exist
  • Error string: Other exceptions (permissions, Drive errors, etc.)

Build docs developers (and LLMs) love

Get started for freeTalk to us