Saltar a contenido

BotCity Studio SDK

El BotCity Studio SDK es un paquete todo en uno que contiene todas las herramientas necesarias para construir, implementar y ejecutar tus automatizaciones de BotCity.

Incluye las herramientas BotCity Studio, BotCity Runner, BotCity CLI (interfaz de línea de comandos) y Session Manager.

El procedimiento de instalación del BotCity Studio SDK es muy sencillo y consta de solo dos pasos principales:

  1. Descargar y descomprimir el BotCity Wizard
  2. Seguir las instrucciones en pantalla

Descargar

El asistente se puede descargar directamente desde BotCity Orchestrator accediendo a la página de Studio.

Esta página se encuentra en:

Con la página de Studio abierta, selecciona la opción compatible con tu sistema operativo.

  • Descargar para Windows
  • Descargar para Linux
  • Descargar para MacOS

Captura de pantalla de la página de BotCity Studio, que muestra las herramientas de BotCity Studio: una herramienta para generar código automático para interactuar con elementos gráficos; BotCity Runner: el software responsable de ejecutar las tareas creadas en Orchestrator; BotCity Diagnostic: una herramienta que valida la conexión y los requisitos de instalación del SDK. Los enlaces para descargar sistemas Windows, Linux y macOS se destacan en la parte inferior de la página.

Una vez completada la descarga, extrae los archivos y tendrás acceso a dos herramientas: Diagnóstico y Asistente.

Herramienta de Diagnostico

La herramienta BotCity - Diagnóstico está incluida en el paquete del Asistente y su objetivo principal es validar si su entorno cumple con los requisitos previos para instalar y usar el SDK de BotCity Studio.

Con esta herramienta, puede comprobar:

  • Conectividad con BotCity Orchestrator
  • Versión de Java instalada (Runtime y Desarrollo)
  • Versión de Python instalada

Para obtener un diagnóstico de su entorno, simplemente ejecute diagnostic.jar, proporcione las credenciales solicitadas y haga clic en Run Tests. Esto le proporcionará un informe detallado en tres columnas: Test, Result y Notes.

Los resultados de la prueba deberían ser similares a los siguientes:

Captura de pantalla de la herramienta "BotCity Diagnostic". La interfaz muestra un selector de servidor configurado como "Comunidad" y el botón "Ejecutar pruebas". A continuación, una tabla de resultados con tres columnas (Prueba, Resultado y Notas) enumera las comprobaciones de conectividad y entorno: acceso al servidor Orchestrator e inicio de sesión (ambos con SSL habilitado marcado como "PASS" y deshabilitado como "SKIP"), así como el acceso a la descarga del SDK. La tabla también confirma la presencia y las versiones de Java Runtime (17.0.3), Python Development (3.12.4) y Java Development (22.0.1), todas con estado "PASS". En la parte inferior, hay botones para exportar datos y hablar con un especialista.

¡Advertencia!

Si recibe un resultado FAIL en cualquier prueba de conexión, es posible que esté intentando instalar en un entorno bloqueado; consulte la descripción en la columna Notas.

En este caso, es necesario solicitar los permisos descritos en la sección prerrequisitos al equipo responsable.

También puede exportar los resultados de las pruebas a un archivo CSV con el botón Export y hablar con el equipo de soporte haciendo clic en el botón Talk to a Specialist.

Información

Esta es una herramienta completamente opcional, puede usarla si la encuentra necesaria, o si nota algún impedimento al instalar o usar las herramientas de BotCity.

Instalación con Wizard

Para la instalación, utilice el archivo wizard-X.Y.Z, donde X.Y.Z representa la versión del asistente.

Para proceder con la instalación, podemos elegir entre dos opciones:

  • Instalar a través de GUI (interfaz gráfica)
  • Instalar mediante línea de comando (instalación silenciosa)

Instalación mediante GUI (interfaz gráfica)

A través de la interfaz gráfica, el Asistente le guiará por cada paso del proceso de instalación de forma intuitiva, vea el ejemplo a continuación:

Elige dónde instalar

Captura de pantalla del asistente de BotCity. La interfaz presenta 4 pasos, destacando el paso 1: Configuración. Hay un selector de ruta de instalación con un botón de búsqueda, así como un botón para continuar y otro para regresar. En la parte inferior, hay un enlace para obtener más información sobre el SDK de BotCity.

Warning

Ten en cuenta que instalar en ubicaciones como C:\... podría causar problemas de permisos.

Trata de evitar esas ubicaciones o asegúrate de corregir los permisos correspondientemente.

Autenticación con BotCity Orquestador

