Módulo de scripting

El Módulo de Scripting integra motores de Octave y Python, lo que permite a los usuarios escribir y ejecutar cálculos usando cualquiera de los dos lenguajes dentro de Requirements & Systems Portal. El módulo está diseñado para realizar cálculos complejos que no son posibles mediante el ValiEngine estándar.

Si los usuarios desean manipular cualquier otro objeto que no sean Valis numéricos, deben usar la API de Python de Requirements & Systems Portal. Algunos casos de uso de ejemplo incluyen:

• Crear un valor y añadirlo de forma masiva a múltiples Blocks

• Realizar ediciones masivas de identificadores de requisitos

• Ejecutar simulaciones usando Python

• Convertir unidades de valores de potencia a kW.

• Ejecutar un comportamiento de flujo de trabajo personalizado basado en disparadores automatizados

Flujo del Módulo de Scripting

Para usar el módulo, el usuario crea un nuevo script, añade entradas/salidas, escribe código en .m o .py y ejecuta el código para obtener la salida deseada.

Flujo de trabajo del Módulo de Scripting.

Creación de un nuevo script

Para crear un nuevo script, haga clic en la opción "+ Script" (1) dentro de los módulos de scripting.

Aparecerá un cuadro de diálogo que le permitirá introducir el nombre del script, seleccionar el motor (Octave o Python) y disponer de opciones adicionales para que el usuario use/reutilice a partir de las plantillas.

Opción Crear nuevo script

Una vez creado un nuevo script, los usuarios también pueden crear archivos adicionales de texto, JSON y YAML para sus scripts. Para añadir un nuevo archivo, haga clic en la opción “+Add file” (1), añada un nombre y seleccione un tipo de archivo en el cuadro de diálogo. Esto añade un archivo al script.

Para usar cualquiera de los archivos adicionales creados, los usuarios deben incluir las siguientes dos líneas de código en la parte superior del archivo main.py:

import site
site.addsitedir('script_code/')

Después de estas dos líneas, se puede llamar a cualquier archivo adicional usando la instrucción estándar import.

Gestión de secretos:

Para no exponer el uso de credenciales necesarias al utilizar scripts que se conectan ya sea a nuestra API o a la de otras herramientas, es posible definir variables secretas personales que pueden invocarse durante la ejecución del script y así evitar exponerlas a otros usuarios del despliegue al almacenarlas en archivos de script.

Cómo y dónde añadirlos

Los secretos pueden definirse en el panel de Configuración, en User Secrets. Estos secretos pueden reutilizarse dentro del script para iniciar sesión en Requirements & Systems Portal. Aquí tiene un breve vídeo para mostrar cómo puede crear secretos de usuario.

Como su nombre indica, estos secretos son únicos para cada usuario y solo son accesibles por quienes los definieron.

Cómo usar Secrets en un script

Al importar el nombre del secreto desde el módulo “.settings”, los usuarios pueden usar secretos para la autenticación dentro de los scripts.

from .settings import USERNAME, PASSWORD  #case sensitive, use the same word used in the user secrets.

LOGIN_DATA = {
    'domain': 'API_URL',
    'username': USERNAME,
    'password': PASSWORD
}

En tiempo de ejecución, los scripts obtendrán el valor de estas variables a partir de los secretos definidos en la configuración de usuario de quien active el script, y dependen de los permisos de ese usuario. Los scripts no deben contener funciones de salida de estas variables para no exponer secretos de usuario.

Los scripts de uso general configurados para activarse con automatizaciones pueden configurarse con autenticación de un usuario de nivel administrador que pueda eliminar permisos de lectura a todos los demás usuarios, manteniendo así el script oculto.

Sistema de cola

Con el sistema de cola, los usuarios pueden tener la certeza de que sus scripts siempre se ejecutarán, especialmente si automatizaciones predefinidas activan regularmente scripts de flujo de trabajo personalizados. Para ello, acceda a la sección “Runs”. Puede ver todas las ejecuciones de todos los scripts o las ejecuciones de un script específico.

Todas las ejecuciones de scripts ahora se guardarán en el despliegue y podrán consultarse por script o para todos los scripts seleccionando la opción “All scripting” en la parte superior del árbol del Script Module.

