Guía del wizard de carga
El wizard universal (datalab.planitone.co/upload?op=OP_ID) guía al responsable
en 4 pasos y aplica todas las validaciones del schema antes de aceptar el archivo.
Requisitos para poder subir
- Sesión activa con correo institucional.
- Estar asignado como responsable de la operación (override por op) o del área. Ver modelo de permisos.
- La ventana de carga de la operación debe estar abierta (según su
schedule).
Los 4 pasos
Paso 1 · Contexto
Muestra qué operación se está cargando, el ciclo destino (defaultCicloKey, ej. 2026-B),
la hoja esperada y el número de columnas. Enlaza el template oficial si el schema tiene templateUrl.
Paso 2 · Archivo
Acepta .xlsx/.xls. El archivo se parsea client-side con SheetJS; el original
se preserva íntegro (formato, fórmulas, celdas combinadas) subiéndolo a Storage en
/datalab/originales/{certId}/ — es la única fuente para descargas futuras.
Paso 3 · Verificación
Corre la batería de chequeos en orden; si uno crítico falla, se detiene ahí:
| # | Chequeo | Qué valida | Falla típica |
|---|---|---|---|
| 1 | Formato | Extensión y estructura de workbook | PDF renombrado, CSV |
| 2 | Hoja | Existe la hoja del schema (match exacto o por sheetAliases, fuzzy con espacios/case) | Pestaña renombrada por el usuario |
| 3 | Columnas | Los headers de la fila headerRow se mapean a keys canónicas vía aliases; verifica que todas las requiredColumns queden mapeadas | Columna eliminada, header editado sin alias |
| 4 | Registros | La hoja tiene al menos 1 fila de datos bajo el header | Template vacío |
| 5 | Valores controlados | Cada celda de un campo con catálogo (controlledValues + validación enum) está dentro de los valores permitidos | “docente” donde el catálogo dice “PROFESOR” |
| 6 | Campos críticos | criticalFields no vacíos en ninguna fila | Celdas en blanco intercaladas |
| 7 | Formatos y rangos | fieldValidations: patterns, rangos de fecha, enteros acotados, monedas COP | Fecha como texto libre, ‘3’ sin unidad de duración |
Puedes reproducir los chequeos 3, 5 y 7 en el validador interactivo.
D/M/YYYY,
M/D/YYYY y rangos tipo 11y12/03/2025. Aun así, el formato recomendado en los templates
es fecha nativa de Excel (celda tipo fecha), no texto.
Paso 4 · Envío
Construye la submission con su wrapper de estado, guarda las filas parseadas, sube el original a Storage
y notifica. La operación queda en estado PENDIENTE para revisión del analista.
Estados de una carga
PENDIENTE ──► EN REVISIÓN ──► APROBADA ──► PROCESADA ──► (visible en dashboards)
│
└──► RECHAZADA ──► el responsable corrige y vuelve a subir
Formatos multi-hoja SIG
Algunos formatos oficiales SIG agrupan varias operaciones en un solo Excel
(ej. FR-PET-38.02 de Admisiones: P_Inscritos, P_Admitidos, P_Matriculados, P_Gratuidad).
El wizard los detecta con detectSigSheets(): valida cada hoja contra el schema de su operación,
muestra qué hojas vienen diligenciadas y envía solo las marcadas LISTAS cuya ventana esté abierta.
Errores comunes y su causa
| Mensaje | Causa | Solución |
|---|---|---|
| Hoja "P_…" no encontrada | Pestaña renombrada o template equivocado | Descargar template oficial; no renombrar pestañas |
| Faltan columnas: … | Columna eliminada/renombrada, o el archivo es de otra versión del template | Restaurar columnas; verificar versión vigente |
| Valores fuera de catálogo | Texto libre donde va un valor controlado | Revisar el catálogo en el explorador, pestaña Catálogos |
| La hoja no contiene registros | Datos escritos fuera del rango, o header movido de fila | Los datos van justo debajo de la fila de cabeceras (headerRow) |
| Página en blanco al abrir el wizard | Error JS fatal (histórico: app/duplicate-app) | Refrescar con Ctrl+Shift+R; si persiste, reportar a Sistemas |