Captura de pantalla de la herramienta "BotCity Wizard". La interfaz presenta 4 pasos, destacando el paso 2: Iniciar sesión. Un selector de servidor indica el servidor "Community" seleccionado, así como un botón para avanzar y otro para regresar. En la parte inferior, un enlace para obtener más información sobre el SDK de BotCity.

Warning

Para Servidor, asegúrate siempre de usar la URL de BotCity Maestro.

Si tienes un subdominio personalizado, es muy probable que tu URL sea algo como https://tuempresa.botcity.dev.

Para la versión comunitaria, utiliza https://developers.botcity.dev.

Se abrirá una nueva página en tu navegador, permitiéndote iniciar sesión en tu cuenta.

Captura de pantalla que muestra la confirmación de autenticación con BotCity en el navegador.

Si tienes varias organizaciones bajo la misma cuenta, se te pedirá que selecciones una. Captura de pantalla de la herramienta "BotCity Wizard". La interfaz consta de 4 pasos, destacando el paso 2: Iniciar sesión. Hay un selector de organización que indica la organización seleccionada, así como un botón para avanzar y otro para regresar. En la parte inferior, hay un enlace para obtener más información sobre el SDK de BotCity.

Casi listo

Captura de pantalla de la herramienta "BotCity Wizard". La interfaz presenta 4 pasos, destacando el paso 3: Descargar. Una barra de progreso en el centro indica el porcentaje de progreso de la descarga. En la parte inferior, un enlace para obtener más información sobre el SDK de BotCity.

Espera mientras se completa la descarga y se configura el SDK.

¡Estás listo para empezar! 🚀

Captura de pantalla del asistente de BotCity. La interfaz presenta 4 pasos, destacando el paso 4: Finalizar. Esto indica que la configuración del SDK de BotCity está completa. Hay dos botones disponibles: Ir a Orchestrator y abrir el SDK. En la parte inferior, un enlace para obtener más información sobre el SDK de BotCity.

Tip

Ahora hay una copia del Wizard disponible en la carpeta donde se instaló el SDK. Siempre puedes iniciarlo desde allí y volver a esta pantalla.

Configuración de un BotCity Runner

Después de completar la instalación del SDK, puede configurar un Runner en su entorno de ejecución usando la opción Setup Runner.

Captura de pantalla de la herramienta "BotCity Wizard" (versión 2.1.0), titulada "Bienvenido a BotCity SDK". La interfaz describe el SDK como un paquete completo para crear, implementar y ejecutar automatizaciones. Cuenta con tres botones de acción principales con sus respectivos iconos: 1. Iniciar Studio (icono de terminal) para abrir el entorno de desarrollo; 2. Configurar Runner (icono de engranaje) para configurar el agente de ejecución; y 3. Carpeta del SDK (icono de carpeta) para acceder a los archivos locales. En la esquina superior derecha, se indica la versión actual del SDK (v2.20.0) con una opción para cambiarla. En la parte inferior, hay botones para acceder al Orchestrator o hablar con un especialista.

Puede elegir un Runner que ya exista en su espacio de trabajo de Orquestador o crear uno nuevo.

Captura de pantalla de la herramienta "BotCity Wizard" (versión 2.1.0). La interfaz para configurar el Runner en dos pasos: Credenciales y Configuración del Runner. Cuenta con dos botones de acción principales: 1. Ya tengo un Runner; 2. Crear un nuevo Runner. En la parte inferior, un botón para volver atrás.

Si es la primera vez que lo instalas, te recomendamos encarecidamente crear uno para poder ejecutar tus automatizaciones.

Tip

Ver más detalles en la sección Configurar un Runner.

Acciones del BotCity Wizard

Captura de pantalla de la herramienta "BotCity Wizard" (versión 2.1.0), titulada "Bienvenido a BotCity SDK". La interfaz describe el SDK como un paquete completo para crear, implementar y ejecutar automatizaciones. Cuenta con cinco botones de acción principales con sus respectivos iconos: 1. Iniciar Studio (icono de terminal) para abrir el entorno de desarrollo; 2. Configurar Runner (icono de engranaje) para configurar el agente de ejecución; 3. Runner - GUI (icono de pantalla) para abrir el Runner con una interfaz gráfica; 4. Iniciar Runner (icono de capas) para abrir el Runner en una terminal; y 5. Carpeta SDK (icono de carpeta) para acceder a los archivos locales. En la esquina superior derecha, se indica la versión actual del SDK (v2.20.0) con la opción de cambiarla. En la parte inferior, hay botones para acceder al Orchestrator o hablar con un especialista.

