Parámetros Dinámicos¶

Los bots en Unimate pueden recibir parámetros configurables que se envían como argumentos de línea de comandos con el formato –argumento valor. Estos parámetros se configuran durante la creación del bot en el formulario «Nuevo Bot».

Configuración en el Formulario¶

En la interfaz de «Nuevo Bot» se incluye una sección específica para configurar parámetros dinámicos:

Configuración de parámetros en el formulario de Nuevo Bot

Campos de configuración por parámetro:

Nombre del parámetro: Identificador que se usará como –nombre
Tipo de dato: Texto, Número, Fecha, Lista de opciones (se ingresarán separadas por coma), Secreto (para administrar contraseñas), Adjunto (para adjuntar archivos, los cuales se cargarán en una carpeta temporal del agente y podrán ser accedidos desde el bot)
Valor por defecto: Valor inicial, si no se especifica se mostrará vacío
Descripción: Explicación de qué hace el parámetro

Cómo Funcionan los Parámetros¶

Flujo completo de parámetros:

Desarrollador configura parámetros en «Nuevo Bot»
Usuario modifica valores antes de cada ejecución
Portal envía comando al agente vía WebSocket
Agente ejecuta bot recibe los argumentos con este formato: python main.py –param1 valor1 –param2 valor2
Bot procesa argumentos usando la libreria argparse de Python

Ejemplo de ejecución:

# Lo que ejecuta el agente basado en parámetros configurados:
python main.py --archivo_entrada "datos_enero.xlsx" --formato_salida "JSON" --limite 1000

Tipos de Parámetros Soportados¶

Texto (String) Parámetros de texto libre para nombres, descripciones.

Configuración:
├── Nombre: cliente_nombre
├── Tipo: Texto
└── Ejemplo: "Empresa ABC"

En Python:

import argparse

parser = argparse.ArgumentParser()
parser.add_argument('--cliente_nombre', type=str, required=True)
args = parser.parse_args()

# Usar el parámetro en el script
print(f"Procesando cliente: {args.cliente_nombre}")
nombre_reporte = f"Reporte_{args.cliente_nombre}.xlsx"

Número (Integer/Float) Parámetros numéricos para cantidades, límites.

Configuración:
├── Nombre: cantidad_dias
├── Tipo: Número entero
├── Por defecto: 30
└── Ejemplo: 15

En Python:

import argparse
from datetime import datetime, timedelta

parser = argparse.ArgumentParser()
parser.add_argument('--cantidad_dias', type=int, default=30)
args = parser.parse_args()

# Usar el parámetro en el script
fecha_limite = datetime.now() - timedelta(days=args.cantidad_dias)
print(f"Procesando últimos {args.cantidad_dias} días desde {fecha_limite.date()}")

Booleano (True/False) Parámetros de activación/desactivación.

Configuración:
├── Nombre: debug_mode
├── Tipo: Booleano
├── Obligatorio: ☐ No
├── Por defecto: False
└── Ejemplo: True/False

En Python:

parser.add_argument('--debug_mode',
                   action='store_true',
                   help='Activar modo debug')

Lista de Opciones Parámetros con valores predefinidos.

Configuración:
├── Nombre: sucursal
├── Tipo: Lista de opciones
├── Opciones: Suc1, Suc2, Suc3, Suc4
├── Obligatorio: ☑ Sí
└── Ejemplo: "Suc2"

En Python:

import argparse

parser = argparse.ArgumentParser()
parser.add_argument('--sucursal', type=str, required=True,
                   choices=['Suc1', 'Suc2', 'Suc3', 'Suc4'])
args = parser.parse_args()

# Usar el parámetro en el script
print(f"Conectando a base de datos de {args.sucursal}")
db_config = {
    'Suc1': 'server1.empresa.com',
    'Suc2': 'server2.empresa.com',
    'Suc3': 'server3.empresa.com',
    'Suc4': 'server4.empresa.com'
}
servidor = db_config[args.sucursal]

Ejemplo de Implementación¶

Bot compatible con parámetros dinámicos:

import argparse
import sys
from datetime import datetime

