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

Keine Bearbeitungszusammenfassung
Markierung: 2017-Quelltext-Bearbeitung
 
(236 dazwischenliegende Versionen von 7 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.


[[Webservice Personalstammdaten Import|Link zur Funktionsbeschreibung]].
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>


===Beispiele 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.


Neues Personal mit Personalnummer "PNR123" ab 01.01.2020.
=== Formatierung der Anfrage ===
/New?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&keyDate=01.01.2020


===Beispiele Benutzer===
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.


Neuer Benutzer mit Username "USER1"
Eine URL kann in eine JSON-Datei konvertiert werden und eine JSON-Datei in eine oder mehrere URLs.
/New?objectType=AlexUser&indexQuery=UserX&matchString=USER1


==Objekt ändern==
Ein Datum wird immer als <code>DD.MM.YYYY</code> übertragen.


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


Format für Datum:
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:
DD.MM.YYYY


Ergebnis:
'''/New'''
  Enthält eine etwaige Fehlermeldung.
?objectType=
&indexQuery=
&matchString=
  [&keyDate=]


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


Beim Setzen von '''zeitlich abgrenzbaren''' Eigenschaften von Personal wird der Beginn automatisch begrenzt mit ''''Ist bis'.'''
==== Schema für JSON-File ====


Wird ein keyDate mitgegeben, so wird der Beginn mit dem MAXIMUM zwischen keyDate und "Ist bis" genommen.
Die, dem Webservice mittels POST-Argumentübertragung, zur Verfügung gestellte JSON-Datei muss folgendem Schema entsprechen:


Setzen von Email "test@example.com" bei Personal mit Personalnummer "PNR123".
{
/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=EmployeeEmailAddress&valueString=test@example.com
    "$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"
    ]
}


Setzen von Kartennummer "1234567" bei Personal mit Personalnummer "PNR123" ab 01.01.2020.
==== <code>objectType</code> ====
Der <code>objectType</code> enthält den Objekttyp des zu ändernden Objekts.


''<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>''
* Für Personal: <code>Employee</code>
/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=EmployeeCardID&valueString=1234567&keyDate=01.01.2020
* Für Benutzer: <code>AlexUser</code>


Setzen von Zuname "Mustermann" bei Personal mit Personalnummer "PNR123" ab 01.10.2020.
==== <code>indexQuery</code> ====
/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=Surname&valueString=Mustermann&keyDate=01.10.2020
Der <code>indexQuery</code> enthält den Index über den das Objekt gesucht wird.


Setzen von Vorname "Max" bei Personal mit Personalnummer "PNR123".
* Für Personal: <code>EmployeeIDX</code>
/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=Forname&valueString=Max
* Für Benutzer: <code>UserX</code>


===Beispiele Benutzer===
==== <code>matchString</code> ====
Der <code>matchString</code> enthält den Wert für die Indexsuche.


Setzen von Email "test@example.com" bei User mit Username "USER1".
* Für Personal die Personalnummer.
/Set?objectType=AlexUser&indexQuery=UserX&matchString=USER1&importType=UserEmail&valueString=test@example.com
* Für Benutzer der Benutzername.


Setzen von Username "USER1NEU" bei User mit Username "USER1".
==== <code>importType</code> ====
/Set?objectType=AlexUser&indexQuery=UserX&matchString=USER1&importType=Username&valueString=USER1NEU
Der <code>importType</code> enthält die Eigenschaft die geändert werden soll.


==Externe Kennzeichen (Foreign Keys)==
==== <code>valueString</code> ====
Der <code>valueString</code> enthält den Wert der zu setzenden Eigenschaft als Zeichenkette. Eigenschaften können folgende Werte annehmen:


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.
* 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!'''


Fremdschlüssel stehen für die gängigsten Objekttypen zur Verfügung:
==== <code>keyDate</code> (optional) ====
Das <code>keyDate</code> enthält den Wert des '''Von'''-Datums der zu setzenden Eigenschaft.


*Berufsgruppe
==== <code>toDate</code> (optional) ====
*Planungseinheit
Das <code>toDate</code> enthält den Wert des '''Bis'''-Datums der zu setzenden Eigenschaft.
*Vertrag
*Qualifikation
*Lohnartenumschlüsselung


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


Der Import von eingebetteten Objekten (Records) ist ebenfalls möglich.
===Formatierung der Ausgabe ===


Beispiele für eingebettete Objekte:
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"
    ]
}


*Anspruchszeile am Personal
==Beispiele==
*Informationen über Kinder für Pflegefreistellung


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


Setzen von Anspruchszeile bei Personal.
Diese Aufrufe des Webservice:
/Set?objectType=Employee&indexQuery=EmployeeIDX&matchString=PNR123&importType=EmployeeEntitlement_Urlaub&valueString=EmployeeRecEntitlementKeyDate####02.02.2012&EmployeeRecEntitlementCustomPostingKeyDate####03.02.2012&EmployeeRecEntitlementValue####200,00&keyDate=01.10.2020


==Ausgabe==
/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


Json-Objekt in der Form:
führen zu diesem Personalstamm:


{ "request" : ""
{{AlexBild2
, "status" : ""
|'''Personalstammdaten importieren'''
, "details" : ""
|'''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]]
||}}


