Parte 1: Aspectos básicos

La Parte 1 del tutorial le presenta la creación de scripts en Robots y el uso de la API de HighBond para automatizar parcialmente un proceso

¿Qué aprenderé?

Aprenderá cómo hacer lo siguiente:

• configurar, crear y probar un script de Python/HCL en un robot HighBond

• usar la API de HighBond para interactuar con un objeto de Diligent One

• utilizar HCL para importar y transformar algunos datos, y guardar la salida en Resultados

Escenario: guardar los resultados de la salida en la aplicación Resultados de Diligent One

Supongamos que necesita realizar algunos análisis de datos recurrentes en Robots. Después de realizar el análisis, desea guardar los resultados obtenidos en la aplicación Resultados para realizar acciones correctivas para los asuntos o para visualizar los datos.

Desea programar un script de Robots que contenga el análisis de datos para ejecutarlo sin intervención del usuario todas las noches. No quiere tener que preocuparse de si existe una tabla en Resultados para recibir los resultados de la salida todas las noches, ni por tener que recuperar manualmente un identificador único de tabla. Desea que el script encuentre automáticamente la tabla correcta, según el nombre, o que cree una nueva tabla si no existe una tabla con ese nombre.

En la Parte 1 del tutorial automatizaremos parcialmente este proceso de punta a punta. En la Parte 2 lo automatizaremos totalmente.

Iniciar sesión en Diligent One y llevar a cabo algunas tareas de configuración

Lo primero que debe hacer es iniciar sesión en la instancia de Diligent One de su organización y llevar a cabo algunas tareas de configuración. Las tareas se completan de manera rápida y sencilla.

Un recordatorio: debe ser Administrador del sistema Launchpad y tener acceso a las aplicaciones Robots y Resultados para poder realizar todas las tareas que se incluyen en este tutorial.

Iniciar sesión en Diligent One

Crear una colección y un análisis en la aplicación Resultados

Cree una colección y un análisis en Resultados para almacenar la tabla que va a crear. Una colección es un contenedor de primer nivel en Resultados, mientras que un análisis es un contenedor de segundo nivel.

Crear una colección

Crear un análisis

Crear un robot en la aplicación Robots

Cree un robot que contenga el script que va a crear.

Crear un token de API de HighBond en Launchpad

Para poder usar la API de HighBond, necesita un token de API de HighBond. Puede crear un nuevo token o usar uno existente. Proteja el token como si se tratara de una contraseña y evite compartirlo con otras personas.

Crear y probar el script en modo interactivo

Usted crea y prueba scripts en el editor de scripts de Robots. La ejecución de scripts o de celdas de scripts individuales de forma manual en el editor de scripts se considera modo interactivo. Debe interactuar manualmente con el script para ejecutarlo.

En la Parte 2 del tutorial, programará el script para que se ejecute sin intervención del usuario.

Crear una variable de contraseña para el token de la API de HighBond

Antes de comenzar a crear el scripts, cree una variable de contraseña para el token de la API de HighBond.

Copiar y pegar bloques de código en las celdas del editor de scripts

1. Desde la siguiente tabla, copie y pegue cada bloque de código en celdas independientes en el editor de scripts.

   Para agregar una nueva celda en el editor de scripts, haga clic en Agregar una celda debajo en la barra de herramientas del editor de scripts. Si lo desea, puede agregar cuatro celdas vacías más en este momento.

2. Después de pegar el código de una celda y realizar las actualizaciones especificadas en el código, haga clic en Ejecutar la celda seleccionada para ver la salida.

   

Pautas

• Conserve el mismo orden Asegúrese de que el código de las celdas del editor de scripts siga el mismo orden que el código de la siguiente tabla. Si alguna de las celdas no está en el orden correcto, el script no se podrá completar con éxito.

  Nota

  Junto a cada celda del editor de scripts aparece un número cuando ejecuta la celda. Por ejemplo: [7]. El número no es un número de celda. Se trata de un indicador de secuencia que se actualiza de forma dinámica y muestra el orden en el que se ejecutó la celda durante una sesión de creación de scripts.

• Use el botón Copiar En los bloques de código que se encuentran debajo, pase el cursor sobre el bloque y haga clic en el botón Copiar para copiar todo el código del bloque.

• Copie y pegue con cuidado Al copiar y pegar código, asegúrese de contar con todo el código. Python no permite que falte ningún elemento, como paréntesis de apertura y cierre ( ) .

  Copie y pegue únicamente el código. No incluya los ejemplos de la salida de la celda que aparecen después de los bloques de código que se encuentran más adelante.

  Copiar y pegar con cuidado lo ayudará a evitar los errores de tiempo de ejecución.

• Trabaje celda por celda Ver la salida celda por celda lo ayudará a comprender la estructura de la lógica del script. Si bien la primera celda no tiene una salida visible, debe ejecutarla antes de poder ejecutar cualquiera de las demás celdas.

• Lea los comentarios del código Además de los comentarios en la siguiente tabla, lea los comentarios del código para comprender qué está haciendo el código.

  # Comment text

