Standard-Webschnittstelle für Zeiterfassung im PLANTA-Hybrid Neu ab DB 39.5.16

Benutzerbezogene Schnittstellen

Alle benutzerbezogenen Schnittstellen haben in ihrer URL einen Parameter, mit dem die Benutzer-ID aus PLANTA pulse übergeben wird.

Query-Parameter:

Name	Mussfeld	Datentyp	Format
userID	X	String	Pulse-ID des Benutzers

GET /pulse/timeTracking/1.0/users/{userID}/postingObjects

Query-Parameter:

Name	Mussfeld	Datentyp	Format
plannedOnly		String	Wird für plannedOnly der Wert "true" (Groß-/Kleinschreibung irrelevant) übergeben, dann werden nur die Buchungsobjekte zurückgegeben, auf die der Benutzer eingeplant ist.
queryText		String	Erlaubt die Übergabe eines Strings, um die Ergebnisse einzuschränken. Implementierung basiert auf der pulse Such-Implementation. Beispiel: projectId:4711 Konzept
projectsOnly		String	Wird für projectsOnly der Wert "true" (Groß-/Kleinschreibung irrelevant) übergeben, dann werden in dem Resultat keine Vorgänge ausgegeben.

Ruft die bebuchbaren Planungsobjekte des Systems für den übergebenen Benutzer ab.

• Die Implementation ist der Funktion "Projekte und Vorgänge für Zeiterfassung hinzufügen" aus dem Standard-Zeiterfassungsmodul nachempfunden:
  • Projekte
    • Nicht gesperrt
    • Kein Ist-Ende
    • Aktiv
  • Vorgänge
    • Nicht gesperrt
    • Kein Ist-Ende
    • Kein Meilenstein
    • Kein Sammelvorgang
    • Nicht nach pulse als Board exportiert
  • Ein Abteilungsfilter existiert im Standard seit DB 13 nicht mehr.
    • Die Schnittstelle kann beim Kunden dann individuell angepasst werden, so wie man auch die Funktion im Zeiterfassungsmodul anpassen würde.

Rückgabewert:

Eine Liste von Planungsobjekten:

Name	Datentyp	Beschreibung
projectUUID	String	UUID des Projekts in PLANTA project (DI 060934)
functionalID	String	Fachliche ID des Projekts (DI 041317)
name	String	Projektbezeichnung (DI 023655)
keyDate	String	Globaler Stichtag (DI 000132). Wird hier für alle Projekte ausgegeben, um später auf PLANTA project-Seite einfach Anpassungen zu machen, um die bebuchbaren Objekte einzuschränken. Format: yyyy-mm-dd oder leer
tasks	Array	Array von Task Objekten

Task

Name	Datatyp	Beschreibung
UUID	String	UUID des Vorgangs in PLANTA project (DI 060936)
functionalID	String	Fachliche ID des Vorgangs (DI 041467). Wenn diese leer ist, dann die technische ID (DI 001098)
name	String	Vorgangsbezeichnung (DI 000807)
planned	Boolean	Gibt an, ob der Benutzer als Ressource in diesem Vorgang eingeplant ist

GET /pulse/timeTracking/1.0/users/{userID}/attendance

Ruft die Soll-/Ist-Arbeitszeit ab.

• Die Daten sind eine Kombination der Daten aus DT203 (Anwesenheit) und DT468 (Periode).
• Über die optionalen Query-Parameter kann der abgerufene Zeitraum eingeschränkt werden.

Query-Parameter:

Name	Mussfeld	Datentyp	Format
startDate		String	yyyy-mm-dd
endDate		String	yyyy-mm-dd

Rückgabewert:

Chronologisch sortierter Array von Attendance

Name	Datentyp	Beschreibung
periodUUID	String	UUID aus der DT468 (DI 060941)
unitPerPeriod	Float	Soll-Arbeitszeit an diesem Tag (DI 001339)
availCap	Float	Verfügbare Kapazität an diesem Tag (Soll * Faktoren) (DI 001337)
vacation	Float	Anzahl Stunden Urlaub an diesem Tag (DI 001340 umgerechnet)
absence	Float	Anzahl Stunden Abwesenheit an diesem Tag (DI 001341 umgerechnet)
date	String	Datum im Format yyyy-mm-dd (DI 001327)
time	Array	Array von Time Objekten

Time

Name	Datentyp	Beschreibung
attendanceUUID	String	UUID aus der DT203 (DI 065304)
type	String	Ein Kenner aus dem AttendanceType enum (DI 065317)
duration	Float	Dauer in Stunden (DI 065320)
startTime	Uhrzeit	Start der Zeitscheibe (DI 065318)
endTime	Uhrzeit	Ende der Zeitscheibe (DI 065319)
comment	String	Kommentar (DI 065321)

