Scenariusz "Integracja Business Central i HCM & LMS"
Extension — SMART Payroll and SMART HCM & LMS Connector (dodatek do SMART Payroll)
W systemie istnieje możliwość skonfigurowania integracji między Business Central a SMART HCM & LMS (Human Capital Management & Learning Management System). Integracja zapewnia automatyczną synchronizację danych kadrowych i płacowych między dwoma systemami.
Główne możliwości:
- synchronizacja struktury organizacyjnej (wydziały, zawody, pozycje, kategorie pracowników)
- synchronizacja danych osób oraz umów z wierszami
- synchronizacja przyczyn nieobecności oraz grup aktywności czasowej
- przesyłanie list płac oraz statusów ewidencji czasu pracy
- pobieranie wniosków o nieobecność z HCM & LMS do Business Central
- obsługa osób międzyfirmowych (cross-company)
Synchronizacja działa w modelu zdarzeniowym: przy zmianie danych w Business Central automatycznie tworzony jest wpis w kolejce integracji, który następnie jest przetwarzany przez kolejkę zadań i wysyłany do HCM & LMS.
Etap 1: Konfiguracja integracji
Ścieżka: HCM & LMS Setup
Na stronie konfiguracji dostępne są następujące bloki pól:
Blok «Ogólne»
| Pole | Opis | Zależności i szczegóły |
|---|---|---|
| HCM Company Id | Identyfikator (GUID) firmy w systemie HCM & LMS. Używany jako AccountId we wszystkich zapytaniach integracji. | Wypełniany automatycznie przy pierwszym otwarciu strony konfiguracji (pobierany z Company.Id). Wymagane do aktywacji. |
| HCM Company Code | Kod firmy w systemie HCM & LMS. | Wymagane do aktywacji. Używany przy tworzeniu wpisu firmy w HCM. Przy usunięciu wartości — kolejka integracji jest czyszczona. |
| Active | Włącza lub wyłącza wymianę danych między systemami. | Przy pierwszej aktywacji system automatycznie generuje początkowe wpisy integracji dla wszystkich encji (szczegóły w Etapie 2). Do aktywacji muszą być wypełnione: HCM Company Id, HCM Company Code, HCM User ID. |
| Integration Token | Token autoryzacji dla API HCM & LMS. | Przechowywany w polu zabezpieczonym (zamaskowanym). Przypisywany indywidualnie. |
| Integration URL | Bazowy adres URL API HCM & LMS. | Nie należy dołączać ścieżek /create, /update, /delete — są dodawane automatycznie. Przypisywany indywidualnie. |
| Restore Integration Func. | Automatyczne przywracanie kolejki zadań integracji przy nieoczekiwanym zatrzymaniu. | Jeśli włączone, system automatycznie restartuje kolejkę zadań przy logowaniu użytkownika, gdy kolejka zatrzymała się z powodu błędu. |
Blok «Administracja»
| Pole | Opis | Zależności i szczegóły |
|---|---|---|
| Default Taxpayer Document Type | Domyślny typ dokumentu tożsamości. Używany do przesyłania danych paszportowych osób. | Zależy od słownika «Typy dokumentów osób» (SMA Person Document Type). Jeśli wypełnione — przy synchronizacji osoby przesyłane są seria, numer, data wydania oraz organ wydający dokumentu wskazanego typu. |
| HCM User ID | Kod użytkownika Business Central, którego zmiany NIE są synchronizowane do HCM. | Zależy od tabeli Users. Wymagane do aktywacji. Używany do zapobiegania pętlom synchronizacji — zmiany wprowadzone przez tego użytkownika (np. ze strony HCM) nie tworzą wpisów integracji. |
| API TimeZone | Strefa czasowa Windows do formatowania dat i czasu w zapytaniach. | Na przykład: «Central European Standard Time» dla Warszawy. |
| Enable Payroll Documents | Czy synchronizować listy płac do HCM & LMS. | Domyślnie włączone. Jeśli wyłączone — listy płac nie są przesyłane. |
| Enable Between Payroll Docs | Czy uwzględniać międzyokresowe listy płac w synchronizacji. | Domyślnie włączone. Działa razem z Enable Payroll Documents. |
| Enable Employee Timesheet | Czy synchronizować statusy ewidencji czasu pracy do HCM & LMS. | Domyślnie włączone. Przesyłane są tylko ewidencje ze statusem «Wydane». |
Blok «Filtry»
| Pole | Opis | Zależności i szczegóły |
|---|---|---|
| Labor Contract Filter | Filtr dla tabeli «Umowa». | Ogranicza, które umowy są synchronizowane do HCM. Edytowany przez AssistEdit — otwiera się konstruktor filtrów. Jeśli pusty — synchronizowane są wszystkie umowy. |
| Position Filter | Filtr dla tabeli «Pozycja». | Ogranicza, które pozycje są synchronizowane do HCM. Edytowany przez AssistEdit. Domyślnie pozycje ze statusem «Planowana» oraz pozycje budżetowe nie są synchronizowane. |
Blok «Portal»
| Pole | Opis | Zależności i szczegóły |
|---|---|---|
| Paid Leave Group Code | Kod grupy aktywności czasowej dla urlopów płatnych. | Zależy od słownika «Grupy aktywności czasowej» (SMA Time Activity Group). Używany do obliczania dni ewidencji czasu pracy na portalu HCM. |
| Unpaid Leave Group Code | Kod grupy aktywności czasowej dla urlopów bezpłatnych. | Zależy od słownika «Grupy aktywności czasowej». |
| Sick Leave Group Code | Kod grupy aktywności czasowej dla zwolnień lekarskich. | Zależy od słownika «Grupy aktywności czasowej». |
| Other Leave Group Code | Kod grupy aktywności czasowej dla innych typów nieobecności. | Zależy od słownika «Grupy aktywności czasowej». |
Etap 2: Aktywacja integracji
Przy ustawieniu pola Active = Tak, system automatycznie tworzy początkowe wpisy integracji do przesłania wszystkich bieżących danych do HCM & LMS. Wpisy tworzone są w następującej kolejności:
- Informacja o organizacji — tworzony jest jeden wpis dla bieżącej firmy
- Zawody (słownik Job Titles) — wszystkie zawody
- Kategorie pracowników (Employee Categories) — wszystkie kategorie
- Przyczyny nieobecności (Causes of Absence) — tylko te, w których włączony jest znacznik «Export to HCM»
- Wydziały (Organizational Units) — wszystkie wydziały
- Grupy aktywności czasowej (Time Activity Groups) — tylko te, w których włączony jest znacznik «Export to HCM»
- Osoby (Persons) — tylko te, w których pole «Firma główna HCM» jest puste
- Pozycje (Positions) — z uwzględnieniem filtra Position Filter, z wyłączeniem pozycji ze statusem «Planowana» oraz pozycji budżetowych
- Umowy (Labor Contracts) — z uwzględnieniem filtra Labor Contract Filter, tylko z wypełnionym numerem pracownika. Dla każdej umowy tworzone są również:
- wiersze umowy (zatwierdzone)
- listy płac (jeśli Enable Payroll Documents jest włączone, za ostatni rok)
- statusy ewidencji czasu pracy (jeśli Enable Employee Timesheet jest włączone, tylko ze statusem «Wydane»)
Uwaga: kolejność tworzenia jest istotna — słowniki (zawody, kategorie, przyczyny nieobecności, wydziały) tworzone są jako pierwsze, aby przy przetwarzaniu encji zależnych (pozycje, umowy) dane referencyjne były już w HCM & LMS.
Po aktywacji należy uruchomić kolejkę zadań (Job Queue) w celu faktycznego wysłania danych. Kolejka zadań tworzona jest automatycznie przy instalacji dodatku ze statusem «Wstrzymane» — należy ją aktywować ręcznie. Zalecany interwał: 1–5 minut.
Etap 3: Strony, między którymi zintegrowane są systemy
Poniżej przedstawiono mapowanie pól dla każdej encji podlegającej synchronizacji. Strzałka wskazuje kierunek przesyłania danych:
- → Business Central do HCM & LMS
- ← HCM & LMS do Business Central
- ↔ wymiana dwukierunkowa
Dla każdej encji wskazano, jakie zmiany pól w Business Central inicjują synchronizację oraz jakie operacje są obsługiwane (tworzenie, modyfikowanie, usuwanie).
3.1. Informacja o organizacji (Business Central) → Nazwa organizacji (HCM & LMS)
Operacje: modyfikowanie
Synchronizacja jest inicjowana przy zmianie dowolnego z pól: Nazwa, Adres, Telefon, Strona internetowa, E-mail.
| Pole Business Central | Pole HCM & LMS | Opis i zależności |
|---|---|---|
| — | id | Pobierany z HCM Company Id w konfiguracji |
| — | Code | Pobierany z HCM Company Code w konfiguracji |
| Nazwa (Name) | Nazwa organizacji (Name) | Nazwa firmy |
| Telefon (Phone No.) | Telefon (Telephone1) | Telefon firmy |
| Adres (Address) | Adres (Address) | Adres firmy |
| Strona internetowa (Home Page) | Strona internetowa (WebSiteUrl) | Strona główna firmy |
| Główna działalność (SMA Principal Activity) | Opis (Description) | Przesyłane tylko jeśli wypełnione |
| E-mail (E-Mail) | E-mail (Emailaddress1) | Adres e-mail firmy |
3.2. Zawody (Business Central) → Zawody (HCM & LMS)
Operacje: tworzenie, modyfikowanie, usuwanie
Synchronizacja jest inicjowana przy: tworzeniu, zmianie pól Nazwa lub Status, usuwaniu, zmianie kodu.
| Pole Business Central | Pole HCM & LMS | Opis i zależności |
|---|---|---|
| Kod (Code) | Kod (Code) | Kod zawodu |
| Nazwa (Name) | Nazwa (Name) | Nazwa zawodu |
| Status (Status) | Stan (State) | Jeśli Status = «Zamknięty» → «Inactive», w przeciwnym razie → «Active» |
3.3. Kategorie pracowników (Business Central) → Poziom stanowiska (HCM & LMS)
Operacje: tworzenie, modyfikowanie, usuwanie
Synchronizacja jest inicjowana przy: tworzeniu, zmianie pola Opis, usuwaniu, zmianie kodu.
| Pole Business Central | Pole HCM & LMS | Opis i zależności |
|---|---|---|
| Kod (Code) | Kod (Code) | Kod kategorii |
| Opis (Description) | Nazwa (Name) | Nazwa poziomu stanowiska |
3.4. Wydziały (Business Central) → Wydział (HCM & LMS)
Operacje: tworzenie, modyfikowanie, usuwanie
Synchronizacja jest inicjowana przy: tworzeniu, zmianie pól Nazwa, Pełna nazwa, Status, Kierownik, Wydział nadrzędny lub Data początkowa, usuwaniu.
| Pole Business Central | Pole HCM & LMS | Opis i zależności |
|---|---|---|
| Kod (Code) | Kod (Code) | Kod wydziału |
| Nazwa (Name) | Nazwa (Name) | Krótka nazwa wydziału |
| Pełna nazwa (Full Name) | Opis (Description) | Pełna nazwa wydziału |
| Kierownik (Manager No.) | Kierownik wydziału (HeadOfSubdivisionId) | Zależy od: Pracownik → Osoba. Przesyłany jest SystemId osoby kierownika. Dla osób międzyfirmowych używany jest SystemId z firmy głównej. |
| Pozycja kierownika | Pozycja kierownika (HeadOfSubdivisionPositionId) | Zależy od: Pracownik → Pozycja (SMA Position No.). Przesyłany jest SystemId pozycji kierownika. |
| Wydział nadrzędny (Parent Code) | Wydział główny (MainSubdivisionId) | Zależy od: wydział nadrzędny. Przesyłany jest SystemId wydziału nadrzędnego. |
| Data początkowa (Starting Date) | Data utworzenia (CreatedOn) | Data utworzenia wydziału |
| Status (Status) | Stan (State) | Jeśli Status = «Zamknięty» → «Inactive», w przeciwnym razie → «Active» |
3.5. Pozycje (Business Central) → Pozycje (HCM & LMS)
Operacje: tworzenie, modyfikowanie, usuwanie
Synchronizacja jest inicjowana przy: tworzeniu, zmianie kontrolowanych pól, usuwaniu. Pozycje z filtra Position Filter oraz ze statusem «Planowana» lub budżetowe nie są synchronizowane.
| Pole Business Central | Pole HCM & LMS | Opis i zależności |
|---|---|---|
| Numer (No.) | Kod (Code) | Numer pozycji |
| Zawód (Job Title Code) | Nazwa (Name) | Zależy od: słownik Zawody. Przesyłana jest nazwa zawodu (Job Title.Name). |
| Pracownik na pozycji | Pracownik (employeeId) | Określany automatycznie: wyszukiwany jest aktywny pracownik przypisany do tej pozycji przez umowę. Przesyłany jest SystemId osoby. Jeśli brak pracownika — null. |
| Data przypisania | Data przypisania (positionAssignmentDate) | Określana automatycznie: data rozpoczęcia ostatniego zatwierdzonego wiersza umowy dla tej pozycji. |
| Jest kierownikiem | Kierownik wydziału (IsHeadOfSubdivision) | Określane automatycznie: true, jeśli ten pracownik jest kierownikiem jakiegoś wydziału. |
| Data początkowa (Starting Date) | Data otwarcia pozycji (PositionOpeningDate) | Data otwarcia pozycji. Puste, jeśli nie wypełnione. |
| Data końcowa (Ending Date) | Data zamknięcia pozycji (PositionClosingDate) | Data zamknięcia pozycji. Puste, jeśli nie wypełnione. |
| Etat (Rate) | Ekwiwalent pełnego etatu (FullTimeEquivalency) | Etat pozycji (np. 1.0 lub 0.5) |
| Data zatwierdzenia (Approval Date) | Data zatwierdzenia (ApprovalDate) | Data zatwierdzenia pozycji. Puste, jeśli nie wypełnione. |
| Status (Status) | Status (Status) | Wartość tekstowa statusu |
| Status (Status) | Stan (State) | Jeśli Status = «Zamknięty» → «Inactive», w przeciwnym razie → «Active» |
| Zawód (Job Title Code) | Zawód (jobId) | Zależy od: słownik Zawody. Przesyłany jest SystemId zawodu. |
| Wydział (Org. Unit Code) | Wydział (SubdivisionId) | Zależy od: słownik Wydziały. Przesyłany jest SystemId wydziału. |
| Pozycja nadrzędna (Parent Position No.) | Pozycja kierownika (ManagerPositionId) | Zależy od: pozycja nadrzędna. Przesyłany jest SystemId pozycji nadrzędnej. |
| Wydział + Zawód | Profil stanowiska (jobProfileId) | Pole złożone: tworzone jako kombinacja SystemId wydziału i SystemId zawodu przez «/». |
3.6. Osoby (Business Central) → Pracownicy (HCM & LMS)
Operacje: tworzenie, modyfikowanie, usuwanie
Synchronizacja jest inicjowana przy: tworzeniu, zmianie pól (imię, nazwisko, drugie imię, płeć, data urodzenia, e-mail, telefony, NIP, stan cywilny), usuwaniu. Również inicjowana przy zmianie dokumentu osoby typu wskazanego w Default Taxpayer Document Type.
Interakcja międzyfirmowa: dlaczego jest potrzebna
W Business Central każda firma posiada własną, oddzielną kartę osoby fizycznej. Ta sama osoba (np. Jan Kowalski) może mieć kartę osoby w Firmie A i oddzielną kartę w Firmie B. To standardowe zachowanie BC — dane każdej firmy są izolowane.
W HCM & LMS natomiast istnieje jeden jedyny rekord pracownika na każdą osobę fizyczną — niezależnie od tego, w ilu firmach pracuje.
Dlatego konektor musi określić, z której firmy BC pobierać dane do synchronizacji każdej osoby fizycznej do HCM & LMS, oraz zapewnić, że wszystkie firmy odwołują się do tego samego rekordu w HCM & LMS.
Pole «Firma główna HCM» (SMAHCM Primary Company Name)
To kluczowe pole na karcie osoby fizycznej, które określa rolę tego rekordu w synchronizacji międzyfirmowej:
- Pusta wartość — ten rekord jest główny (źródłowy). Dane osoby fizycznej są wysyłane do HCM & LMS z tego rekordu.
- Wypełniona wartość (nazwa innej firmy) — ten rekord jest wtórny (kopia). Nie jest synchronizowany samodzielnie do HCM & LMS. Wartość wskazuje, w której firmie znajduje się główny rekord tej osoby.
Jak pole jest wypełniane automatycznie:
Przy tworzeniu lub zmianie karty osoby fizycznej system automatycznie szuka dopasowań we wszystkich firmach z aktywną integracją HCM & LMS:
- Wyszukiwanie po NIP + Data urodzenia: system sprawdza wszystkie inne firmy z aktywną integracją. Jeśli znajdzie osobę z takim samym NIP i datą urodzenia, gdzie pole «Firma główna HCM» jest puste (tzn. ta osoba jest główna w tamtej firmie) — bieżący rekord jest oznaczany jako wtórny (wypełniana jest nazwa tamtej firmy).
- Wyszukiwanie awaryjne po dokumencie osoby: jeśli NIP jest pusty, system szuka dopasowania po serii i numerze dokumentu osoby (oznaczonego jako dokument domyślny).
- Pierwsze dopasowanie wygrywa: jeśli dopasowanie znaleziono w kilku firmach, używane jest pierwsze znalezione.
Pole można również wypełnić ręcznie. Przy ręcznym ustawieniu system zaproponuje skopiowanie wszystkich danych z głównej karty osoby.
Na co wpływa pole «Firma główna HCM»:
- Synchronizacja osoby: tylko rekordy z pustym polem są wysyłane do HCM & LMS. Rekordy wtórne są pomijane.
- Podstawienie SystemId: gdy inne encje (umowy o pracę, wiersze umów, karty czasu, stanowiska, jednostki organizacyjne) odwołują się do wtórnej osoby, system automatycznie podstawia SystemId głównej osoby z firmy głównej. To zapewnia, że w HCM & LMS wszystkie odwołania prowadzą do jednego rekordu pracownika.
- Aktywacja integracji (Krok 2): przy początkowym tworzeniu rekordów integracji system pomija osoby z wypełnionym polem «Firma główna HCM».
Jak określany jest pracownik (Employee) dla osoby
W celu wypełnienia pól związanych z pracownikiem (numer pracownika, jednostka organizacyjna, stanowisko, profil stanowiska, data zatrudnienia) system szuka głównego pracownika we wszystkich firmach z aktywną integracją według następującego priorytetu:
- Główne miejsce pracy — najwyższy priorytet. Szukana jest zatwierdzona umowa o pracę z trybem pracy «Główne miejsce».
- Współpraca wewnętrzna — jeśli nie znaleziono głównego miejsca, szukana jest umowa z trybem «Współpraca wewnętrzna».
- Współpraca zewnętrzna — najniższy priorytet. Szukana jest umowa z trybem «Współpraca zewnętrzna».
Wyszukiwanie najpierw wykonywane jest w bieżącej firmie. Jeśli nie znaleziono — szukane jest w innych firmach, gdzie istnieje główny rekord tej osoby. Brane są pod uwagę tylko zatwierdzone umowy o pracę.
Źródło danych dla pól kontaktowych
- Dane osobowe (imię, nazwisko, data urodzenia, płeć, telefony, e-maile, NIP, stan cywilny, dane paszportowe) — pobierane są z głównego rekordu osoby (gdzie pole «Firma główna HCM» jest puste).
- Dane związane z pracownikiem (employeeId, subdivisionId, jobProfileId, employmentStartDate) — pobierane są od znalezionego głównego pracownika według priorytetu opisanego powyżej.
- Jeśli główny pracownik znajduje się w innej firmie niż główna osoba, system przełącza się na rekord osoby z firmy pracownika w celu uzyskania danych kontaktowych.
| Pole Business Central | Pole HCM & LMS | Opis i zależności |
|---|---|---|
| Kod (No.) | Kod (code) | Kod osoby |
| Nazwisko (Last Name) | Nazwisko (lastName) | Nazwisko |
| Imię (First Name) | Imię (firstName) | Imię |
| Drugie imię (Middle Name) | Drugie imię (middleName) | Drugie imię |
| Płeć (Gender) | Płeć (gender) | Mapowanie wartości: Mężczyzna → «Male», Kobieta → «Female», Niebinarna → «Nonbinarygenderdiverse», Samookreślona → «SelfDescribed», Nie chcę odpowiadać → «Idontwishtoanswer». Przesyłane tylko jeśli wypełnione. |
| Data urodzenia (Birth Date) | Data urodzenia (birthdate) | Data urodzenia w formacie RRRR-MM-DD |
| Data zatrudnienia (Employment Date) | Data rozpoczęcia pracy (employmentStartDate) | Zależy od: Pracownik (Employee). Data pierwszego zatrudnienia. Przesyłana tylko jeśli wypełnione. |
| E-mail firmowy (Company Email) | Email (email) | Firmowy adres e-mail |
| Telefon komórkowy (Mobile Phone No.) | Telefon komórkowy (mobilePhone) | Telefon komórkowy |
| Telefon (Phone No.) | Telefon (telephone) | Telefon osobisty |
| E-mail (E-Mail) | Osobisty e-mail (personalEmail) | Osobisty adres e-mail |
| Telefon firmowy (Company Phone No.) | Telefon firmowy (businessPhoneNo) | Telefon firmowy |
| Stan cywilny (Person Family Status) | Stan cywilny (maritalStatus) | Mapowanie wartości: Wolny/a → «Single», Rozwiedziony/a → «Divorced», Żonaty/Zamężna → «Married», Wdowiec/Wdowa → «Widowed», Związek partnerski → «CivilMarriage». Przesyłane tylko jeśli wypełnione. |
| NIP (VAT Registration No.) | NIP (VATRegistration) | Numer identyfikacji podatkowej. Pole wymagane. |
| Seria dokumentu | Seria paszportu (passportSeries) | Zależy od: pole Default Taxpayer Document Type w konfiguracji. Pobierane z dokumentu osoby wskazanego typu, ważnego na bieżącą datę. |
| Numer dokumentu | Numer paszportu (passportNumber) | Zależy od: pole Default Taxpayer Document Type w konfiguracji. |
| Data wydania dokumentu | Data wydania paszportu (passportIssueDate) | Zależy od: pole Default Taxpayer Document Type w konfiguracji. Przesyłane tylko jeśli wypełnione. |
| Organ wydający dokument | Organ wydający paszport (passportIssuedBy) | Zależy od: pole Default Taxpayer Document Type w konfiguracji. |
| Wydział pracownika | Wydział (subdivisionId) | Zależy od: Pracownik → Wydział. Przesyłany jest SystemId wydziału. |
| Wydział + Zawód pracownika | Profil stanowiska (jobProfileId) | Zależy od: Pracownik → Wydział + Zawód. Pole złożone. |
| Numer pracownika | Numer pracownika (employeeId) | Zależy od: wyszukiwanie głównego pracownika po umowach. Priorytet: miejsce główne → wewnętrzne łączenie → zewnętrzne łączenie. |
3.7. Umowy (Business Central) → Kontrakty (HCM & LMS)
Operacje: tworzenie, modyfikowanie, usuwanie
Synchronizacja jest inicjowana przy: tworzeniu, zmianie kontrolowanych pól, usuwaniu. Umowy filtrowane są przez filtr Labor Contract Filter w konfiguracji.
| Pole Business Central | Pole HCM & LMS | Opis i zależności |
|---|---|---|
| Numer umowy (No.) | Kod (Code) | Numer umowy |
| Numer + Imię i nazwisko | Nazwa (Name) | Tworzone automatycznie: numer umowy + pełne imię pracownika |
| Data początkowa (Starting Date) | Data początkowa (StartingDate) | Data rozpoczęcia obowiązywania umowy. Puste, jeśli nie wypełnione. |
| Data końcowa (Ending Date) | Data końcowa (EndingDate) | Data zakończenia obowiązywania umowy. Null, jeśli nie wypełnione (umowa na czas nieokreślony). |
| Osoba (Person No.) | Kontakt (ContactId) | Zależy od: osoba umowy. Przesyłany jest SystemId osoby. Dla osób międzyfirmowych używany jest SystemId z firmy głównej. |
| Numer pracownika (Employee No.) | Kod pracownika (EmployeeId) | Numer pracownika |
| Wydział pracownika | Wydział (SubdivisionId) | Zależy od: Pracownik → Wydział. Przesyłany jest SystemId wydziału. |
| Wydział + Zawód pracownika | Profil stanowiska (jobProfileId) | Zależy od: Pracownik → Wydział + Zawód. Pole złożone. |
| Typ umowy (Contract Type) | Typ współpracy (CooperationType) | Mapowanie wartości: Umowa cywilna → «Civil Contract», Umowa o pracę → «Labor Contract» |
| Tryb pracy (Work Mode) | Charakter pracy (Type) | Mapowanie wartości: Miejsce główne → «Main», Wewnętrzne łączenie → «internal cowork», Zewnętrzne łączenie → «external cowork» |
| Status (Status) | Stan (State) | Jeśli Status = «Zamknięty» → «Inactive», w przeciwnym razie → «Active» |
3.8. Wiersze umowy (Business Central) → Przypisanie na pozycję (HCM & LMS)
Operacje: tworzenie, modyfikowanie, usuwanie
Wiersze umowy zawierają informacje o operacjach kadrowych: Zatrudnienie, Łączenie, Przeniesienie, Zwolnienie.
Synchronizacja jest inicjowana przy: tworzeniu (zatwierdzeniu wiersza), zmianie, usuwaniu. Przy zatwierdzeniu wiersza aktualizowana jest również odpowiednia pozycja.
| Pole Business Central | Pole HCM & LMS | Opis i zależności |
|---|---|---|
| Nazwa wydziału pozycji | Nazwa (Name) | Zależy od: Pozycja → Wydział. Pobierana jest nazwa wydziału pozycji. |
| Pozycja (Position No.) | Pozycja (PositionId) | Zależy od: słownik Pozycje. Przesyłany jest SystemId pozycji. |
| Numer umowy (Contract No.) | Kontrakt (EmployeeContractId) | Zależy od: umowa. Przesyłany jest SystemId umowy. |
| Osoba (Person No.) | Kontakt (ContactId) | Zależy od: umowa → osoba. Przesyłany jest SystemId osoby. Dla osób międzyfirmowych — SystemId z firmy głównej. |
| Wydział pozycji | Wydział (SubdivisionId) | Zależy od: Pozycja → Wydział. Przesyłany jest SystemId wydziału. |
| Zawód pozycji | Zawód (JobId) | Zależy od: Pozycja → Zawód. Przesyłany jest SystemId zawodu. |
| Wydział + Zawód | Profil stanowiska (jobProfileId) | Pole złożone: SystemId wydziału + «/» + SystemId zawodu. |
| Data początkowa (Starting Date) | Data utworzenia (CreatedOn) | Data rozpoczęcia obowiązywania wiersza |
| Data początkowa (Starting Date) | Data przypisania (AssignmentDate) | Data przypisania na pozycję |
| Data końcowa (Ending Date) | Data zwolnienia (RemovedDate) | Data zakończenia wiersza. Jeśli puste — wyszukiwana jest data zakończenia z wpisu Employee Job Entry dla tej pozycji. |
| Pozycja główna | Pozycja główna (PrimaryPosition) | Określane automatycznie: true, jeśli tryb pracy = «Miejsce główne», typ operacji ≠ «Łączenie», i jest to ostatni zatwierdzony wiersz z najpóźniejszą datą rozpoczęcia. |
| Typ operacji (Operation Type) | Typ operacji (OperationType) | Wartość tekstowa typu operacji kadrowej (Zatrudnienie, Przeniesienie, Łączenie, Zwolnienie itp.) |
| Okres próbny | Na okresie próbnym (IsOnProbation) | Określane automatycznie: true, jeśli wypełnione są obie daty okresu próbnego (Trial Period Start Date i Trial Period End Date). |
| Wynagrodzenie | Wynagrodzenie (Salary) | Zależy od: warunki umowy (SMA Labor Contract Terms). Wyszukiwana jest kwota dla składników wynagrodzenia (wynagrodzenie/etat), określonych w konfiguracji Kadr (Element Code Salary Days, Salary Hours, Salary Amount, Hourly Rate, Daily Rate). |
| Waluta | Waluta (Currency) | Zależy od: waluta w warunkach umowy. Jeśli puste — pobierany jest kod waluty lokalnej z konfiguracji księgi głównej. Przesyłany jest kod ISO waluty. |
| Status (Status) | Status (Status) | Mapowanie: Otwarty → «Open», Zatwierdzony → «Approved» |
3.9. Przyczyny nieobecności (Business Central) → Przyczyny nieobecności (HCM & LMS)
Operacje: tworzenie, modyfikowanie, usuwanie
Uwaga: synchronizowane są tylko przyczyny nieobecności, w których włączony jest znacznik «Export to HCM» (SMA Export to HCM = Tak). Ten znacznik dodawany jest przez rozszerzenie konektora do standardowej tabeli «Przyczyny nieobecności» (Cause of Absence).
Synchronizacja jest inicjowana przy: tworzeniu, zmianie pól Opis, Opis szczeg ółowy, Typ aktywności czasowej lub znacznika Export to HCM, usuwaniu.
| Pole Business Central | Pole HCM & LMS | Opis i zależności |
|---|---|---|
| Kod (Code) | Kod (code) | Kod przyczyny nieobecności |
| Opis (Description) | Nazwa (name) | Nazwa przyczyny nieobecności |
| Opis szczegółowy (SMA Detailed Description) | Opis (description) | Rozszerzony opis przyczyny |
| Typ aktywności czasowej (SMA Time Activity Type) | Typ (type) | Wartość tekstowa typu |
| Grupa aktywności czasowej | Grupa (groupid) | Określane automatycznie: wyszukiwana jest grupa aktywności czasowej (ze znacznikiem Export to HCM), która zawiera ten kod nieobecności w swoich kodach filtrowania. Jeśli grupa nie zostanie znaleziona — wartość pusta. |
3.10. Grupy aktywności czasowej (Business Central) → Grupy nieobecności (HCM & LMS)
Operacje: tworzenie, modyfikowanie, usuwanie
Uwaga: synchronizowane są tylko grupy, w których włączony jest znacznik «Export to HCM» (SMA Export to HCM = Tak). Ten znacznik dodawany jest przez rozszerzenie konektora do tabeli «Grupy aktywności czasowej» (SMA Time Activity Group).
| Pole Business Central | Pole HCM & LMS | Opis i zależności |
|---|---|---|
| Opis (Description) | Nazwa (name) | Nazwa grupy nieobecności |
| Opis (Description) | Opis (description) | Duplikowane w polu opisu |
3.11. Wnioski o nieobecność (Business Central) ← Nieobecności (HCM & LMS)
Kierunek: HCM & LMS → Business Central
W Business Central tworzone są wnioski trzech typów: Wniosek urlopowy, Wniosek o delegację, Wniosek o inne nieobecności.
| Pole Business Central | Pole HCM & LMS | Opis i zależności |
|---|---|---|
| Kod | Kod | Tworzenie, modyfikowanie, usuwanie |
| Opis | Nazwa | Tworzenie, modyfikowanie, usuwanie |
| Kod aktywności czasowej | Kod nieobecności (Reason code) | Wypełnienie klucza obcego dla tego kodu jest wymagane. Tworzenie, modyfikowanie, usuwanie. |
| Grupa aktywności czasowej | Grupa aktywności czasowej | Wypełnienie klucza obcego dla tej grupy jest wymagane. Wybierany jest kod lub grupa. |
| Data wniosku | Data wniosku | Tworzenie, modyfikowanie, usuwanie |
| Data początkowa | Data początkowa | Tworzenie, modyfikowanie, usuwanie |
| Data końcowa | Data końcowa | Tworzenie, modyfikowanie, usuwanie |
| Dni kalendarzowe | Liczba dni | Tworzenie, modyfikowanie, usuwanie |
3.12. Wpisy naliczeń pracowniczych (Business Central) → Salda nieobecności (HCM & LMS)
Operacje: tworzenie
| Pole Business Central | Pole HCM & LMS | Opis i zależności |
|---|---|---|
| Na datę | Na datę | Data obliczenia salda |
| Kod aktywności czasowej | Kod nieobecności (Reason code) | Kod przyczyny nieobecności |
| Planowane dni kalendarzowe | Planowane dni kalendarzowe | Zaplanowane dni |
| Wykorzystanie dni kalendarzowych | Wykorzystanie dni kalendarzowych | Wykorzystane dni |
| Wyrównanie dni kalendarzowych | Wyrównanie dni kalendarzowych | Skompensowane dni |
| Saldo planowane dni kalendarzowe | Saldo planowane dni kalendarzowe | Planowane saldo |
| Saldo na datę | Saldo na datę | Faktyczne saldo na datę |
3.13. Listy płac (Business Central) → Dokumenty wypłat (HCM & LMS)
Operacje: tworzenie
Synchronizacja jest inicjowana przy: zaksięgowaniu (posting) listy płac.
Zależności: synchronizacja działa tylko jeśli pole Enable Payroll Documents jest włączone w konfiguracji. Jeśli również włączone jest Enable Between Payroll Docs — synchronizowane są także dokumenty międzyokresowe. W przeciwnym razie — tylko dokumenty z pustym typem grupy obliczeniowej.
Nagłówek
| Pole Business Central | Pole HCM & LMS | Opis i zależności |
|---|---|---|
| Numer dokumentu (No.) | Numer (DocumentNumber) | Numer listy płac |
| Kod pracownika (Employee No.) | Kod pracownika (EmployeeId) | Numer pracownika |
| Opis (Posting Description) | Opis (Name) | Opis księgowania |
| Data księgowania (Posting Date) | Data księgowania (PostingDate) | Data księgowania dokumentu |
| Kod okresu (Period Code) | Okres (Period) | Zależy od: słownik Okresy płacowe. Przesyłana jest nazwa okresu. |
| Stornowane (Reversed) | Korekta (IsCorrected) | Znacznik stornowania. Przesyłany tylko jeśli dokument jest stornowany. |
Wiersze
| Pole Business Central | Pole HCM & LMS | Opis i zależności |
|---|---|---|
| Typ składnika | Typ składnika | Typ składnika obliczeniowego |
| Kod składnika | Kod składnika | Kod składnika obliczeniowego |
| Opis | Opis | Opis składnika |
| Planowane godziny | Planowane godziny | Planowane godziny |
| Rzeczywiste godziny | Rzeczywiste godziny | Rzeczywiste godziny |
| Kwota wynagrodzenia | Kwota wynagrodzenia | Kwota naliczenia |
| Kwota podatku | Kwota podatku | Kwota opodatkowana |
3.14. Statusy ewidencji czasu pracy (Business Central) → Ewidencje czasu pracy (HCM & LMS)
Operacje: tworzenie, usuwanie
Zależności: synchronizacja działa tylko jeśli pole Enable Employee Timesheet jest włączone w konfiguracji. Przesyłane są tylko ewidencje ze statusem «Wydane» (Released).
Synchronizacja jest inicjowana przy: zmianie statusu ewidencji na «Wydane» (tworzenie wpisu), usuwaniu.
| Pole Business Central | Pole HCM & LMS | Opis i zależności |
|---|---|---|
| Imię i nazwisko + Okres | Nazwa (Name) | Tworzone automatycznie: pełne imię pracownika + « - » + nazwa okresu |
| Osoba | Kontakt (ContactId) | Zależy od: Pracownik → Osoba. Przesyłany jest SystemId osoby. Dla osób międzyfirmowych — SystemId z firmy głównej. |
| Umowa | Kontrakt (ContractId) | Zależy od: Pracownik → Umowa. Przesyłany jest SystemId umowy. |
| Kod okresu (Period Code) | Okres (Period) | Zależy od: słownik Okresy płacowe. Przesyłana jest nazwa okresu. |
Etap 4: Tworzenie wpisów w tabeli HCM & LMS Integration Records
Przy każdej zmianie w określonych polach stron w Etapie 3, na stronie HCM & LMS Integration Records wyświetlane są wpisy tych zmian. Każdy wpis odpowiada jednej operacji synchronizacji.
| Pole | Opis |
|---|---|
| Numer operacji (Entry No.) | Numer porządkowy wpisu |
| Typ wpisu (Record Type) | Typ operacji: Tworzenie, Modyfikowanie, Usuwanie |
| Tabela (Table Id) | Numer tabeli, w której nastąpiła zmiana |
| Nazwa tabeli (Table Name) | Nazwa tabeli |
| Data i godzina utworzenia | Data i godzina utworzenia wpisu |
| ID użytkownika | Kod użytkownika, który zainicjował zmianę |
| Status przetwarzania (Processing Status) | Status przetwarzania: «Utworzone» (oczekuje na wysłanie) lub «Przetworzone» (wysłane) |
| Tekst ostatniego błędu (Last Error Text) | Tekst błędu w przypadku niepowodzenia wysyłki. Pomaga w diagnostyce problemów. |
Dostępne akcje na stronie
- Oznacz jako utworzone — przywraca status wpisu na «Utworzone», aby kolejka zadań ponownie spróbowała go wysłać. Używane do ponownego wysyłania po błędzie.
- Wyślij wpisy — natychmiastowe ręczne wysyłanie wpisów bez oczekiwania na kolejkę zadań.
- Pokaż informacje zapytania — wyświetla dane JSON, które zostaną lub zostały wysłane do HCM & LMS. Przydatne do diagnostyki.
- Otwórz wpis źródłowy — otwiera kartę wpisu w Business Central, który zainicjował ten wpis integracji.
- Usuń wybrane — usuwa wybrane wpisy z kolejki integracji. Ta akcja nie może być cofnięta.
Etap 5: Obsługa błędów i monitorowanie
Co się dzieje w przypadku błędu
Jeśli wysyłanie wpisu do HCM & LMS kończy się błędem:
- Status wpisu pozostaje «Utworzone»
- Tekst błędu zapisywany jest w polu «Tekst ostatniego błędu»
- Przy następnym uruchomieniu kolejki zadań system ponownie spróbuje wysłać ten wpis
Jeśli przy aktualizacji wpisu (operacja «Modyfikowanie») HCM & LMS zwraca błąd 404 (wpis nie znaleziony), system automatycznie zmienia typ operacji na «Tworzenie» i ponawia próbę.
Ponowne wysyłanie
Aby ręcznie ponownie wysłać błędne wpisy:
- Otwórz stronę HCM & LMS Integration Records
- Znajdź wpisy ze statusem «Przetworzone» i niepustym tekstem błędu
- Naciśnij «Oznacz jako utworzone» — status zmieni się na «Utworzone»
- Wpis zostanie przetworzony przy następnym uruchomieniu kolejki zadań, lub naciśnij «Wyślij wpisy» aby wysłać natychmiast
Przywracanie kolejki zadań
Jeśli kolejka zadań zatrzymała się z powodu błędu:
- Włącz pole Restore Integration Func. w konfiguracji HCM & LMS Setup
- System automatycznie zrestartuje kolejkę przy następnym zalogowaniu użytkownika z odpowiednimi uprawnieniami
- Zalecany interwał kolejki zadań: 1–5 minut