Puede detener un script en ejecución haciendo clic en el botón “Stop” en el menú desplegable Actions.

Acción Stop para un script.

Gestión de permisos

Los scripts tienen sus propios permisos, que pueden gestionarse directamente desde el Módulo de Scripting o desde el Project Module, en “Permissions”.

Ejecutar scripts desde un dashboard

Los usuarios también pueden crear dashboards de interacción personalizados mediante botones “Run Script”. Estos son similares a los botones Request disponibles anteriormente, usados para activar llamadas REST, pero pueden configurarse para ejecutar uno o varios scripts con solo pulsar un botón.

Mediante el uso de la API de Python en los scripts llamados, se pueden configurar dashboards de interacción personalizados en los que elementos como cuadros de texto estándar puedan usarse como campos de entrada y salida para un script, que luego también puede afectar, directa e indirectamente, a otros elementos mostrados.

Para ello, vaya al Project Module y entre en “Dashboards”. Luego entre en su dashboard personalizado y haga clic en el icono Plus en la esquina inferior derecha. Después seleccione la opción “Run script” del desplegable “Actions”.

Esto crea un botón desde el que puede ejecutar scripts que actualizan bloques específicos de su dashboard.

Un caso de uso interesante es aquel en el que las ejecuciones de prueba aprobadas y fallidas se cuentan y se muestran en un bloque de texto en el mismo dashboard.

Script & Automatizaciones

Las automatizaciones preconfiguradas pueden activar scripts. Por ejemplo, se puede configurar que un cálculo complejo se ejecute automáticamente si se modifican sus entradas definidas. Además, mediante el uso de la API de Python de Requirements & Systems Portal, también se puede programar un comportamiento complejo a medida para crear flujos de trabajo personalizados.

Las automatizaciones no solo activarán scripts, sino que también transmitirán la información sobre qué objetos las activaron para que los scripts puedan actuar directamente sobre esos objetos. La información del objeto está disponible en la variable de diccionario “kwargs”, bajo la clave ‘triggered_objects', como en el siguiente ejemplo:

object_data = kwargs['triggered_objects'][0]

Las automatizaciones también ejecutarán scripts si son activadas por usuarios que no tienen permisos para ver dichos scripts, lo que permite la personalización de flujos de trabajo y cálculos por parte de usuarios administradores mientras se limita el acceso al código subyacente, como modelos matemáticos y físicos propietarios.

Se pueden encontrar scripts de flujo de trabajo de ejemplo en la carpeta templates del repositorio público de valifn.

Imágenes personalizadas de Valifn

Los usuarios on-prem disponen de la función adicional de personalizar su instancia de valifn para ejecutar cualquier paquete de Python que deseen, siempre que el hardware de su servidor pueda soportarlo. Los usuarios on-prem también tendrán la capacidad de gestionar qué imagen de valifn se utilizará en tiempo de ejecución del script.

Como se muestra, esta opción está disponible como un campo de texto en la Configuración general de cada script individual.

Cómo crear una imagen personalizada

Puede encontrar más instrucciones sobre cómo configurar sus propias imágenes de valifn en las páginas de documentación del repositorio público:

• Usage · valispace/valifn-octave Wiki (github.com)

• Usage · valispace/valifn-python Wiki (github.com)

Ejemplos de scripts de Python

Se pueden encontrar ejemplos de scripts utilizables tanto en el proyecto de ejemplo Valicopter 5000 de un despliegue (nuevos despliegues) como en el repositorio público de Github de ValiFn.

Estos ejemplos pueden activarse manualmente o mediante automatizaciones (exclusivamente en algunos casos) y pueden usarse tal cual o ser modificados por los usuarios para realizar cualquier tipo de comportamiento a medida.

Muchos de estos ejemplos se crearon como demostraciones de las posibilidades del módulo de scripting y las automatizaciones para crear flujos de trabajo automatizados a medida. Se anima a los usuarios a personalizar cualquier script existente según sus necesidades y a compartir cualquier script de propósito general y mejoras en el repositorio público de ValiFn.

Advertencia de sospecha en hijos (Automatización)

Fundamento

