updateTimeSheet
Purpose
Update an existing time sheet in PPM.
Note: This operation supports the Day in Days option and Period in Days option, which were introduced since PPM Center version 8.00 Service Pack 1. For more information, see the Time Sheet Update Service section in Project and Portfolio Management Center Version 8.00.01 (Service Pack 1) Release Notes.
Function
This operation updates an unsubmitted time sheet object, identified by time sheet ID in PPM.
The user performing this operation must have the permission to update this particular time sheet, meaning that the user must meet one of the following conditions:
-
Have the Time Mgmt: Edit Time Sheets access grant.
-
Be one of the following:
-
The resource of this time sheet
-
The delegate of the resource
-
The manager of the resource
-
This operation can do the following:
-
Update the description of the time sheet.
-
Delete the time sheet line.
Note: Missing unsubmitted timesheet line will be removed. -
Add the time sheet line. The status of the newly-added line is "unsubmitted."
-
Update the time sheet lines.
The following fields cannot be updated through this operation.
-
Resource
-
Time Period
-
Policy fields
-
Sequence
-
Time sheet status
-
Time sheet line status
The system creates audit information throughout the whole process.
Once the time sheet is updated, the system performs the following functionalities:
-
The system reevaluates the status of the time sheet according to the statuses of its lines.
-
The actual effort set to Task or Request work items is synchronized with those Tasks or Requests in Project Management or Demand Management accordingly.
Input
An object of TimeSheetBean that must have the following fields:
-
timeSheetID: Existing time sheet ID in PPM Center.
Settings for the other fields depend on the functionality you want to achieve. For details, refer to the following:
Update the Description for a Time Sheet
To update the description for a time sheet, set the following field.
-
description: If the description field is null or blank, the time sheet keeps the original description.
To delete a specific time sheet line, remove the TimeSheetLineBean together with the specific line ID from TimeSheetBean.
To add a new time sheet line, refer to the Create a Time Sheet Line section in operation createTimeSheet.
Important: If you want to update a time sheet or a time sheet line within the existing TimeSheetBean, you have to input the whole TimeSheetBean. For example, if the time sheet contains 100 lines, you should input all 100 lines using Web service, not only the one that you want to update. Otherwise, all the lines that you did not input will be missing from the time sheet.
Return
The updated TimeSheetBean.
Limitations
-
All data, specified in the properties, must comply with what is expected in PPM, no data validation is performed by the Web service operation.
-
Notes are not implemented in this Web service operation.
Java Interface
UpdateTimeSheetResponseDocument updateTimeSheet(UpdateTimeSheetDocument in)
Java Examples
Example: update an existing time sheet.
TimeSheetBean createdTimeSheetBean = null; public void testUpdateTimeSheet() { System.out.println("testUpdateTimeSheet started ..."); try { if(createdTimeSheetBean == null) testCreateTimeSheet();
TimeServiceStub stub = new TimeServiceStub(ctx, WSURL); UpdateTimeSheetDocument updateTimeSheetDocument = UpdateTimeSheetDocument.Factory.newInstance(); final TimeSheetBean updateTimeSheetBean = updateTimeSheetDocument.addNewUpdateTimeSheet().addNewTimeSheet Bean();
// set required fields
updateTimeSheetBean.setTimeSheetId(createdTimeSheetBean.getTime SheetId());
updateTimeSheetBean.setResourceId(createdTimeSheetBean.getResou rceId());
updateTimeSheetBean.setPeriodId(createdTimeSheetBean.getPeriodI d());
// set all other fields updateTimeSheetBean.setDescription("my desc"); TimeSheetStatus timeSheetStatus = updateTimeSheetBean.addNewState(); timeSheetStatus.setCode(new BigInteger("1")); timeSheetStatus.setMeaning("unsubmitted"); TimeSheetLineBean timeSheetLineBean = updateTimeSheetBean.addNewTimeSheetLines();
// set required fields timeSheetLineBean.setTimeSheetLineId(createdTimeSheetBean.getTi meSheetLinesArray(0).getTimeSheetLineId());
timeSheetLineBean.setWorkItemId("2"); timeSheetLineBean.setWorkItemSetId("1"); timeSheetLineBean.setWorkItemType("MISC"); // TASK, REQUEST, PACKAGE, MISC TimeSheetLineStatus timeSheetLineStatus = timeSheetLineBean.addNewState(); timeSheetLineStatus.setCode(new BigInteger("1")); timeSheetLineStatus.setMeaning("unsubmitted");
UserDataInfo userDataInfo = timeSheetLineBean.addNewUserDataBean(); userDataInfo.setUserData1("my userdata1"); userDataInfo.setVisUserData1("my visible userdata1");
TimeActualsBean timeActualsBean1 = timeSheetLineBean.addNewTimeActualsList(); timeActualsBean1.setTotalsFlag(true); timeActualsBean1.setEffortsListArray(new double[] {1,2,3,4,5,0,0}); TimeActualsBean timeActualsBean2 = timeSheetLineBean.addNewTimeActualsList(); timeActualsBean2.setTotalsFlag(false); timeActualsBean2.setEffortsListArray(new double[] {1,2,3,4,5,0,0});
timeActualsBean2.setEffortsListArray(new double[] {1,2,3,4,5,0,0});
UpdateTimeSheetResponseDocument response = stub.updateTimeSheet(updateTimeSheetDocument); TimeSheetBean returnTimeSheetBean = response.getUpdateTimeSheetResponse().getReturn();
System.out.println("Time Sheet was updated " + returnTimeSheetBean.getTimeSheetId()); } catch(Exception e) { e.printStackTrace(); } System.out.println("testUpdateTimeSheet completed"); }
Errors and Exceptions
When an error occurs on this operation, you will receive a description of the root cause in the log or in the response message.
The server log file content is similar to the following:
Exception in thread "main" org.apache.axis2.AxisFault: [root cause description]
Response message:
<exception:exceptionDetails xmlns:exception="http:// www.mercury.com/ppm/ws/exception"> <exception:detail>[root cause description] </exception:detail> </exception:exceptionDetails>
Possible root cause descriptions:
Message Code |
Message |
Cause(s) |
Possible Corrective Action |
---|---|---|---|
ex.cannotEditTimesheet |
User cannot edit Timesheet |
You may not have the required access grant or Time Management License. |
Check the user licenses and privileges (access grants). |
ex.timesheetNotExist |
Timesheet does not exist |
Time Sheet ID is invalid (Cancelled time sheets must still be kept in the database). |
Check the validity of the time sheet ID. |
ex.workitemInvalid |
Timesheet line could not be created, item added is not valid for this resource |
Invalid data in the new time sheet line. It could be caused by a certain field or one of the following causes:
|
If work item type is 'PROJECT' or 'TASK', check if the resource has the access to the work item ID; or if the work item type is 'REQUEST', check if the work item set ID is the request type ID. |
ex.chargeCodeNotExist |
Charge code does not exist |
Charge code ID is invalid or charge code does not exist anymore in the database. |
Check the validity of the charge code ID. |
ex.chargeCodePercentagesMustSum100 |
Charge codes percentages must sum to 100, but are {0} |
For each line, a list of charge codes can be defined. Each charge code must have a percentage. The sum of all the percentages per each line must sum to 100. |
Check the sum of all charge codes percentages for each line. |
ex.MissingTimeActuals |
Incorrect number of Effort Data in Time Actuals |
For each actual list, Web service checks the number of items with the calendar date. |
Check the number of items in the actual list. |