Wykorzystanie skryptów i interfejsów API firmy Workiva może znacząco usprawnić operacje i przepływy pracy. Podobnie jak w przypadku wszystkich projektów skryptowych, stosowanie się do najlepszych praktyk w zakresie tworzenia kodu i kontroli wersji zapewnia efektywne zarządzanie projektem, ciągłość i sukces.
Poniżej znajdziesz kilka wskazówek i trików dotyczących skryptów Workiva, przydatnych przy tworzeniu projektów i przepływów pracy.
Edytor skryptów Workiva
Edytor skryptów Workiva został stworzony, aby pomóc w integracji kodu produkcyjnego z Workiva, monitorowaniu przebiegów produkcyjnych i początkowym rozwiązywaniu problemów, gdy się pojawią. To nie jest kompleksowy edytor kodu i nie planujemy, aby stał się nim w przyszłości.
Środowisko programistyczne
Jeśli dysponujesz już środowiskiem programistycznym dla przedsiębiorstw i systemem kontroli wersji, zalecamy korzystanie z nich przy tworzeniu i testowaniu skryptów.
Kluczowe elementy środowiska programistycznego obejmują Edytor kodu (popularne przykłady to VSCode, PyCharm, Jupyteritp.) i System kontroli wersji (popularne przykłady to GitHub i GitLab). Dla osób niebędących inżynierami lub tych, które wolą nie pracować w interfejsie wiersza poleceń, dostępne są lekkie narzędzia, takie jak GitHub Desktop i SourceTree, które mogą usprawnić pracę w systemach kontroli wersji.
Jeżeli nie posiadasz środowiska programistycznego, rozważ jego utworzenie. W międzyczasie pamiętaj o zapisywaniu kopii swoich skryptów (przed, w trakcie i po wszelkich zmianach/aktualizacjach) i pamiętaj o trzymaniu wersji roboczej/rozwojowej skryptów oddzielnie od wersji produkcyjnych, aby ograniczyć ryzyko przypadkowego nadpisania.
Rozwój skryptów
Podczas opracowywania i testowania projektów skryptowych należy wziąć pod uwagę następujące główne praktyki dotyczące języka Python i kontroli wersji:
Pyton
W miarę możliwości stosuj się do wytycznych PEP 8 - Style Guide for Python Code. Spójność kodu jest niezwykle korzystna dla czytelności, łatwości utrzymania i ciągłości kodu.
Aby tworzyć solidne, niezawodne i skalowalne skrypty Pythona na poziomie produkcyjnym, należy skupić się na kluczowych obszarach, takich jak:
- Uwierzytelnianie: Skuteczne tworzenie, zarządzanie i ponowne generowanie odpowiedniego tokena nośnika zapewnia, że tylko autoryzowani użytkownicy lub systemy mogą uzyskać dostęp do zasobów, danych lub funkcjonalności obszaru roboczego.
- Modułowość: Podziel duże skrypty na mniejsze, niezależne i wielokrotnego użytku jednostki (funkcje, klasy, moduły/pliki). Dzięki temu skrypt jest łatwiejszy do czytania, testowania, debugowania i konserwacji w dłuższej perspektywie.
- Rejestrowanie: Dołącz szczegółowe rejestrowanie w celu przechwytywania najważniejszych zdarzeń i komunikatów o stanie, co jest niezbędne do monitorowania wydajności i rozwiązywania problemów.
-
Obsługa błędów: Dodaj logikę obsługi błędów, aby skrypty były bardziej odporne, niezawodne i przyjazne dla użytkownika dzięki płynnemu zarządzaniu nieoczekiwanymi sytuacjami zamiast powodowania awarii.
Uwaga: Użyj obsługi błędów, aby poradzić sobie z nieoczekiwanymi sytuacjami. Nie należy na nim polegać w celu kompensacji lub maskowania konsekwencji wydajnościowych nieoptymalnego projektu skryptu (na przykład, jeśli skrypt generuje dużą liczbę odpowiedzi
429: Zbyt wiele żądań, projekt skryptu i przepływ pracy należy przebudować w celu zoptymalizowania wywołań API; nie należy polegać na efektywnym obsłudze dużej liczby odpowiedzi 429 dla powodzenia skryptu). - Dokumentacja: Wyjaśnia, co robi kod i jak go używać (zarówno wewnętrznie za pomocą komentarzy i docstringów, jak i zewnętrznie za pomocą podręczników użytkownika (README), umożliwiając innym programistom i przyszłym użytkownikom zrozumienie i skuteczną i wydajną modyfikację skryptu.
- Śledzenie wersji: Włącz wersjonowanie semantyczne do swoich projektów skryptowych, aby ułatwić śledzenie wersji.
- Konwencje nazewnictwa:Używaj jasnych konwencji nazewnictwa dla swoich skryptów (na przykład:
customername_function_v1_3.py). - Testowanie i weryfikacja zgodności kodu. Użyj pakietów Pythona, takich jak
ruffiflake8, aby wykonać kontrolę lint i formatowania. Można również wykorzystać rozbudowaną gamę dodatkowych narzędzi i rozszerzeń dostępnych dla popularnych edytorów kodu, które stanowią przewodniki i pomoc w formatowaniu i analizowaniu kodu. -
Pomoc w kodzie AI: dostępnych jest wiele darmowych i płatnych narzędzi do kodowania AI, z których możesz skorzystać, aby uzyskać pomoc w debugowaniu i optymalizacji.
Uwaga: Choć pomocni są asystenci kodu AI, nie zastępują oni wiedzy i doświadczenia niezbędnych do tworzenia zaawansowanych skryptów i automatyzacji.
Kontrola wersji
- Korzystaj z jednego źródła prawdy: Używaj swojego systemu kontroli wersji jako centralnego repozytorium i jednego źródła prawdy dla swoich projektów skryptowych. Często zatwierdzaj zmiany, aby mieć pewność, że wszystkie najnowsze prace rozwojowe i testowe zostaną przechwycone i centralnie zapisane.
- Dokładnie udokumentuj zmiany: Dodaj jak najwięcej szczegółów i informacji pomocniczych do wszystkich zatwierdzeń i żądań ściągnięcia w systemie kontroli wersji, aby udokumentować wszystkie zmiany (kto wprowadził zmianę, na czym ona polega, dlaczego została wprowadzona itp.).
Najlepsze praktyki dotyczące przepływu pracy
Podczas opracowywania, testowania i wdrażania skryptów przestrzeganie najlepszych praktyk przepływu pracy pomoże zmaksymalizować wydajność skryptów i zminimalizować potencjalne błędy i problemy. Oto niektóre z głównych filarów procesu prac rozwojowych:
- Wszystkie prace nad tworzeniem skryptów i testy wykonuj w środowisku programistycznym, a nie produkcyjnym.
- Przenieś swój skrypt do tymczasowej przestrzeni roboczej, w której będziesz mógł go przetestować w Workiva.
WAŻNE : Do testów należy używać danych niepochodzących z produkcji . - Wdróż skrypt do produkcyjnego obszaru roboczego dopiero po pomyślnym przetestowaniu.
Przenoszenie kodu do Workiva
Gdy główne etapy rozwoju i testowania zostaną ukończone i wszystko będzie działać zgodnie z oczekiwaniami, możesz przenieść swój kod do Workiva. Chociaż możesz ręcznie przesyłać zmiany do Workiva z poziomu edytora skryptów Workiva, zdecydowanie zalecamy zautomatyzowanie przesyłania kodu z systemu kontroli wersji do Workiva przy użyciu interfejsów API skryptów. Jest to zalecany proces, ponieważ automatyzacja oszczędza czas i zmniejsza liczbę błędów.
Uruchamianie i monitorowanie skryptów
Skrypty można uruchamiać bezpośrednio z Edytora skryptów, z Łańcuchów, z Interfejsów API skryptów lub ze Zintegrowanych automatyzacji. Niezależnie od sposobu uruchamiania skryptów, zalecamy korzystanie z Edytora skryptów do monitorowania uruchomień i rozwiązywania problemów.
Rejestrowanie
Edytor skryptów zawiera sekcję „Logi”; zalecamy, aby skrypty zawierały szczegółowe dzienniki w celu zapewnienia szczegółowych i kompleksowych informacji o działaniu skryptu. Informacje te są często bardzo przydatne przy debugowaniu, monitorowaniu i zrozumieniu działania skryptu. Standardowy pakiet Python logging jest przykładem narzędzia do rejestrowania zdarzeń, które można skonfigurować w celu dostarczania przydatnych informacji o operacjach skryptu (na przykład: znacznik czasu, poziom rejestrowania, komunikat itp.). Pamiętaj o wykorzystaniu różnych poziomów rejestrowania (INFO, DEBUG, ERROR itd.) i dołączeniu szczegółowych i przydatnych komunikatów.
Wielu zaawansowanych użytkowników uwzględnia również funkcjonalność umożliwiającą przesyłanie dzienników do wyznaczonego arkusza kalkulacyjnego Workiva w tym samym obszarze roboczym. Umożliwia to łatwiejszy dostęp, szybszą analizę i efektywne przeszukiwanie dzienników. Poniżej znajduje się przykład danych wyjściowych dziennika do arkusza kalkulacyjnego Workiva (identyfikatory arkusza kalkulacyjnego i arkusza zostały zaciemnione):
Debugowanie i dodawanie nowych funkcji
Jeżeli w trakcie działania skryptu wystąpią jakiekolwiek problemy, zalecamy przeprowadzenie debugowania i aktualizacji w środowisku programistycznym, a nie produkcyjnym. Gdy poprawki/aktualizacje zostaną ukończone, przetestowane i zatwierdzone w systemie kontroli wersji, możesz bezpiecznie przesłać zaktualizowany skrypt z powrotem do Workiva.
Ten sam przepływ pracy należy zastosować podczas dodawania nowych funkcji do istniejących skryptów: wszystkie aktualizacje i testy należy wykonywać w środowisku programistycznym. Gdy wszystkie aktualizacje skryptu zostaną ukończone, pomyślnie przetestowane i zatwierdzone w systemie kontroli wersji, możesz przesłać zaktualizowany skrypt do Workiva.