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