Wykorzystanie skryptów Workiva i interfejsów API może znacznie usprawnić operacje i przepływy pracy. Podobnie jak w przypadku wszystkich projektów skryptowych, przestrzeganie najlepszych praktyk w zakresie tworzenia kodu i kontroli wersji skutkuje skutecznym zarządzaniem projektem, ciągłością i sukcesem.
Poniżej znajdziesz kilka porad i wskazówek dotyczących tworzenia skryptów w Workiva dla rozwoju 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 przebiegu produkcji i wstępnym rozwiązywaniu problemów w przypadku ich wystąpienia. Nie jest to wszechstronny edytor kodu i nie planujemy go nim uczynić.
Środowisko programistyczne
Jeśli masz już środowisko programistyczne i system kontroli wersji, zalecamy korzystanie z niego do tworzenia i testowania skryptów.
Kluczowe komponenty środowiska programistycznego obejmują edytor kodu (popularne przykłady to VSCode, PyCharm, Jupyter, itp.) oraz system kontroli wersji (popularne przykłady to GitHub i GitLab). Dla osób niebędących inżynierami lub tych, którzy 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śli nie masz ś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 upewnij się, że przechowujesz wersje rozwojowe/robocze swoich skryptów oddzielnie od wersji produkcyjnych, aby ograniczyć przypadkowe nadpisania.
Tworzenie skryptów
Podczas opracowywania i testowania projektów skryptowych rozważ przestrzeganie wiodących praktyk Pythona i kontroli wersji:
Python
W miarę możliwości postępuj zgodnie z PEP 8 - Style Guide for Python Code. Spójność kodu jest bardzo korzystna dla czytelności, łatwości konserwacji i ciągłości.
Aby tworzyć solidne, niezawodne i skalowalne skrypty Python na poziomie produkcyjnym, skup się na kluczowych obszarach, w tym:
- Uwierzytelnianie: Skuteczne tworzenie, zarządzanie i regeneracja odpowiedniego tokena na okaziciela zapewnia, że tylko autoryzowani użytkownicy lub systemy mogą uzyskać dostęp do zasobów, danych lub funkcji obszaru roboczego.
- Modułowość: Podziel duże skrypty na mniejsze, niezależne jednostki wielokrotnego użytku (funkcje, klasy, moduły/pliki). Dzięki temu skrypt jest łatwiejszy do odczytania, przetestowania, debugowania i utrzymania w czasie.
- Rejestrowanie: Uwzględnij szczegółowe rejestrowanie w celu przechwytywania kluczowych zdarzeń i komunikatów o stanie, co jest niezbędne do monitorowania wydajności i rozwiązywania wszelkich problemów.
-
Obsługa błędów: Uwzględnij logikę obsługi błędów, aby skrypty były bardziej solidne, niezawodne i przyjazne dla użytkownika, z wdziękiem radząc sobie z nieoczekiwanymi sytuacjami zamiast się zawieszać.
Uwaga: Użyj obsługi błędów, aby rozwiązać nieoczekiwane sytuacje. Nie polegaj na nim, aby zrekompensować lub zamaskować konsekwencje wydajności nieoptymalnego projektu skryptu (na przykład, jeśli twój skrypt generuje dużą liczbę odpowiedzi 429/Too Many Requests, projekt skryptu i przepływ pracy powinny zostać zrefaktoryzowane w celu optymalizacji wywołań API, nie powinieneś polegać na skutecznej obsłudze dużej liczby 429 dla powodzenia skryptu).
- Dokumentacja: Wyjaśnia, co robi kod i jak go używać (zarówno wewnętrznie poprzez komentarze i docstrings, jak i zewnętrznie poprzez podręczniki użytkownika (README), umożliwiając innym programistom i przyszłym użytkownikom skuteczne i wydajne zrozumienie i modyfikowanie skryptu.
- Śledzenie wersji: Włącz semantyczne wersjonowanie do swoich projektów skryptowych, aby pomóc w śledzeniu wersji.
- Konwencje nazewnictwa: Używaj jasnych konwencji nazewnictwa dla swoich skryptów (na przykład:
customername_function_v1_3.py). - Przetestuj i zweryfikuj zgodność z kodem. Użyj pakietów Pythona, takich jak
ruffiflake8, aby przeprowadzić kontrole lint i formatu. Możesz także skorzystać z rozbudowanych narzędzi dodatkowych i rozszerzeń dostępnych dla popularnych edytorów kodu, aby uzyskać przewodniki i pomoc w formatowaniu kodu i lintingu. -
Pomoc w kodzie AI: dostępnych jest wiele darmowych i płatnych narzędzi kodu AI, które możesz wykorzystać do pomocy w debugowaniu i optymalizacji.
Uwaga: Asystenci kodu AI, choć pomocni, nie zastępują wiedzy i doświadczenia wymaganego do tworzenia zaawansowanych skryptów i automatyzacji.
Kontrola wersji
- Korzystaj z jednego źródła prawdy: Używaj systemu kontroli wersji jako centralnego repozytorium i jednego źródła prawdy dla swoich projektów skryptowych. Często zatwierdzaj zmiany, aby upewnić się, że wszystkie najnowsze prace rozwojowe i testy są przechwytywane i przechowywane centralnie.
- W pełni dokumentuj zmiany: Dodaj jak najwięcej szczegółów i informacji pomocniczych do wszystkich commitów i pull requestów w systemie kontroli wersji, aby udokumentować wszystkie zmiany (kto dokonał zmiany, jaka jest zmiana, dlaczego zmiana została wprowadzona itp.)
Najlepsze praktyki w zakresie przepływu pracy
Podczas opracowywania, testowania i wdrażania skryptów przestrzeganie najlepszych praktyk dotyczących przepływu pracy pomoże zmaksymalizować wydajność skryptów i zminimalizować potencjalne błędy i problemy. Niektóre z głównych filarów przepływu pracy deweloperskiej obejmują:
- Wszystkie czynności związane z tworzeniem i testowaniem skryptów przeprowadzaj w środowisku deweloperskim , a nie w środowisku produkcyjnym.
- Przenieś skrypt do obszaru roboczego, w którym możesz go przetestować w Workiva.
WAŻNE: Do testowania użyj nieprodukcyjnych danych . - Wdrażaj skrypt w produkcyjnym obszarze roboczym do użytku operacyjnego dopiero po jego pomyślnym przetestowaniu.
Przenoszenie kodu do Workiva
Po zakończeniu głównego rozwoju i testowania, gdy wszystko działa zgodnie z oczekiwaniami, możesz przenieść swój kod do Workiva. Chociaż możesz ręcznie przesyłać zmiany do Workiva z 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 mogą być uruchamiane 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 przebiegu i rozwiązywania problemów.
Rejestrowanie
Edytor skryptów zawiera sekcję "Dzienniki"; zalecamy, aby twoje skrypty zawierały szczegółowe dzienniki, aby zapewnić szczegółowe i kompleksowe informacje o operacjach skryptu. Informacje te są często bardzo przydatne do debugowania, monitorowania i zrozumienia działania skryptu. Standardowy pakiet logowania Pythona jest przykładem narzędzia logowania, które można skonfigurować w celu dostarczania przydatnych informacji o operacjach skryptu (na przykład: znacznik czasu, poziom logowania, komunikat itp.) Upewnij się, że korzystasz z różnych poziomów dziennika (INFO, DEBUG, ERROR itp.) i dołączasz szczegółowe i przydatne komunikaty dziennika.
Wielu zaawansowanych użytkowników korzysta również z funkcji przesyłania dzienników do wyznaczonego arkusza kalkulacyjnego Workiva w tym samym obszarze roboczym. Pozwala to na łatwiejszy dostęp, szybszą analizę i wydajne wysyłanie zapytań do dzienników. Oto przykład danych wyjściowych dziennika do arkusza kalkulacyjnego Workiva (identyfikatory arkusza kalkulacyjnego i arkusza zostały zaciemnione):
Debugowanie i dodawanie nowych funkcji
Jeśli podczas działania skryptu wystąpią jakiekolwiek problemy, zalecamy przeprowadzenie debugowania i aktualizacji w środowisku programistycznym, a nie produkcyjnym. Gdy te 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 powinien być stosowany podczas dodawania nowych funkcji do istniejących skryptów: wykonuj wszystkie aktualizacje i testy w środowisku programistycznym. Gdy wszystkie aktualizacje skryptów zostaną ukończone, pomyślnie przetestowane i zatwierdzone w systemie kontroli wersji, możesz przesłać zaktualizowany skrypt do Workiva.