Import pracowników - API

Niezbędne środowisko

API systemu wiod.app jest zgodne ze standardem Rest API. Opis metod i parametrów jest dostępny w formacie Postman i można go pobrać logując się do systemu, z profilu firmy, na karcie API skąd również możemy wygenerować klucz API.

Wygenerowany klucz / token – ma takie same uprawnienia jak administrator systemu.

Do połączenia się poprzez API do systemu wiod.app można wykorzystać skrypty pisane w języku Python 3 oraz wszystkie inne, które wspierają komunikację za pomocą Rest API. Przy opisie importu użytkowników użyty zostanie język Python a instrukcja zawiera wszystkie niezbędne kroki, jakie trzeba wykonać na komputerze aby uruchomić narzędzie i dokonać importu.

UWAGA: Zdecydowanie zalecamy aby testy dotyczące API oraz prac z API były przeprowadzane na darmowych kontach – używając ich jako konta testowe. Po testach konto takie można usunąć z systemu wiod.app

Instalacja środowiska Python

Do pracy z API można wykorzystać istniejące środowisku w systemie Linux lub Windows, przy czym na potrzeby niniejszej instrukcji, zostanie pobrane i zainstalowane standardowe środowisko (program) Python 3 w aktualnej wersji. Do instalacji można wykorzystać uprawnienia administratora lub nie posiadając takich uprawnień, pobrać środowisko i po rozpakowaniu na pulpit użyć je do importu pracowników.

Krok 1: Pobranie środowiska ze strony producenta.

Na stronie https://www.python.org/downloads/windows/ pobieramy najnowszą wersję środowiska w zależności od możliwości albo w wersji instalacyjnej albo w wersji „przenośnej” w formacie archiwum ZIP.

W naszym przykładzie pobieramy paczkę Windows installer (64-bit), która standardowo pobierana jest do folderu Pobrane, a następnie instalujemy w kontekście administratora lub na zasoby lokalne użytkownika np. na Pulpit. Środowiska potrzebujemy tylko do instalacji użytkowników, stąd po wykorzystaniu skryptu program Python 3 można usunąć.

W oknie startowym proszę zaznaczyć: Add python.exe to PATH oraz wybrać opcję Instal Now:

Po tej operacji, nasz system Windows jest gotowy do uruchamiania skryptów napisanych w języku Python 3.

Krok 2: Pobranie skryptu

Przykładowy skrypt – przygotowany na potrzeby importu – został umieszczony pod  tym linkiem: import_users.py. Warto następnie utworzyć np. na Pulpicie osobny folder w którym będziemy wykonywać operację importu. Należy zatem przejść na Pulpit i utworzyć nowy folder np. „wiod.app” czy „Import„. W naszym przykładzie na pulpicie, został utworzony folder „wiod.app” i do niego został przegrany plik pobrany z linku powyżej:

Krok 3: Przygotowanie pliku importu

Nasz skrypt wymaga aby plik zawierający pracowników był przygotowany zgodnie z formatem csv jaki generowany jest przez Microsoft Excel. Wzór formatu zalecamy pobrać stąd: użytkownicy_wzór.xlsx Po uzupełnieniu pliku danymi,  należy go zapisać w formacie *.csv wybierając jako format zapisu „CSV ( rozdzielany przecinkami) (*.csv)” lub podobny.

Znaczenie pól jest tożsame z formularzem zakładania pracownika w systemie wiod.app, tj.:

• name – imię pracownika
• surname – nazwisko pracownika
• position – stanowisko
• contract_type_id – identyfikator rodzaju umowy (czytaj niżej)
• email – adres e-mail
• phone – telefon
• canLogin – czy pracownik może się logować true / false (sugerujemy wykonywać testy z opcją false)
• isInspector – czy pracownik jest inspektorem – w przypadku standardowych poracowników, zawsze = false
• notifications_enabled – czy włączone powiadomienia mailowe – sugerujemy przy imporcie ustawienie = false
• roles = identyfikator  roli (czytaj niżej)
• companies – identyfikator firmy do której pracownik ma prawa (czytaj niżej).

Skąd pobrać identyfikatory? Te numeryczne odpowiedniki ustawień, można pobrać z innych metod API ale dla naszego przykładu podamy informacje gdzie w systemie wiod.app można podejrzeć te numery, zaczynając od najłatwiejszych:

companies – identyfikator firmy do której pracownik ma prawa – jest w linku, widoczny w pasku przeglądarki, gdy wejdziemy do profilu firmy, do której chcemy dodać pracownika:

w powyższym przypadku = 161.

roles = identyfikator  roli – jest w linku, widoczny w pasku przeglądarki, gdy wejdziemy do ról firmy, do której chcemy dodać pracownika:

