Bfx.Abstract.Model.WebService.dll: Unterschied zwischen den Versionen

Keine Bearbeitungszusammenfassung
Markierung: 2017-Quelltext-Bearbeitung
Markierung: 2017-Quelltext-Bearbeitung
 
(210 dazwischenliegende Versionen von 6 Benutzern werden nicht angezeigt)
Zeile 1: Zeile 1:
{{DISPLAYTITLE:Webservice - Objekte anlegen und ändern}}
{{DISPLAYTITLE:Webservice - Objekte anlegen und ändern}}


Ab Version 2021.16 können beliebige Objekte angelegt und deren Eigenschaften (z.B. Zuname, E-Mail Adressen, etc.) über diese Webservice Schnittstelle geändert werden.
Das [[Webservice]] - '''Objekte anlegen und ändern''' ist eine [[Programmfunktion]] zum Anlegen von [[Objekttyp#Objekt|Objekten]] eines [[Objekttyp]]s und zum Ändern von [[Objekttyp#Eigenschaften|Eigenschaften]] eines [[Objekttyp#Objekt|Objekts]] über das HTTP-Protokoll.


Es kann dazu verwendet werden
* '''Personalstammdaten zu importieren'''
* Benutzerstammdaten zu importieren
* [[Eigenschaften_importieren|Eigenschaften zu importieren]]


==Objekt anlegen==
== Ausgangssituation ==


  /New
=== Voraussetzungen ===
  ?objectType=<Objekttyp des neuen Objektes>
 
  &indexQuery=<Index für Verifizierung>
{{webservice_prerequisites|Intern:Webservice_Eigenschaften_Import_Aktivierung}}
  &matchString=<Wert für Suche auf Index>
* <code>/New</code>: Anlage eines neuen Objekts.
  &keyDate=<Stichtag bei zeitlich begrenzbaren Eigenschaften>
** kann entfallen wenn der Parameter <code>Systemeinstellungen: Object Import Einstellungen: Eigenschaften-Import: Neu erstellen falls nicht gefunden?</code> aktiviert ist. <ref name="issue7363">{{githubissue|7363}}</ref>
* <code>/Set</code>: Ändern eines bestehenden Objekts.
 
=== Formatierung der Anfrage ===
 
Die Daten werden dem Webservice entweder '''in der URL kodiert''' als '''GET'''-Argumentübertragung, oder als '''[https://de.wikipedia.org/wiki/JavaScript_Object_Notation 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 <code>DD.MM.YYYY</code> übertragen.
 
==== Schema für URL-Kodierung ====
 
Der [https://de.wikipedia.org/wiki/URL-Encoding Prozent-Encodierte] [https://de.wikipedia.org/wiki/Query-String 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",
        "lines"
    ]
}
 
==== <code>objectType</code> ====
Der <code>objectType</code> enthält den Objekttyp des zu ändernden Objekts.
 
* Für Personal: <code>Employee</code>
* Für Benutzer: <code>AlexUser</code>
 
==== <code>indexQuery</code> ====
Der <code>indexQuery</code> enthält den Index über den das Objekt gesucht wird.


===Beispiel Personal===
* Für Personal: <code>EmployeeIDX</code>
* Für Benutzer: <code>UserX</code>


Details zur Anlage eines neuen Personals finden Sie [[Webservice Personalstammdaten Import|hier]]
==== <code>matchString</code> ====
Der <code>matchString</code> enthält den Wert für die Indexsuche.


===Beispiel Benutzer===
* Für Personal die Personalnummer.
* Für Benutzer der Benutzername.


Neuer Benutzer mit Username "USER1"
==== <code>importType</code> ====
/New?objectType=AlexUser&indexQuery=UserX&matchString=USER1
Der <code>importType</code> enthält die Eigenschaft die geändert werden soll.


==Objekt ändern==
==== <code>valueString</code> ====
Der <code>valueString</code> enthält den Wert der zu setzenden Eigenschaft als Zeichenkette. Eigenschaften können folgende Werte annehmen:


/Set
* Zeichenketten: <code>"Mayr"</code>, <code>"Groß"</code>, <code>"Ü"</code>
?objectType=<Objekttyp auf dem geändert wird>
* Ganze Zahlen: <code>"1"</code>, <code>"2"</code>, <code>"10000"</code>
&indexQuery=<Index über den das Objekt gefunden wird>
* Gleitkommazahlen: <code>"1.123"</code>, <code>"1.4567"</code>
&matchString=<Wert für Suche auf Index>
* Fremdschlüssel: Verweis auf "Station 1" in Eigenschaft "Stammplanungseinheit"
&importType=<Eigenschaft die geändert werden soll>
* Komplexe Werte: Kinder für Pflege-Anspruch oder Anspruchszeile
&valueString=<Wert der der Eigenschaft, URL-Encoded>
** Format uncodiert: <code>Property1####Value&Property2####Value ... &PropertyN####Value</code>
&keyDate=<Stichtag bei zeitlich begrenzbaren Eigenschaften>
** '''Muss in URL codiert werden!'''


Format für Datum:
==== <code>keyDate</code> (optional) ====
DD.MM.YYYY
Das <code>keyDate</code> enthält den Wert des '''Von'''-Datums der zu setzenden Eigenschaft.


Ergebnis:
==== <code>toDate</code> (optional) ====
Enthält eine etwaige Fehlermeldung.
Das <code>toDate</code> enthält den Wert des '''Bis'''-Datums der zu setzenden Eigenschaft.


===Beispiele Personal===
==== <code>keyString</code> (optional) ====
Der <code>keyString</code> enthält den Schlüsselwert der zu setzenden Eigenschaft.


Beim Setzen von zeitlich abgrenzbaren Eigenschaften wird der Beginn automatisch begrenzt mit dem 'Ist bis'-Datum der Stammplanungseinheit des Mitarbeiters.
===Formatierung der Ausgabe ===


Wird ein keyDate mitgegeben, so wird entweder dieses Datum verwendet oder als Beginn das Maximum zwischen keyDate und "Ist bis" genommen.
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"
    ]
}


Wird kein keyDate mitgegeben, so wird entwerder der 1. des aktuellen Monats genommen oder auch das Maximum zwischen keyDate und "Ist bis".
==Beispiele==


Beispiel:
=== Beispiel: Ein Personal mit Standardinformationen anlegen ===


*Dezember 2021 befindet sich im Status IST
Diese Aufrufe des Webservice:
*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<br />


<br />
/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


*Setzen von Email "test@example.com" bei Personal mit Personalnummer "PNR123"
führen zu diesem Personalstamm:


/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=EmployeeEmailAddress&valueString=test@example.com
{{AlexBild2
|'''Personalstammdaten importieren'''
|'''Eigenschaften'''
|'''{{Alex}}-Personalstamm Gruppe: Allgemein'''
|
* Personalnummer
* Zuname
* Vorname
* Kurzname
* Titel vor Name
* Titel nach Name
* Geschlecht
* Geburtstag
* Berufsgruppe
* Beschäftigungszeitraum
* Stamm-Planungseinheit
* E-Mail-Adresse
[[Datei:Balken weiss 400.png]]
|[[Datei:Webservice_Personalstammdaten_Import.png]]
||}}


*Setzen von Kartennummer "1234567" bei Personal mit Personalnummer "PNR123" ab 01.01.2020
=== Beispiel: Neues Objekt anlegen ===
**''<small>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!</small>''


  /Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=EmployeeCardID&valueString=1234567&keyDate=01.01.2020
{| class="mw-collapsible mw-collapsed wikitable" style=""
! 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
|}


*Setzen von Zuname "Mustermann" bei Personal mit Personalnummer "PNR123" ab 01.10.2020
=== Beispiel: Eigenschaften in Personal ändern ===


  /Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=Surname&valueString=Mustermann&keyDate=01.10.2020
Der Einfachheit halber nehmen wir an, es gibt bereits ein Personal mit Personalnummer <code>1</code>.
 
{| class="mw-collapsible mw-collapsed wikitable" style=""
! Ä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"
    }
  ]
}
<ref name="issue8070">{{githubissue|8070}}</ref>
|-
| 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 ([[Bfx.Abstract.Model.WebService.dll#Datums-Automatik|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"
    }
  ]
}
|}


*Setzen von Vorname "Max" bei Personal mit Personalnummer "PNR123"
==== Besonderheiten ====
===== Beschäftigungsausmaß =====
Die Eigenschaft '''Beschäftigungsausmaß in Prozent''' wird je nach Abrechnungsart unterschiedlich angesprochen:<ref name="issue8393">{{githubissue|8393}}</ref>
* nur _7up: <code>EmploymentFactorPercent</code>
* nur Standard: <code>BESCH_GRAD_IN_PROZENT</code>
* gemischt: beides erlaubt


  /Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=Forename&valueString=Max
=== 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_<span class="col-red" style="color: rgb(183, 58, 58)">Urlaub</span> → hier muss nach dem _ der Name der Anspruchsart gesendet werden


*Setzen von Beschäftigungsausmaß 62,5% bei Personal mit Personalnummer "PNR123" ab 01.03.2022
EmployeeRecEntitlementKeyDate → Stichtag der Anspruchszeile


/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=EmploymentFactorPercent&valueString=62,5&keyDate=01.03.2022
EmployeeRecEntitlementCustomPostingKeyDate → Zubuchungstag der Anspruchszeile


===Beispiele Benutzer===
EmployeeRecEntitlementValue → Zusatzanspruch der Anspruchszeile


*Setzen von Email "test@example.com" bei User mit Username "USER1"
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")


/Set?objectType=AlexUser&indexQuery=UserX&matchString=USER1&importType=UserEmail&valueString=test@example.com


*Setzen von Username "USER1NEU" bei User mit Username "USER1"
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 <span>Alex<sup>®</sup></span> eingegeben werden.


/Set?objectType=AlexUser&indexQuery=UserX&matchString=USER1&importType=Username&valueString=USER1NEU
=== Beispiel: Eigenschaften in Benutzer ändern ===


==Externe Kennzeichen (Foreign Keys)==
Der Einfachheit halber nehmen wir an, es gibt bereits einen Benutzer mit Benutzername <code>U1</code>.


Der Import von Externen Kennzeichen (Foreign Keys) ist über die interne <code>ObjectID</code> von ALEX möglich oder über Fremdschlüssel, die zuvor initialisiert werden müssen.
{| class="mw-collapsible mw-collapsed wikitable" style=""
! Ä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"
    }
  ]
}
|-
|}


Fremdschlüssel stehen für die gängigsten Objekttypen zur Verfügung:
=== 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


*Berufsgruppe
{{AlexBild|Mitarbeiter Birgit Bauer|[[Datei:Bfx.Abstract.Model.WebService.dll 1677587063032.png|300px]]}}
*Planungseinheit
*Qualifikation
*Vertrag
*Lohnartenumschlüsselung


<br />
==== 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.


*Setzen der Berufsgruppe mit externem Kennzeichen "B1" bei Personal mit Personalnummer "1"
{
  "objectType": "AlexUser",
  "indexQuery": "UserX",
  "importType": "UserEmail",
  "lines": [
    {
      "matchString": "4",
      "valueString": "birgit.bauer@bitfactory.at"
    }
  ]
}


/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=1&importType=EmployeeJobGroup&valueString=B1
==== Ergebnis ====
<div class=" mw-collapsible mw-collapsed" overflow:auto;">
<div>'''JSON Datei'''</div>
<div class="mw-collapsible-content">
{
"request": "/Set",
"status": "ok"
}
</div></div>


*Setzen der Planungseinheit mit externem Kennzeichen "P1" bei Personal mit Personalnummer "1"
==== Datenbank für Beispiel ====
[https://drive.google.com/open?id=1-NdY1jZcZhxpCMDU_dtqFuRn_yxK07ew&authuser=alex%40bitfactory.at&usp=drive_fs DokuDB Bsp 1]


/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=1&importType=MasterAllocation&valueString=P1
=== Cheatsheet ===


*Setzen der Qualifikation mit externem Kennzeichen "AS" bei Personal mit Personalnummer "1" per 01.03.2022
{| class="mw-collapsible mw-collapsed wikitable" style=""
!Eigenschaft
!<code>importType</code>
!<code>valueString</code>
!Zusätzliche Informationen
|-
|Stamm-Planungseinheit
|MasterAllocation
|[[Bfx.Abstract.Model.WebService.dll#Referenzen_auf_andere_Objekte|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


/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=1&importType=EmployeeQualifications&keyString=AS&keyDate=01.03.2022
1 = männlich
|
|-
|Geburtstag
|DayOfBirth
|Datum
|
|-
|Berufsgruppe
|EmployeeJobGroup
|[[Bfx.Abstract.Model.WebService.dll#Referenzen_auf_andere_Objekte|wie konfiguriert]]
|
|-
|Beschäftigt
|Employed
|leer
|<code>keyDate</code> für Beschäftigt ab


==Eingebettete Objekte (Records)==
<code>toDate</code> für Beschäftigt bis
|-
|E-Mail Adresse
|EmployeeEmailAddress
|Zeichenkette
|
|-
|Lohnartenumschlüsselung
|EmployeeAccountToWageTypeMap
|[[Bfx.Abstract.Model.WebService.dll#Referenzen_auf_andere_Objekte|wie konfiguriert]]
|
|-
|Kartennummer
|EmployeeCardID
|Zeichenkette
|
|-
|Inaktivzeiten
|MaternityProtection
|0 = Schwanger


Der Import von eingebetteten Objekten (Records) ist ebenfalls möglich
1 = Mutterschutz


Beispiele für eingebettete Objekte:
2 = Karenz


*Anspruchszeile am Personal
3 = Sonstige Inaktivzeit
*Informationen über Kinder für Pflegefreistellung


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 <ref name="issue8393"/>
|BESCH_GRAD_IN_PROZENT<br/>EmploymentFactorPercent
|Gleitkommazahl
|Je nach Abrechnungsart unterschiedlich:


*Setzen von Anspruchszeile bei Personal mit der Personalnummer "PNR123"
nur _7up: EmploymentFactorPercent


/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
nur Standard: BESCH_GRAD_IN_PROZENT


EmployeeEntitlement_<span class="col-red">Urlaub</span> → hier muss nach dem _ die Kurzbezeichnung der Anspruchsart gesendet werden
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_<span class="col-red" style="color: rgb(183, 58, 58)">NAME</span>
|EmployeeRecEntitlementKeyDate: Stichtag


EmployeeRecEntitlementKeyDate → Stichtag der Anspruchszeile
EmployeeRecEntitlementCustomPostingKeyDate: Zubuchungstag


EmployeeRecEntitlementCustomPostingKeyDate → Zubuchungstag der Anspruchszeile
EmployeeRecEntitlementValue: Zusatzanspruch


EmployeeRecEntitlementValue → Zusatzanspruch der Anspruchszeile
|<span class="col-red" style="color: rgb(183, 58, 58)">NAME</span> = Name der Anspruchsart aus Stammdaten
|-
|Kinder für Pflegefreistellung
|EmployeeChildren
| ChildName:    Name


keyDate → Beginn-Datum der Anspruchszeile (hier gilt aber auch die oben beschriebene Logik bzgl. dem Maximum zwischen keyDate und "Ist bis")<br />
ChildBirthday: Geburtstag
|<code>keyString</code> enthält Index des Kindes
0 = 1. Kind


<br />
6 = 7. Kind
|
|-
|Poolzuteilungen
|PoolAllocations
|leer
|<code>keyString</code> enthält Planungseinheit [[Bfx.Abstract.Model.WebService.dll#Referenzen_auf_andere_Objekte|wie konfiguriert]]
<code>keyDate</code> und <code>toDate</code> für Zeitbereich der Poolzuteilung
|}


*Setzen von Kindern beim Personal (max. 7 Kinder sind möglich) mit der Personalnummer "PNR123"
== Zeitbereich Korrektur bei Personal ==


1. Kind: Franz, Geburtstag: 03.02.2012
Im Personalstamm gibt es Eigenschaften, die zeitlich abgegrenzt werden können, zum Beispiel:
/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=EmployeeChildren&keyString=0&valueString=ChildName%23%23%23%23Franz%26ChildBirthday%23%23%23%2303.02.2012
* Stammplanungseinheit
2. Kind: Hans, Geburtstag: 03.02.2013
* Beschäftigungsgrad
/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=EmployeeChildren&keyString=1&valueString=ChildName%23%23%23%23Hans%26ChildBirthday%23%23%23%2303.02.2013
* Sollstunden
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)==
Für deren Änderung muss ein Zeitbereich angegeben werden.


Beispiele für zeitlich abgegrenzte Eigenschaften:
Diese Eigenschaften beeinflussen die Berechnung der Zeitkonten und dürfen sich auf abgeschlossenen Plänen nicht ändern.


*Inaktivzeiten
Darum können keine Eigenschaften vor dem '''Abgeschlossen-Bis'''-Datum der aktuellen Stammplanungseinheit des Personals durch das Webservice geändert werden.


*Setzen von 'Mutterschutz' bei Personal mit der Personalnummer "PNR123"
Der Zeitbereich der Änderung wird nach folgenden Kriterien angenommen:
* wird ein <code>keyDate</code> übergeben, wird dieses verwendet.
* wird kein <code>keyDate</code> an die Schnittstelle übergeben, wird automatisch der '''1. des aktuellen Monats''' angenommen.
* wird ein <code>toDate</code> übergeben, wird dieses verwendet.
* wird kein <code>toDate</code> an die Schnittstelle übergeben, wird automatisch '''unendlich''' angenommen.


/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=MaternityProtection&valueString=1&keyDate=01.01.2020&toDate=01.08.2020
Der entstandene Zeitbereich wird nun mit dem '''Abgeschlossen-Bis'''-Datum begrenzt.


==Ausgabe==
=== 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.  |  |  |  |  |  | * | * | * | * | * |->


Json-Objekt in der Form:
==Referenzen auf andere Objekte==


{ "request" : ""
Der Import Referenzen auf andere Objekte ist möglich über
, "status" : ""
, "details" : ""
}


*"request": Angeforderter Request als "Handshake"
* die interne <code>ObjectID</code> von ALEX.
*"status": "ok" oder "error"
* externe Kennzeichen, die zuvor initialisiert werden müssen.
*"details": Optionale Detailinformationen bei "error"


==File Import==
Sind Externe Kennzeichen gesetzt kann trotzdem über die <code>ObjectID</code> importiert werden:
* Parameter <code>Systemeinstellungen: Object Import Einstellungen: Eigenschaften-Import: Referenzen entsprechen 'ObjektID'?</code>


Der Pfad für die Importfiles kann in den Systemeinstellungen in der Gruppe "Object Import Einstellungen" beim Parameter "Eigenschaften-Import Pfad" festgelegt werden.
{{AlexBild|Systemeinstellungen für Objekt Import|[[Datei:Bfx.Abstract.Model.WebService.dll 1665738827331.png]]|}}


Die gewünschte Dateierweiterung kann beim Parameter "Eigenschaften-Import Dateierweiterung" eingetragen werden.
Fremdschlüssel stehen für folgende Objekttypen zur Verfügung:


Der definierte Ordner wird alle 2 Minuten auf neue Dateien geprüft. 
*Berufsgruppe
*Planungseinheit
*Qualifikation
*Vertrag
*Lohnartenumschlüsselung


===Format für Datei===
==File Import==


{
Zusätzlich zum Webservice können Dateien im JSON-Format auch über einen Daemon-Prozess importiert werden.
    "objectType": "string",
    "indexQuery": "string",
    "importType": "string",
    "lines": [
        {
            "matchString": "string",
            "valueString": "string",
            "keyDate": "DD.MM.YYYY"
        }
    ]
}


===Beispiele Personal===
Der Daemon muss im Configfile konfiguriert werden.


Setzen von Kartennummer "1234567" bei Personal mit Personalnummer "1" ab 01.01.2020.
Der Pfad und die Endung der Dateien kann in den Systemeinstellungen eingestellt werden.
* <code>Systemeinstellungen: Object Import Einstellungen: Eigenschaften-Import Pfad</code>
* <code>Systemeinstellungen: Object Import Einstellungen: Eigenschaften-Import Dateierweiterung</code>


{
Dateien werden alle 2 Minuten importiert.
    "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.
==Interaktiver Test von POST ==


{
Unter Systemeinstellung -> rechte Maustaste auf Reiter -> Test Object Import kann ein Eingabefenster geöffnet werden.
    "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.
In dieses Eingabefenster können Dateien im JSON-Format kopiert werden.


{
Damit kann das Format des POST Mechanismus auf Richtigkeit getestet werden.
    "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":
{{AlexBild|Test Object Import|[[Datei:Test Object Import 01.png]]|}}
{
    "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 <code>/Set</code> Webservice auch ge<code>POST</code>et werden
==Protokollierung==
Damit Änderungen über die Webservice-Schnittstelle protokolliert werden, muss beim Parameter "Eigenschaften-Import: Benutzer für Webservice" ein Benutzer hinterlegt werden.


<br />
Der hinterlegte Benutzer benötigt SUPERVISOR-Berechtigung für das ganze System.


==Häufig benutzte Werte==
{{AlexBild|Benutzer WEBSERVICE|[[Datei:Bfx.Abstract.Model.WebService.dll 1662712309556.png]]|}}


{{AlexBild|Protokoll Personal|[[Datei:Bfx.Abstract.Model.WebService.dll 1662712457699.png]]|}}


== Fußnoten ==


==Bit Factory interne Zusatzinfos==
[[Category:Schnittstellen]]
[[Intern:Webservice Eigenschaften Import Aktivierung|Aktivierung]]
[[Category:Teamleader-Angebotsunterlagen]]
[[Kategorie:Webservice]]

Aktuelle Version vom 15. Januar 2024, 14:18 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

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]
  • /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",
       "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!

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:

Personalstammdaten importieren
Eigenschaften Alex®-Personalstamm Gruppe: Allgemein
  • Personalnummer
  • Zuname
  • Vorname
  • Kurzname
  • Titel vor Name
  • Titel nach Name
  • Geschlecht
  • Geburtstag
  • Berufsgruppe
  • Beschäftigungszeitraum
  • Stamm-Planungseinheit
  • E-Mail-Adresse

Balken weiss 400.png

Webservice Personalstammdaten Import.png

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"
    }
  ]
}

[2]

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

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

JSON Datei
{
"request": "/Set",
"status": "ok"
}

Datenbank für Beispiel

DokuDB Bsp 1

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

toDate für Beschäftigt bis

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

keyDate und toDate für Zeitbereich der Poolzuteilung

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

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
Test Object Import 01.png

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

Fußnoten

Diskussionen