Leveraging Workiva Scripting and APIs can significantly streamline operations and workflows. As with all scripting projects, following best practices for code development and version control results in effective project management, continuity, and success.
Below are some Workiva Scripting tips and tricks for project development and workflows.
Workiva Scripting Editor
The Workiva Scripting Editor was created to assist with integrating production code into Workiva, monitoring production runs, and to do initial troubleshooting when issues arise. It is not a comprehensive code editor, and we have no plans to make it one.
Development Environment
If you already have an enterprise development environment and version control system, we recommend that you use that for all your scripting development and testing.
Key components of a development environment include a Code Editor (popular examples include VSCode, PyCharm, Jupyter, etc.), and a Version Control System (popular examples include GitHub and GitLab). For non-engineers or those who prefer not to work in a command line interface, there are lightweight tools such as GitHub Desktop and SourceTree that can streamline work in version control systems.
If you do not have a development environment, consider setting one up. In the meantime, make sure to save copies of your scripts (before, during, and after any changes/updates), and be sure that you keep the development/working versions of your scripts separate from the production versions to reduce accidental overwrites.
Scripting Development
During development and testing of scripting projects, consider following leading Python and version control practices:
Python
Follow PEP 8 - Style Guide for Python Code as much as possible. Code consistency is greatly beneficial for readability, maintainability, and continuity.
To build robust, reliable, and scalable production-level Python scripts, make sure to focus on key areas including:
- Authentication: Effectively creating, managing, and regenerating the appropriate bearer token ensures that only authorized users or systems can access the workspace’s resources, data, or functionality.
- Modularity: Break large scripts into smaller, independent, and reusable units (functions, classes, modules/files). This makes the script easier to read, test, debug, and maintain over time.
- Logging: Include verbose logging to capture key events and status messages, which is vital for monitoring performance and troubleshooting any issues.
-
Error handling: Include logic for error handling to make scripts more robust, reliable, and user-friendly by gracefully managing unexpected situations instead of crashing.
Note: Use error handling to address unexpected situations. Do not depend on it to compensate for, or mask the performance consequences of, a suboptimal script design (for example, if your script generates a large number of 429/Too Many Requests responses, your script design and workflow should be refactored to optimize API calls, you should not rely on effective handling of large numbers of 429s for script success).
- Documentation: Explains what the code does and how to use it (both internally via comments and docstrings and externally via user guides (READMEs), enabling other developers and future you to understand and modify the script effectively and efficiently.
- Version tracking: Incorporate semantic versioning into your scripting projects to assist with version tracking.
-
Naming conventions: Use clear naming conventions for your scripts (for example:
customername_function_v1_3.py). -
Test and verify code compliance. Use Python packages such as
ruffandflake8to perform lint and format checks. You can also leverage the extensive add-on tools and extensions available for popular code editors for guides and assistance with code formatting and linting. -
AI code assistance: there are many free and paid AI code tools available that you can leverage to help with debugging and optimization.
Note: While helpful, AI code assistants do not replace the knowledge and expertise required to develop advanced scripts and automations.
Version Control
- Have a single source of truth: Use your version control system as the central repository and single source of truth for your scripting projects. Commit changes often to ensure all of the latest development work and testing is captured and centrally stored.
- Fully document changes: Add as much detail and supporting information as possible in all commits and pull requests in your version control system to document all changes (who made the change, what is the change, why the change was made, etc.).
Workflow Best Practices
When developing, testing, and deploying scripts, following workflow best practices will help maximize script performance and minimize potential errors and issues. Some of the main pillars of the development workflow include:
- Conduct all script development and testing in your development environment, not your production environment.
- Transfer your script to a staging workspace/area where you can test your script on Workiva.
IMPORTANT: Use non-production data for your testing. - Only deploy your script to your production workspace for operational use after it has been successfully tested.
Transferring Code to Workiva
Once your main development and testing are complete and everything works as expected, you can transfer your code to Workiva. While you can manually push changes to Workiva from the Workiva Scripting Editor, we strongly recommend that you automate pushing your code from your version control system to Workiva using the Scripting APIs. This is the recommended process as the automation saves time and reduces errors.
Running and Monitoring Scripts
Scripts can be triggered directly from the Scripting Editor, from Chains, from the Scripting APIs, or from Integrated Automations. Regardless of how your scripts are triggered, we recommend that you use the Scripting Editor to monitor runs and to troubleshoot issues.
Logging
The Scripting Editor includes a “Logs” section; we recommend that your scripts incorporate verbose logging to provide detailed and comprehensive information about the script’s operations. This information is often very useful for debugging, monitoring, and understanding your script's operations. The standard Python logging package is an example of a logging utility that can be set up to provide useful information about script operations (for example: timestamp, log level, message, etc.). Make sure to utilize the various log levels (INFO, DEBUG, ERROR, etc.) and include detailed and useful log messages.
Many advanced users also include functionality to push logs to a designated Workiva spreadsheet in the same workspace. This allows for easier access, faster analysis, and efficient querying of logs. Here is an example of a log output to a Workiva spreadsheet (spreadsheet and sheet IDs have been obfuscated):
Debugging and Adding New Features
If any issues occur during your script’s operations, we recommend you perform debugging and updating in your development environment, not your production environment. Once those fixes/updates are finished, tested, and committed to your version control system, you can then safely push the updated script back to Workiva.
This same workflow should be used when adding new features to existing scripts: perform all updates and testing in your development environment. Once all script updates are complete, successfully tested, and committed to your version control system, you can push the updated script to Workiva.