Standard Web Interface for Time Recording in PLANTA Hybrid New from DB 39.5.16

User-Related Interfaces

All user-related interfaces have a parameter in their URL via which the PLANTA pulse user ID is transmitted.

Query parameter:

Name	Mandatory field	Data type	Format
userID	X	String	Pulse ID of the user

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

Query parameter:

Name	Mandatory field	Data type	Format
plannedOnly		String	If the value "true" (upper/lower case irrelevant) is transmitted for plannedOnly, only the posting objects on which the user is planned are returned.
queryText		String	Permits the transmission of a string for a restriction of the results. Implementation is based on the pulse search implementation. Example: projectId:4711 Konzept
projectsOnly		String	If the value "true" (upper/lower case irrelevant) is transmitted for projectsOnly, no tasks are displayed in the result.

Retrieves the postable planning objects of the system for the transmitted user:

• The implementation is a faithful imitation of the "Add Projects and Tasks for Time Recording" function from the standard time recording module:
  • Projects
    • Not locked
    • No actual end
    • Active
  • Tasks
    • Not locked
    • No actual end
    • No milestone
    • No summary task
    • Not exported to pulse as a board
  • Since DB 13, there is no more department filter in the standard.
    • The interface can then be adjusted individually on the customer’s system, just like one would adjust the function in the time recording module.

Return value:

A list of planning objects:

Name	Data type	Description
projectUUID	String	UUID of the project in PLANTA project (DI 060934)
functionalID	String	Functional ID of the project (DI 041317)
name	String	Project name (DI 023655)
keyDate	String	Global key date (DI 000132). Is displayed here for all projects so that later simple adjustments can be made on the part of PLANTA project in order to restrict postable objects. Format: yyyy-mm-dd or empty
tasks	Array	Array of Task objects

Task

Name	Data type	Description
UUID	String	UUID of the project in PLANTA project (DI 060936)
functionalID	String	Functional ID of the task (DI 041467). If it is empty, the technical ID is applicable (DI 001098)
name	String	Task name (DI 000807)
planned	Boolean	Specifies whether the user is planned in this task as a resource

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

Retrieves the planned/actual hours worked.

• The data is a combination of the data from DT203 (presence) and DT468 (period).
• Via the optional query parameter, the period to be retrieved can be restricted.

Query parameter:

Name	Mandatory field	Data type	Format
startDate		String	yyyy-mm-dd
endDate		String	yyyy-mm-dd

Return value:

Chronologically sorted array of Attendance

Name	Data type	Description
periodUUID	String	UUID from DT468 (DI 060941)
unitPerPeriod	Float	Hours to be worked on this day (DI 001339)
availCap	Float	Available capacity on this day (planned * factors) (DI 001337)
vacation	Float	Number of hours of vacation on this day (DI 001340 converted)
absence	Float	Number of hours of absence on this day (DI 001341 converted)
date	String	Date in yyyy-mm-dd format (DI 001327)
time	Array	Array of Time objects

Time

Name	Data type	Description
attendanceUUID	String	UUID from DT203 (DI 065304)
type	String	Code from the AttendanceType enum (DI 065317)
duration	Float	Duration in hours (DI 065320)
startTime	Time	Start of the time slice (DI 065318)
endTime	Time	End of the time slice (DI 065319)
comment	String	Comment (DI 065321)

AttendanceType Enum

Key	Description
attendance	Presence
break	Break
travel_billable	Travel time (working time)
travel_time	Travel time (no working time)
travel	1 journey
overnight_stay	1 overnight stay
unknown	Unknown value

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

Retrieves the filtered load records of the user. The filter:

• Actual load = 0
• Not canceled
• The hours were not imported from a card via Hybrid

Query parameter:

Name	Mandatory field	Data type	Format
startDate		String	yyyy-mm-dd
endDate		String	yyyy-mm-dd
modifiedSince		String	yyyy-mm-dd
modifiedUntil		String	yyyy-mm-dd

Return value

A list of postings:

Name	Data type	Description
taskUUID	String	UUID of the task in PLANTA project (DI 060936)
taskName	String	Task name in PLANTA project (DI 000807)
taskFunctionalID	String	Functional ID of the task (DI 041467). If it is empty, the technical ID is applicable (DI 001098)
bookingPossible	Boolean	Maps the filters which make up the "Not postable objects" area in PLANTA project (project/task locked, projects inactive, or resource assignment has actual end)
projectUUID	String	UUID of the project in PLANTA project (DI 060934)
projectFunctionalID	String	Functional ID of the project (DI 041317)
projectName	String	Project name in PLANTA project (DI 000690)
load	Number	Load as a number (DI 001510)
date	String	Date in YYYY-MM-DD format (DI 001519)
comment	String	Comment (DI 001438)
order	String	Order (DI 027646)
orderItem	Number	Order item (DI 027647)
loadUUID	String	UUID of the load in PLANTA project (DI 060945)
created_on	String	Creation date in YYYY-MM-DD format (DI 001500)
modified_on	String	Modification date in YYYY-MM-DD format (DI 001501)
created_by	String	Creating user (DI 001503)
modified_by	String	Modifying user (DI 001504)
keyDate	String	Global key date (DI 000132). Is displayed here for all projects so that later simple adjustments can be made on the part of PLANTA project in order to restrict postable objects. Format: yyyy-mm-dd or empty

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

