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

Keine Bearbeitungszusammenfassung
Markierung: 2017-Quelltext-Bearbeitung
Markierung: 2017-Quelltext-Bearbeitung
 
(202 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>
&matchString=<Wert für Suche auf Index>
&keyDate=<Stichtag bei zeitlich begrenzbaren Eigenschaften>


===Beispiel Personal===
{{webservice_prerequisites|Intern:Webservice_Eigenschaften_Import_Aktivierung}}
* <code>/New</code>: Anlage eines neuen Objekts.
** 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.


Details zur Anlage eines neuen Personals finden Sie [[Webservice Personalstammdaten Import|hier]]
=== 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.


Optional kann ein neues Personal auch mit dem Aufruf [https://alexwiki.bitfactory.at/wiki/Bfx.Abstract.Model.WebService.dll#Objekt_.C3.A4ndern|'''/Set'''] angelegt werden, wenn folgender Parameter aktiviert ist:
Eine URL kann in eine JSON-Datei konvertiert werden und eine JSON-Datei in eine oder mehrere URLs.


* Systemeinstellungen - Object Import Einstellungen: '''Eigenschaften-Import: Neu erstellen falls nicht gefunden?'''
Ein Datum wird immer als <code>DD.MM.YYYY</code> übertragen.


* <u>''<small>Info Umsetzung:</small>''</u>
==== Schema für URL-Kodierung ====
** ''<small>Issue [https://github.com/bitfactory-software/alex/issues/7363|#7363]</small>''
** ab Version V2022.18


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=]


===Beispiel Benutzer===
'''/Set'''
?objectType=
&indexQuery=
&matchString=
&importType=
&valueString=
[&keyDate=]
[&toDate=]
[&keyString=]


Neuer Benutzer mit Username "USER1"
==== Schema für JSON-File ====
/New?objectType=AlexUser&indexQuery=UserX&matchString=USER1


==Objekt ändern==
Die, dem Webservice mittels POST-Argumentübertragung, zur Verfügung gestellte JSON-Datei muss folgendem Schema entsprechen:


  /Set
  {
?objectType=<Objekttyp auf dem geändert wird>
    "$schema": "https://json-schema.org/draft/2020-12/schema",
&indexQuery=<Index über den das Objekt gefunden wird>
    "title": "Set",
&matchString=<Wert für Suche auf Index>
    "description": "Format für Anfragen an das Set-Webservice",
&importType=<Eigenschaft die geändert werden soll>
    "type": "object",
&valueString=<Wert der der Eigenschaft, URL-Encoded>
    "properties": {
  &keyDate=<Stichtag bei zeitlich begrenzbaren Eigenschaften>
        "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"
    ]
  }


Format für Datum:
==== <code>objectType</code> ====
DD.MM.YYYY
Der <code>objectType</code> enthält den Objekttyp des zu ändernden Objekts.


Ergebnis:
* Für Personal: <code>Employee</code>
Enthält eine etwaige Fehlermeldung.
* Für Benutzer: <code>AlexUser</code>


===Beispiele Personal===
==== <code>indexQuery</code> ====
Der <code>indexQuery</code> enthält den Index über den das Objekt gesucht wird.


Beim Setzen von zeitlich abgrenzbaren Eigenschaften wird der Beginn automatisch begrenzt mit dem 'Ist bis'-Datum der Stammplanungseinheit des Mitarbeiters.
* Für Personal: <code>EmployeeIDX</code>
* Für Benutzer: <code>UserX</code>


Wird ein keyDate mitgegeben, so wird entweder dieses Datum verwendet oder als Beginn das Maximum zwischen keyDate und "Ist bis" genommen.
==== <code>matchString</code> ====
Der <code>matchString</code> enthält den Wert für die Indexsuche.


Wird kein keyDate mitgegeben, so wird entwerder der 1. des aktuellen Monats genommen oder auch das Maximum zwischen keyDate und "Ist bis".
* Für Personal die Personalnummer.
* Für Benutzer der Benutzername.


Beispiel:
==== <code>importType</code> ====
Der <code>importType</code> enthält die Eigenschaft die geändert werden soll.


*Dezember 2021 befindet sich im Status IST
==== <code>valueString</code> ====
*Jänner 2022 befindet sich im Status Planung
Der <code>valueString</code> enthält den Wert der zu setzenden Eigenschaft als Zeichenkette. Eigenschaften können folgende Werte annehmen:
*"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 />
* Zeichenketten: <code>"Mayr"</code>, <code>"Groß"</code>, <code>"Ü"</code>
* Ganze Zahlen: <code>"1"</code>, <code>"2"</code>, <code>"10000"</code>
* Gleitkommazahlen: <code>"1.123"</code>, <code>"1.4567"</code>
* Fremdschlüssel: Verweis auf "Station 1" in Eigenschaft "Stammplanungseinheit"
* Komplexe Werte: Kinder für Pflege-Anspruch oder Anspruchszeile
** Format uncodiert: <code>Property1####Value&Property2####Value ... &PropertyN####Value</code>
** '''Muss in URL codiert werden!'''


*Setzen von Email "test@example.com" bei Personal mit Personalnummer "PNR123"
==== <code>keyDate</code> (optional) ====
Das <code>keyDate</code> enthält den Wert des '''Von'''-Datums der zu setzenden Eigenschaft.


/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=EmployeeEmailAddress&valueString=test@example.com
==== <code>toDate</code> (optional) ====
Das <code>toDate</code> enthält den Wert des '''Bis'''-Datums der zu setzenden Eigenschaft.


*Setzen von Kartennummer "1234567" bei Personal mit Personalnummer "PNR123" ab 01.01.2020
==== <code>keyString</code> (optional) ====
**''<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>''
Der <code>keyString</code> enthält den Schlüsselwert der zu setzenden Eigenschaft.


/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=EmployeeCardID&valueString=1234567&keyDate=01.01.2020
===Formatierung der Ausgabe ===


*Setzen von Zuname "Mustermann" bei Personal mit Personalnummer "PNR123" ab 01.10.2020
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"
    ]
}


