Creación de scripts Python y HCL en Robots

La aplicación Robots ofrece la creación de scripts basada en la nube y nativa que usted puede usar para el análisis de datos o para automatizar partes del flujo de trabajo de Diligent One de su organización. La creación de scripts en Robots combina toda la potencia de Python y todas sus bibliotecas compatibles con HighBond Command Language (HCL), nuestra biblioteca personalizada de Python para el análisis de datos centrado en el dominio y la automatización de Diligent One.

Robots continúa permitiendo el análisis de datos y la automatización de datos con ACLScript y scripts que se cargan desde Analytics. Por lo tanto, puede beneficiarse de su inversión existente en ACL (Audit Command Language) y de todas las posibilidades que ofrecen Python, un lenguaje de programación estándar en la industria, y HCL.

Tres tipos de robots

La aplicación Robots contiene tres tipos de robots. Si bien son muy similares en muchos aspectos, los distintos tipos de robots admiten diferentes escenarios de creación de scripts:

• El robot ACL Permite análisis de datos a gran escala con scripts que usted carga desde Analytics y tareas programadas. Los scripts se pueden ejecutar en las instalaciones físicas o en la nube.

• El robot HighBond Permite análisis de datos a gran escala con scripts de Python/HCL creados directamente en el robot y tareas programadas. Los scripts solo se pueden ejecutar en la nube.

• Robot de flujo de trabajo Admite el análisis leve de datos o la automatización de partes de su flujo de trabajo de Diligent One, con scripts de Python/HCL creados directamente en el robot y tareas basadas en eventos o programadas. Los scripts solo se pueden ejecutar en la nube.

  Nota

  Para acceder a los robots de flujo de trabajo, debe contar con una suscripción Profesional y un tipo de usuario de Administrador del sistema.

  La intención es que un Administrador del sistema con una suscripción Profesional pueda configurar tareas en robots de flujo de trabajo que estén desencadenadas por acontecimientos de Diligent One. Esta funcionalidad aún se está desarrollando y todavía no está disponible.

Comparación entre los tipos de robots

Los tres tipos de robots están pensados para diferentes propósitos y funcionan de manera independiente unos de otros. No es posible combinar ACLScript y Python/HCL en un único robot.

Característica del robot	Robot ACL	Robot HighBond	Robot de flujo de trabajo
Propósito	análisis de datos y automatización		automatización de la plataforma Diligent One
Lenguajes admitidos	ACLScript	Python Pandas, NumPy, Requests y otras bibliotecas estándar de Python Biblioteca de Python personalizada de HCL (HighBond Command Language)
Ubicación de la creación de scripts	Analytics	Robots
Ubicación de la ejecución del script	nube en la instalación	nube
Opciones para ejecutar una tarea	programados ejecutar ad hoc (manualmente)		activados por un evento de Diligent One programados ejecutar ad hoc (manualmente)
Tiempo de ejecución máximo de la tarea	Agente de Robots basado en la nube: 60 minutos Agente de Robots en las instalaciones físicas: controlado por la red del cliente	Ningún límite Nota Se planificó un límite de 12 horas, pero todavía no se implementó. Si necesita detener una tarea que se ha estado ejecutando durante mucho tiempo, puede hacer clic en Cancelar ejecución de la tarea en la ficha Ejecuciones de tareas.	15 minutos
Tareas máximas que se ejecutan simultáneamente	5	5	50
Permisos necesarios	ser un colaborador del robot nivel de acceso controlado por el rol del robot del colaborador (Propietario, Editor, Revisor)		Tipo de usuario Administrador del sistema con una suscripción Profesional

Editor de scripts de Robots

Los robots HighBond y robots de Flujo de trabajo contienen un editor de scripts integrado para crear scripts de Python/HCL y ejecutarlos de manera interactiva (manualmente). El editor de scripts está basado en la aplicación Jupyter Notebook, un entorno de desarrollo muy conocido y utilizado en la comunidad de la ciencia de los datos. El editor de scripts utiliza un Enfoque basado en celdas para la creación de scripts.

Enfoque basado en celdas para la creación de scripts

La función más clara del editor de scripts es su capacidad de utilizar varias celdas que contienen los bloques individuales de código que conforman un script. Si no está familiarizado con Jupyter Notebook, es posible que, en un primer momento, el enfoque basado en celdas para la creación de scripts le resulte complicado. Sin embargo, es fácil de usar y tiene ventajas que descubrirá y apreciará rápidamente.

Características clave de la creación de scripts basada en celdas

• El uso de varias celdas es opcional Si no lo desea, no es necesario que utilice varias celdas. Puede crear y ejecutar un script completo usando una única celda.

