Standard Web Interfaces for project-pulse Integration

Since web interfaces do not possess a template system, these interfaces cannot be used as templates for the creation of new web interfaces.

Workload - Load

Transfers the hours recorded on cards in PLANTA pulse to the tasks in PLANTA project

Member - Resource Assignment

Copies the member assignments created in PLANTA pulse to PLANTA project as resource assignments for the respective task

Time Recording

Transfers the hours reported on PLANTA project tasks in PLANTA pulse to the same tasks in PLANTA project

User-Related Interfaces

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

Query parameters:

Name	Mandatory field	Data type	Format
userID	X	string	pulse ID of the user

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

Query parameters:

Name	Data type	Format
plannedOnly	string	If the value "true" (not case-sensitive) is transmitted for `plannedOnly`, only the posting objects on which the user is planned are returned.
queryText	string	Permits the transmission of a string to restrict the results. Implementation based on the pulse view implementation. Example: `projectId:4711 concept`
projectsOnly	string	If the value "true" (not case-sensitive) is transmitted for `projectsOnly`, no tasks will be displayed in the result.

Calls the postable planning objects of the system for the transferred 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, in the same way as the function in the time recording module is adjusted.

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 to make simple adjustments on the part of PLANTA project later 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 task in PLANTA project (DI 060936)
functionalID	string	Functional ID of the task (DI 041467). If it is empty, the technical ID is used (DI 001098)
name	string	Task name (DI 000807)
planned	Boolean	Specifies whether the user is planned in this task as a resource
remainingEffort	Number	Remaining effort, reduced by the actual load not yet taken into account in scheduling. The value is automatically adjusted as soon as the actual hours booked are received by PLANTA project.

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

Retrieves the planned/actual working time.

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 parameters:

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 that day (DI 001339)
availCap	Float	Available capacity on that day (planned * factors) (DI 001337)
vacation	Float	Number of hours of vacation on that day (DI 001340 converted)
absence	Float	Number of hours of absence on that 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

Calls the filtered load records of the user. The filters:

Actual load != 0
Not canceled
The hours were not imported from a card via hybrid

Query parameters:

Name	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 used (DI 001098)
bookingPossible	Boolean	Maps the filters which form the "Non-postable objects" area in PLANTA project (project/task locked, project inactive or resource assignment has no 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	Modification user (DI 001504)
keyDate	string	Global key date (DI 000132). Is displayed here for all projects to make simple adjustments on the part of PLANTA project later in order to restrict postable objects. Format: yyyy-mm-dd or empty
remainingEffort	Number	Remaining effort, reduced by the actual load not yet taken into account in scheduling. The value is automatically adjusted as soon as the actual hours booked are received by PLANTA project.

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

Retrieves the resources for which a certain user can post.

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

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 favorites in PLANTA project by the respective user.

Only data of tasks is sent which would be displayed in the Time Recording module in PLANTA project standard under "My Time Recording Favorites":
- 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 used (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
remainingEffort	Number	Remaining effort, reduced by the actual load not yet taken into account in scheduling. The value is automatically adjusted as soon as the actual hours booked are received by PLANTA project.

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 which serves to hand over the load ID from PLANTA project.

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

Workload

Parameters:

Name	Mandatory field for 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 the `yyyy-MM-dd'T'HH:mm:ss.SSSZ` format
order		string	Order (DI 027646)
orderItem		Number	Order item (DI 027647)

In PUT, there are no mandatory fields (except the workloadID in the URL of course!)

You only have to send the changed fields.
Since it is prohibited in PLANTA project to move a load on another project / task, it is useless to send the taskUUID.

POST /pulse/timeTracking/1.0/workloads

Creates an encumbrance (DT472)

Cost type is taken from the default cost type of the resource

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)
cardID	string	pulse: cardId (DI066832)

/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)
cardID	string	pulse: cardId (DI066832)

DELETE

Deletes a load

Return value:

Name	Data type	Description
UUID	string	UUID of the load
cardID	string	pulse: cardId (DI066832)

POST /pulse/timeTracking/1.0/workloadSearch

Expects bodies with at least one of the following parameters as a list:

Name	Data type	Description
userID	string	PLANTA pulse ID of the user
cardID	string	PLANTA pulse ID of the card
taskUUID	string	UUID of the task in PLANTA project (DI 060936)

Query parameters:

Name	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 used (DI 001098)
bookingPossible	Boolean	Maps the filters which form the "Non-postable objects" area in PLANTA project (project/task locked, project inactive or resource assignment has no 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	Modification user (DI 001504)
keyDate	string	Global key date (DI 000132). Is displayed here for all projects to make simple adjustments on the part of PLANTA project later in order to restrict postable objects. Format: yyyy-mm-dd or empty
remainingEffort	Number	Remaining effort, reduced by the actual load not yet taken into account in scheduling. The value is automatically adjusted as soon as the actual hours booked are received by PLANTA project.

Orders / Account Assignment Elements

GET /pulse/timeTracking/1.0/orders

This can be used to return account assignment elements for posting. As soon as the interface is active, the corresponding fields are unlocked on the UI.

Return value:

Order

Name	Data type	Description
orderId	string	Identifier
orderName	string	Name
orderItems	Array<OrderPosition>	Order positions

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 Status Codes

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