/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=Surname&valueString=Mustermann&keyDate=01.10.2020
==Beispiele==


*Setzen von Vorname "Max" bei Personal mit Personalnummer "PNR123"
=== Beispiel: Ein Personal mit Standardinformationen anlegen ===


/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=Forename&valueString=Max
Diese Aufrufe des Webservice:


*Setzen von Beschäftigungsausmaß 62,5% bei Personal mit Personalnummer "PNR123" ab 01.03.2022
/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


/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=EmploymentFactorPercent&valueString=62,5&keyDate=01.03.2022
führen zu diesem Personalstamm:


===Beispiele Benutzer===
{{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 Email "test@example.com" bei User mit Username "USER1"
=== Beispiel: Neues Objekt anlegen ===


  /Set?objectType=AlexUser&indexQuery=UserX&matchString=USER1&importType=UserEmail&valueString=test@example.com
{| 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 Username "USER1NEU" bei User mit Username "USER1"
=== Beispiel: Eigenschaften in Personal ändern ===


/Set?objectType=AlexUser&indexQuery=UserX&matchString=USER1&importType=Username&valueString=USER1NEU
Der Einfachheit halber nehmen wir an, es gibt bereits ein Personal mit Personalnummer <code>1</code>.


==Externe Kennzeichen (Foreign Keys)==
{| class="mw-collapsible mw-collapsed wikitable" style=""
 
! Änderung !! URL Aufruf (codiert) !! JSON Aufruf
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.
|-
 
| Email auf test@example.com ||
Fremdschlüssel stehen für die gängigsten Objekttypen zur Verfügung:
/Set
 
?objectType=Employee
*Berufsgruppe
&indexQuery=EmployeeIDX
*Planungseinheit
&matchString=1
*Qualifikation
&importType=EmployeeEmailAddress
*Vertrag
&valueString=test@example.com
*Lohnartenumschlüsselung
||
 
{
<br />
  "objectType": "Employee",
 
  "indexQuery": "EmployeeIDX",
*Setzen der Berufsgruppe mit externem Kennzeichen "B1" bei Personal mit Personalnummer "1"
  "importType": "EmployeeEmailAddress",
 
  "lines": [
  /Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=1&importType=EmployeeJobGroup&valueString=B1
    {
 
      "matchString": "1",
*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)
      "valueString": "test@example.com"
 
    }
  /Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=1&importType=MasterAllocation&valueString=P1
  ]
 
}
*Setzen der Qualifikation mit externem Kennzeichen "AS" bei Personal mit Personalnummer "1" per 01.03.2022
|-
 
| Kartennumer auf 3 ab 01.01.2020
  /Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=1&importType=EmployeeQualifications&keyString=AS&keyDate=01.03.2022
||
 
/Set
==Eingebettete Objekte (Records)==
?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"
    }
  ]
}
|}


