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 te ayuda a gestionar el código en Workiva, ejecutar scripts, supervisar las ejecuciones en producción y resolver problemas. Para tareas avanzadas de desarrollo, pruebas, análisis de código, depuración y control de versiones, utiliza un entorno de desarrollo específico.
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 : Utiliza una autorización de API para solicitar tokens de acceso de corta duración para las API de Workiva. Concede únicamente los ámbitos que requiera la integración, protege el ID y el secreto del cliente, y nunca almacenes las credenciales en los registros. Para obtener instrucciones, consulta Configuración de la API de Workiva .
- 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.
- Registro: Incluye registros útiles y estructurados para registrar eventos importantes, cambios de estado, advertencias y errores. Nunca registres credenciales, tokens de acceso, datos de entrada en tiempo de ejecución ni otra información confidencial.
-
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 confíes en que esto compense o enmascare las consecuencias en 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 rediseñarse para optimizar las llamadas a la API; no debes basarte en la gestión eficaz de un gran número de respuestas 429 para que el script funcione correctamente). - 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 el desarrollo inicial y las pruebas unitarias en tu entorno de desarrollo.
- Transfiere el script a un espacio de trabajo de prueba u otra área controlada para realizar pruebas de integración en Workiva. Utiliza datos que no sean de producción.
- Implementa el script en el entorno de producción solo una vez que se hayan completado las pruebas.
Transferencia del Código a Workiva
Una vez finalizados el desarrollo y las pruebas, transfiere el código a Workiva. Puedes actualizar las fuentes manualmente en el Editor de scripts, pero te recomendamos encarecidamente que automatices la implementación desde tu sistema de control de versiones mediante la API de scripts de Workiva. La implementación automatizada ahorra tiempo, reduce los errores manuales y ayuda a mantener Workiva sincronizado con tu código fuente bajo control de versiones.
La implementación automatizada de fuentes requiere una autorización de API con el ámbito «script:write » de . Si la implementación también recupera o verifica fuentes, requiere el script « :read» . Envía X-Version: 2026-01-01 con cada solicitud de API. Para obtener instrucciones sobre la concesión, consulta Configuración de la API de Workiva . Para conocer las operaciones compatibles, consulta la guía de la API de scripting de « » en .
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 titulada « » (Registros de ). Recomendamos encarecidamente que tus scripts utilicen un registro detallado y estructurado para registrar operaciones importantes, cambios de estado, advertencias y errores. Un buen registro es esencial para supervisar el rendimiento, resolver problemas y comprender el comportamiento de los scripts.
El paquete estándar de Python para el registro de eventos puede incluir información útil, como marcas de tiempo, niveles de registro y mensajes. Utiliza los niveles adecuados, como DEBUG , INFO , WARNING y ERROR , para controlar la cantidad de información generada. No registres credenciales, tokens de acceso, datos de entrada en tiempo de ejecución ni otra información confidencial.
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.