Standard-Web-Schnittstellen für project-pulse-Integration
Da Webschnittstellen kein Vorlagesystem besitzen, können diese Schnittstellen nicht als Vorlage zum Erstellen neuer Webschnitstellen benutzt werden.
Workload - Belastung
- Überträgt die in PLANTA pulse auf Karten erfassten Rückmeldung auf die Vorgänge in PLANTA project
Member - Ressourcenzuordnung
- Überträgt die in PLANTA pulse erfassten Mitgliedszuordnungen als Ressourcenzuordnungen für den entsprechenden Vorgang nach PLANTA project
Zeiterfassung
- Überträgt die in PLANTA pulse auf PLANTA project-Vorgängen erfassten Rückmeldung auf dieselben Vorgänge in PLANTA project
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.
- Projekte
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 Ergebnismenge 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
taskUUIDzu 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 |