A continuación se muestran algunas acciones que puede realizar desde la pantalla de inicio del Wizard:

  • Change version: Cambia la versión a una más reciente o anterior, así como a una versión de desarrollo.
  • Launch Studio: Inicia BotCity Studio.
  • Setup Runner: Configura BotCity Runner.
  • Runner - GUI: Inicia BotCity Runner como una aplicación visual (GUI).
  • Launch Runner: Inicia BotCity Runner como un proceso en segundo plano.
  • Folder sdk: Abre la carpeta donde se instaló el SDK.
  • Go to Orquestrador: Abre BotCity Orchestrator en tu navegador predeterminado.
  • Talk to a Specialist: Abre el canal de soporte de BotCity.

Instalación mediante línea de comando (instalación silenciosa)

Otra forma de instalar el SDK es mediante la línea de comando, ingresando los parámetros necesarios para la instalación.

Comandos de instalación

Podemos instalarlo usando el comando wizard install e ingresando algunos parámetros.

El comando más simple posible es aquel en el que solo ingresamos los parámetros obligatorios email y password, que se utilizan para la autenticación en BotCity Orquestador.

wizard install 
  --email "user@server.com"
  --password "bot32r$3usr74"

Consejo

  • Puede ser necesario informar la versión del Wizard en el comando, si no se encuentra. wizard-X.Y.Z install ...
  • Para sistemas Linux y macOS, agregue el comando java -jar antes del comando del Wizard. java -jar wizard-X.Y.Z.jar install ...

Para realizar la instalación completa, con todos los parámetros, podemos utilizar el siguiente comando:

wizard install 
  --dir "C:\BotCity"
  --server "https://developers.botcity.dev"
  --email "user@server.com"
  --password "bot32r$3usr74"
  --organization "superbots"
  --runner "vm-01"

Tabla de parámetros para el comando de instalación:

Opción Obligatorio Definición Valor predeterminado
dir No Carpeta donde se instalará el SDK Depende del sistema operativo
server No URL del orquestador de BotCity Orquestador https://developers.botcity.dev
email Sí Correo electrónico de cuenta de usuario
password Sí Contraseña de cuenta de usuario
organization No Organización a utilizar (label) Primera organización en la lista
runner No Corredor a configurar (machineId) Vacío

Actualizar comandos

Para actualizar la configuración del SDK, podemos usar el comando wizard update, informando siempre el parámetro password, los demás parámetros son opcionales. Además de los parámetros de instalación, podemos ingresar el parámetro version para actualizar la versión del SDK.

Advertencia

Cuando no se proporciona el parámetro "version", siempre se actualizará a la última versión del SDK.

Solo podemos ingresar un parámetro opcional como en el siguiente ejemplo (incluye actualización de versión):

wizard update
  --password "bot32r$3usr74"
  --runner "vm-01"

O haga una actualización completa, con todos los parámetros como en el siguiente ejemplo:

wizard update 
  --server "https://developers.botcity.dev"
  --email "user@server.com"
  --password "bot32r$3usr74"
  --organization "superbots"
  --runner "vm-01"
  --version "v2.16.5"

consejo

La versión del SDK se puede verificar en el archivo setup.json en la carpeta donde se instaló el SDK.

Con este comando no podemos cambiar la ubicación de instalación del SDK, por lo que debemos rehacer la instalación.

Tabla de parámetros para el comando de actualización:

Opción Obligatorio Definición Valor predeterminado
server No URL del orquestador de BotCity Orquestador Se mantiene instalado
email No Correo electrónico de cuenta de usuario Se mantiene instalado
password Sí Contraseña de cuenta de usuario
organization No Organización a utilizar (etiqueta) Se mantiene instalado
runner No Corredor a configurar (machineId) Se mantiene instalado
version No Versión a instalar Última versión

Explorando el contenido

Después de extraer el archivo descargado, encontrarás la siguiente estructura de carpetas:

.
├── bin
├── bots
├── conf
│   ├── conf.bcf
│   └── properties.json
├── logs
├── probes
├── run
├── scripts
├── startup
├── venvs
├── win32
│   └── java
├── .cookieCli
├── .workspaceCli
├── BotCLI.bat
├── BotRunner.bat
├── BotRunnerBackgroundWrapper.bat
├── BotRunner-gui.bat
├── BotStudio.exe
├── diagnostic.jar
├── install.log
├── setup.json
└── wizard-X.Y.Z.exe

.
├── .cookieCli
├── .workspaceCli
├── bin
├── BotCLI.sh
├── BotRunner-gui.sh
├── BotRunner.sh
├── bots
├── BotStudio.sh
├── conf
│   ├── conf.bcf
│   └── properties.json
├── diagnostic.jar
├── install.log
├── logs
├── probes
├── run
├── scripts
├── setup.json
├── startup
├── venvs
└── wizard-X.Y.Z.jar

