PartyRole (strona w roli)
PartyRole (strona w roli) opisuje przypisanie roli do strony w danym kontekście – np. „Strona X jako klient", „Strona Y jako dostawca w zamówieniu Z", „Strona X jako płatnik w księgowości". Rozszerza DomainResource i uzupełnia Party: Party to podmiot (kto), PartyRole to ten podmiot w konkretnej roli, opcjonalnie z okresem ważności i kontekstem.
1. Zakres i zastosowanie
PartyRole jest używany do:
- Rola w kontekście – ta sama Party może mieć wiele PartyRole (klient w księgowości, dostawca w magazynie, płatnik w dokumencie), każdy z własnym okresem lub kontekstem
- Okres ważności – rola „klient" dla Party X może być ważna od–do (umowa, uprawnienia)
- Kontekst – rola może być przypisana do dokumentu, umowy, jednostki organizacyjnej lub „globalnie" (brak kontekstu = systemowo)
Rola jest wyrażona jako CodeableConcept ze słownika party-role (employee, employer, customer, supplier, payer); wariant kadrowy: hr (employee, employer).
2. Struktura (pola)
Poza polami z DomainResource (id, resourceType, meta, owner, comment, category, status, type, contained, attribute):
| Nazwa | Kard. | Typ | Opis |
|---|---|---|---|
| identifier | 0..* | Identifier | Identyfikatory roli (system + value) w przestrzeni wdrożeniowej; system z NamingSystem |
| party | 0..1 | Reference(Party) | Strona, której dotyczy rola („kto" w roli – klient, dostawca, płatnik itp.); może wskazywać Party w contained |
| role | 0..1 | CodeableConcept | Rola (system https://api-erp.kamsoft.pl/vs/party-role); w profilach roli (§2a) pole wymagane |
| period | 0..1 | Period | Okres ważności roli (start, end) |
| context | 0..1 | Reference | Kontekst przypisania (umowa, dokument, jednostka organizacyjna) – opcjonalny |
| contextIdentifier | 0..1 | Identifier | Identyfikator kontekstu, gdy kontekst nie jest zasobem API |
Uwaga: PartyRole referuje do pojedynczej Party przez party. Party nie zawiera PartyRole. Relacja między dwiema stronami w rolach jest opisana przez PartyRelationship (partyFrom, partyTo). Jeśli osobny zasób Party nie jest potrzebny, party może być osadzony w contained (inline). status (z DomainResource) w kadrach: hr/party-role-status (active, inactive); type: hr/party-role-type.
2a. Profile roli
Rodzaj roli opisuje profil (StructureDefinition). Profil rozpoznaje się po meta.profile oraz po kodzie w polu role; w schemacie każdego profilu role jest wymagane. Schematy: profile kanoniczne.
| Profil | role |
Znaczenie |
|---|---|---|
EmployeeRole |
employee |
rola pracownika w zatrudnieniu |
EmployerRole |
employer |
rola pracodawcy |
CustomerRole |
customer |
rola odbiorcy |
SupplierRole |
supplier |
rola dostawcy |
PayerRole |
payer |
rola płatnika |
GET /v1/party-roles?role=https://api-erp.kamsoft.pl/vs/party-role|employee&profile=https://api-erp.kamsoft.pl/ns/StructureDefinition/EmployeeRole
Parametr role jest wymagany; obsługiwane wartości to employee i employer (kadry), inne kody dają pustą listę. Które profile są dostępne u danego klienta, mówi supportedProfile w karcie możliwości; profil bez obsługi nie występuje w karcie i zapytanie o niego kończy się błędem.
3. Operacje
Odpowiedź to koperta { "items": [...], "nextToken": null }, stronicowana parametrami count (domyślnie 20) i offset (domyślnie 0).
| Operacja | Parametry | Odpowiedź |
|---|---|---|
GET /v1/party-roles |
role (wymagany, system|value), party (system|value, przestrzeń wewnętrzna Party), profile, count, offset |
200 koperta z PartyRole[] |
Zasób jest tylko do odczytu; brak POST/PATCH i tras z {id}.
4. Relacja Party – PartyRole
- Party – dane główne o podmiocie (identyfikatory, nazwa, adresy, kontakty). Party NIE zawiera referencji do PartyRole. Aby uzyskać role strony, należy odpytać PartyRole z filtrem
role=…&party=<przestrzeń>|<wartość>. - PartyRole – referuje do Party przez party (strona w roli). Przypisanie „Party X w roli Y [w kontekście] [w okresie]": identifier, party → Party, role → CodeableConcept, period, context / contextIdentifier. Relacja między dwiema stronami (np. klient do dostawcy) jest opisana przez PartyRelationship (partyFrom, partyTo).
W dokumentach (faktura, zamówienie) można użyć referencji do Party + referencji do PartyRole (z odpowiednią role), lub tylko referencji do Party i CodeableConcept role w dokumencie. PartyRole jako osobny obiekt jest przydatny gdy role są rejestrowane, wersjonowane lub mają okres ważności (np. „kartoteka klienta" = PartyRole z role=customer, party=Party X; relacja do sprzedawcy w PartyRelationship).
5. Mapowanie na systemy ERP
| System | Odpowiednik | Uwagi |
|---|---|---|
| SAP HCM / S/4HANA | Customer master (role), vendor master (role), business partner | Party = BP master; PartyRole = przypisanie roli BP |
| SAP SuccessFactors | Employee role | Employee (Party) + przypisanie roli (PartyRole) |
| Oracle HCM Cloud | Person, assignment | Person (Party); assignment zawiera rolę (PartyRole) |
| Workday | Worker, assignment | Worker (Party); assignment (PartyRole) z datami obowiązywania |
6. Powiązane zasoby
→ Party — Informacje o podmiocie
→ PartyRelationship — Relacja między PartyRole
→ Core Master Data Overview — Wspólne dane główne