利用 Workiva 指令碼和 API 可以顯著簡化操作和工作流程。與所有指令碼專案一樣，遵循程式碼開發及版本控制的最佳做法，可達到有效的專案管理、連續性及成功(地)。
以下是一些 Workiva Scripting 專案開發和工作流程的提示和技巧。
Workiva 指令碼編輯者
建立 Workiva 指令碼編輯者是為了協助整合生產程式碼至 Workiva、監控生產執行，以及在問題發生時進行初步的故障排除。它是而非 一個全面的程式碼編輯者，我們也沒有計劃將它變成一個全面的程式碼編輯者。
開發環境
如果您已經擁有企業級的開發環境和版本控制系統，我們建議您使用該系統進行所有指令碼的開發和測試。
開發環境的主要分量包括程式碼編輯者 (流行的例子包括VSCode,PyCharm,Jupyter 等)，以及版本控制系統 (流行的例子包括GitHub 和GitLab)。對於非工程師或不喜歡在命令列介面工作的人，有一些輕量級的工具，例如GitHub Desktop 和SourceTree ，可以簡化版本控制系統中的工作。
如果您沒有開發環境，請考慮設定一個。在此期間，請務必儲存您的指令碼複製本（在任何變更/更新之前、期間及之後），並確保將您的指令碼開發/工作版本與生產版本分開保存，以減少意外覆寫。
指令碼開發
在指令碼專案的開發與測試期間，請考慮遵循領先的 Python 與版本控制項/控制措施：
Python
盡可能遵循PEP 8 - Python 程式碼樣式指南 。程式碼的一致性對於可讀性、可維護性和連續性有很大的好處。
若要建立穩健、可靠且可擴充的生產級 Python 指令碼，請務必聚焦處理以下關鍵領域： 資料鍵/金鑰：有效地建立、管理和再生適當的承載令牌，以確保只有授權使用者或系統才能存取工作區的資源、資料或功能：
- 驗證： 有效地建立、管理和再生適當的承載令牌，確保只有授權的使用者或系統才能存取/使用工作區的資源、資料或功能。
- 模組化： 將大型指令碼分解/中斷為較小、獨立且可重複使用的單元（函數、類別、模組/檔案）。這可讓指令碼更容易閱讀、測試、除錯，並隨時間進行維護。
- 記錄： 包括詳盡記錄，以捕捉關鍵事件和狀態資訊，這對於監控效能和排除任何問題都非常重要。
-
錯誤處理： 包括錯誤處理的邏輯，藉由優雅地處理意外狀況而非當機，使指令碼更穩健、可靠且對使用者更友善。
附註： 使用錯誤處理來處理意外情況 。不要從屬於參照它來補償或掩蓋次佳指令碼設計的效能後果 (例如，如果您的指令碼產生大量 429/Too Many Requests 回應，您的指令碼設計和工作流程應該重整以最佳化 API 呼叫，您不應該依賴有效處理大量 429 來取得指令碼的成功)。
- 說明文件： 說明程式碼的作用與使用方式（內部透過註解/評論/留言，外部則透過使用者指南 (READMEs)），讓其他開發人員與未來的您能有效率地理解並修改指令碼。
- 版本追蹤： 將semantic versioning 納入您的指令碼專案，以協助版本追蹤。
- 命名慣例： 為您的指令碼使用清楚的命名慣例 (例如:
customername_function_v1_3.py)。 - 測試並驗證程式碼是否合規/符合規範。使用 Python 套件，例如
ruff和flake8來執行 lint 和格式設定檢查。您也可以利用廣受歡迎的程式碼編輯者所提供的大量附加元件，以獲得程式碼格式設定和校驗的指南和協助。 -
AI 程式碼協助/說明： 有許多免費和付費的 AI 程式碼工具可供使用，您可以利用這些工具協助進行除錯和最佳化。
附註： 雖然人工智慧程式碼協助/說明很有幫助，但並不能取代開發進階指令碼與自動化所需的知識與專業。
版本控制/控制項/控制措施
- 擁有單一真實來源： 使用您的版本控制系統作為您指令碼專案的中央儲存庫和單一真實來源。經常提交變更，以確保所有最新的開發工作和測試都能被擷取並集中儲存。
- 完整說明變更文件： 在版本控制系統中的所有提交和拉取請求中，盡可能新增更多的細節和支持資訊，以記錄所有變更（誰做的變更、是什麼變更、為什麼做這個變更等）。
工作流程最佳做法
在開發、測試和部署指令碼時，遵循工作流程最佳做法將有助於最大化指令碼效能，並將潛在錯誤和問題降至最低。開發工作流程的一些主要支柱包括：
- 在您的開發 環境中進行所有指令碼開發及測試，而非您的生產環境。
- 將指令碼傳輸至暫存工作區/區域，以便在 Workiva 上測試您的指令碼。
重要提示： 使用非生產 資料進行測試。 - 只有在測試成功(地)後，才能將指令碼部署到您的生產工作區以供操作使用。
將程式碼轉移至 Workiva
一旦您的主要開發和測試完成，且一切運作符合預期，您就可以將程式碼傳輸到 Workiva。 雖然您可以從 Workiva Scripting 編輯者手動推送變更至 Workiva，我們強烈建議您使用Scripting APIs 自動化推送您的程式碼從版本控制系統至 Workiva 。這是推薦的流程 ，因為自動化可儲存時間並減少錯誤。
執行與監控指令碼
指令碼可直接從 Scripting Editor、Chains（自動化工作流程）、Scripting API 或 Integrated Automations 觸發程序。無論您的指令碼是如何觸發程序，我們都建議您使用 Scripting Editor 來監控執行情形並排除問題。
登入
指令碼編輯者包括一個「日誌」區段 (UI)/章節；我們建議您的指令碼加入詳盡的記錄，以提供有關指令碼運作的詳細且全面的資訊。這些資訊通常對於除錯、監控和瞭解您的指令碼作業非常有用。標準 Python記錄 套件是一個可以設定記錄公用程式的範例，以提供有關指令碼操作的有用資訊 (例如：時間戳記、記錄層級、訊息等)。確保利用各種記錄層級 (INFO、DEBUG、ERROR 等)，並包括詳細且有用的記錄訊息。
許多進階使用者還包括將記錄推送至同一工作區指定 Workiva 試算表的函數功能。這可讓您更輕鬆存取/使用記錄，加快分析速度並提高查詢效率。以下是日誌輸出至 Workiva 試算表的範例 (試算表和工作表 ID 已被混淆)：
調試和新增的功能
如果您的指令碼在執行過程中發生任何問題，我們建議您在開發環境而非生產環境中執行除錯與更新。一旦這些修正/更新完成、測試完成並提交至版本控制系統，您就可以安全地將更新後的指令碼推回 Workiva。
為現有指令碼新增新功能時，也應使用相同的工作流程：在開發環境中執行所有更新與測試。一旦所有指令碼更新完成、測試成功(地)，並提交至版本控制系統，即可將更新後的指令碼推送至 Workiva。