En la carpeta raíz del SDK, encontrarás los siguientes archivos:

  • .cookieCli: archivo de cookie de sesión del BotCity CLI.
  • .workspaceCli: archivo de espacio de trabajo utilizado por el CLI.
  • bin: carpeta que contiene los archivos binarios .jar correspondientes al BotCity SDK.
  • BotCLI.bat/BotCLI.sh: acceso directo para utilizar el BotCity CLI (herramienta de línea de comandos).
  • BotRunner-gui.bat/BotRunner-gui.sh: acceso directo para iniciar el BotCity Runner en modo gráfico.
  • BotRunner.bat/BotRunner.sh: acceso directo para iniciar el BotCity Runner en modo headless (en segundo plano).
  • bots: carpeta de caché de bots (uso interno del BotCity Runner).
  • BotStudio.exe/BotStudio.sh: acceso directo para iniciar el BotCity Studio.
  • conf: carpeta que contiene los archivos de configuración.
    • conf.bcf: archivo de configuración del BotCity Studio.
    • properties.json: archivo de propiedades del BotCity Studio (utilice el menú de 'Preferencias' para editar los valores en lugar de modificar directamente este archivo).
  • diagnostic.jar: herramienta para validar los prerrequisitos del entorno para usar las herramientas de BotCity.
  • install.log: archivo de registro de instalación generado por el asistente.
  • logs: carpeta de almacenamiento de registros del BotCity Runner.
  • probes: carpeta con información sobre los horarios de comunicación del Runner con el Orquestador.
  • run: carpeta utilizada por el BotCity Runner durante la ejecución.
  • scripts: carpeta para almacenar scripts que pueden ser ejecutados por el BotCity Runner.
  • setup.json: archivo que contiene información de la instalación, como la versión del SDK instalada y las credenciales de acceso utilizadas.
  • startup: carpeta que contiene un script que puede ser ejecutado por el BotCity Runner al inicializarse.
  • venvs: carpeta utilizada por el BotCity Runner para gestionar los entornos virtuales de las automatizaciones en Python.
  • win32: carpeta que contiene la versión de Java utilizada por el SDK.
  • wizard-X.Y.Z.exe/wizard-X.Y.Z.jar: copia del BotCity Wizard creada dentro de la carpeta de instalación.

Configuración

La configuración del SDK de BotCity Studio se realiza a través del archivo conf.bcf ubicado en el directorio "conf".

Usando el Wizard, este archivo se genera automáticamente para ti, pero aún puedes personalizarlo según tus necesidades.

Echemos un vistazo al contenido del archivo conf.bcf:

server=https://developers.botcity.dev
workspace=<Your Workspace Here>
key=<Your Key Here>
login=<Your Login Here>
machineId=<Your Machine ID Here>
logScreen=true
logApplication=true
  • server: URL del servidor de BotCity Maestro.
  • workspace: Espacio de trabajo de BotCity Maestro.
  • key: Clave de API de BotCity Orquestador ubicada en la página Ambiente de desarrollo.
  • login: Usuario de API de BotCity Orquestador ubicado en la página Ambiente de desarrollo.
  • machineId: ID de máquina de la máquina actual. Consulta Máquinas.
  • logScreen: Opción booleana que define si se envían capturas de pantalla periódicamente a BotCity Studio.
  • logApplication: Opción booleana que define si los registros de BotCity Runner se envían periódicamente a BotCity Studio.

Prueba de tu SDK de BotCity Studio

La forma más sencilla de probar tu SDK de BotCity Studio es utilizar la herramienta BotCity CLI.

Para ello, abre una terminal en la carpeta que contiene el SDK de BotCity Studio y ejecuta el siguiente comando:

./BotCLI.bat bot list

./BotCLI.sh bot list

Si tu SDK de BotCity Studio está configurado correctamente, deberías ver la siguiente salida:

...
 SUCCESS  List of bots successfully returned!

Note

Si ves un mensaje de ÉXITO seguido de un mensaje de ERROR, significa que tu SDK de BotCity Studio está configurado correctamente, pero probablemente aún no has implementado ningún bot.

Siguientes pasos

El entorno del SDK de BotCity Studio ya está instalado y configurado. Este entorno permite desarrollar y ejecutar automatizaciones de BotCity.

También puede separar los entornos de desarrollo y ejecución; para ello, siga los mismos pasos de instalación y configuración en equipos diferentes.

Para conocer los siguientes pasos, consulte la sección Desarrollando tu Primer Bot, donde aprenderá a crear su primera automatización con herramientas como BotCity Studio y los frameworks de BotCity.