AttendanceType Enum

Schlüssel	Beschreibung
attendance	Anwesenheit
break	Pause
travel_billable	Fahrzeit (Arbeitszeit)
travel_time	Fahrzeit (keine Arbeitszeit)
travel	1 Fahrt
overnight_stay	1 Übernachtung
unknown	Unbekannter Wert

GET /pulse/timeTracking/1.0/users/{userID}/workloads

Ruft die gefilterten Belastungsdatensätze des Benutzers ab. Die Filter:

• Belastung-Ist = 0
• Nicht storniert
• Die Stunden kamen nicht über Hybrid von einer Karte

Query-Parameter:

Name	Mussfeld	Datentyp	Format
startDate		String	yyyy-mm-dd
endDate		String	yyyy-mm-dd
modifiedSince		String	yyyy-mm-dd
modifiedUntil		String	yyyy-mm-dd

Rückgabewert

Eine Liste an Buchungen:

Name	Datentyp	Beschreibung
taskUUID	String	UUID des Vorgangs in PLANTA project (DI 060936)
taskName	String	Vorgangsbezeichnung in PLANTA project (DI 000807)
taskFunctionalID	String	Fachliche ID des Vorgangs (DI 041467). Wenn diese leer ist, dann die technische ID (DI 001098)
bookingPossible	Boolean	Bildet die Filter ab, die in PLANTA project den Bereich "Nicht bebuchbare Objekte" ausmachen (Projekt/Vorgang gesperrt, Projekt inaktiv oder Ressourcenzuordnung hat Ist-Ende)
projectUUID	String	UUID des Projekts in PLANTA project (DI 060934)
projectFunctionalID	String	Fachliche ID des Projekts (DI 041317)
projectName	String	Projektbezeichnung in PLANTA project (DI 000690)
load	Number	Belastung als Zahl (DI 001510)
date	String	Datum im Format YYYY-MM-DD (DI 001519)
comment	String	Kommentar (DI 001438)
order	String	Auftrag (DI 027646)
orderItem	Number	Auftragsposition (DI 027647)
loadUUID	String	UUID der Belastung in PLANTA project (DI 060945)
created_on	String	Anlagedatum im Format YYYY-MM-DD (DI 001500)
modified_on	String	Änderungsdatum im Format YYYY-MM-DD (DI 001501)
created_by	String	Anlagebenutzer (DI 001503)
modified_by	String	Änderungsbenutzer (DI 001504)
keyDate	String	Globaler Stichtag (DI 000132). Wird hier für alle Projekte ausgegeben, um später auf PLANTA project-Seite einfach Anpassungen zu machen, um die bebuchbaren Objekte einzuschränken. Format: yyyy-mm-dd oder leer

GET /pulse/timeTracking/1.0/users/{userID}/subordinates

Ruft die Ressourcen ab, für die ein gewisser Mitarbeiter buchen darf.

• Es werden nur interne und externe Mitarbeiter ausgegeben, keine Abteilungen (DI 003414 = "1I" OR "1E")
• Wird gesteuert über Zugriff auf Ressourcen
• Es werden nur Ressourcen ausgegeben, die auch mit PLANTA pulse verknüpft sind.
• Der Benutzer, für den abgefragt wird, ist in der Ergebnissmenge nicht enthalten.

Rückgabewert:

Ein Array von Resource Objekten

Resource

Name	Datentyp	Beschreibung
resourceUUID	String	PLANTA pulse-ID des Benutzers
resourceName	String	Name der Ressource (DI 001275)
resourceType	String	1I für Interner Mitarbeiter, 1E für Externer Mitarbeiter

/pulse/timeTracking/1.0/users/{userID}/bookingFavorite

GET

Wird benutzt, um die Buchungsobjekte zu holen, die in PLANTA project vom übergebenen Benutzer als Favorit markiert sind.

• Es werden nur Daten zu Vorgängen gesendet, die im PLANTA project-Standard im Zeiterfassungsmodul unter "Meine Zeiterfassungsfavoriten" auftauchen würden:
  • Projekt/Vorgang ist nicht gesperrt
  • Projekt ist aktiv
  • Vorgang ist kein Meilenstein
  • Vorgang ist kein Sammelvorgang
  • Ressourcenzuordnung hat kein Ist-Ende

Rückgabewert:

bookingFavorite