def main():
    parser = argparse.ArgumentParser(description='Bot de Reportes por Sucursal')

    # Parámetros configurados en el formulario
    parser.add_argument('--cliente_nombre', type=str, required=True)
    parser.add_argument('--sucursal', type=str, required=True,
                       choices=['Suc1', 'Suc2', 'Suc3', 'Suc4'])
    parser.add_argument('--fecha_reporte', type=str, required=True)
    parser.add_argument('--cantidad_dias', type=int, default=30)

    args = parser.parse_args()

    # Logs informativos (aparecen en tiempo real en Unimate)
    print(f"Bot iniciado - {datetime.now()}")
    print(f"Cliente: {args.cliente_nombre}")
    print(f"Sucursal: {args.sucursal}")
    print(f"Fecha reporte: {args.fecha_reporte}")
    print(f"Días a procesar: {args.cantidad_dias}")

    try:
        # Validar fecha
        fecha = datetime.strptime(args.fecha_reporte, '%Y-%m-%d')
        print(f"Fecha validada: {fecha.strftime('%d/%m/%Y')}")

        # Configurar conexión según sucursal
        servidores = {
            'Suc1': 'server1.empresa.com',
            'Suc2': 'server2.empresa.com',
            'Suc3': 'server3.empresa.com',
            'Suc4': 'server4.empresa.com'
        }

        servidor = servidores[args.sucursal]
        print(f"Conectando a: {servidor}")

        # Generar nombre del archivo
        archivo_salida = f"reporte_{args.cliente_nombre}_{args.sucursal}_{args.fecha_reporte}.xlsx"
        print(f"Archivo de salida: {archivo_salida}")

        # Procesamiento principal
        print("Generando reporte...")
        # Tu lógica de negocio aquí

        print("Reporte generado exitosamente")

    except ValueError as e:
        print(f"ERROR: Formato de fecha inválido - {str(e)}")
        sys.exit(1)
    except Exception as e:
        print(f"ERROR: {str(e)}")
        sys.exit(1)

if __name__ == "__main__":
    main()

Validación de Parámetros¶

El sistema valida automáticamente:

Tipos de datos correctos
Valores obligatorios presentes
Rangos numéricos respetados
Opciones válidas en listas
Formatos de fecha correctos
Longitud de strings

Validaciones personalizadas en el bot:

def validar_parametros(args):
    errores = []

    # Validar archivo existe
    if not os.path.exists(args.archivo_entrada):
        errores.append(f"Archivo no encontrado: {args.archivo_entrada}")

    # Validar extensión
    if not args.archivo_entrada.endswith(('.xlsx', '.csv')):
        errores.append("Archivo debe ser .xlsx o .csv")

    if errores:
        for error in errores:
            print(f"ERROR: {error}")
        sys.exit(1)

    print("Todos los parámetros son válidos")

Mejores Prácticas¶

Nomenclatura - Usa snake_case para nombres de parámetros - Sé descriptivo pero conciso - Evita abreviaciones confusas - Mantén consistencia en el estilo

Valores por Defecto - Define valores sensatos para parámetros opcionales - Usa valores que funcionen en la mayoría de casos - Documenta por qué elegiste esos defaults - Permite sobreescribir fácilmente

Validación - Valida temprano en el script - Proporciona mensajes claros de error - Usa exit codes apropiados (0=éxito, 1=error) - Logea validaciones importantes

Documentación - Incluye help descriptivo en cada argumento - Proporciona ejemplos de uso - Documenta rangos y limitaciones - Explica dependencias entre parámetros

Configuración en el Portal¶

Al crear o editar un bot, puedes definir sus parámetros:

Definición de Parámetros¶

Configuración de Parámetros - Procesador de Datos
┌──────────────────────────────────────────────────────────┐
  Nombre      │ Tipo    │ Obligatorio │ Valor Defecto
├──────────────────────────────────────────────────────────┤
  archivo     │ Archivo │ Sí          │ -
  formato     │ Lista   │ No          │ CSV
  limite      │ Entero  │ No          │ 500
  debug       │ Boolean │ No          │ False
  columnas    │ Lista   │ No          │ -
└──────────────────────────────────────────────────────────┘

Configuración por Ejecución¶

Cada vez que ejecutas el bot puedes personalizar los valores:

Ejecutar Bot: Procesador de Datos
┌───────────────────────────────────────────────┐
  archivo: datos_diciembre_2024.xlsx
  formato: CSV                  ┌─ CSV
  limite:  1000                 │ JSON
  debug:   Desactivado          │ XLSX
  columnas: Agregar...          └─────────────

  [ Cancelar ]  [ Ejecutar ]