Descripciones de celdas y bloques de código

N°. de celda	Bloque de código y descripción
Celda 1	Importar los componentes necesarios El código de la celda 1 importa algunos componentes de código adicionales. Importación en Python Para extender las funciones centrales de Python, con frecuencia debe importar componentes de código adicional, como bibliotecas, módulos o clases. Si recién comienza a usar Python, no se preocupe demasiado por los nombres de estos componentes o las diferencias que existen entre ellos. import hcl Cada vez que abre el editor de scripts de Robots, se importa la biblioteca de HCL por valor predeterminado y no es necesario importarla explícitamente. Puede omitir import hcl , pero lo especificamos explícitamente aquí para que comprenda lo que está ocurriendo.
	Bloque de código para la celda 1 Copie y pegue este bloque de código en la celda 1 del editor de scripts y después ejecute la celda. Al ejecutar esta celda, no hay una salida visible. # CELL 1 # Import the HighBond Command Language (HCL) custom Python library import hcl # Import the date, datetime, and timedelta classes from the Python datetime module from datetime import date, datetime, timedelta
Celda 2	Definir las variables que se usan en el script El código de la celda 2 define varias variables. Las variables son necesarias porque algunos valores que se utilizan en el script pueden cambiar: variables de fecha el nombre de la tabla de Resultados que el script creó incluye un sufijo con la fecha actual o el mes actual variable del nombres de tabla le permite especificar el nombre de tabla que desee variables de identificadores contienen los identificadores exclusivos generados por el sistema para la tabla y el análisis que contiene la tabla Nota Para guardar los resultados de la salida de Robots a Resultados, necesita el identificador exclusivo de la tabla de destino en Resultados. En la celda 3, recupera el identificador a nivel de la programación. La función print() le permite ver los valores actuales de algunas de las variables
	Bloque de código para la celda 2 Copie y pegue el siguiente bloque de código en la celda 2 del editor de scripts. En el código de bloque que pegó, actualice v_analysis_id = "XXXXXX" (línea 19) con el identificador de análisis de Resultados que guardó en el archivo de texto temporal. Por ejemplo: v_analysis_id = "93671" . Opcional. Actualice la parte de la cadena de v_table_name de Test table 1 como lo desee (línea 15). Cambie únicamente el nombre de la tabla. No cambie nada más. Por ejemplo: v_table_name = f"My table name ({current_date})" Ejecute la celda. # CELL 2 # Define the variables used in the script # Assign the current date to a variable, and break out date and month into separate variables # The timedelta() method gives you the option of adjusting the date for a script that runs after midnight (Diligent One platform time) today = date.today() # - timedelta(days = 1) current_date = today.strftime("%d-%b-%Y") current_month = today.strftime("%b") # Assign the current Diligent One server timestamp to a variable highbond_datetime = datetime.now() # Specify a table name that already exists in Results, or that you want to create v_table_name = f"Test table 1 ({current_date})" # Create variables for Diligent One table and analysis ID numbers v_table_id = None v_analysis_id = "XXXXXX" # Display the variable values print("date =", current_date) print("month =", current_month) print("table name =", v_table_name) print("current Diligent One platform datetime =", highbond_datetime) Ejemplo de la salida de la celda date = 29-Sep-2021 month = Sep table name = Test table 1 (29-Sep-2021) current Diligent One platform datetime = 2021-09-29 11:03:45.988875
Celda 3	Crear una tabla en Resultados El código de la celda 3 utiliza la API de HighBond para encontrar o crear la tabla de Resultados con el nombre que usted especificó en la celda anterior (el valor de v_table_name ). Las solicitudes de la API se hacen con dos métodos de HCL: hcl.api_get – obtiene una lista de todas las tablas del análisis hcl.api_post – si el nombre de la tabla que especificó no existe en el análisis, crea una tabla con ese nombre Nota Este bloque de código representa el valor fundamental del script. Por medio del uso de la API de HighBond, puede interactuar a nivel de la programación con la aplicación Resultados sin necesidad de abrir manualmente la aplicación. Esto significa que puede lograr su objetivo de ejecutar el script sin intervención del usuario sin necesidad de preocuparse por si existe una tabla en Resultados para recibir los resultados de la salida. En la Parte 2 del tutorial, extenderemos el script para usar este mismo enfoque basado en la API para encontrar o crear automáticamente una colección y un análisis.
	Bloque de código para la celda 3 Copie y pegue este bloque de código en la celda 3 del editor de scripts y después ejecute la celda. # CELL 3 # Find a table with the name specified in v_table_name. If the table doesn't exist, create it. # Get a list of all tables in v_analysis_id tables = hcl.api_get(f"analyses/{v_analysis_id}/tables") # Convert the list from a JSON string to a Python dictionary tables_dict = tables.json() # Loop through the tables in the tables dictionary to search for v_table_name # If the name exists, assign its unique ID to v_table_id for table in tables_dict["data"]: if table['attributes']['name'] == v_table_name: v_table_id = table['id'] print(f"The ID of the existing table is {v_table_id}") # If v_table_name does not exist, create a table with that name in Results # Refresh the tables dictionary and assign the unique ID of the newly created table to v_table_id if v_table_id == None: hcl.api_post(f"analyses/{v_analysis_id}/tables", {"data": {"type": "tables", "attributes": {"name": v_table_name, "description": f"Description of {v_table_name}", "table_type": "data_analytic"}}}) tables = hcl.api_get(f"analyses/{v_analysis_id}/tables") tables_dict = tables.json() for table in tables_dict["data"]: if table['attributes']['name'] == v_table_name: v_table_id = table['id'] print(f"The ID of the newly created table is {v_table_id}") Ejemplo de la salida de la celda The ID of the newly created table is 209717