Der Import von eingebetteten Objekten (Records) ist ebenfalls möglich
==== Besonderheiten ====
 
===== Beschäftigungsausmaß =====
Beispiele für eingebettete Objekte:
Die Eigenschaft '''Beschäftigungsausmaß in Prozent''' wird je nach Abrechnungsart unterschiedlich angesprochen:<ref name="issue8393">{{githubissue|8393}}</ref>
 
* nur _7up: <code>EmploymentFactorPercent</code>
*Anspruchszeile am Personal
* nur Standard: <code>BESCH_GRAD_IN_PROZENT</code>
*Informationen über Kinder für Pflegefreistellung
* gemischt: beides erlaubt
 
 
*Setzen von Anspruchszeile bei Personal mit der Personalnummer "PNR123"


=== 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
  /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
EmployeeEntitlement_<span class="col-red">Urlaub</span> → hier muss nach dem _ die Kurzbezeichnung der Anspruchsart gesendet werden


EmployeeRecEntitlementKeyDate → Stichtag der Anspruchszeile
EmployeeRecEntitlementKeyDate → Stichtag der Anspruchszeile
Zeile 147: Zeile 579:
EmployeeRecEntitlementValue → Zusatzanspruch der Anspruchszeile
EmployeeRecEntitlementValue → Zusatzanspruch der Anspruchszeile


keyDate → Beginn-Datum der Anspruchszeile (hier gilt aber auch die oben beschriebene Logik bzgl. dem Maximum zwischen keyDate und "Ist bis")<br />
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")


<br />


*Setzen von Kindern beim Personal (max. 7 Kinder sind möglich) mit der Personalnummer "PNR123"
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.


1. Kind: Franz, Geburtstag: 03.02.2012
=== Beispiel: Eigenschaften in Benutzer ändern ===
/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)==
Der Einfachheit halber nehmen wir an, es gibt bereits einen Benutzer mit Benutzername <code>U1</code>.
 
Beispiele für zeitlich abgegrenzte Eigenschaften:
 
*Inaktivzeiten
 
*Setzen von 'Mutterschutz' bei Personal mit der Personalnummer "PNR123"
 
/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===


{| 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": "string",
  "objectType": "AlexUser",
    "indexQuery": "string",
  "indexQuery": "UserX",
    "importType": "string",
  "importType": "UserEmail",
    "lines": [
  "lines": [
        {
    {
            "matchString": "string",
      "matchString": "U1",
            "valueString": "string",
      "valueString": "test@example.com"
            "importType": "string",
    }
            "keyString": "string",
  ]
            "keyDate": "DD.MM.YYYY"
        }
    ]
  }
  }
 
|-
===Beispiele Personal===
| Benutzername auf U2 ||
 