└───────────────────────────────────────────────┘

Tipos de Parámetros¶

Texto (String)¶

Para nombres, rutas, descripciones.

parser.add_argument('--nombre', type=str, help='Nombre del reporte')

En el portal: Campo de texto libre

Número (Integer/Float)¶

Para cantidades, límites, porcentajes.

parser.add_argument('--limite', type=int, help='Cantidad máxima')
parser.add_argument('--porcentaje', type=float, help='Porcentaje de descuento')

En el portal: Campo numérico con validación

Booleano (Boolean)¶

Para activar/desactivar funcionalidades.

parser.add_argument('--debug', action='store_true', help='Modo debug')

En el portal: Checkbox verdadero/falso

Archivo (File)¶

Para rutas de archivos de entrada.

parser.add_argument('--archivo', type=str, help='Archivo de entrada')

En el portal: Selector de archivos con explorador

Lista (Choice)¶

Para opciones predefinidas.

parser.add_argument('--formato',
                   choices=['CSV', 'JSON', 'XLSX'],
                   help='Formato de salida')

En el portal: Dropdown con opciones

Lista Múltiple (Multiple)¶

Para múltiples valores del mismo tipo.

parser.add_argument('--columnas', nargs='+', help='Columnas a procesar')

En el portal: Campo de texto con separador (comas)

Validación de Parámetros¶

Validaciones automáticas del portal:

Validaciones Básicas¶

Tipo de dato correcto (número, texto, booleano)
Campos obligatorios completados
Valores en rangos permitidos (min/max)
Formato de archivo válido

Validaciones Avanzadas¶

# En el bot puedes agregar validaciones personalizadas:
def validar_parametros(args):
    if args.limite <= 0:
        raise ValueError("El límite debe ser mayor que 0")

    if args.archivo and not os.path.exists(args.archivo):
        raise FileNotFoundError(f"Archivo no encontrado: {args.archivo}")

    if args.formato == 'XLSX' and args.limite > 1048576:
        raise ValueError("XLSX no soporta más de 1M de filas")

Parámetros Avanzados¶

Parámetros Dependientes¶

Algunos parámetros pueden depender del valor de otros:

# Si formato es XLSX, mostrar parámetro de hoja
if args.formato == 'XLSX':
    parser.add_argument('--hoja', type=str, default='Sheet1')

Parámetros de Fecha/Hora¶

parser.add_argument('--fecha-desde',
                   type=str,
                   help='Fecha inicio (YYYY-MM-DD)')
parser.add_argument('--fecha-hasta',
                   type=str,
                   help='Fecha fin (YYYY-MM-DD)')

Variables de Entorno¶

Para información sensible como credenciales:

import os

# El bot puede usar variables de entorno
api_key = os.getenv('API_KEY', args.api_key)
database_url = os.getenv('DATABASE_URL', args.database_url)

En el portal: Campos marcados como «Sensibles» se cifran

Plantillas de Parámetros¶

Para bots similares, puedes crear plantillas:

Plantilla: Procesador de Archivos Excel
├── archivo (Obligatorio): Archivo de entrada
├── hoja (Opcional): Nombre de la hoja
├── rango (Opcional): Rango de celdas (A1:Z100)
└── formato_salida: CSV, JSON, TXT

Beneficios:

Configuración rápida de nuevos bots
Reutilización de parámetros comunes
Estandarización de nomenclatura
Validaciones consistentes

Debugging de Parámetros¶

Para probar localmente los parámetros:

# Simular ejecución desde el portal
python main.py --archivo "test.xlsx" --formato "CSV" --limite 100 --debug

En el código del bot:

def main():
    parser = argparse.ArgumentParser()
    # ... definir argumentos ...

    args = parser.parse_args()

    # Debug: mostrar todos los parámetros recibidos
    if hasattr(args, 'debug') and args.debug:
        print("=== PARÁMETROS RECIBIDOS ===")
        for key, value in vars(args).items():
            print(f"{key}: {value}")
        print("=" * 30)

El portal también mostrará:

Log completo de parámetros enviados
Errores de validación específicos
Valores procesados por el bot