利用 Workiva 脚本和 API 可以显著简化操作和工作流程。与所有脚本项目一样，遵循代码开发和版本控制的最佳实践可以带来有效的项目管理、连续性和成功。
以下是一些关于 Workiva 脚本编写的技巧和窍门，可用于项目开发和工作流程。
Workiva脚本编辑器
Workiva 脚本编辑器旨在帮助将生产代码集成到 Workiva 中，监控生产运行，并在出现问题时进行初步故障排除。它不是一个 全面 的代码编辑器，我们也没有计划将其开发成一个全面的代码编辑器。
开发环境
如果您已经拥有企业开发环境和版本控制系统，我们建议您将其用于所有脚本开发和测试。
开发环境的关键组件包括 代码编辑 器（流行的例子包括 VSCode、 PyCharm、 Jupyter等）和 版本控制系统 （流行的例子包括 GitHub 和 GitLab） 。对于非工程师或不喜欢使用命令行界面的人来说，有一些轻量级工具，例如 GitHub Desktop 和 SourceTree ，可以简化版本控制系统中的工作。
如果您还没有开发环境，请考虑搭建一个。同时，请务必保存脚本副本（在任何更改/更新之前、期间和之后），并确保将脚本的开发/工作版本与生产版本分开，以减少意外覆盖。
脚本开发
在脚本项目的开发和测试过程中，请考虑遵循主流的 Python 和版本控制实践：
Python
尽可能遵循 PEP 8 - Python 代码风格指南 。代码一致性对可读性、可维护性和连续性都大有裨益。
要构建健壮、可靠且可扩展的生产级 Python 脚本，请务必关注以下关键领域：
- 身份验证： 有效地创建、管理和重新生成适当的持有者令牌可确保只有授权用户或系统才能访问工作区的资源、数据或功能。
- 模块化： 将大型脚本拆分成更小、独立和可重用的单元（函数、类、模块/文件）。这样一来，脚本就更容易阅读、测试、调试和长期维护。
- 日志记录： 包含详细的日志记录，以捕获关键事件和状态消息，这对于监控性能和排查任何问题至关重要。
-
错误处理： 添加错误处理逻辑，使脚本更加健壮、可靠和用户友好，能够优雅地处理意外情况，而不是崩溃。
注： 使用错误处理来解决 意外情况。不要依赖它来弥补或掩盖次优脚本设计带来的性能后果（例如，如果您的脚本生成大量 429/请求过多响应，则应重构脚本设计和工作流程以优化 API 调用，您不应依赖有效处理大量 429 来保证脚本成功）。
- 文档： 解释代码的功能以及如何使用它（内部通过注释和文档字符串，外部通过用户指南（README）），使其他开发人员和未来的您能够有效且高效地理解和修改脚本。
- 版本跟踪： 将 语义化版本控制 融入到您的脚本项目中，以帮助进行版本跟踪。
- 命名约定：为您的脚本使用清晰的命名约定（例如：
customername_function_v1_3.py）。 - 测试并验证代码合规性。使用 Python 包，例如
ruff和flake8来执行 lint 和格式检查。您还可以利用流行的代码编辑器提供的丰富插件工具和扩展程序，获取代码格式化和代码检查方面的指南和帮助。 -
AI 代码辅助： 有许多免费和付费的 AI 代码工具可供您使用，以帮助进行调试和优化。
注： 虽然人工智能代码助手很有帮助，但它们并不能取代开发高级脚本和自动化程序所需的知识和专业技能。
版本控制
- 拥有单一数据源： 使用版本控制系统作为脚本项目的中央存储库和单一数据源。经常提交更改，以确保所有最新的开发工作和测试都被捕获并集中存储。
- 完整记录更改： 在版本控制系统中的所有提交和拉取请求中尽可能添加详细信息和支持信息，以记录所有更改（谁进行了更改、更改了什么、为什么进行了更改等）。
工作流程最佳实践
在开发、测试和部署脚本时，遵循工作流程最佳实践将有助于最大限度地提高脚本性能，并最大限度地减少潜在的错误和问题。开发工作流程的一些主要支柱包括：
- 所有脚本开发和测试都应在 您的 开发环境中进行，而不是在您的生产环境中。
- 将您的脚本转移到暂存工作区/区域，您可以在 Workiva 上测试您的脚本。
重要提示： 请使用 非生产 环境数据进行测试。 - 只有在脚本经过成功测试后，才能将其部署到生产工作区以供运行使用。
将代码转移至 Workiva
一旦您的主要开发和测试完成，并且一切运行正常，您就可以将代码转移到 Workiva。虽然您可以从 Workiva 脚本编辑器手动将更改推送到 Workiva，但我们强烈建议 您使用 脚本API 将代码从版本控制系统 自动推送到 Workiva。这是推荐的流程 ，因为自动化可以节省时间并减少错误。
运行和监控脚本
脚本可以直接从脚本编辑器、链、脚本 API 或集成自动化中触发。无论脚本是如何触发的，我们都建议您使用脚本编辑器来监控运行情况并解决问题。
日志记录
脚本编辑器包含一个“日志”部分；我们建议您的脚本包含详细的日志记录，以便提供有关脚本操作的详细和全面的信息。这些信息对于调试、监控和了解脚本的运行情况通常非常有用。标准的 Python logging 包是一个日志记录实用程序的示例，可以进行设置以提供有关脚本操作的有用信息（例如：时间戳、日志级别、消息等）。请务必使用各种日志级别（INFO、DEBUG、ERROR 等），并包含详细且有用的日志消息。
许多高级用户还添加了将日志推送到同一工作区中指定的 Workiva 电子表格的功能。这样可以更方便地访问日志，更快地进行分析，并高效地查询日志。以下是 Workiva 电子表格的日志输出示例（电子表格和工作表 ID 已进行模糊处理）：
调试和添加新功能
如果在脚本运行过程中出现任何问题，我们建议您在开发环境中进行调试和更新，而不是在生产环境中进行调试和更新。一旦这些修复/更新完成、测试并提交到您的版本控制系统，您就可以安全地将更新后的脚本推送回 Workiva。
向现有脚本添加新功能时，也应采用相同的工作流程：在开发环境中执行所有更新和测试。所有脚本更新完成后，经过成功测试并提交到版本控制系统后，即可将更新后的脚本推送到 Workiva。