/Set
Setzen von Kartennummer "1234567" bei Personal mit Personalnummer "1" ab 01.01.2020.
?objectType=AlexUser
 
&indexQuery=UserX
&matchString=U1
&importType=Username
&valueString=U2
||
  {
  {
    "objectType": "Employee",
  "objectType": "AlexUser",
    "indexQuery": "EmployeeIDX",
  "indexQuery": "UserX",
    "importType": "EmployeeCardID",
  "importType": "Username",
    "lines": [
  "lines": [
        {
    {
            "matchString": "1",
      "matchString": "U1",
            "valueString": "1234567",
      "valueString": "U2"
            "keyDate": "01.01.2020"
    }
        }
  ]
    ]
  }
  }
|-
|}


Setzen von Email "test@example.com" bei Personal mit Personalnummer "1" ab 01.01.2020.
=== 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


{
{{AlexBild|Mitarbeiter Birgit Bauer|[[Datei:Bfx.Abstract.Model.WebService.dll 1677587063032.png|300px]]}}
    "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.
==== 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": "Employee",
  "objectType": "AlexUser",
    "indexQuery": "EmployeeIDX",
  "indexQuery": "UserX",
    "importType": "Surname",
  "importType": "UserEmail",
    "lines": [
  "lines": [
        {
    {
            "matchString": "1",
      "matchString": "4",
            "valueString": "Mair",
      "valueString": "birgit.bauer@bitfactory.at"
            "keyDate": "01.01.2020"
    }
        },
  ]
        {
            "matchString": "2",
            "valueString": "Huber",
            "keyDate": "01.02.2020"
        }
    ]
  }
  }


Setzen von Zuname, Vorname, Berufsgruppe und Kind bei Personal mit Personalnummer "1":
==== Ergebnis ====
<div class=" mw-collapsible mw-collapsed" overflow:auto;">
<div>'''JSON Datei'''</div>
<div class="mw-collapsible-content">
  {
  {
    "objectType": "Employee",
"request": "/Set",
    "indexQuery": "EmployeeIDX",
"status": "ok"
    "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"
        }
    ]
  }
  }
</div></div>


