Programaciones

Una programación (cron) pone un script a correr solo: todos los días a las 7h00, cada 15 minutos, el último viernes del mes, o cada 5 minutos en una ventana nocturna hasta que el trabajo del día esté hecho. Un script puede tener varias programaciones, cada una con su horario, zona horaria y argumentos.

En esta página usamos la programación Indicadores diários de la app Gestión de Clientes, que ejecuta el script atualizar_indicadores todos los días a las 7h00 (zona Europe/Lisbon).

#Crear y abrir programaciones

En el árbol lateral, expande el nodo del script. La fila Programaciones muestra cuántas existen; debajo de ella, cada programación aparece con el nombre, el horario resumido y, cuando está apagada, la marca (desactivada).

• Para crear: haz clic en el + de la fila Programaciones (Nueva programación). Se abre el editor en una pestaña nueva.
• Para editar: haz clic en el nombre de la programación.
• En el menú ⋮ de cada programación tienes Activar/Desactivar y Eliminar. Eliminar detiene la programación para siempre, pero el historial de ejecuciones del script se mantiene.

El editor tiene el formulario a la izquierda y el panel Ejecuciones a la derecha (solo después de guardado — ver el final de la página). Arriba, el interruptor Activo enciende y apaga la programación, y Guardar lo guarda todo.

#Elegir la frecuencia

El campo Frecuencia ofrece tres tarjetas — tres naturalezas de programación:

Tarjeta	Sirve para
Repetir	«Cada N minutos u horas, sin parar.» Sondeos, sincronizaciones continuas.
En momentos concretos	«A una hora del día, en los días que elijas.» El clásico: diario, semanal, mensual.
Ventana de vigilancia	«Sondea cada N minutos entre dos horas y para cuando el trabajo del día esté hecho.»

Bajo las tarjetas, el atajo Escribir la expresión a mano cambia los controles por un campo de Expresión cron libre — para quien ya trae una. Acepta 5 campos o 6 (con segundos), ej.: 0 9 * * 1-5. Volver a los controles deshace el cambio.

#Repetir

1. Elige la tarjeta Repetir.
2. En Unidad, elige minutos u horas.
3. Con minutos, define ¿Cada cuántos minutos? (ej.: 15). Con horas, define Al minuto — el minuto de cada hora en que se dispara (ej.: 0 corre a las 9h00, 10h00, 11h00…).

#En momentos concretos

1. Elige la tarjeta En momentos concretos.

2. En Repite, elige la variante:

   Opción	Campos que aparecen
   Todos los días (en los días elegidos)	A la hora + Días — siete botones (Lun…Dom) con los atajos Todos, Laborables y Fin de semana. Cualquier combinación sirve: lunes, miércoles y viernes, por ejemplo.
   Una vez por semana	A la hora + Día de la semana.
   Una vez al mes	A la hora + En el mes, corre (ver abajo).

3. Para el mensual, En el mes, corre tiene tres formas:

   Opción	Ejemplo
   En un día fijo	Día 1, día 15… Con Día del mes por encima de 28, el editor avisa: «En los meses sin ese día no corre. Para "el último día", usa la opción propia.»
   En una posición (ej.: último viernes)	Posición (1.º, 2.º, 3.º, 4.º, 5.º o último) + Día de la semana — ej.: el último viernes del mes.
   El último día del mes	31, 30, 28 o 29 — lo que el mes tenga.

#La zona horaria

Toda programación tiene una Zona horaria — las horas que defines son horas de esa zona, no del servidor. El selector lista todas las zonas IANA, con búsqueda (ej.: Lisbon, Sao_Paulo). Una programación a las 9h00 en America/Sao_Paulo corre a las 9h00 de São Paulo, aunque el servidor esté en Europa — y los cambios de hora de verano quedan a cargo de la plataforma.

Una programación nueva empieza en la zona horaria del navegador de quien la crea; cámbiala si el script tiene que ejecutarse en otra.

#Si queda sin ejecutar

A veces la hora marcada pasa sin ejecución: el servidor estaba apagado, se reinició a medias, o la ejecución anterior aún corría. La sección Si queda sin ejecutar decide qué hacer con esas ocurrencias:

Opción	Consecuencia
Ignorar	No recupera. Queda registrado que se perdió (estado Perdida en el panel Ejecuciones).
Solo la más reciente	Recupera la última que quedó por hacer; las anteriores quedan registradas como perdidas.
Todas	Recupera todas las que quedaron por hacer, en el orden en que estaban marcadas.

Las ejecuciones recuperadas aparecen en el historial del script con el origen Recuperación.

#Ventana de vigilancia

La tercera tarjeta resuelve un patrón que el cron clásico no expresa: «a partir de las 18h00, intenta cada 5 minutos; cuando lo consigas, corre una vez y para hasta mañana». Típico para esperar que llegue un archivo, que un cierre de día termine en otro sistema, o que una tabla se rellene.

Los campos:

Campo	Qué define
Cada	El intervalo de sondeo: 1, 2, 3, 5, 10, 15, 20 o 30 minutos.
De las / Hasta	Las horas en que la ventana abre y cierra, en la zona elegida.
Días	Los días de la semana en que la ventana existe (los mismos siete botones y atajos).
Si algún script da error, parar el resto del día	Activado, un error cierra la ventana hasta el día siguiente en vez de seguir intentando.

Sin nada más, la ventana ejecuta el script en el primer disparo de cada día y cierra hasta el día siguiente. El poder verdadero está en la validación:

#El script de validación

La sección Script de validación acepta un pequeño código Python que decide, en cada sondeo, si ya se puede ejecutar:

1. Haz clic en Añadir validación. Se abre un editor en un modal.
2. Escribe una función main(input) que devuelve True (listo — el principal corre una vez y la ventana cierra hasta mañana) o False (aún no — espera e intenta en el próximo intervalo).
3. Usa Probar validación para ejecutarla ya, con los argumentos de la programación: ves el veredicto (Puede ejecutar (corre 1×) o Aún no — espera), la duración y los logs.
4. Cierra el modal y haz clic en Guardar en el editor de la programación.

# Devuelve True cuando el archivo del día ya llegó al FTP interno.
from api_manager import db


def main(input):
    linha = db("Dados CRM").query_one(
        "select count(*) as n from cargas_diarias where dia = date('now')"
    )
    return bool(linha and linha["n"] > 0)

La validación corre en el mismo entorno del script principal: recibe el mismo input (argumentos y contexto), y tiene los mismos archivos, el mismo entorno Python y el mismo SDK (db, http, log, …).

#Argumentos de la programación

La sección Argumentos define pares nombre/valor que llegan al script en input["args"] en todas las ejecuciones de esta programación — igual que en la ejecución manual, los valores llegan como texto. Así es como el mismo script sirve a dos programaciones distintas: un exportar diario con {"ambito": "dia"} y uno mensual con {"ambito": "mes"}, por ejemplo.

#Guardar, activar, acompañar

• Guardar crea (o actualiza) la programación. El botón solo se activa cuando el nombre está relleno y el horario es válido.
• El interruptor Activo de arriba enciende y apaga sin borrar nada — en el árbol, una programación apagada muestra (desactivada).
• Una programación activa de un script en Borrador no corre: las ocurrencias quedan Saltada, con la nota «El script está en borrador».

#El panel Ejecuciones

Después de guardado, el lado derecho del editor muestra el panel Ejecuciones — la programación vista desde fuera, actualizada en vivo:

• La primera línea dice si el motor de programaciones de la instalación está vivo («Programador activo · última verificación hace Ns»). Si no está corriendo, aparece un aviso claro — las horas previstas existen, pero nadie las va a cumplir hasta que el programador arranque. En ese caso, habla con quien administra la instalación.
• Debajo, la lista de ocurrencias — cada hora marcada y su estado:

Estado	Significa
Por hacer	Hora futura, aún por cumplir.
Corriendo	La ejecución está en curso ahora.
Hecha	Corrió.
Perdida	Quedó sin correr y la política es Ignorar (o ya no era recuperable). El motivo aparece en la fila.
Saltada	No llegó a correr — ej.: script en borrador, o solapamiento con la ejecución anterior.

En una programación con validación, hacer clic en una ocurrencia abre los Intentos de la validación: cada sondeo con el veredicto (listo, aún no o error) y el mensaje. Las secuencias de «aún no» aparecen colapsadas — «12 intentos sin novedad» — para que las tres líneas que importan no se pierdan en medio.

#Preguntas frecuentes

Lo marqué para el día 31 y hay meses en que no corre. Es el comportamiento de En un día fijo: en los meses sin ese día, no corre — el editor avisa cuando eliges 29, 30 o 31. Para «el fin del mes», usa El último día del mes.

La ejecución de las 9h00 apareció como Saltado (solapamiento). La ejecución anterior aún corría cuando la nueva hora llegó. La plataforma nunca ejecuta la misma programación dos veces al mismo tiempo. Si pasa con frecuencia, ensancha el intervalo o reduce el trabajo por ejecución.

La validación devolvió True pero el principal corrió solo una vez — la condición sigue siendo verdadera. Es a propósito: cuando la validación devuelve True, el principal corre una vez y la ventana cierra hasta el día siguiente. Sin eso, una condición que quedara verdadera pondría el script a correr en bucle hasta el final de la ventana.

Cambió la hora (verano/invierno) — ¿tengo que ajustar las programaciones? No. Las horas se interpretan en la Zona horaria de la programación; el cambio de hora lo trata la plataforma.

Una ejecución aparece como Abortada — «el servidor se reinició» o «se quedó colgada». Una ejecución que quedó marcada «en curso» sin nadie ejecutándola — el servidor se reinició a medias, o le perdió el rastro — se da por abortada, para que el bloqueo de solapamiento no se quede atascado para siempre. La comprobación corre al arrancar y cada 5 minutos, pero una ejecución que este servidor tiene de verdad en curso nunca es atrapada: solo las que ya no tienen dueño y, en la comprobación periódica, solo las de más de 30 minutos.