• Divisiones lógicas Las celdas le permiten dividir un script en bloques lógicos que usted escoja y ejecutar los bloques manualmente de forma independiente o como una secuencia completa.

  Por ejemplo, una organización básica de un script en cuatro celdas podría ser la siguiente:

  • primera celda importar las bibliotecas de Python

  • segunda celda importar los datos

  • tercera celda realizar el análisis de los datos

  • cuarta celda enviar los resultados del análisis

• Ventajas de las celdas El uso de celdas para el desarrollo de scripts ofrece las siguientes ventajas:

  • Puede trabajar en celdas individuales de forma aislada, probarlas y mejorarlas, mientras ignora de forma temporal la lógica del script que se encuentra en otras celdas.

  • Después de ejecutar las celdas importadas iniciales una vez, ya no necesita ejecutarlas al desarrollar y probar las celdas posteriores.

  • Puede usar celdas para imponer un orden visual en sus scripts. Esto hace que la relación entre los diferentes bloques lógicos sea más fácil de ver y comprender tanto para usted como para otras personas.

• Indicador de la secuencia Junto a cada celda, hay un indicador numérico que muestra el orden en el que se ha ejecutado la celda durante una sesión de scripts. Por ejemplo: [7].

  Cuando ejecuta una celda, el indicador se incrementa según las otras celdas que haya ejecutado en el interín. De este modo, por ejemplo, un indicador podría pasar de [7] a [10] si había ejecutado otras dos celdas en el interín u otra celda dos veces.

• Memoria de la sesión y valores almacenados Los valores de las variables y los marcos de datos que se mantienen en la memoria durante una sesión de creación de scripts se actualizan de acuerdo con la secuencia en la que usted ejecuta las celdas.

  En general, usted estructura las celdas para que se ejecuten de forma secuencial de arriba hacia abajo durante la ejecución programada y sin intervención del usuario del script. Algunos valores de variables o marcos de datos pueden actualizarse de forma progresiva según la lógica del script. Si ejecuta las celdas manualmente en un orden que no es el establecido, el estado actual del valor de la variable o el marco de datos tal vez no sea el que usted supone y tal vez obtenga un resultado impreciso o un error. Para restaurar el valor de la variable o el marco de datos a su estado deseado, vuelva a ejecutar todas las celdas en las que se hace referencia al marco de datos o la variable en el orden indicado.

• Visualización de la salida de la celda Por valor predeterminado, al ejecutar una celda solo se muestra la salida de la última expresión de la celda. Si desea ver la salida de varias expresiones de una celda, puede colocar las expresiones en celdas independientes. Sin embargo, un enfoque más adecuado es ajustar una opción de configuración en el editor de scripts.

  • Configure celdas para mostrar la salida de todas las expresiones:

    from IPython.core.interactiveshell import InteractiveShell
    InteractiveShell.ast_node_interactivity = "all"

  • Restaure las celdas para mostrar la salida de la última expresión únicamente:

    from IPython.core.interactiveshell import InteractiveShell
    InteractiveShell.ast_node_interactivity = "last_expr"

  Consejo

  Puede usar el ajuste de configuración para pasar de un modo a otro según sea necesario. Si desea conocer otras opciones de configuración para la salida de la celda, consulte la documentación de Jupyter o IPython en línea.

Métodos abreviados del teclado en el editor de scripts de Robots

Los métodos abreviados del teclado del editor de scripts brindan comodidad y ayudan a desarrollar los scripts con más rapidez. En el editor de scripts, para ver una lista de los métodos abreviados disponibles, use alguno de estos métodos:

• Pulse Ctrl+ /.

• Haga clic en el icono de métodos abreviados del teclado en la barra del título.

Los métodos abreviados disponibles se indican debajo.

Método abreviado del teclado	Acción
Ctrl + Mayús. + Intro	Ejecutar la celda seleccionada
Ctrl + Mayús. + M	Ejecutar todas las celdas en secuencia
Ctrl + Mayús. + Y	Ejecutar la celda seleccionada y todas las celdas que se encuentran arriba
Ctrl + Mayús. + U	Ejecutar la celda seleccionada y todas las celdas que se encuentran abajo
Ctrl + Mayús. + I	Detener la ejecución del script
Ctrl + Mayús. + K Ctrl + Mayús. + Flecha hacia arriba	Seleccionar la celda de arriba
Ctrl + Mayús. + J Ctrl + Mayús. + Flecha hacia abajo	Seleccionar la celda de abajo
Ctrl + Mayús. + H Ctrl + Mayús. + Inicio	Seleccionar la primera celda
Ctrl + Mayús. + L Ctrl + Mayús. + Fin	Seleccionar la última celda
Ctrl + Mayús. + A	Agregar celda arriba
Ctrl + Mayús. + B	Agregar una celda debajo
Ctrl + Mayús. + D	Eliminar la celda seleccionada
Ctrl + Mayús. + Z	Mover celda hacia arriba
Ctrl + Mayús. + X	Mover celda hacia abajo