Este script se activa mediante una automatización que debe configurarse para activarse por un cambio en un requisito existente, ya que el script actúa sobre las propiedades del requisito editado. Su acción actualmente definida es colocar una discusión en cada uno de sus hijos (si los tiene) con un mensaje personalizado sobre el estado de cambio del requisito padre.

Personalización sugerida

Otras acciones posibles podrían ser crear una tarea o añadir el requisito editado a una revisión.

Acciones actuales

• Comprueba si el requisito que activó la automatización preconfigurada tiene hijos

• Si tiene hijos, publica una discusión en cada requisito hijo indicando que el padre ha sido actualizado.

• La discusión incluye la identidad del usuario que editó el requisito, activando así la automatización.

Nueva tarea (Automatización)

Fundamento

Al crear un nuevo Block, un posible cliente requirió que las tareas se crearan automáticamente y se asignaran a un usuario específico. En este ejemplo, una automatización preconfigurada activada por la creación de un nuevo Block creará una nueva tarea y le asignará un usuario. Se ideó añadir el objeto activador como entrada, pero ese desarrollo no se finalizó.

Personalización sugerida

Usa el kwargs['triggered_objects'][0] para extraer la información del objeto que activó la automatización y añadirla al campo de entrada de la tarea.

Acciones actuales

• Publica una nueva tarea asignada a un usuario especificado.

Estadísticas de requisitos

Fundamento

Un ejemplo sencillo de cómo se puede crear un contador más personalizado con más valores estadísticos que los proporcionados en los bloques predeterminados disponibles en los documentos de Dashboards y Analysis. Puede ejecutarse manualmente o configurarse para ejecutarse desde una automatización cada vez que se crea, modifica o elimina un requisito.

Personalizaciones sugeridas

1. Toma la información extraída sobre los requisitos y deriva estadísticas más complejas comparándola con valores actualizados previamente. Cada valor puede indicar cuánto aumentó/disminuyó expresado en porcentaje.

2. Compara las estadísticas de la implementación ejecutando individualmente el script en cada proyecto y añadiendo una instancia especial que obtenga estadísticas de todos los proyectos, mostrándolas en un dashboard.

3. Configura una advertencia personalizada para los administradores del proyecto si las estadísticas muestran una caída repentina en el número de requisitos, lo que señalaría un posible cambio drástico en el proyecto.

Acciones actuales

• Genera estadísticas generales de requisitos para un único proyecto en la implementación.

• Aplica parches a Valis precreados con los resultados.

Generación de especificaciones

Fundamento

Un script de ejemplo que demuestra la potencia de la API de Python para crear informes totalmente automatizados. Aunque el script principal también está disponible en la página de documentación de integraciones, esta versión en particular ha sido adaptada para ejecutarse desde el módulo de scripting de la implementación.

Puede activarse mediante una automatización o manualmente.

Personalizaciones sugeridas

1. Crea un informe completo adaptando el proceso actual de obtención de requisitos para extraer Blocks y otros objetos que se completarán en el informe

2. Añade otros campos personalizables, que pueden obtenerse de bloques de texto personalizados de dashboard, desde los cuales it can also be triggered.

3. Cambia el archivo de salida final a un PDF en lugar de un archivo de Word editable.

Acciones actuales

• Toma un archivo de Word como plantilla, de una implementación determinada, y devuelve, como salida, archivos generados, tantos como especificaciones haya, colocados en la gestión de archivos de la implementación (consulta Exportación de especificaciones basada en plantilla de Microsoft Word para más detalles).

Dashboard de pruebas

Fundamento

Los contadores de dashboard aún no se han puesto al día con el módulo de Testing, y todavía no existen contadores automatizados para pruebas. Este script se desarrolló como prueba de concepto para un contador personalizado que aún no se ha implementado. Inicialmente se concibió para ejecutarse mediante activación manual desde un botón Run Script en un Dashboard.

Personalizaciones sugeridas

1. Amplía las estadísticas de pruebas que se publican de vuelta en Dashboards.

2. Si una ejecución de prueba es exitosa, publica el resultado en una tarea conectada y cambia su estado a “Done”.

Acciones actuales

• Devuelve una cadena, colocada en bloques de texto predefinidos del Dashboard, con estadísticas calculadas de ejecución de pruebas.

• Puede recibir entrada desde una automatización o activarse manualmente.