Retrieves the resources for which a particular employee is allowed to make postings.

• Only internal and external employees are displayed, no departments (DI 003414 = "1I" OR "1E")
• Is controlled via Access to resources
• Only resources which are also linked to PLANTA pulse are displayed.
• The user for whom the query is made is not included in the query output.

Return value:

An array of Resource objects

Resource

Name	Data type	Description
resourceUUID	String	PLANTA pulse ID of the user
resourceName	String	Name of the resource (DI 001275)
resourceType	String	1I for internal employee, 1E for external employee

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

GET

Is used to fetch the posting objects which have been marked as a favorite in PLANTA project by the transmitted user.

• Only data on tasks which would be listed in PLANTA project standard in the time recording module under "My Time Recording Favorites" is sent:
  • Project/task is not locked
  • Project is active
  • Task is no milestone
  • Task is no summary task Resource assignment has no actual end

Return value:

bookingFavorite

Name	Data type	Description
taskUUID	String	UUID of the task in PLANTA project (DI 060936)
taskFunctionalID	String	Functional ID of the task (DI 041467). If it is empty, the technical ID is applicable (DI 001098)
taskName	String	Task name in PLANTA project (DI 000807)
projectUUID	String	UUID of the project in PLANTA project (DI 060934)
projectFunctionalID	String	Functional ID of the project (DI 041317)
projectName	String	Project name in PLANTA project (DI 000690)
keyDate	String	Global key date (DI 000132) Format: yyyy-mm-dd or empty

POST

Sets the favorite flag on a resource assignment.

Parameters:

Name	Mandatory field	Data type	Description
taskUUID	x	String	UUID of the task in PLANTA project (DI 060936)

DELETE

Deletes the favorite flag on a resource assignment.

Parameters:

Name	Mandatory field	Data type	Description
taskUUID	x	String	UUID of the task in PLANTA project (DI 060936)

Workloads

The PUT/DELETE interfaces have a parameter in their URL via which the load ID from PLANTA project is transmitted.

Name	Mandatory field	Data type	Format
workloadID	X	String	UUID of the load (DI 060945)

Workload

Parameters:

Name	Mandatory field in POST	Data type	Description
taskUUID	x	String	UUID of the task in PLANTA project (DI 060936)
userID	x	String	PLANTA pulse ID of the user
load	x	Number	Load (DI 001510)
comment	x	String	Comment (DI 001438)
date	x	String	Load date (DI 001519) in yyyy-MM-dd'T'HH:mm:ss.SSSZ format
order		String	Order (DI 027646)
orderItem		Number	Order item (DI 027647)

There are no mandatory fields in PUT (except the workloadID in the URL of course!)

• Only changed fields must be sent.
• Since PLANTA project does not permit loads to be moved under another project / another task, it does not make any sense to send the taskUUID.

POST /pulse/timeTracking/1.0/workloads

Creates a load (DT472)

The default cost type of the resource is applied as cost type

Return value:

Name	Data type	Description
UUID	String	UUID of the load
taskUUID	String	UUID of the task in PLANTA project (DI 060936)
userID	String	PLANTA project ID of the user
load	Number	Load (DI 001510)
comment	String	Comment (DI 001438)
date	String	Load date (DI 001519) (format is currently not defined)

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

PUT

Changes a load

Return value:

Name	Data type	Description
UUID	String	UUID of the load
taskUUID	String	UUID of the task in PLANTA project (DI 060936)
load	Number	Load (DI 001510)
comment	String	Comment (DI 001438)
date	String	Load date (DI 001519) (format is currently not defined)

DELETE

Deletes a load

Return value:

Name	Data type	Description
UUID	String	UUID of the load

Orders / Account Assignment Elements

GET /pulse/timeTracking/1.0/orders

Can be used to return account assignment elements for posting. As soon as this interface is active, respective fields are unlocked on the UI.

Return value:

Order

Name	Data type	Description
orderId	String	Identifier
orderName	String	Name
orderItems	Array<OrderPosition>	Order items

OrderPosition

Name	Data type	Description
posId	Number	Identifier
posName	String	Name

Error Treatment

Error Object

Name	Data type	Description
statusCode	Number	HTTP status code
message	String	Error message
details	String	e.g. stacktrace
type (opt.)	String	In 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