Webservice - Objekte anlegen und ändern


Beliebige Objekte können angelegt und deren Eigenschaften (z.B. Zuname, E-Mail Adressen, etc.) über diese Webservice Schnittstelle geändert werden.

Aufruf

http://IP:PORT/New?Parameter zum Anlegen von neuen Objekten
http://IP:PORT/Set?Parameter zum Ändern von Objekten
  • IP: Wie im ALEX-Config-File eingestellt
  • HTTP-Server-PORT: Wie im ALEX-Config-File eingestellt
  • Parameter: wie im Folgenden beschrieben

Objekt anlegen

/New
?objectType=<Objekttyp des neuen Objektes>
&indexQuery=<Index für Verifizierung>
&matchString=<Wert für Suche auf Index>
&keyDate=<Stichtag bei zeitlich begrenzbaren Eigenschaften>

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

/Set
?objectType=<Objekttyp auf dem geändert wird>
&indexQuery=<Index über den das Objekt gefunden wird>
&matchString=<Wert für Suche auf Index>
&importType=<Eigenschaft die geändert werden soll>
&valueString=<Wert der Eigenschaft, URL-Encoded>
&keyDate=<Stichtag bei zeitlich begrenzbaren Eigenschaften>

Format für Datum: 

DD.MM.YYYY

Ergebnis: 

Enthält eine etwaige Fehlermeldung.

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


  • 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
Bfx.Abstract.Model.WebService.dll 1665738827331.png


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 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": "1",
           "valueString": "ChildName####Karl&ChildBirthday####03.02.2014"
       }
   ]
}

Der Inhalt des Files kann dem /Set Webservice auch gePOSTet 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

Bekannte Felder, welche momentan noch nicht importiert werden können:

  • Personal Info - Stadt/Land (hier würde noch eine Entwicklung benötigt, um Externe Kennzeichen beim Objekt Stadt zu verwalten)

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
Bfx.Abstract.Model.WebService.dll 1662712309556.png
Protokoll Personal
Bfx.Abstract.Model.WebService.dll 1662712457699.png

Bit Factory interne Zusatzinfos

Aktivierung Einfache Testmöglichkeit

Abgerufen von „https://alexwiki.bitfactory.at/w/index.php?title=Bfx.Abstract.Model.WebService.dll&oldid=73654“
Keine Kategorien vergebenBearbeiten

Diskussionen