Der Inhalt des Files kann dem <code>/Set</code> Webservice auch ge<code>POST</code>et werden
==== Datenbank für Beispiel ====
[https://drive.google.com/open?id=1-NdY1jZcZhxpCMDU_dtqFuRn_yxK07ew&authuser=alex%40bitfactory.at&usp=drive_fs DokuDB Bsp 1]


<br />
=== Cheatsheet ===


==Häufig benutzte Werte==
{| class="mw-collapsible mw-collapsed wikitable" style=""
 
=== Personal ===
 
==== ImportType ====
{| class="wikitable" style=""
|+
!Eigenschaft
!Eigenschaft
!ImportType
!<code>importType</code>
!<code>valueString</code>
!Zusätzliche Informationen
!Zusätzliche Informationen
|-
|-
|Stamm-Planungseinheit
|Stamm-Planungseinheit
|MasterAllocation
|MasterAllocation
|[[Bfx.Abstract.Model.WebService.dll#Referenzen_auf_andere_Objekte|wie konfiguriert]]
|
|
|-
|-
|Zuname
|Zuname
|Surname
|Surname
|Zeichenkette
|
|
|-
|-
|Vorname
|Vorname
|Forename
|Forename
|Zeichenkette
|
|
|-
|-
|Kurzname
|Kurzname
|Nickname
|Nickname
|Zeichenkette
|
|
|-
|-
|Titel vor Name
|Titel vor Name
|EmployeeTitleBeforeName
|EmployeeTitleBeforeName
|Zeichenkette
|
|
|-
|-
|Titel nach Name
|Titel nach Name
|EmployeeTitleAfterName
|EmployeeTitleAfterName
|Zeichenkette
|
|
|-
|-
|Geschlecht
|Geschlecht
|Sex
|Sex
|ValueString: 0 = weiblich; 1 = männlich
|0 = weiblich
 
1 = männlich
|
|-
|-
|Geburtstag
|Geburtstag
|DayOfBirth
|DayOfBirth
|Datum
|
|
|-
|-
|Berufsgruppe
|Berufsgruppe
|EmployeeJobGroup
|EmployeeJobGroup
|[[Bfx.Abstract.Model.WebService.dll#Referenzen_auf_andere_Objekte|wie konfiguriert]]
|
|
|-
|-
|Beschäftigt
|Beschäftigt
|Employed
|Employed
|keyDate für Beschäftigt ab
|leer
toDate für Beschäftigt bis
|<code>keyDate</code> für Beschäftigt ab
 
<code>toDate</code> für Beschäftigt bis
|-
|-
|E-Mail Adresse
|E-Mail Adresse
|EmployeeEmailAddress
|EmployeeEmailAddress
|Zeichenkette
|
|-
|Lohnartenumschlüsselung
|EmployeeAccountToWageTypeMap
|[[Bfx.Abstract.Model.WebService.dll#Referenzen_auf_andere_Objekte|wie konfiguriert]]
|
|
|-
|-
|Kartennummer
|Kartennummer
|EmployeeCardID
|EmployeeCardID
|Zeichenkette
|
|
|-
|-
|Inaktivzeiten
|Inaktivzeiten
|MaternityProtection
|MaternityProtection
|ValueString:
|0 = Schwanger
0 = Schwanger


1 = Mutterschutz
1 = Mutterschutz
Zeile 366: Zeile 756:
3 = Sonstige Inaktivzeit
3 = Sonstige Inaktivzeit


sollte es noch weitere geben, siehe Kundenmodul
weitere kundenspezifische möglich
|
|-
|-
|Telefonnummer
|Telefonnummer
|EmployeePhoneNumber
|EmployeePhoneNumber
|Zeichenkette
|
|
|-
|-
|Sozialversicherungs-Nr.
|Sozialversicherungs-Nr.
|EmployeeSocialInsurance
|EmployeeSocialInsurance
|Zeichenkette
|
|
|-
|-
|Straße
|Straße
|EmployeeStreet
|EmployeeStreet
|Zeichenkette
|
|
|-
|-
|Handzeichen für Pflegedoku
|Handzeichen für Pflegedoku
|EmployeeSignature
|EmployeeSignature
|Zeichenkette
|
|
|-
|-
|Einstufung
|Einstufung
|EmployeeJobEvaluation
|EmployeeJobEvaluation
|Zeichenkette
|
|
|-
|-
|Beschäftigungsausmaß in Prozent <ref name="issue8393"/>
|BESCH_GRAD_IN_PROZENT<br/>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_<span class="col-red" style="color: rgb(183, 58, 58)">NAME</span>
|EmployeeRecEntitlementKeyDate: Stichtag
EmployeeRecEntitlementCustomPostingKeyDate: Zubuchungstag
EmployeeRecEntitlementValue: Zusatzanspruch
|<span class="col-red" style="color: rgb(183, 58, 58)">NAME</span> = Name der Anspruchsart aus Stammdaten
|-
|Kinder für Pflegefreistellung
|EmployeeChildren
| ChildName:    Name
ChildBirthday: Geburtstag
|<code>keyString</code> enthält Index des Kindes
0 = 1. Kind
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
|}
|}
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
== 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 <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.
 
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 <code>ObjectID</code> von ALEX.
* externe Kennzeichen, die zuvor initialisiert werden müssen.
 
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>
 
{{AlexBild|Systemeinstellungen für Objekt Import|[[Datei: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.
* <code>Systemeinstellungen: Object Import Einstellungen: Eigenschaften-Import Pfad</code>
* <code>Systemeinstellungen: Object Import Einstellungen: Eigenschaften-Import Dateierweiterung</code>
 
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.
 
{{AlexBild|Test Object Import|[[Datei: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.
 
{{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