Aprovechar los scripts y las API de Workiva puede agilizar considerablemente las operaciones y los flujos de trabajo. Como en todos los proyectos de scripting, seguir las mejores prácticas para el desarrollo de código y el control de versiones da como resultado una gestión eficaz del proyecto, continuidad y éxito.
A continuación encontrarás algunos consejos y trucos de Workiva Scripting para el desarrollo de proyectos y flujos de trabajo.
Editor de scripts de Workiva
El Editor de Scripts de Workiva se creó para ayudar a integrar el código de producción en Workiva, supervisar los procesos de producción y solucionar los problemas iniciales cuando surjan. no es un editor de código completo, y no tenemos planes de convertirlo en uno.
Entorno de desarrollo
Si ya tienes un entorno de desarrollo empresarial y un sistema de control de versiones, te recomendamos que lo utilices para todo tu desarrollo y pruebas de scripts.
Los componentes clave de un entorno de desarrollo incluyen un Editor de Código (ejemplos populares son VSCode, PyCharm, Jupyter, etc.), y un Sistema de Control de Versiones (ejemplos populares son GitHub y GitLab). Para quienes no sean ingenieros o prefieran no trabajar en una interfaz de línea de comandos, existen herramientas ligeras como GitHub Desktop y SourceTree que pueden agilizar el trabajo en los sistemas de control de versiones.
Si no tienes un entorno de desarrollo, considera la posibilidad de establecer uno. Mientras tanto, asegúrate de guardar copias de tus guiones (antes, durante y después de cualquier cambio/actualización), y asegúrate de que mantienes las versiones de desarrollo/trabajo de tus guiones separadas de las versiones de producción para reducir las sobreescrituras accidentales.
Desarrollo de scripts
Durante el desarrollo y las pruebas de los proyectos de scripts, considera seguir las principales prácticas de Python y de control de versiones:
Python
Sigue PEP 8 - Guía de estilo para el código Python en la medida de lo posible. La coherencia del Código es muy beneficiosa para la legibilidad, el mantenimiento y la continuidad.
Para crear scripts Python robustos, fiables y escalables a nivel de producción, asegúrate de centrarte en áreas clave como:
- Autenticación: Crear, gestionar y regenerar eficazmente el Token de portador adecuado garantiza que sólo los usuarios o sistemas autorizados puedan acceder a los recursos, datos o funcionalidad del espacio de trabajo.
- Modularidad: Divide los scripts grandes en unidades más pequeñas, independientes y reutilizables (funciones, clases, módulos/archivos). Esto facilita la lectura, las pruebas, la depuración y el mantenimiento del script a lo largo del tiempo.
- Iniciando sesión: Incluye un registro detallado para capturar eventos clave y mensajes de estado, lo que es vital para controlar el rendimiento y solucionar cualquier incidencia.
-
Tratamiento de errores: Incluye lógica para el tratamiento de errores para que los scripts sean más robustos, fiables y fáciles de usar, gestionando con elegancia las situaciones inesperadas en lugar de bloquearse.
Nota: Utiliza el tratamiento de errores para resolver situaciones inesperadas. No dependas de él para compensar o enmascarar las consecuencias sobre el rendimiento de un diseño de script subóptimo (por ejemplo, si tu script genera un gran número de respuestas 429/Demasiadas Solicitudes, el diseño de tu script y el flujo de trabajo deberían refactorizarse para optimizar las llamadas a la API, no deberías depender de la gestión eficaz de un gran número de 429 para el éxito del script).
- Documentación: Explica lo que hace el código y cómo utilizarlo (tanto internamente, mediante comentarios y docstrings, como externamente, mediante guías del usuario (READMEs)), permitiendo a otros desarrolladores y a ti en el futuro comprender y modificar el script con eficacia y eficiencia.
- Seguimiento de versiones: Incorpora versionado semántico a tus proyectos de scripts para facilitar el seguimiento de las versiones.
- Convenciones de nomenclatura: Borra las convenciones de nomenclatura de tus scripts (por ejemplo:
customername_function_v1_3.py). - Evalúa y verifica el cumplimiento del Código. Utiliza paquetes de Python como
ruffyflake8para realizar comprobaciones de pelusa y formato. También puedes aprovechar las numerosas herramientas complementarias y extensiones disponibles para los editores de código más populares, a fin de obtener guías y ayuda para el formateo y la corrección del código. -
Asistentes de código de IA: existen muchas herramientas de código de IA gratuitas y de pago que puedes aprovechar para que te ayuden con la depuración y la optimización.
Nota: Aunque son útiles, los asistentes de código de IA no reemplazan los conocimientos y la experiencia necesarios para desarrollar scripts y automatizaciones avanzados.
Control de Versiones
- Tener una única fuente de confianza: Utiliza tu sistema de control de versiones como depósito central y única fuente de confianza para tus proyectos de programación. Confirma los cambios a menudo para asegurarte de que todo el trabajo de desarrollo y las pruebas más recientes se capturan y almacenan de forma centralizada.
- Documenta completamente los cambios: Añade tantos detalles e información de apoyo como sea posible en todos los commits y pull requests de tu sistema de control de versiones para documentar todos los cambios (quién hizo el cambio, qué es el cambio, por qué se hizo el cambio, etc.).
Mejores prácticas de flujo de trabajo
Al desarrollar, probar y desplegar scripts, seguir las mejores prácticas de flujo de trabajo ayudará a maximizar el rendimiento del script y a minimizar posibles errores e incidencias. Algunos de los principales pilares del flujo de trabajo de desarrollo incluyen:
- Realiza todo el desarrollo y las pruebas del script en tu entorno de desarrollo , no en tu entorno de producción.
- Transfiere tu script a un espacio de trabajo/área de preparación donde puedas probar tu script en Workiva.
IMPORTANTE: Utiliza datos que no sean de producción para tus pruebas. - Solo despliega tu script en tu espacio de trabajo de producción para su uso operativo después de que se haya probado correctamente.
Transferencia del Código a Workiva
Una vez que hayas completado el desarrollo principal y las pruebas y todo funcione como esperabas, puedes transferir tu código a Workiva. Aunque puedes enviar manualmente los cambios a Workiva desde el Editor de scripts de Workiva, te recomendamos encarecidamente que automatices el envío de tu código desde tu sistema de control de versiones a Workiva utilizando las API de scripts . Este es el proceso recomendado ya que la automatización ahorra tiempo y reduce los errores.
Ejecutando y supervisando scripts.
Los scripts pueden activarse directamente desde el Editor de scripts, desde Cadenas, desde las API de scripts o desde Automatizaciones integradas. Independientemente de cómo se activen tus scripts, te recomendamos que utilices el Editor de scripts para supervisar las ejecuciones y solucionar incidencias.
Iniciando sesión
El editor de scripts incluye una sección de "Registros"; recomendamos que tus scripts incorporen un registro detallado para proporcionar información detallada y exhaustiva sobre las operaciones del script. Esta información suele ser muy útil para depurar, supervisar y comprender las operaciones de tu script. El paquete estándar de Python logging es un ejemplo de utilidad de registro que puede establecerse para proporcionar información útil sobre las operaciones de script (por ejemplo: marca de tiempo, nivel de registro, mensaje, etc.). Asegúrate de utilizar los distintos niveles de registro (INFO, DEBUG, ERROR, etc.) e incluye mensajes de registro detallados y útiles.
Muchos usuarios avanzados también incluyen la funcionalidad de enviar registros a una hoja de cálculo Workiva designada en el mismo espacio de trabajo. Esto permite un acceso más fácil, un análisis más rápido y una consulta eficaz de los registros. He aquí un ejemplo de salida de registro a una hoja de cálculo Workiva (los ID de hoja y de hoja se han ofuscado):
Depurando y Agregando Nuevas Funciones
Si se produce alguna incidencia durante el funcionamiento de tu script, te recomendamos que realices la depuración y actualización en tu entorno de desarrollo, no en tu entorno de producción. Una vez que esas correcciones/actualizaciones estén terminadas, evaluadas y confirmadas en tu sistema de control de versiones, puedes enviar el script actualizado a Workiva de forma segura.
Este mismo flujo de trabajo debe utilizarse al añadir nuevas funciones a los scripts existentes: realiza todas las actualizaciones y pruebas en tu entorno de desarrollo. Una vez que todas las actualizaciones del script estén completas, probadas correctamente y confirmadas en tu sistema de control de versiones, puedes enviar el script actualizado a Workiva.