Las funciones de Jupyter Notebook no se incluyen en el editor de scripts de Robots

Tal como se indica más atrás, el editor de scripts de Robots está basado en la aplicación Jupyter Notebook. Estas funciones de Jupyter no están incluidas en el editor de scripts, aunque algunas de ellas tal vez se incluyan con el tiempo a medida que el producto continúe evolucionando:

• Operaciones en el nivel de la celda:

  • deshacer y volver a hacer operaciones de celda

  • copiar y pegar celdas

  • dividir y fusionar celdas

• Celdas Markdown (para contenido de texto)

Guardar el resultado del script en un archivo de log

Cuando ejecuta un script Python y HCL con una tarea de robot, tiene la opción de guardar el resultado del script en el archivo de log que acompaña cada ejecución de la tarea. El log es un archivo JSON con el mismo nombre que la tarea (nombre_tarea.json).

Para activar la opción, seleccione Guardar el resultado del script en el archivo de log de ejecución de la tarea cuando guarde y confirme y envíe una versión de un script. La opción se puede configurar independientemente para cada versión de un script, de modo que si quiere guardar el resultado de un script, asegúrese de seleccionar la opción correspondiente a la versión específica del script que ejecuta la tarea.

El resultado del script hace referencia a todo el contenido de la secuencia stdout producida por un script. Normalmente, stdout es todo lo que el script imprime o muestra en la pantalla al ejecutarlo de forma interactiva. Básicamente, al seleccionar Guardar el resultado del script en el archivo de log de ejecución de la tarea, captura de manera permanente todo lo que se muestra en la pantalla. Este resultado capturado puede ser útil para la revisión durante el desarrollo y la solución de problemas de los scripts.

Información adicional:

• La opción se aplica solo a las tareas Aunque seleccione Guardar el resultado del script en el archivo de log de ejecución de la tarea en el editor de scripts de Robots, la opción se aplica solo a los scripts que ejecuta una tarea del robot. La opción no tiene efecto si se ejecuta un script interactivamente en el editor de scripts.

• Mensajes de error en el archivo de log de ejecución de la tarea Los mensajes de error de Python (la secuencia stderr) siempre se incluyen en el archivo de log de ejecución de la tarea, independientemente de cómo configure Guardar el resultado del script en el archivo de log de ejecución de la tarea.

• Acceder al archivo de log de la ejecución de la tarea En la ficha Ejecuciones de tareas, hay un archivo de log de ejecución de la tarea disponible por cada tarea ejecutada. Seleccione una tarea ejecutada y el archivo de log correspondiente aparece en la sección Salida del panel lateral Detalles de las ejecuciones de las tareas. Si desea revisar el archivo, puede descargarlo a su computadora.

Transición de ACLScript a Python y HCL

Python es un lenguaje de programación con fines generales y es significativamente más complejo que ACLScript, que es un lenguaje de creación de scripts relativamente directo, diseñado para el área de los estudios analíticos de auditoría.

Nuestra intención es que, con el tiempo, HCL replique muchos de los comandos y las funciones disponibles en ACLScript. Para comenzar a usar HCL, nuestra biblioteca de Python personalizada, debe tener (como mínimo) conocimientos básicos de Python. Es aconsejable que quienes deseen pasar de ACLScript a Python/HCL realicen un buen curso introductorio de Python.

Convenciones de codificación de Python

Tendrá que acostumbrarse a ciertas convenciones de codificación que no se utilizan en ACLScript pero sí son obligatorias en Python y HCL:

• Distinción entre mayúsculas y minúsculas La sintaxis de Python y HCL distingue entre mayúsculas y minúsculas, mientras que la sintaxis de ACLScript no lo hace.

  En Python:

  • print("Hello World!") funciona

  • PRINT("Hello World!") arroja un error

• Sin abreviaturas Los nombres de los parámetros, los métodos y las funciones de Python y HCL se deben escribir completos. A diferencia de lo que ocurre con ACLScript, no se permite el uso de abreviaturas.

• La sangría es importante Python utiliza sangrías para implementar estructuras de control, como instrucciones condicionales y bucles. El uso incorrecto de la sangría provoca errores. ACLScript ignora las sangrías.

Bibliotecas externas de Python

