Markierung: 2017-Quelltext-Bearbeitung |
Markierung: 2017-Quelltext-Bearbeitung |
||
Zeile 55: | Zeile 55: | ||
&valueString= | &valueString= | ||
&keyDate= | &keyDate= | ||
& | &toDate= | ||
&keyString= | &keyString= | ||
Zeile 112: | Zeile 112: | ||
==== <code>objectType</code> ==== | ==== <code>objectType</code> ==== | ||
Der <code>objectType</code> enthält den Objekttyp des zu ändernden Objekts. | Der <code>objectType</code> enthält den Objekttyp des zu ändernden Objekts. | ||
Zeile 119: | Zeile 118: | ||
==== <code>indexQuery</code> ==== | ==== <code>indexQuery</code> ==== | ||
Der <code>indexQuery</code> enthält den Index über den das Objekt gesucht wird. | Der <code>indexQuery</code> enthält den Index über den das Objekt gesucht wird. | ||
Zeile 126: | Zeile 124: | ||
==== <code>matchString</code> ==== | ==== <code>matchString</code> ==== | ||
Der <code>matchString</code> enthält den Wert für die Indexsuche. | Der <code>matchString</code> enthält den Wert für die Indexsuche. | ||
Zeile 133: | Zeile 130: | ||
==== <code>importType</code> ==== | ==== <code>importType</code> ==== | ||
Der <code>importType</code> enthält die Eigenschaft die geändert werden soll. | Der <code>importType</code> enthält die Eigenschaft die geändert werden soll. | ||
==== <code>valueString</code> ==== | ==== <code>valueString</code> ==== | ||
Der <code>valueString</code> enthält den Wert der zu setzenden Eigenschaft als Zeichenkette. Eigenschaften können folgende Werte annehmen: | Der <code>valueString</code> enthält den Wert der zu setzenden Eigenschaft als Zeichenkette. Eigenschaften können folgende Werte annehmen: | ||
Zeile 145: | Zeile 140: | ||
* Fremdschlüssel: Verweis auf "Station 1" in Eigenschaft "Stammplanungseinheit" | * Fremdschlüssel: Verweis auf "Station 1" in Eigenschaft "Stammplanungseinheit" | ||
* Komplexe Werte: Kinder für Pflege-Anspruch oder Anspruchszeile | * Komplexe Werte: Kinder für Pflege-Anspruch oder Anspruchszeile | ||
==== <code>keyDate</code> optional ==== | |||
Das <code>keyDate</code> enthält den Wert des Von-Datums der zu setzenden Eigenschaft. | |||
==== <code>toDate</code> optional ==== | |||
Das <code>toDate</code> enthält den Wert des Bis-Datums der zu setzenden Eigenschaft. | |||
==Aufruf== | ==Aufruf== |
Version vom 29. Dezember 2022, 14:45 Uhr
Das Webservice - "Objekte anlegen und ändern" ist eine Programmfunktion zum Anlegen von Objekten eines Objekttyps und zum Ändern von Eigenschaften eines Objekts über das HTTP-Protokoll.
Es kann dazu verwendet werden
- das Personal aktuell zu halten
- die Benutzer aktuell zu halten
- Eigenschaften zu importieren
Ausgangssituation
Voraussetzungen
Um die Programmfunktion nutzen zu können
- muss der Webservice-Daemon konfiguriert sein.
- muss ein gültiger WebApi-Port konfiguriert sein.
- muss Bfx.Abstract.Model.WebService.dll als Plugin konfiguriert sein.
- kann ein Zertifikat zur Verschlüsselung verwendet werden.
- kann ein Sicherer Link-Aufruf konfiguriert werden.
Das Webservice stellt dann folgende Zugriffspfade an der konfigurierten Webservice-Adresse zur Verfügung:
/New
/Set
Der Bediener des Webservice muss mit dem HTTP-Protokoll und seinen Möglichkeiten zur Argumentübertragung[1][2] vertraut sein.
Der Bediener des Webservice muss zudem die Formate kennen, welche übergeben werden können.
Formatierung
Die Daten werden dem Webservice entweder in der URL kodiert als GET-Argumentübertragung, oder als JSON formatierte Datei mittels POST-Argumentübertragung übergeben.
Eine URL kann in eine JSON-Datei konvertiert werden und eine JSON-Datei in eine oder mehrere URLs.
Ein Datum wird immer als DD.MM.YYYY
übertragen.
Schema für URL-Kodierung
Der Prozent-Encodierte Query-String der URL muss folgendes Format haben:
/New ?objectType= &indexQuery= &matchString= &keyDate=
/Set ?objectType= &indexQuery= &matchString= &importType= &valueString= &keyDate= &toDate= &keyString=
Schema für JSON-File
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Set", "description": "format for the set-webservice", "type": "object", "properties": { "objectType": { "type": "string" }, "indexQuery": { "type": "string" }, "importType": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "matchString": { "type": "string" }, "valueString": { "type": "string" }, "importType": { "type": "string" }, "keyString": { "type": "string" }, "keyDate": { "type": "string", "pattern": "^(3[01]|[12][0-9]|0[1-9]).(1[0-2]|0[1-9]).[0-9]{4}$" } }, "required": [ "matchString", "valueString" ] } } }, "required": [ "objectType", "indexQuery", "importType" ] }
objectType
Der objectType
enthält den Objekttyp des zu ändernden Objekts.
- Für Personal:
Employee
- Für Benutzer:
AlexUser
indexQuery
Der indexQuery
enthält den Index über den das Objekt gesucht wird.
- Für Personal:
EmployeeIDX
- Für Benutzer:
UserX
matchString
Der matchString
enthält den Wert für die Indexsuche.
- Für Personal die Personalnummer.
- Für Benutzer der Benutzername.
importType
Der importType
enthält die Eigenschaft die geändert werden soll.
valueString
Der valueString
enthält den Wert der zu setzenden Eigenschaft als Zeichenkette. Eigenschaften können folgende Werte annehmen:
- Zeichenketten:
"Mayr"
,"Groß"
,"Ü"
- Ganze Zahlen:
"1"
,"2"
,"10000"
- Gleitkommazahlen:
"1.123"
,"1.4567"
- Fremdschlüssel: Verweis auf "Station 1" in Eigenschaft "Stammplanungseinheit"
- Komplexe Werte: Kinder für Pflege-Anspruch oder Anspruchszeile
keyDate
optional
Das keyDate
enthält den Wert des Von-Datums der zu setzenden Eigenschaft.
toDate
optional
Das toDate
enthält den Wert des Bis-Datums der zu setzenden Eigenschaft.
Aufruf
Objekt anlegen
Beispiel Personal
Details zur Anlage eines neuen Personals finden Sie hier
Optional kann ein neues Personal auch mit dem Aufruf Set angelegt werden, wenn folgender Parameter aktiviert ist:
- Systemeinstellungen - Object Import Einstellungen: Eigenschaften-Import: Neu erstellen falls nicht gefunden?
- Bit Factory interne Zusatzinfo:
- siehe Issue #7363
- ab Version V2022.18
Beispiel Benutzer
Neuer Benutzer mit Username "USER1"
/New?objectType=AlexUser&indexQuery=UserX&matchString=USER1
Objekt ändern
Beispiele Personal
Beim Setzen von zeitlich abgrenzbaren Eigenschaften wird der Beginn automatisch begrenzt mit dem 'Ist bis'-Datum der Stammplanungseinheit des Mitarbeiters.
Wird ein keyDate mitgegeben, so wird entweder dieses Datum verwendet oder als Beginn das Maximum zwischen keyDate und "Ist bis" genommen.
Wird kein keyDate mitgegeben, so wird entwerder der 1. des aktuellen Monats genommen oder auch das Maximum zwischen keyDate und "Ist bis".
Beispiel:
- Dezember 2021 befindet sich im Status IST
- Jänner 2022 befindet sich im Status Planung
- "Ist bis" ist somit der 1.1.2022
- Parameter Zuname wird mit Stichtag 1.3.2022 gesendet
- Ergebnis: Zuname wird per 1.3.2022 hinterlegt
- Parameter Zuname wird mit Stichtag 1.11.2021 gesendet
- Ergebnis: Zuname wird per 1.1.2022 hinterlegt
- Ergebnis: Zuname wird per 1.1.2022 hinterlegt
- Setzen von Email "test@example.com" bei Personal mit Personalnummer "PNR123"
/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=EmployeeEmailAddress&valueString=test@example.com
- Setzen von Kartennummer "1234567" bei Personal mit Personalnummer "PNR123" ab 01.01.2020
- Achtung, ist das "Ist bis" Datum z. B. der 01.03.2020 so würde der Beginn auch erst ab 01.03.2020 gesetzt werden!
/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=EmployeeCardID&valueString=1234567&keyDate=01.01.2020
- Setzen von Zuname "Mustermann" bei Personal mit Personalnummer "PNR123" ab 01.10.2020
/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=Surname&valueString=Mustermann&keyDate=01.10.2020
- Setzen von Vorname "Max" bei Personal mit Personalnummer "PNR123"
/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=Forename&valueString=Max
- Setzen von Beschäftigungsausmaß 62,5% bei Personal mit Personalnummer "PNR123" ab 01.03.2022
/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=EmploymentFactorPercent&valueString=62,5&keyDate=01.03.2022
- Eingabe Austritt bei Personal mit Personalnummer "PNR123" per 31.08.2022
/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=Employed&toDate=31.08.2022
Beispiele Benutzer
- Setzen von Email "test@example.com" bei User mit Username "USER1"
/Set?objectType=AlexUser&indexQuery=UserX&matchString=USER1&importType=UserEmail&valueString=test@example.com
- Setzen von Username "USER1NEU" bei User mit Username "USER1"
/Set?objectType=AlexUser&indexQuery=UserX&matchString=USER1&importType=Username&valueString=USER1NEU
Externe Kennzeichen (Foreign Keys)
Der Import von Externen Kennzeichen (Foreign Keys) ist über die interne ObjectID
von ALEX möglich oder über Fremdschlüssel, die zuvor initialisiert werden müssen.
Sind Externe Kennzeichen gesetzt, soll aber trotzdem über die ObjektID importiert werden, so muss folgender Parameter am System gesetzt werden: "Eigenschaften-Import: Referenzen entsprechen 'ObjektID'?" (unter Object Import Einstellungen)
Systemeinstellungen für Objekt Import |
Fremdschlüssel stehen für die gängigsten Objekttypen zur Verfügung:
- Berufsgruppe
- Planungseinheit
- Qualifikation
- Vertrag
- Lohnartenumschlüsselung
- Setzen der Berufsgruppe mit externem Kennzeichen "B1" bei Personal mit Personalnummer "1"
/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=1&importType=EmployeeJobGroup&valueString=B1
- Setzen der Planungseinheit mit externem Kennzeichen "P1" bei Personal mit Personalnummer "1" (könnte auch mit keyDate und mit toDate erweitert werden für eine zeitliche Abgrenzung, z. B. beim Wechsel der Stammplanungseinheit)
/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=1&importType=MasterAllocation&valueString=P1
- Stammplanungseinheit verlängern
- Wurde der Austritt z. B. per 09.09.2022 erfasst und der Mitarbeiter bleibt nun doch bis 16.09.2022, so muss der Befehl folgendermaßen gesendet werden
/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=1&importType=MasterAllocation&valueString=P1&keyDate=01.09.2022&toDate=16.09.2022
- Setzen der Qualifikation mit externem Kennzeichen "AS" bei Personal mit Personalnummer "1" per 01.09.2022 bis 31.12.2022
/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=1&importType=EmployeeQualifications&keyString=AS&keyDate=01.09.2022&toDate=31.12.2022
Eingebettete Objekte (Records)
Der Import von eingebetteten Objekten (Records) ist ebenfalls möglich. Der valueString
eingebetteter Objekte folgt dem Muster:
Property1####Value&Property2####Value ... &PropertyN####Value
Beispiele für eingebettete Objekte:
- Anspruchszeile am Personal
- Informationen über Kinder für Pflegefreistellung
- Setzen von Anspruchszeile bei Personal mit der Personalnummer "PNR123"
importType für Anspruchsart
EmployeeEntitlement_NAME: NAME = Name der Anspruchsart aus Stammdaten
Properties für valueString für Anspruchszeile EmployeeRecEntitlementKeyDate: Stichtag der Anspruchszeile im Personalstamm EmployeeRecEntitlementCustomPostingKeyDate: Zubuchungstag der Anspruchszeile im Personalstamm EmployeeRecEntitlementValue: Zusatzanspruch der Anspruchszeile im Personalstamm
Beispiel für valueString für Anspruchszeile nicht URL-Encoded EmployeeRecEntitlementKeyDate####02.02.2012&EmployeeRecEntitlementCustomPostingKeyDate####03.02.2012&EmployeeRecEntitlementValue####200,00
Encodiert in der URL sieht das so aus:
/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=EmployeeEntitlement_Urlaub&valueString=EmployeeRecEntitlementKeyDate%23%23%23%2302.02.2012%26EmployeeRecEntitlementCustomPostingKeyDate%23%23%23%2303.02.2012%26EmployeeRecEntitlementValue%23%23%23%23200,00&keyDate=01.10.2020
Das keyDate
ist das Von-Datum der Anspruchszeile im Personalstamm und ergibt sich aus dem gewünschten Berechnungszeitruam der Anspruchsart. (hier gilt auch die oben beschriebene Logik bzgl. dem Maximum zwischen keyDate und "Ist bis")
ACHTUNG: Anspruchszeilen sollten nur einmalig bei der Initialanlage des Personals eingespielt werden. Alle folgenden Änderungen (z.B. Gültigkeit der Anspruchszeile erhöhen) müssen direkt in Alex® eingegeben werden.
- Setzen von Kindern beim Personal (max. 7 Kinder sind möglich) mit der Personalnummer "PNR123"
importType für Kinder EmployeeChildren
keyString für Kinder enthält Index des Kindes 0 = 1. Kind 1 = 2. Kind ... 6 = 7. Kind
Properties für valueString für Kind ChildName: Name des Kindes ChildBirthday: Geburtstag des Kindes
1. Kind: Franz, Geburtstag: 03.02.2012
/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=EmployeeChildren&keyString=0&valueString=ChildName%23%23%23%23Franz%26ChildBirthday%23%23%23%2303.02.2012
2. Kind: Hans, Geburtstag: 03.02.2013
/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=EmployeeChildren&keyString=1&valueString=ChildName%23%23%23%23Hans%26ChildBirthday%23%23%23%2303.02.2013
7. Kind: Karl, Geburtstag: 03.02.2014
/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=EmployeeChildren&keyString=6&valueString=ChildName%23%23%23%23Karl%26ChildBirthday%23%23%23%2303.02.2014
Zeitlich abgegrenzte Eigenschaften (Timeline)
Beispiele für zeitlich abgegrenzte Eigenschaften:
- Inaktivzeiten
- Schwanger: valueString=0
- Mutterschutz: valueString=1
- Karenz: valueString=2
- Sonstige Inaktivzeit: valueString=3
- Setzen von 'Mutterschutz' bei Personal mit der Personalnummer "PNR123" von 1.1.2020 bis 1.8.2020
/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=MaternityProtection&valueString=1&keyDate=01.01.2020&toDate=01.08.2020
Ausgabe
Json-Objekt in der Form:
{ "request" : "" , "status" : "" , "details" : "" }
- "request": Angeforderter Request als "Handshake"
- "status": "ok" oder "error"
- "details": Optionale Detailinformationen bei "error"
File Import
Der Pfad für die Importfiles kann in den Systemeinstellungen in der Gruppe "Object Import Einstellungen" beim Parameter "Eigenschaften-Import Pfad" festgelegt werden.
Die gewünschte Dateierweiterung kann beim Parameter "Eigenschaften-Import Dateierweiterung" eingetragen werden.
Der definierte Ordner wird alle 2 Minuten auf neue Dateien geprüft.
Format für Datei
{ "objectType": "string", "indexQuery": "string", "importType": "string", "lines": [ { "matchString": "string", "valueString": "string", "importType": "string", "keyString": "string", "keyDate": "DD.MM.YYYY" } ] }
Beispiele Personal
Setzen von Kartennummer "1234567" bei Personal mit Personalnummer "1" ab 01.01.2020.
{ "objectType": "Employee", "indexQuery": "EmployeeIDX", "importType": "EmployeeCardID", "lines": [ { "matchString": "1", "valueString": "1234567", "keyDate": "01.01.2020" } ] }
Setzen von Email "test@example.com" bei Personal mit Personalnummer "1" ab 01.01.2020.
{ "objectType": "Employee", "indexQuery": "EmployeeIDX", "importType": "EmployeeEmailAddress", "lines": [ { "matchString": "1", "valueString": "test@example.com", "keyDate": "01.01.2020" } ] }
Setzen von Zuname "Mair" bei Personal mit Personalnummer "1" ab 01.01.2020 und setzen von Zuname "Huber" bei Personal mit Personalnummer "2" ab 01.02.2020.
{ "objectType": "Employee", "indexQuery": "EmployeeIDX", "importType": "Surname", "lines": [ { "matchString": "1", "valueString": "Mair", "keyDate": "01.01.2020" }, { "matchString": "2", "valueString": "Huber", "keyDate": "01.02.2020" } ] }
Setzen von Zuname, Vorname, Berufsgruppe und 1. Kind bei Personal mit Personalnummer "1":
{ "objectType": "Employee", "indexQuery": "EmployeeIDX", "lines": [ { "matchString": "1", "importType": "Surname", "valueString": "Mair", "keyDate": "01.12.2000" }, { "matchString": "1", "importType": "Forename", "valueString": "Franz" }, { "matchString": "1", "importType": "EmployeeJobGroup", "valueString": "DGKS", "keyDate": "01.02.2018" }, { "matchString": "1", "importType": "EmployeeChildren", "keyString": "0", "valueString": "ChildName####Karl&ChildBirthday####03.02.2014" } ] }
Der Inhalt des Files kann dem /Set
Webservice auch gePOST
et werden
Häufig benutzte Werte
Personal
ImportType
Eigenschaft | ImportType | Zusätzliche Informationen |
---|---|---|
Stamm-Planungseinheit | MasterAllocation | |
Zuname | Surname | |
Vorname | Forename | |
Kurzname | Nickname | |
Titel vor Name | EmployeeTitleBeforeName | |
Titel nach Name | EmployeeTitleAfterName | |
Geschlecht | Sex | ValueString: 0 = weiblich; 1 = männlich |
Geburtstag | DayOfBirth | |
Berufsgruppe | EmployeeJobGroup | |
Beschäftigt | Employed | keyDate für Beschäftigt ab
toDate für Beschäftigt bis |
E-Mail Adresse | EmployeeEmailAddress | |
Lohnartenumschlüsselung | EmployeeAccountToWageTypeMap | |
Kartennummer | EmployeeCardID | |
Inaktivzeiten | MaternityProtection | ValueString:
0 = Schwanger 1 = Mutterschutz 2 = Karenz 3 = Sonstige Inaktivzeit sollte es noch weitere geben, siehe Kundenmodul |
Telefonnummer | EmployeePhoneNumber | |
Sozialversicherungs-Nr. | EmployeeSocialInsurance | |
Straße | EmployeeStreet | |
Handzeichen für Pflegedoku | EmployeeSignature | |
Einstufung | EmployeeJobEvaluation | |
Beschäftigungsausmaß in Prozent | BESCH_GRAD_IN_PROZENT | |
Sollstunden Montag | SOLL_MO | |
Sollstunden Dienstag | SOLL_DI | |
Sollstunden Mittwoch | SOLL_MI | |
Sollstunden Donnerstag | SOLL_DO | |
Sollstunden Freitag | SOLL_FR | |
Sollstunden Samstag | SOLL_SA | |
Sollstunden Sonntag | SOLL_SO | |
Sollstunden FEIERTAG | SOLL_FT | |
Fixes Monatssoll in Stunden | SOLL_MONAT_FIX | |
Arbeitstage je Woche | WorkingDaysPerWeek |
Protokollierung
Damit Änderungen über die Webservice-Schnittstelle protokolliert werden, muss beim Parameter "Eigenschaften-Import: Benutzer für Webservice" ein Benutzer hinterlegt werden.
Der hinterlegte Benutzer hat die SUPERVISOR-Berechtigung für das ganze System.
Benutzer WEBSERVICE |
Protokoll Personal |