Celda 4	Realizar algunos análisis de datos El código de la celda 4 realiza algunos análisis de datos sencillos que demuestran un par de métodos de HCL: hcl.read_csv() – importar dos archivos CSV a los marcos de HCL join() – unir los marcos de datos en un campo común Los marcos de datos son estructuras similares a las tablas, que organizan los datos en filas y columnas. Nota Podría reemplazar cualquier análisis de datos que envíe un marco de datos de HCL que usted luego guarda en la aplicación Resultados.
	Bloque de código para la celda 4 Copie y pegue este bloque de código en la celda 4 del editor de scripts y después ejecute la celda. # CELL 4 # Perform data analysis to identify prohibited transactions made with corporate purchase cards # Import CSV files to HCL dataframes pcard_transactions = hcl.read_csv("https://help.highbond.com/helpdocs/analytics/tutorial_data/pcard_trans.csv") prohibited_merchant_codes = hcl.read_csv("https://help.highbond.com/helpdocs/analytics/tutorial_data/prohib_codes.csv") # Join HCL dataframes on the common MerchCode/MerchantCode columns prohibited_transactions = pcard_transactions.join(other = prohibited_merchant_codes, lkey = ["MerchCode"], lcolumns = ["AccountNumber", "TransDate", "VendorName", "Description", "UnitCost", "Quantity", "Amount"], rkey = ["MerchantCode"], rcolumns = ["MerchantType"], join_type='inner') # Display the joined dataframe prohibited_transactions Ejemplo de salida de la celda (un marco de datos de HCL)
Celda 5	Guardar la salida del análisis de datos en la tabla de Resultados El código de la celda 5 guarda la salida del análisis de datos en la tabla de Resultados que el script encontró o creó previamente. El método to_hb_results() de HCL guarda un marco de datos HCL en Resultados.
	Bloque de código para la celda 5 Copie y pegue este bloque de código en la celda 5 del editor de scripts y después ejecute la celda. # CELL 5 # Save the results to the existing or newly created Results table # Save the HCL dataframe to Results prohibited_transactions.to_hb_results(table_id = v_table_id, overwrite=False) Ejemplo de la salida de la celda 202 es el código de estado HTTP para "Aceptado". 202

Comprobar la nueva tabla en Resultados

Veamos la aplicación Resultados para confirmar que se haya creado la nueva tabla y que la tabla contenga los resultados de la salida del análisis de datos de ejemplo.

Obtener más información

Puede experimentar libremente con el script y probar diferentes opciones para crear tablas de Resultados.

Guardar el script y salir del editor de scripts

Comparación entre el modo de desarrollo y el de producción de Robots

Modo de desarrollo

Al salir del editor de scripts de Robots, tómese un momento para orientarse. Se encuentra en el modo de desarrollo de Robots El modo de desarrollo se distingue por la presencia de un encabezado con un fondo oscuro y porque el botón Desarrollo está seleccionado.

Cada vez que desee editar un script o ejecutarlo de manera interactiva, tal como acaba de hacer, debe regresar al modo de desarrollo. No puede editar ni ejecutar scripts de manera interactiva si está en el modo de producción de Robots.

Modo de producción

Utilice los botones Desarrollo y Producción para pasar del modo de desarrollo al modo de producción.

El modo de producción se distingue por la presencia de un encabezado con un fondo claro y porque el botón Producción está seleccionado. Cada vez que vuelva a entrar en un robot, irá al modo de producción.

Lo que aprendió

¡Felicitaciones! Ahora tiene una comprensión básica del uso de la generación de scripts nativa de Robots con la API de HighBond.

Específicamente, ha aprendido a hacer lo siguiente:

• crear y probar un script de Python/HCL en un robot HighBond

• usar la API de HighBond para interactuar con un objeto de Diligent One

• utilizar HCL para importar y transformar algunos datos, y guardar la salida en Resultados

¿Qué sigue?

En la Parte 2 del tutorial automatizará por completo el proceso con el que ha estado trabajando:

• extienda el script para que no sea necesario crear manualmente colecciones o análisis en la aplicación Resultados

• cree una tarea programada para poder ejecutar el script sin intervención del usuario

Vaya a >  Parte 2: Aumente sus conocimientos

 

Resolución de problemas

Si obtiene un error de Python (un bloque de error rojo) al ejecutar una celda o el script completo, lleve a cabo el procedimiento de resolución de problemas que se incluye a continuación.