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
- Personalstammdaten zu importieren
- Benutzerstammdaten zu importieren
- Eigenschaften zu importieren
Ausgangssituation
Voraussetzungen
Neben den Voraussetzungen für den Betrieb eines Webservice muss das richtige Plugin konfiguriert sein.
Das Webservice stellt dann folgende Zugriffspfade zur Verfügung:
/New
: Anlage eines neuen Objekts.- kann entfallen wenn der Parameter
Systemeinstellungen: Object Import Einstellungen: Eigenschaften-Import: Neu erstellen falls nicht gefunden?
aktiviert ist. [1]
- kann entfallen wenn der Parameter
/Set
: Ändern eines bestehenden Objekts.
Formatierung der Anfrage
Die Daten werden dem Webservice entweder in der URL kodiert als GET-Argumentübertragung, oder als JSON formatierte Zeichenkette 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. Parameter in eckigen Klammern sind optional:
/New ?objectType= &indexQuery= &matchString= [&keyDate=]
/Set ?objectType= &indexQuery= &matchString= &importType= &valueString= [&keyDate=] [&toDate=] [&keyString=]
Schema für JSON-File
Die, dem Webservice mittels POST-Argumentübertragung, zur Verfügung gestellte JSON-Datei muss folgendem Schema entsprechen:
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Set", "description": "Format für Anfragen an das 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", "lines" ] }
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
- Format uncodiert:
Property1####Value&Property2####Value ... &PropertyN####Value
- Muss in URL codiert werden!
- Format uncodiert:
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.
keyString
(optional)
Der keyString
enthält den Schlüsselwert der zu setzenden Eigenschaft.
Formatierung der Ausgabe
JSON-String nach dem Schema:
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "New/Set-Result", "description": "Format für Ausgabe des New/Set-Webservice", "type": "object", "properties": { "request": { "type": "string", "description": "Angeforderter Request als 'Handshake'" }, "status": { "type": "string", "description": "'ok' oder 'error'" }, "details": { "type": "string", "description": "Optionale Detailinformationen bei 'error'" } }, "required": [ "request", "status" ] }
Beispiele
Beispiel: Ein Personal mit Standardinformationen anlegen
Diese Aufrufe des Webservice:
/New?objectType=Employee&indexQuery=EmployeeIDX&matchString=16 /Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=16&importType=MasterAllocation&valueString=SR&keyDate=01.01.2022 /Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=16&importType=Surname&valueString=Mustermann /Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=16&importType=Forename&valueString=Johann /Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=16&importType=Nickname&valueString=Hans /Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=16&importType=EmployeeTitleBeforeName&valueString= /Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=16&importType=EmployeeTitleAfterName&valueString= /Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=16&importType=Sex&valueString=1 /Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=16&importType=DayOfBirth&valueString=29.03.1965 /Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=16&importType=EmployeeJobGroup&valueString=V /Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=16&importType=Employed&keyDate=01.07.1993 /Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=16&importType=EmployeeEmailAddress&valueString=johann.mustermann@gmail.com
führen zu diesem Personalstamm:
Beispiel: Neues Objekt anlegen
Objekttyp | Beschreibung | URL Aufruf | JSON Aufruf |
---|---|---|---|
Personal | Neues Personal mit Personalnummer 1 |
/New ?objectType=Employee &indexQuery=EmployeeIDX &matchString=1 |
nicht möglich |
Benutzer | Neuer Benutzer mit Benutzername U1 |
/New ?objectType=AlexUser &indexQuery=UserX &matchString=U1 |
nicht möglich |
Beispiel: Eigenschaften in Personal ändern
Der Einfachheit halber nehmen wir an, es gibt bereits ein Personal mit Personalnummer 1
.
Änderung | URL Aufruf (codiert) | JSON Aufruf |
---|---|---|
Email auf test@example.com |
/Set ?objectType=Employee &indexQuery=EmployeeIDX &matchString=1 &importType=EmployeeEmailAddress &valueString=test@example.com |
{ "objectType": "Employee", "indexQuery": "EmployeeIDX", "importType": "EmployeeEmailAddress", "lines": [ { "matchString": "1", "valueString": "test@example.com" } ] } |
Kartennumer auf 3 ab 01.01.2020 |
/Set ?objectType=Employee &indexQuery=EmployeeIDX &matchString=1 &importType=EmployeeCardID &valueString=3 &keyDate=01.01.2020 |
{ "objectType": "Employee", "indexQuery": "EmployeeIDX", "importType": "EmployeeCardID", "lines": [ { "matchString": "1", "valueString": "3", "keyDate": "01.01.2020" } ] } |
Zuname auf Mustermann ab 01.10.2020 |
/Set ?objectType=Employee &indexQuery=EmployeeIDX matchString=1 &importType=Surname &valueString=Mustermann &keyDate=01.10.2020 |
{ "objectType": "Employee", "indexQuery": "EmployeeIDX", "importType": "Surname", "lines": [ { "matchString": "1", "valueString": "Mustermann", "keyDate": "01.10.2020" } ] } |
Vorname auf Max |
/Set ?objectType=Employee &indexQuery=EmployeeIDX &matchString=1 &importType=Forename &valueString=Max |
{ "objectType": "Employee", "indexQuery": "EmployeeIDX", "importType": "Forename", "lines": [ { "matchString": "1", "valueString": "Max" } ] } |
Beschäftigungsausmaß auf 62,5% ab 01.03.2022 |
/Set ?objectType=Employee &indexQuery=EmployeeIDX &matchString=1 &importType=BESCH_GRAD_IN_PROZENT &valueString=62,5 &keyDate=01.03.2022 |
{ "objectType": "Employee", "indexQuery": "EmployeeIDX", "importType": "BESCH_GRAD_IN_PROZENT", "lines": [ { "matchString": "1", "valueString": "62,5", "keyDate": "01.03.2022" } ] } |
Austritt auf 31.08.2022 |
/Set ?objectType=Employee &indexQuery=EmployeeIDX &matchString=1 &importType=Employed &toDate=31.08.2022 |
{ "objectType": "Employee", "indexQuery": "EmployeeIDX", "importType": "Employed", "lines": [ { "matchString": "1", "valueString": "", "toDate": "31.08.2022" } ] } |
Berufsgruppe auf B1 |
/Set ?objectType=Employee &indexQuery=EmployeeIDX &matchString=1 &importType=EmployeeJobGroup &valueString=B1 |
{ "objectType": "Employee", "indexQuery": "EmployeeIDX", "importType": "EmployeeJobGroup", "lines": [ { "matchString": "1", "valueString": "B1" } ] } |
Stammplanungseinheit auf P1 |
/Set ?objectType=Employee &indexQuery=EmployeeIDX &matchString=1 &importType=MasterAllocation &valueString=P1 &keyDate=01.09.2022 |
{ "objectType": "Employee", "indexQuery": "EmployeeIDX", "importType": "MasterAllocation", "lines": [ { "matchString": "1", "valueString": "P1", "keyDate": "01.09.2022" } ] } |
Stammplanungseinheit P1 abgrenzen |
/Set ?objectType=Employee &indexQuery=EmployeeIDX &matchString=1 &importType=MasterAllocation &valueString=P1 &keyDate=01.09.2022 &toDate=16.09.2022 |
{ "objectType": "Employee", "indexQuery": "EmployeeIDX", "importType": "MasterAllocation", "lines": [ { "matchString": "1", "valueString": "P1", "keyDate": "01.09.2022", "toDate": "16.09.2022" } ] } |
Qualifikation AS von 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 |
{ "objectType": "Employee", "indexQuery": "EmployeeIDX", "importType": "EmployeeQualifications", "lines": [ { "matchString": "1", "keyString": "AS", "keyDate": "01.09.2022", "toDate": "31.12.2022" } ] } |
Anspruch von Urlaub (beachten |
/Set ?objectType=Employee &indexQuery=EmployeeIDX &matchString=1 &importType=EmployeeEntitlement_Urlaub &valueString =EmployeeRecEntitlementKeyDate%23%23%23%2302.02.2012%26 EmployeeRecEntitlementCustomPostingKeyDate %23%23%23%2303.02.2012%26 EmployeeRecEntitlementValue%23%23%23%23200,00 &keyDate=01.10.2020 |
{ "objectType": "Employee", "indexQuery": "EmployeeIDX", "importType": "EmployeeEntitlement_Urlaub", "lines": [ { "matchString": "1", "valueString": "EmployeeRecEntitlementKeyDate####02.02.2012& EmployeeRecEntitlementCustomPostingKeyDate ####03.02.2012& EmployeeRecEntitlementValue####200,00", "keyDate": "01.10.2020" } ] } |
Kind 1 |
/Set ?objectType=Employee &indexQuery=EmployeeIDX &matchString=PNR123 &importType=EmployeeChildren &keyString=0 &valueString =ChildName%23%23%23%23Franz%26 ChildBirthday%23%23%23%2303.02.2012 |
{ "objectType": "Employee", "indexQuery": "EmployeeIDX", "importType": "EmployeeChildren", "lines": [ { "matchString": "1", "keyString": "0", "valueString": "ChildName####Franz& ChildBirthday####03.02.2012" } ] } |
Mutterschutz von 01.01.2020 bis 01.08.2020 |
/Set ?objectType=Employee &indexQuery=EmployeeIDX &matchString=1 &importType=MaternityProtection &valueString=1 &keyDate=01.01.2020 &toDate=01.08.2020 |
{ "objectType": "Employee", "indexQuery": "EmployeeIDX", "importType": "MaternityProtection", "lines": [ { "matchString": "1", "valueString": "1", "keyDate": "01.01.2020", "toDate": "01.08.2020" } ] } |
Poolzuteilung auf P1 (2387) |
/Set ?objectType=Employee &indexQuery=EmployeeIDX &matchString=1 &importType=PoolAllocations &keyString=2387 &valueString= &keyDate=01.09.2022 |
{ "objectType": "Employee", "indexQuery": "EmployeeIDX", "importType": "PoolAllocations", "lines": [ { "matchString": "1", "keyString": "2387", "valueString": "", "keyDate": "01.09.2022" } ] } |
Besonderheiten
Beschäftigungsausmaß
Die Eigenschaft Beschäftigungsausmaß in Prozent wird je nach Abrechnungsart unterschiedlich angesprochen:[3]
- nur _7up:
EmploymentFactorPercent
- nur Standard:
BESCH_GRAD_IN_PROZENT
- gemischt: beides erlaubt
Beispiel: Anspruchszeile
/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
EmployeeEntitlement_Urlaub → hier muss nach dem _ der Name der Anspruchsart gesendet werden
EmployeeRecEntitlementKeyDate → Stichtag der Anspruchszeile
EmployeeRecEntitlementCustomPostingKeyDate → Zubuchungstag der Anspruchszeile
EmployeeRecEntitlementValue → Zusatzanspruch der Anspruchszeile
keyDate → Beginn-Datum der Anspruchszeile - meist Eintrittsdatum oder 1. des Eintrittmonats (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.
Beispiel: Eigenschaften in Benutzer ändern
Der Einfachheit halber nehmen wir an, es gibt bereits einen Benutzer mit Benutzername U1
.
Änderung | URL Aufruf (codiert) | JSON Aufruf |
---|---|---|
Email auf test@example.com |
/Set ?objectType=AlexUser &indexQuery=UserX &matchString=U1 &importType=UserEmail &valueString=test@example.com |
{ "objectType": "AlexUser", "indexQuery": "UserX", "importType": "UserEmail", "lines": [ { "matchString": "U1", "valueString": "test@example.com" } ] } |
Benutzername auf U2 |
/Set ?objectType=AlexUser &indexQuery=UserX &matchString=U1 &importType=Username &valueString=U2 |
{ "objectType": "AlexUser", "indexQuery": "UserX", "importType": "Username", "lines": [ { "matchString": "U1", "valueString": "U2" } ] } |
Beispiel 1: Email in Personal ändern
Ausgangssituation
Im folgenden Beispiel verfügt die Mitarbeiterin mit der Personalnummer 4, Birgit Bauer über eine hinterlegte E-Mail-Adresse
- E-Mail-Adresse: bauer@bitfactory.com
- Personalnummer: 4
Mitarbeiter Birgit Bauer |
Aufruf der Funktion
Um die E-Mail-Adresse von einem Mitarbeiter mit der Personalnummer 4 zu ändern, muss das folgende JSON-Format als Zeichenkette mit der POST-Methode übertragen werden.
{ "objectType": "AlexUser", "indexQuery": "UserX", "importType": "UserEmail", "lines": [ { "matchString": "4", "valueString": "birgit.bauer@bitfactory.at" } ] }
Ergebnis
{ "request": "/Set", "status": "ok" }
Datenbank für Beispiel
Cheatsheet
Eigenschaft | importType
|
valueString
|
Zusätzliche Informationen | |
---|---|---|---|---|
Stamm-Planungseinheit | MasterAllocation | wie konfiguriert | ||
Zuname | Surname | Zeichenkette | ||
Vorname | Forename | Zeichenkette | ||
Kurzname | Nickname | Zeichenkette | ||
Titel vor Name | EmployeeTitleBeforeName | Zeichenkette | ||
Titel nach Name | EmployeeTitleAfterName | Zeichenkette | ||
Geschlecht | Sex | 0 = weiblich
1 = männlich |
||
Geburtstag | DayOfBirth | Datum | ||
Berufsgruppe | EmployeeJobGroup | wie konfiguriert | ||
Beschäftigt | Employed | leer | keyDate für Beschäftigt ab
| |
E-Mail Adresse | EmployeeEmailAddress | Zeichenkette | ||
Lohnartenumschlüsselung | EmployeeAccountToWageTypeMap | wie konfiguriert | ||
Kartennummer | EmployeeCardID | Zeichenkette | ||
Inaktivzeiten | MaternityProtection | 0 = Schwanger
1 = Mutterschutz 2 = Karenz 3 = Sonstige Inaktivzeit weitere kundenspezifische möglich |
||
Telefonnummer | EmployeePhoneNumber | Zeichenkette | ||
Sozialversicherungs-Nr. | EmployeeSocialInsurance | Zeichenkette | ||
Straße | EmployeeStreet | Zeichenkette | ||
Handzeichen für Pflegedoku | EmployeeSignature | Zeichenkette | ||
Einstufung | EmployeeJobEvaluation | Zeichenkette | ||
Beschäftigungsausmaß in Prozent [3] | BESCH_GRAD_IN_PROZENT EmploymentFactorPercent |
Gleitkommazahl | Je nach Abrechnungsart unterschiedlich:
nur _7up: EmploymentFactorPercent nur Standard: BESCH_GRAD_IN_PROZENT gemischt: beides | |
Sollstunden Montag | SOLL_MO | Gleitkommazahl | ||
Sollstunden Dienstag | SOLL_DI | Gleitkommazahl | ||
Sollstunden Mittwoch | SOLL_MI | Gleitkommazahl | ||
Sollstunden Donnerstag | SOLL_DO | Gleitkommazahl | ||
Sollstunden Freitag | SOLL_FR | Gleitkommazahl | ||
Sollstunden Samstag | SOLL_SA | Gleitkommazahl | ||
Sollstunden Sonntag | SOLL_SO | Gleitkommazahl | ||
Sollstunden FEIERTAG | SOLL_FT | Gleitkommazahl | ||
Fixes Monatssoll in Stunden | SOLL_MONAT_FIX | Gleitkommazahl | ||
Arbeitstage je Woche | WorkingDaysPerWeek | Gleitkommazahl | ||
Anspruchsart | EmployeeEntitlement_NAME | EmployeeRecEntitlementKeyDate: Stichtag
EmployeeRecEntitlementCustomPostingKeyDate: Zubuchungstag EmployeeRecEntitlementValue: Zusatzanspruch |
NAME = Name der Anspruchsart aus Stammdaten | |
Kinder für Pflegefreistellung | EmployeeChildren | ChildName: Name
ChildBirthday: Geburtstag |
keyString enthält Index des Kindes
0 = 1. Kind 6 = 7. Kind |
|
Poolzuteilungen | PoolAllocations | leer | keyString enthält Planungseinheit wie konfiguriert
|
Zeitbereich Korrektur bei Personal
Im Personalstamm gibt es Eigenschaften, die zeitlich abgegrenzt werden können, zum Beispiel:
- Stammplanungseinheit
- Beschäftigungsgrad
- Sollstunden
Für deren Änderung muss ein Zeitbereich angegeben werden.
Diese Eigenschaften beeinflussen die Berechnung der Zeitkonten und dürfen sich auf abgeschlossenen Plänen nicht ändern.
Darum können keine Eigenschaften vor dem Abgeschlossen-Bis-Datum der aktuellen Stammplanungseinheit des Personals durch das Webservice geändert werden.
Der Zeitbereich der Änderung wird nach folgenden Kriterien angenommen:
- wird ein
keyDate
übergeben, wird dieses verwendet. - wird kein
keyDate
an die Schnittstelle übergeben, wird automatisch der 1. des aktuellen Monats angenommen. - wird ein
toDate
übergeben, wird dieses verwendet. - wird kein
toDate
an die Schnittstelle übergeben, wird automatisch unendlich angenommen.
Der entstandene Zeitbereich wird nun mit dem Abgeschlossen-Bis-Datum begrenzt.
Beispiel
Abgeschlossen-Bis * 1. aktueller Monat * | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | inf ----------------------------------------------------------------------------------- Zeitbereich | | | | | | | * | * | * | * | Zeitbereich korr. | | | | | | | * | * | * | * | ----------------------------------------------------------------------------------- Zeitbereich | * | * | * | * | * | * | * | * | * | * | Zeitbereich korr. | | | | * | * | * | * | * | * | * | ----------------------------------------------------------------------------------- Zeitbereich | | | | | | * | * | * | * | * |-> Zeitbereich korr. | | | | | | * | * | * | * | * |-> ----------------------------------------------------------------------------------- Zeitbereich | * | * | * | | | | | | | | Zeitbereich korr. | | | | | | * | * | * | * | * |->
Referenzen auf andere Objekte
Der Import Referenzen auf andere Objekte ist möglich über
- die interne
ObjectID
von ALEX. - externe Kennzeichen, die zuvor initialisiert werden müssen.
Sind Externe Kennzeichen gesetzt kann trotzdem über die ObjectID
importiert werden:
- Parameter
Systemeinstellungen: Object Import Einstellungen: Eigenschaften-Import: Referenzen entsprechen 'ObjektID'?
Systemeinstellungen für Objekt Import |
Fremdschlüssel stehen für folgende Objekttypen zur Verfügung:
- Berufsgruppe
- Planungseinheit
- Qualifikation
- Vertrag
- Lohnartenumschlüsselung
File Import
Zusätzlich zum Webservice können Dateien im JSON-Format auch über einen Daemon-Prozess importiert werden.
Der Daemon muss im Configfile konfiguriert werden.
Der Pfad und die Endung der Dateien kann in den Systemeinstellungen eingestellt werden.
Systemeinstellungen: Object Import Einstellungen: Eigenschaften-Import Pfad
Systemeinstellungen: Object Import Einstellungen: Eigenschaften-Import Dateierweiterung
Dateien werden alle 2 Minuten importiert.
Interaktiver Test von POST
Unter Systemeinstellung -> rechte Maustaste auf Reiter -> Test Object Import kann ein Eingabefenster geöffnet werden.
In dieses Eingabefenster können Dateien im JSON-Format kopiert werden.
Damit kann das Format des POST Mechanismus auf Richtigkeit getestet werden.
Test Object Import |
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 benötigt SUPERVISOR-Berechtigung für das ganze System.
Benutzer WEBSERVICE |
Protokoll Personal |