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
Delete a Time Sheet Line
Add a new Time Sheet Line

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.

Delete a Time Sheet Line

To delete a specific time sheet line, remove the TimeSheetLineBean together with the specific line ID from TimeSheetBean.

Add a new Time Sheet Line

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)

Parameters	Description
UpdateTimeSheetDocument	Wrapper for TimeSheetBean. See the following example for the construction.The bean includes: Long timeSheetId; Long resourceId; Long periodId; String description; Integer sequence; TimeSheetStatus state; // constants correspond to those in model.TimeSheet List timeSheetLines; // list of TimeSheetLineBean objects String bucketShowLevel ^a; String bucketReportMethod;^a String periodHoursCalcTypeCode;^a Double hoursPerPeriod;^a Double workdayHours;^a Boolean allowMultipleTimeSheets;^a String hoursInPeriodType;^a Double maximumHoursPerDay;^a Double maximumHoursPerTimeSheet;^a Double minimumHoursPerTimeSheet;^a Double maximumPercentPerTimeSheet;^a Double minimumPercentPerTimeSheet;^a Boolean notifyDelinquentTimeSheet;^a Boolean reqActivitiesRequiredFlag;^a Boolean tskActivitiesRequiredFlag;^a Boolean prjActivitiesRequiredFlag;^a Boolean pkgActivitiesRequiredFlag;^a Boolean miscActivitiesRequiredFlag;^a Boolean reqWorkItemEnabledFlag;^a Boolean tskWorkItemEnabledFlag;^a Boolean prjWorkItemEnabledFlag;^a Boolean pkgWorkItemEnabledFlag;^a Boolean mscWorkItemEnabledFlag;^a Boolean enforcementLevelError;^a String exceptionMessage; ^b Long timeApproverParticipantGroupId;^b Long timeApproverSecurityGroupId;^b List timeApproverUsersIds;^b // list of Long user ids Long billingApproverParticipantGroupId;^b Long billingApproverSecurityGroupId;^b List billingApproverUsersIds; ^b// list of Long user ids
UpdateTimeSheetResponseDocument	Wrapper for TimeSheetBean. See the following example for retrieving the bean and its fields.
a. Policy fields - for creation only b. Read-only fields

Parameters

Description

UpdateTimeSheetDocument

Wrapper for TimeSheetBean. See the following example for the construction.The bean includes:

Long timeSheetId;
Long resourceId;
Long periodId;
String description;
Integer sequence;
TimeSheetStatus state; // constants correspond to those in model.TimeSheet
List timeSheetLines; // list of TimeSheetLineBean objects
String bucketShowLevel ^a;
String bucketReportMethod;^a
String periodHoursCalcTypeCode;^a
Double hoursPerPeriod;^a
Double workdayHours;^a
Boolean allowMultipleTimeSheets;^a
String hoursInPeriodType;^a
Double maximumHoursPerDay;^a
Double maximumHoursPerTimeSheet;^a
Double minimumHoursPerTimeSheet;^a
Double maximumPercentPerTimeSheet;^a
Double minimumPercentPerTimeSheet;^a
Boolean notifyDelinquentTimeSheet;^a
Boolean reqActivitiesRequiredFlag;^a
Boolean tskActivitiesRequiredFlag;^a
Boolean prjActivitiesRequiredFlag;^a
Boolean pkgActivitiesRequiredFlag;^a
Boolean miscActivitiesRequiredFlag;^a
Boolean reqWorkItemEnabledFlag;^a
Boolean tskWorkItemEnabledFlag;^a
Boolean prjWorkItemEnabledFlag;^a
Boolean pkgWorkItemEnabledFlag;^a
Boolean mscWorkItemEnabledFlag;^a
Boolean enforcementLevelError;^a
String exceptionMessage; ^b
Long timeApproverParticipantGroupId;^b
Long timeApproverSecurityGroupId;^b
List timeApproverUsersIds;^b // list of Long user ids
Long billingApproverParticipantGroupId;^b
Long billingApproverSecurityGroupId;^b
List billingApproverUsersIds; ^b// list of Long user ids

UpdateTimeSheetResponseDocument

Wrapper for TimeSheetBean. See the following example for retrieving the bean and its fields.

a. Policy fields - for creation only

b. Read-only fields

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: Work item ID does not exist in the type. Work item ID does not exist in the work item set ID.	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.