Python admite una gran cantidad de bibliotecas externas o paquetes, que usted puede instalar para ampliar la funcionalidad de la instalación principal de Python y la biblioteca estándar de Python. Una biblioteca externa de Python es una colección de módulos de código relacionados diseñados para hacer cosas específicas más allá de lo que usted puede hacer con el núcleo de Python y la biblioteca estándar. O hace que ciertas cosas sean más rápidas y fáciles de hacer que en el núcleo de Python.

Bibliotecas externas incluidas en Python de Diligent One

La instalación de Diligent One de Python incluye ciertas bibliotecas externas de forma predeterminada, por lo que no necesita instalarlas explícitamente. Con la excepción de la propia biblioteca HCL Python de Diligent, debe importar las bibliotecas preinstaladas para usarlas en la lógica de scripts Python/HCL posteriores.

Bibliotecas externas preinstaladas en el entorno Python de Diligent One:

Biblioteca	Descripción	Declaraciones de importación de Python
HCL	La biblioteca HCL, o HighBond Command Language, es la biblioteca Python personalizada de Diligent para el análisis de datos centrado en el dominio y la automatización de Diligent One.	no requerido
Pandas	La biblioteca Pandas proporciona un poderoso conjunto de herramientas para la manipulación y el análisis de datos en Python, incluidos los marcos de datos, que son matrices de datos bidimensionales similares a hojas de cálculo o tablas.	import pandas o import pandas as pd (opcionalmente, crea un alias abreviado para el nombre de la biblioteca)
NumPy	La biblioteca NumPy ofrece computación científica rápida y poderosa en Python, incluidas operaciones algebraicas y estadísticas básicas, operaciones matemáticas avanzadas y la creación y realización de cálculos en matrices multidimensionales.	import numpy o import numpy as np (opcionalmente, crea un alias abreviado para el nombre de la biblioteca)
Requests	La biblioteca Requests proporciona una sintaxis ligera para realizar solicitudes HTTP en Python e interactuar con las API basadas en la web.	import requests o import requests as req (opcionalmente, crea un alias abreviado para el nombre de la biblioteca)
Cryptography	La biblioteca Cryptography admite la incorporación de algoritmos criptográficos en Python.	import cryptography o import cryptography as crypt (opcionalmente, crea un alias abreviado para el nombre de la biblioteca)

Instalación de bibliotecas externas adicionales

Los robots HighBond admiten la instalación de bibliotecas externas adicionales además de las que están preinstaladas con el entorno Python de Diligent One. Para instalar una biblioteca adicional, use pip, una herramienta para descargar e instalar paquetes de Python. De forma predeterminada, pip descarga los paquetes del Python Package Index (PyPI), un repositorio de código abierto del software de Python. También puede usar pip para instalar paquetes desde otro lugar.

Por ejemplo, para instalar pyexcel, una biblioteca de Python para trabajar con archivos y datos de Excel, use este comando en el editor de scripts de Robots:

pip install pyexcel

Incluso si instala una biblioteca externa, no hay garantía de que el editor de scripts de Robots admita todas las funciones de la biblioteca externa. Por ejemplo, es posible que no admita la visualización de gráficos y trazados disponibles en ciertas bibliotecas externas.

Uso de Python y HCL para trabajar con las API

Puede usar los scripts de Python/HCL en Robots para trabajar con las API, tanto las API de terceros como la propia API de Diligent One.

Trabajo con una API de otro fabricante

Para trabajar con la API de otro fabricante, comience por importar la biblioteca Requests de Python en el editor de scripts de Robots:

import requests

Ahora puede crear solicitudes de API con la sintaxis de solicitudes de Python y recibir respuestas. Para ver un ejemplo sencillo de cómo utilizar Python con una solicitud de API de otro desarrollador en Robots, consulte Parte 3: Extienda su alcance en Comience a crear scripts en Robots y usar la API de Diligent HighBond.

La explicación en detalle sobre cómo usar Python con las API de terceros está más allá del alcance de nuestra documentación. Sin embargo, existen muchos recursos en línea que pueden servir de guía detallada.

Trabajo con la API de HighBond

La API de HighBond es la interfaz para desarrolladores de la plataforma Diligent One. Puede usar la API para automatizar las interacciones y el flujo de trabajo de Diligent One, generar reportes e integrar Diligent One con otros sistemas de su organización.

HCL incluye métodos que permiten una interacción directa con la API de HighBond. Si desea obtener más información, consulte Métodos de la API de HighBond de HCL.

También puede usar la biblioteca Requests de Python con la API de HighBond. No obstante, para mayor facilidad, recomendamos usar los métodos de HCL.

Si desea ver un tutorial introductorio que cubre el uso de Python y HCL con la API de HighBond, consulte Comience a crear scripts en Robots y usar la API de Diligent HighBond..