*"request": Angeforderter Request als "Handshake"
=== Beispiel: Neues Objekt anlegen ===
*"status": "ok" oder "error"
*"details": Optionale Detailinformationen bei "error"


==Dateiimport==
{| 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
|}


Der Pfad für die Importfiles kann in den Systemeinstellungen in der Gruppe <code>Object Import Einstellungen</code> im Property <code>Eigenschaften-Import Pfad</code> festgelegt werden. Die gewünschte Dateierweiterung kann im Property <code>Eigenschaften-Import Dateierweiterung</code> eingestellt werden.
=== Beispiel: Eigenschaften in Personal ändern ===


===Format für Datei===
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": "string",
  "objectType": "Employee",
    "indexQuery": "string",
  "indexQuery": "EmployeeIDX",
    "importType": "string",
  "importType": "EmployeeEmailAddress",
    "lines": [
  "lines": [
        {
    {
            "matchString": "string",
      "matchString": "1",
            "valueString": "string",
      "valueString": "test@example.com"
            "keyDate": "DD.MM.YYYY"
    }
        }
  ]
    ]
}
|-
| 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"
    }
  ]
  }
  }
|}
==== 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
=== 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
EmployeeRecEntitlementKeyDate → Stichtag der Anspruchszeile


===Beispiele Personal===
EmployeeRecEntitlementCustomPostingKeyDate → Zubuchungstag der Anspruchszeile


Setzen von Kartennummer "1234567" bei Personal mit Personalnummer "1" ab 01.01.2020.
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 <span>Alex<sup>®</sup></span> eingegeben werden.
=== Beispiel: Eigenschaften in Benutzer ändern ===
Der Einfachheit halber nehmen wir an, es gibt bereits einen Benutzer mit Benutzername <code>U1</code>.
{| 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": "Employee",
  "objectType": "AlexUser",
    "indexQuery": "EmployeeIDX",
  "indexQuery": "UserX",
    "importType": "EmployeeCardID",
  "importType": "UserEmail",
    "lines": [
  "lines": [
        {
    {
            "matchString": "1",
      "matchString": "U1",
            "valueString": "1234567",
      "valueString": "test@example.com"
            "keyDate": "01.01.2020"
    }
        }
  ]
    ]
  }
  }
|-
| 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
{{AlexBild|Mitarbeiter Birgit Bauer|[[Datei:Bfx.Abstract.Model.WebService.dll 1677587063032.png|300px]]}}


Setzen von Email "test@example.com" bei Personal mit Personalnummer "1" ab 01.01.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": "EmployeeEmailAddress",
  "importType": "UserEmail",
    "lines": [
  "lines": [
        {
    {
            "matchString": "1",
      "matchString": "4",
            "valueString": "test@example.com",
      "valueString": "birgit.bauer@bitfactory.at"
            "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.
==== 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"
    "importType": "Surname",
    "lines": [
        {
            "matchString": "1",
            "valueString": "Mair",
            "keyDate": "01.01.2020"
        },
        {
            "matchString": "2",
            "valueString": "Huber",
            "keyDate": "01.02.2020"
        }
    ]
  }
  }
</div></div>
==== Datenbank für Beispiel ====
[https://drive.google.com/open?id=1-NdY1jZcZhxpCMDU_dtqFuRn_yxK07ew&authuser=alex%40bitfactory.at&usp=drive_fs DokuDB Bsp 1]
=== Cheatsheet ===
{| 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
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
<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
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 <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
|}
== 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]]|}}


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