Plantillas de proyecto

Una plantilla es un proyecto de partida con la estructura ya resuelta: el manejo de errores, los reintentos, el cierre seguro y la bitácora. Tú escribes solo la parte propia de tu proceso, y partes de una estructura probada:

• No preguntan nada al crear. Todo lo que se ajusta vive en el archivo Data/Config.xlsx del proyecto, con un valor por defecto y una descripción por clave.
• Corren tal como correrán en producción. No hay modos especiales: lo que ves en el Designer es lo que hace el robot desatendido.
• Se adaptan a la plataforma. Un proyecto Windows recibe además la apertura, recuperación y cierre de tu aplicación; uno headless recibe la versión sin escritorio.

Crear un proyecto desde una plantilla

La pantalla de inicio del Designer muestra la galería: Proceso en blanco primero y después las plantillas incluidas y las de tu equipo (también tienes Nuevo proyecto en blanco · Ctrl+Shift+N sobre la galería). Todas, salvo la de en blanco, traen Config.xlsx, errores de negocio y de sistema, reintentos y bitácora.

1. Pulsa la tarjeta de la plantilla. Se abre Nuevo proyecto con su descripción y la lista de archivos que trae (Ver playbooks los muestra antes de crear).
2. Escribe el nombre, la ubicación y, si quieres, una descripción.
3. Elige la plataforma: windows o headless. No se puede cambiar después (ver Configuración del proyecto).
4. Pulsa Crear proyecto. Se abre con main.play listo para ejecutar.

El proyecto recuerda de qué plantilla y versión nació (en project.zoanproj), pero a partir de ahí es tuyo: cambiarlo no toca la plantilla.

Qué hace cada plantilla y qué claves trae: Plantillas incluidas.

El archivo Config.xlsx

Los valores que cambian entre ambientes o que el negocio ajusta (rutas, nombres de colas, roles, reintentos) no van escritos en los playbooks: van en Data/Config.xlsx, un Excel que cualquiera puede ajustar sin tocar el flujo:

Hoja	Para qué
Settings	Lo que se ajusta por proyecto o ambiente: fuentes, colas, carpetas, roles.
Constants	Valores técnicos que rara vez cambian: número de reintentos, esperas.

Cada hoja tiene tres columnas: Name, Value y Description. Una clave repetida en una hoja posterior sobrescribe la anterior.

Al empezar, main invoca InitAllSettings, que lee el archivo y deja todo en la variable Config. main se lo pasa a los demás playbooks en su entrada in_Config. Cada valor se lee así:

str(Config["Cola"])                     // en main: texto
toInt(in_Config["ReintentosSistema"])   // en un playbook invocado: número

• Añadir una clave: agrega una fila en Settings (o Constants) y léela con Config["TuClave"] (o in_Config["TuClave"]). No hay que declararla en ningún otro lado.
• Viaja en el paquete: Config.xlsx se publica con el proceso, así que el robot desatendido usa los mismos valores que probaste. Para otro ambiente, cambia el archivo y publica una versión nueva.
• Nada de secretos: contraseñas y llaves van en Credenciales, no en el Excel.

Errores de negocio y de sistema

Todas las plantillas distinguen los dos tipos de error:

• Error de negocio: un dato impide seguir (un campo vacío, un valor fuera de regla). Reintentar no lo arregla. Lánzalo con Throw y el tipo de error Excepción de negocio (BusinessRuleException): el elemento se marca y el proceso sigue con el siguiente.
• Error de sistema: la aplicación no respondió, se cayó la red. Se ejecuta Recuperar y se reintenta según ReintentosSistema y EsperaReintentoMs.

Finalizar corre siempre en el finally, también si alguien termina la ejecución. Y si alguien pide Detener, las plantillas por elementos terminan el elemento en curso y cierran limpio (ver Should Stop).

Plantillas propias del equipo

Cualquier proyecto puede convertirse en plantilla para que tu equipo empiece igual.

Guardar un proyecto como plantilla

Con el proyecto abierto: ☰ → Archivo → Guardar como plantilla, o clic derecho sobre la raíz del proyecto en el panel Proyecto.

• Se guarda lo que viajaría en el paquete del proceso: se respeta .zoanignore y no se copia project.zoanproj.
• Toma el nombre, la descripción y la plataforma del proyecto.
• Aparece en la galería junto a las incluidas. Guardarla otra vez con el mismo nombre la actualiza.

Si quieres que la tarjeta muestre etiquetas, pasos de «cómo funciona» o un icono, pon un template.json en la raíz del proyecto (con el mismo formato de las plantillas incluidas). Ese archivo es el manifiesto de la plantilla y no se copia a los proyectos que nazcan de ella.

Compartirla: exportar e importar

• Exportar: clic derecho sobre la tarjeta de la plantilla → Exportar plantilla…. Genera un archivo .zoantpl, que se comparte como cualquier archivo. Sirve también con las plantillas incluidas.
• Importar: en la galería, tarjeta Importar plantilla → elige el .zoantpl. Queda en tus plantillas; importar otra vez la misma la actualiza.
• Quitar: clic derecho sobre una plantilla propia → Quitar plantilla (va a la papelera). Las incluidas no se pueden quitar.

Un .zoan no es una plantilla

Un archivo .zoan es un proceso publicado. Si lo intentas importar como plantilla, el Designer te lo dice: ábrelo como proyecto y usa Guardar como plantilla.

Las plantillas propias viven en tu carpeta de usuario (%APPDATA%\Zoan\templates). Clic derecho sobre una de ellas → Mostrar en el Explorador te lleva a la carpeta.