WorktimeApi Resource

Funktionalität rund um die Zeit(daten)erfassung
Generell gilt, dass nur am HELIUM V angemeldete REST-API Benutzer diese Funktionen durchführen können. Weiters werden die Rechte des Benutzers berücksichtigt. Er kann - wenn er darf - im Namen einer anderen Person/Mitarbeiter die Buchungen durchführen.

Der Benutzer der API ist dafür verantwortlich, dass chronologisch richtige Zeitbuchungen entstehen, da der HELIUM V Server zum gegebenen Zeitpunkt (noch) nicht in Zukunft schauen kann.

Weiterführende Dokumentation kann im HELIUM V Benutzerhandbuch nachgelesen werden.

GET /api/v1/worktime/activities

Liefert eine Liste aller verfügbaren Tätigkeiten (Arbeitszeitartikel) die innerhalb der Zeiterfassung durchgeführt werden können.

Request Parameters
name type description constraints
filter_cnr query (optional) die Sondertätigkeiten auf diese Kennung einschränken  
limit query (optional) die maximale Anzahl von gelieferten Einträgen. Default ist 50. int
startIndex query (optional) die Id (eines ItemEntry Eintrags, mit dem die Liste beginnen soll int
userid query des am HELIUM V Servers angemeldeten Benutzers  
Response Body
media type data type description
application/json array of ItemEntry (JSON) eine (leere) Liste der für den Benutzer verfügbaren Tätigkeiten
application/xml;charset=UTF-8 object

Example

Request
GET /api/v1/worktime/activities
Content-Type: */*
Accept: application/json

                
...
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
[ {
  "cnr" : "...",
  "description" : "...",
  "description2" : "...",
  "name" : "...",
  "shortName" : "...",
  "stockAmount" : 12345.0,
  "costs" : 12345.0,
  "billOfMaterialType" : "...",
  "available" : true,
  "comments" : [ "...", "..." ],
  "hidden" : true,
  "unitCnr" : "...",
  "typeCnr" : "...",
  "itemgroupCnr" : "...",
  "itemclassCnr" : "...",
  "revision" : "...",
  "stockAmountInfo" : {
    "stockAmount" : 12345.0,
    "reservedAmount" : 12345.0,
    "missingAmount" : 12345.0,
    "availableAmount" : 12345.0
  },
  "referenceNumber" : "...",
  "index" : "...",
  "preferredType" : "...",
  "customerItemCnr" : "...",
  "id" : 12345
} ]

POST /api/v1/worktime/barcode

Eine HELIUM V Barcode Zeitbuchung erzeugen.

Request Body
media type data type description
application/json BarcodeRecordingEntry (JSON) Datenstruktur für eine (belegbezogene) Zeitbuchung über den Barcode
application/xml;charset=UTF-8 object

Example

Request
POST /api/v1/worktime/barcode
Content-Type: application/json

                
{
  "barcode" : "...",
  "machineId" : 12345,
  "forStaffId" : 12345,
  "forStaffCnr" : "...",
  "userId" : "...",
  "year" : 12345,
  "month" : 12345,
  "day" : 12345,
  "hour" : 12345,
  "minute" : 12345,
  "second" : 12345,
  "where" : "..."
}
Response
HTTP/1.1 201 Created

POST /api/v1/worktime/batch

Request Parameters
name type description
userid query
Request Body
media type data type
application/json TimeRecordingBatchEntryList (JSON)
application/xml timeRecordingBatchEntryList (XML)

Example

Request
POST /api/v1/worktime/batch
Content-Type: application/json

                
{
  "entries" : [ {
    "recordingEnum" : "Coming",
    "HVID" : 12345,
    "todoType" : "PROJECT",
    "hvDetailId" : 12345,
    "remark" : "...",
    "detailItemCnr" : "...",
    "forStaffId" : 12345,
    "forStaffCnr" : "...",
    "userId" : "...",
    "year" : 12345,
    "month" : 12345,
    "day" : 12345,
    "hour" : 12345,
    "minute" : 12345,
    "second" : 12345,
    "where" : "..."
  }, {
    "recordingEnum" : "Stop",
    "HVID" : 12345,
    "todoType" : "NOTINITIALIZED",
    "hvDetailId" : 12345,
    "remark" : "...",
    "detailItemCnr" : "...",
    "forStaffId" : 12345,
    "forStaffCnr" : "...",
    "userId" : "...",
    "year" : 12345,
    "month" : 12345,
    "day" : 12345,
    "hour" : 12345,
    "minute" : 12345,
    "second" : 12345,
    "where" : "..."
  } ],
  "rowCount" : 12345
}
Response
HTTP/1.1 201 Created

POST /api/v1/worktime/coming

Eine KOMMT-Buchung durchführen.

Request Body
media type data type description
application/json TimeRecordingEntry (JSON) ist die Standardzeitbuchung Datenstruktur TimeRecordingEntry
application/xml timeRecordingEntry (XML)

Example

Request
POST /api/v1/worktime/coming
Content-Type: application/json

                
{
  "forStaffId" : 12345,
  "forStaffCnr" : "...",
  "userId" : "...",
  "year" : 12345,
  "month" : 12345,
  "day" : 12345,
  "hour" : 12345,
  "minute" : 12345,
  "second" : 12345,
  "where" : "..."
}
Response
HTTP/1.1 201 Created

GET /api/v1/worktime/documenttypes

Liefert eine Liste aller verfügbaren Belegarten die für die Zeiterfassung verwendet werden können.

Belegarten sind typischerweise Angebot, Auftrag, Los oder Projekt

Request Parameters
name type description
userid query der am HELIUM V Server angemeldete Benutzer
Response Body
media type data type description
application/json array of DocumentType (JSON) eine (leere) Liste von verfügbaren/bebuchbaren Belegarten
application/xml;charset=UTF-8 object

Example

Request
GET /api/v1/worktime/documenttypes
Content-Type: */*
Accept: application/json

                
...
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
[ {
  "id" : "...",
  "documentName" : "..."
} ]

POST /api/v1/worktime/going

Eine GEHT-Buchung durchführen.

Request Body
media type data type description
application/json TimeRecordingEntry (JSON) ist die Standardzeitbuchung Datenstruktur TimeRecordingEntry
application/xml timeRecordingEntry (XML)

Example

Request
POST /api/v1/worktime/going
Content-Type: application/json

                
{
  "forStaffId" : 12345,
  "forStaffCnr" : "...",
  "userId" : "...",
  "year" : 12345,
  "month" : 12345,
  "day" : 12345,
  "hour" : 12345,
  "minute" : 12345,
  "second" : 12345,
  "where" : "..."
}
Response
HTTP/1.1 201 Created

POST /api/v1/worktime/machine

Ein Start oder Stop einer Maschine durchführen.

Die anzugebende Maschine-Id kann über die Resource machine ermittelt werden

Request Body
media type data type description
application/json MachineRecordingEntry (JSON) Datenstruktur zur Speicherung einer Maschinen-Buchung
application/xml machineRecordingEntry (XML)

Example

Request
POST /api/v1/worktime/machine
Content-Type: application/json

                
{
  "machineId" : 12345,
  "productionWorkplanId" : 12345,
  "machineRecordingType" : "STOP",
  "remark" : "...",
  "forStaffId" : 12345,
  "forStaffCnr" : "...",
  "userId" : "...",
  "year" : 12345,
  "month" : 12345,
  "day" : 12345,
  "hour" : 12345,
  "minute" : 12345,
  "second" : 12345,
  "where" : "..."
}
Response
HTTP/1.1 201 Created

GET /api/v1/worktime/monthlyreport

Request Parameters
name type description constraints
filter_withHidden query boolean
month query int
personalid query int
selectoption query "ALL" or "EMPLOYER" or "MY_DEPARTMENT" or "THIS_PERSON" or "WORKER"
sortoption query "COSTCENTER" or "DEPARTMENT" or "DEPARTMENT_COSTCENTER_NAME" or "NAME" or "PERSONALCNR"
toendofmonth query boolean
userid query  
year query int
Response Body
media type data type description
application/json MonthlyReportEntry (JSON)
application/xml;charset=UTF-8 object

Example

Request
GET /api/v1/worktime/monthlyreport
Content-Type: */*
Accept: application/json

                
...
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "pdfContent" : "...",
  "lastPagePng" : "..."
}

POST /api/v1/worktime/order

Eine (Beginn) Buchung mit Auftragsbezug erzeugen.

Die anzugebende Order-Id kann über die Resource order ermittelt werden

Request Body
media type data type description
application/json OrderRecordingEntry (JSON) ist dabei die Auftragszeit Datenstruktur
application/xml orderRecordingEntry (XML)

Example

Request
POST /api/v1/worktime/order
Content-Type: application/json

                
{
  "orderId" : 12345,
  "orderPositionId" : 12345,
  "workItemId" : 12345,
  "remark" : "...",
  "extendedRemark" : "...",
  "forStaffId" : 12345,
  "forStaffCnr" : "...",
  "userId" : "...",
  "year" : 12345,
  "month" : 12345,
  "day" : 12345,
  "hour" : 12345,
  "minute" : 12345,
  "second" : 12345,
  "where" : "..."
}
Response
HTTP/1.1 201 Created

POST /api/v1/worktime/pausing

Eine PAUSE (Unterbrechung)-Buchung durchführen.

Eine Pause (zum Beispiel Mittagspause) wird durch zwei PAUSE Buchungen erzielt.

Request Body
media type data type description
application/json TimeRecordingEntry (JSON) ist die Standardzeitbuchung Datenstruktur TimeRecordingEntry
application/xml timeRecordingEntry (XML)

Example

Request
POST /api/v1/worktime/pausing
Content-Type: application/json

                
{
  "forStaffId" : 12345,
  "forStaffCnr" : "...",
  "userId" : "...",
  "year" : 12345,
  "month" : 12345,
  "day" : 12345,
  "hour" : 12345,
  "minute" : 12345,
  "second" : 12345,
  "where" : "..."
}
Response
HTTP/1.1 201 Created

POST /api/v1/worktime/production

Eine (Beginn) Buchung eines Los durchführen.

Request Body
media type data type description
application/json ProductionRecordingEntry (JSON) ist die Datenstruktur zur Speicherung einer Los-Buchung

Die anzugebende Los-Id kann über die Resource production ermittelt werden @see ProductionApi ProductionApi

application/xml productionRecordingEntry (XML)

Example

Request
POST /api/v1/worktime/production
Content-Type: application/json

                
{
  "productionId" : 12345,
  "machineId" : 12345,
  "productionWorkplanId" : 12345,
  "workItemId" : 12345,
  "remark" : "...",
  "extendedRemark" : "...",
  "forStaffId" : 12345,
  "forStaffCnr" : "...",
  "userId" : "...",
  "year" : 12345,
  "month" : 12345,
  "day" : 12345,
  "hour" : 12345,
  "minute" : 12345,
  "second" : 12345,
  "where" : "..."
}
Response
HTTP/1.1 201 Created

POST /api/v1/worktime/project

Eine (Beginn) Buchung eines Projekts durchführen.

Request Body
media type data type description
application/json ProjectRecordingEntry (JSON) ist die Datenstruktur zur Speicherung einer Projekt-Buchung

Die anzugebende Project-Id kann über die Resource project ermittelt werden
application/xml projectRecordingEntry (XML)

Example

Request
POST /api/v1/worktime/project
Content-Type: application/json

                
{
  "projectId" : 12345,
  "workItemId" : 12345,
  "remark" : "...",
  "extendedRemark" : "...",
  "forStaffId" : 12345,
  "forStaffCnr" : "...",
  "userId" : "...",
  "year" : 12345,
  "month" : 12345,
  "day" : 12345,
  "hour" : 12345,
  "minute" : 12345,
  "second" : 12345,
  "where" : "..."
}
Response
HTTP/1.1 201 Created

GET /api/v1/worktime/specialactivities

Liefert eine Liste aller verfügbaren Sondertätigkeiten die für die Zeiterfassung zur Verfügung stehen.

Sondertätigkeiten sind Tätigkeiten wie "KOMMT", "GEHT", "ARZT", "BEHÖRDE", ...

Es können nur jene Sondertätigkeiten gebucht werden, die laut HELIUM V Konfiguration für den Anwender beziehungsweise dessen Benutzerrolle zur Verfügung steht.

Request Parameters
name type description
userid query
Response Body
media type data type description
application/json array of SpecialActivity (JSON) eine (leere) Liste der für den Benutzer verfügbaren Sondertätigkeiten
application/xml;charset=UTF-8 object

Example

Request
GET /api/v1/worktime/specialactivities
Content-Type: */*
Accept: application/json

                
...
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
[ {
  "id" : 12345,
  "activity" : "..."
} ]

POST /api/v1/worktime/specialtimes

Request Parameters
name type description
userid query
Request Body
media type data type
application/json SpecialTimesEntryList (JSON)
application/xml specialTimesEntryList (XML)

Example

Request
POST /api/v1/worktime/specialtimes
Content-Type: application/json

                
{
  "entries" : [ {
    "timeType" : "Holiday",
    "fromDateMs" : 12345,
    "toDateMs" : 12345,
    "halfDay" : true
  }, {
    "timeType" : "Holiday",
    "fromDateMs" : 12345,
    "toDateMs" : 12345,
    "halfDay" : true
  } ],
  "rowCount" : 12345
}
Response
HTTP/1.1 201 Created

POST /api/v1/worktime/stopping

Eine ENDE Buchung durchführen

Eine Belegbuchung wie beispielsweise Auftrags-, Projekt oder Los-Buchung beenden

Request Body
media type data type
application/json TimeRecordingEntry (JSON)
application/xml timeRecordingEntry (XML)

Example

Request
POST /api/v1/worktime/stopping
Content-Type: application/json

                
{
  "forStaffId" : 12345,
  "forStaffCnr" : "...",
  "userId" : "...",
  "year" : 12345,
  "month" : 12345,
  "day" : 12345,
  "hour" : 12345,
  "minute" : 12345,
  "second" : 12345,
  "where" : "..."
}
Response
HTTP/1.1 201 Created

GET /api/v1/worktime/timebalance

Liefert das Zeitsaldo des angeforderten Benutzers inklusive seines verfügbaren Urlaubs

Request Parameters
name type description constraints
day query der Tag (1-31) int
forStaffCnr query ist die optionale Personalnummer für die der Zeitsaldo abgerufen werden soll. Sind sowohl forStaffId als auch forStaffCnr angegeben, wird forStaffId verwendet. Sind beide nicht angegeben, wird das Zeitsaldo des angemeldeten Benutzer abgerufen.  
forStaffId query ist die optionale PersonalId für die der Zeitsaldo abgerufen werden soll.

Der angemeldete Benutzer kann für jene Personen für die er ausreichend Rechte hat Zeitsalden abrufen.

int
month query ist das Monat (1-12) int
userid query der angemeldete Benutzer  
year query ist das Jahr für das der Zeitsaldo abgerufen werden soll int
Response Body
media type data type description
application/json TimeBalanceEntry (JSON)
application/xml;charset=UTF-8 object

Example

Request
GET /api/v1/worktime/timebalance
Content-Type: */*
Accept: application/json

                
...
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "timeBalance" : 12345.0,
  "availableVacation" : 12345.0,
  "unitVacation" : "..."
}

DELETE /api/v1/worktime/{worktimeId}

Eine Zeitbuchung löschen

Request Parameters
name type description constraints
worktimeId path die Id der zu löschenden Buchung.

Die Zeitbuchungen (und damit auch deren Id) kann über die GET Methode ermittelt werden.

 int
forStaffCnr query ist die optionale Personalnummer für die gelöscht werden soll. Sind sowohl forStaffId als auch forStaffCnr angegeben, wird forStaffId verwendet. Sind beide nicht angegeben, wird das Löschen mit dem angemeldeten Benutzer durchgeführt  
forStaffId query ist die optionale PersonalId für die gelöscht werden soll.

Der angemeldete Benutzer kann für jene Personen für die er ausreichend Rechte hat Zeitbuchungen löschen.

int
userId query der angemeldete Benutzer  

Example

Request
DELETE /api/v1/worktime/{worktimeId}
Content-Type: */*

                
...
Response
HTTP/1.1 204 No Content

GET /api/v1/worktime/{year}/{month}/{day}

Liefert alle ZeitdatenEntry für den angegebenen Tag.

Request Parameters
name type description constraints
day path der Tag (1-31) int
month path ist das Monat (1-12) int
year path ist das Jahr für das die Zeitdaten abgerufen werden sollen int
forStaffCnr query ist jene Personalnummer für welche die Zeitdaten abgerufen werden soll. Kann auch leer sein. Ist sowohl forStaffId als auch forStaffCnr angegeben, gilt forStaffId  
forStaffId query ist jene Benutzer-Id für welche die Zeitdaten abgerufen werden sollen. Kann auch leer sein int
limit query Ist die maximale Anzahl an Datensätzen. Default 50. int
userId query enthält den angemeldeten Benutzer  
Response Body
media type data type description
application/json array of ZeitdatenEntry (JSON) eine (leere) Liste von ZeitdatenEntry für den gewünschten Tag
application/xml;charset=UTF-8 object

Example

Request
GET /api/v1/worktime/{year}/{month}/{day}
Content-Type: */*
Accept: application/json

                
...
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
[ {
  "activityCnr" : "...",
  "description" : "...",
  "time" : "...",
  "duration" : "...",
  "flags" : "...",
  "where" : "...",
  "id" : 12345
} ]