Name	Datentyp	Beschreibung
taskUUID	String	UUID des Vorgangs in PLANTA project (DI 060936)
taskFunctionalID	String	Fachliche ID des Vorgangs (DI 041467). Wenn diese leer ist die technische ID (DI 001098)
taskName	String	Vorgangsbezeichnung in PLANTA project (DI 000807)
projectUUID	String	UUID des Projekts in PLANTA project (DI 060934)
projectFunctionalID	String	Fachliche ID des Projekts (DI 041317)
projectName	String	Projektbezeichnung in PLANTA project (DI 000690)
keyDate	String	Globaler Stichtag (DI 000132) Format: yyyy-mm-dd oder leer

POST

Setzt den Favoritenflag auf einer Ressourcenzuordnung.

Parameter:

Name	Mussfeld	Datentyp	Beschreibung
taskUUID	x	String	UUID des Vorgangs in PLANTA project (DI 060936)

DELETE

Löscht den Favoritenflag auf einer Ressourcenzuordnung.

Parameter:

Name	Mussfeld	Datentyp	Beschreibung
taskUUID	x	String	UUID des Vorgangs in PLANTA project (DI 060936)

Workloads

Die PUT/DELETE-Schnittstellen haben in ihrer URL einen Parameter, mit dem die Belastungs-ID aus PLANTA project übergeben wird.

Name	Mussfeld	Datentyp	Format
workloadID	X	String	UUID der Belastung (DI 060945)

Workload

Parameter:

Name	Mussfeld bei POST	Datentyp	Beschreibung
taskUUID	x	String	UUID des Vorgangs in PLANTA project (DI 060936)
userID	x	String	PLANTA pulse-ID des Benutzers
load	x	Number	Belastung (DI 001510)
comment	x	String	Kommentar (DI 001438)
date	x	String	Belastungsdatum (DI 001519) im Format yyyy-MM-dd'T'HH:mm:ss.SSSZ
order		String	Auftrag (DI 027646)
orderItem		Number	Auftragsposition (DI 027647)

Es gibt keine Mussfelder bei PUT (außer die workloadID in der URL natürlich!)

• Es ist nur nötig, die geänderten Felder zu schicken.
• Da in PLANTA project das Verschieben einer Belastung unter ein anderes Projekt / einen anderen Vorgang nicht erlaubt ist, macht es keinen Sinn, die taskUUID zu schicken.

POST /pulse/timeTracking/1.0/workloads

Erstellt eine Belastung (DT472)

Kostenart wird von der Default-Kostenart der Ressource übernommen

Rückgabewert:

Name	Datentyp	Beschreibung
UUID	String	UUID der Belastung
taskUUID	String	UUID des Vorgangs in PLANTA project (DI 060936)
userID	String	PLANTA project-ID des Benutzers
load	Number	Belastung (DI 001510)
comment	String	Kommentar (DI 001438)
date	String	Belastungsdatum (DI 001519) (Format ist zurzeit nicht definiert)

/pulse/timeTracking/1.0/workloads/{workloadID}

PUT

Ändert eine Belastung

Rückgabewert:

Name	Datentyp	Beschreibung
UUID	String	UUID der Belastung
taskUUID	String	UUID des Vorgangs in PLANTA project (DI 060936)
load	Number	Belastung (DI 001510)
comment	String	Kommentar (DI 001438)
date	String	Belastungsdatum (DI 001519) (Format ist zurzeit nicht definiert)

DELETE

Löscht eine Belastung

Rückgabewert:

Name	Datentyp	Beschreibung
UUID	String	UUID der Belastung

Aufträge / Kontierungselemente

GET /pulse/timeTracking/1.0/orders

Hiermit können Kontierungselemente zur Buchung zurückgegeben werden. Sobald diese Schnittstelle aktiv ist, werden auf der UI entsprechende Felder freigeschaltet.

Rückgabewert:

Order

Name	Datentyp	Beschreibung
orderId	String	Identifier
orderName	String	Bezeichnung
orderItems	Array<OrderPosition>	Auftragspositionen

OrderPosition

Name	Datentyp	Beschreibung
posId	Number	Identifier
posName	String	Bezeichnung

Fehlerbehandlung

Fehler Objekt

Name	Datentyp	Beschreibung
statusCode	Number	HTTP Statuscode
message	String	Fehler Nachricht
details	String	z.B. Stacktrace
type (opt.)	String	Bei PLANTA pulse: PLANTA project-Request

HTTP Statuscodes

Status Code	Description
200	Returned when successful
400	Bad Request
401	Forbidden
403	Returned when the user is not authorized
404	Returned when no endpoint exists at the given address
500	Internal Server Error