w powyższym przypadku = 2

contract_type_id – identyfikator rodzaju umowy – jest w linku, widoczny w pasku przeglądarki, gdy wejdziemy do menu Słowniki->Pracownik::Umowa::Typ (edytuj), wybierz odpowiedni wiersz z listy i z menu ponownie „Edytuj”,  tej firmy, do której chcemy dodać pracownika:

w powyższym przypadku = 16

Tak przygotowany plik, umieszczamy w przygotowanym folderze, u nas na Pulpicie w katalogu wiod.app:

Krok 4: Wygenerowanie tokenu

Aby uzyskać autoryzację za pomocą Rest API, po zalogowaniu się do systemu, przejdź do profilu firmy i w zakładce API, wygeneruj token:

Skopiuj ciąg znaków i zapisz go w jakimś notatniku, będzie nam potrzebny do wywołania skryptu.

Dla konta multi-IOD w każdej firmie do której mamy zamiar importować pracowników należy wygenerować token API. Tokeny są osobne dla każdego podmiotu.

Krok 5: Import

UWAGA: Import użytkowników oznacza dodawanie pracowników do systemu – w zależności zatem od ustawień – każdy z dodanych pracowników otrzyma wiadomość powitalną z systemu wiod.app. Aby nie wysyłać takiej wiadomości, można importując użytkowników ustawić im w pliku importu (Excel powyżej) parametr notifications_enabled na wartość „false”.

Wywołanie skryptu następuje z konsoli, stąd albo uruchamiamy standardową konsolę – cmd.exe – systemu Windows i przechodzimy do naszego folderu, lub trzymając wciśnięty prawu klawisz „shift” klikamy na wolne pole w naszym folderze i wybieramy opcję „Otwórz tutaj okno programu PowerShell”

Widok konsoli – w szczególności kolory – mogą się różnic w zależności od komputera. Nie ma to znaczenia. W naszym przypadku korzystamy ze sposobu opisanego wyżej, stąd otworzyła nam się konsola Power Shell. Aby użyć naszego skryptu, musimy najpierw do środowiska Python dodać wymagane biblioteki, wydając w tym okienku polecenie:

pip install requests

Po wydaniu tego polecenia nastąpi instalacja niezbędnych zależności i możemy uruchomić skrypt poleceniem jak niżej, które wyświetli krótką pomoc na temat parametrów skryptu:

python .\import_users.py

Następnie możemy wydać to samo polecenie z parametrem -h aby uzyskać dokładną pomoc na temat użycia narzędzia importu:

python .\import_users.py -h

Nasz skrypt wymaga aby podać argumenty:

• plik csv, wygenerowany z Excel w którym są pracownicy do importu,
• adres serwera aplikacji czyli https://wiod.app,
• token – wygenerowany w panelu,
• hasło do swojego konta – uprzednio zakodowane w formacie base64.

Do zakodowania hasła możemy użyć dowolnego kodującego narzędzia, ale nasz skrypt został również do tego przygotowany, stąd jednorazowo uruchom skrypt podając swoje hasło do konta. Hasło jest niezbędne – gdyż nasz system szyfruje dane w bazach klientów za pomocą klucza generowanego z hasła (privacy by design) – stąd niezbędne jest jego przekazanie aby mogło dojść do skutecznego rozszyfrowania danych. Nie przechowujemy tych kluczy – gdyż z założenia naszej polityki – nie chcemy mieć technicznej możliwości dostępu do danych naszych klientów.

Uruchom polecenie, w cudzysłowy wpisując hasło do swojego konta, któe zostanie zakodowane do odpowiedniego formatu:

python .\import_users.py -b "TwojeTajneHaslo123#!"

W wyniku którego utrzymujemy ciąg znaków podobny do tego:

Zakodowane hasło Base64: TmFzemVUYWpuZUhhc2xvMTIzIyE=

Następnie uruchamiamy nasz skrypt z pełną listą atrybutów.

Sugerujemy aby dla testu dokonać importu kilku pracowników oraz dokonać go na darmowym koncie – jako koncie testowym.

python .\import_users.py -f .\użytkownicy_wzór.csv -a https://wiod.app -t tu_wpisz_swój_token -p tu_wpisz_zakodowane_hasło

Gdy wszystkie podane atrybuty i plik z użytkownikami są prawidłowe – otrzymujemy w wyniku informację o założonych kontach:

Użytkownik założony: ID=496 (wiersz 1)
Użytkownik założony: ID=497 (wiersz 2)
Użytkownik założony: ID=498 (wiersz 3)

Podsumowanie:
Poprawnie założonych użytkowników: 3

W naszym przykładzie założyliśmy trzech pracowników.