createTimeSheet
Purpose
Create a new time sheet, including time sheet lines 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.
Time Management Web services is not built for the purpose of migrating large volume of time sheets data from a legacy system into PPM. To migrate large volume of time sheets, use TM Bulk Importer.
Creating a time sheet or any other operation is expected to take just slightly less than the same operation in the PPM application. Migration of many time sheets takes too much time with the current web services.
Function
This operation creates a new time sheet in PPM.
The user performing this operation must have the permission to create this particular time sheet, meaning that the user must meet 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.
-
The operation can do the following:
-
Create a time sheet.
-
Attach a time sheet policy to this time sheet.
-
Enter effort for Period in Hours, Period In Days, or Period In Percent.
-
Create time sheet lines in the time sheet.
The system creates audit information throughout the whole create and update process.
Once the new time sheet is created, the system performs the following functionalities:
-
The status of the time sheet is "unsubmitted."
-
The possible time and billing approvers are reevaluated.
This process fills the following fields:
-
timeApproverParticipantGroupId
-
timeApproverSecurityGroupId
-
timeApproverUsersIds
-
billingApproverParticipantGroupId
-
billingApproverSecurityGroupId
-
billingApproverUsersIds
-
-
The actual effort set to Task or Request work items is synched with those Tasks or Requests in Project Management or Demand Management accordingly.
The following field is set only by the functionality of this operation, and cannot be set by the user:
-
Sequence: The sequence number set in the new time sheet would be the next sequence number available, meaning the system automatically increments the number of time sheets that exist for this resource and period by 1.
If the policy does not allow multiple time sheets per resource and period, and a time sheet has already existed for this resource and period, an exception (ex.timesheetExist) is thrown.
Input
TimeSheetBean
The following fields are must be set to complete this operation:
-
resourceId: Existing Resource ID in PPM for whom you log the time sheet.
-
periodId: Existing Time Period ID in PPM with which you log the time period.
Settings for the other fields depend on the functionality you want to achieve. For details, refer to the following:
To create a time sheet, set the following fields.
-
description: If the description filed is not set, a default description is given, composed of Resource name - Time Period name and #Sequence.
Note: After the creation, the time sheet status (the state field) is set to the default value "unsubmitted."
To attach a time sheet policy, set the following fields.
-
Policy fields
(bucketShowLevel, bucketReportMethod, periodHoursCalcTypeCode, hoursInPeriodType, hoursPerPeriod, workdayHours, maximumHoursPerDay, maximumHoursPerTimeSheet, minimumHoursPerTimeSheet, maximumPercentPerTimeSheet, minimumPercentPerTimeSheet, allowMultipleTimeSheets, notifyDelinquentTimeSheet, reqActivitiesRequiredFlag, tskActivitiesRequiredFlag, prjActivitiesRequiredFlag, pkgActivitiesRequiredFlag, miscActivitiesRequiredFlag, reqWorkItemEnabledFlag, tskWorkItemEnabledFlag, prjWorkItemEnabledFlag, pkgWorkItemEnabledFlag, mscWorkItemEnabledFlag, enforcementLevelError)
The BucketShowLevel field is used to determine if policy fields are set. If BucketShowLevel field is not set, the system considers you specify no policy fields.
-
If no policy fields are specified, the policy set for this time sheet is the policy associated with the resource. If no policy is associated with the resource, the derived policy is based on the global policy.
-
If policy fields are specified, then those fields are set as the policy fields in the time sheet.
In both cases, the Time Period Type ID of the policy must match the Period Type ID associated with the Time Period ID which is a required parameter in this operation. All of the fields must be set in order to avoid confusion with the default policy fields that would be set on initial creation.
To create a time sheet line, set the following fields:
-
timeSheetLines:
-
Each new time sheet line must have the following required fields set:
-
workItemId
-
workItemSetId
-
For the other TimeSheetLineBean fields regarding a time sheet line, refer to the following.
It is recommended that you update the time sheet line status by using the approveTimeSheetLine, rejectTimeSheetLine, and reworkTimeSheetLine operations.
To add Charge Codes in a time sheet line, set the following field:
-
chargeCodesList: Each charge code parameter must have an ID of an existing Charge Code in PPM, and a percentage attached to it.
Note: The percentages of the charge codes in the charge code list should sum up to 100.
Note: After the creation, the time sheet line status (the state field) is set to the default value "unsubmitted." To update the time sheet line status, use the approveTimeSheetLine, rejectTimeSheetLine, and reworkTimeSheetLine operations.
To input actual effort in the time sheet line, set the following field.
-
timeActualsList
For each line, there must be at least one non-total record. Records with the total flag set to true are ignored.
Non-total records:
There can be one or more non-total records. If there is one non-total record, it may or may not be associated with an activity. If there are more than one non-total records, each record must be associated with an Activity ID.
When data is added to each non-total record, the totals record is automatically recalculated on the update of the time sheet object.
These relationships are shown in the following diagrams.
A line with one non-total actuals record, which is not associated with an activity:
A line with one non-total actuals record, which is associated with one activity:
A line with several non-total actuals records, where each is associated with one activity:
The following are additional fields that can be set for a time sheet line:
-
updateChargeCodeFlag: Flag that defines whether charge codes can be updateable (Y/N).
-
requireChargeCodeFlag: Flag that defines whether charge codes are required (Y/N).
-
userDataBean: An array of up to 20 user data hidden values and a corresponding array of up to 20 user data visible values.
Return
An object of TimeSheetBean with updated fields. The data is returned as per policy.
Limitations
-
All data, specified in the properties, must comply with what is expected in PPM Center - no data validation is performed by this Web service operation.
-
Notes are not implemented in this Web service operation.
Related Information
updateTimeSheet updates fields of an existing time sheet.
Java Interface
CreateTimeSheetResponseDocument createTimeSheet(CreateTimeSheetDocument in)
Java Examples
Example: create a new time sheet.
/** * * We are assuming existence of basic data that must exist in the app. Meaning: * - admin resource with user id 1 * - time periods starting with period id 30000, at least one * - base time policy named 'Semi-Monthly - Day - Hours' * */
TimeSheetBean createdTimeSheetBean = null; public void testCreateTimeSheet() { System.out.println("testCreateTimeSheet started ..."); try { TimeServiceStub stub = new TimeServiceStub(ctx, WSURL); CreateTimeSheetDocument createTimeSheetDocument = CreateTimeSheetDocument.Factory.newInstance(); final TimeSheetBean newTimeSheetBean = createTimeSheetDocument.addNewCreateTimeSheet().addNewTimeSheet Bean();
newTimeSheetBean.setResourceId(1); // assuming admin user exists with id 1 newTimeSheetBean.setPeriodId(30000); // assuming this time period exists
newTimeSheetBean.setBucketShowLevel("DAY"); newTimeSheetBean.setBucketReportMethod("HOURS");
newTimeSheetBean.setPeriodHoursCalcTypeCode("WORKDAY"); newTimeSheetBean.setHoursPerPeriod(8); newTimeSheetBean.setWorkdayHours(5.5); newTimeSheetBean.setReqActivitiesRequiredFlag(true); newTimeSheetBean.setTskActivitiesRequiredFlag(true); newTimeSheetBean.setPkgActivitiesRequiredFlag(true);
newTimeSheetBean.setMiscActivitiesRequiredFlag(true); newTimeSheetBean.setAllowMultipleTimeSheets(true); newTimeSheetBean.setEnforcementLevelError(true);
TimeSheetLineBean timeSheetLineBean = newTimeSheetBean.addNewTimeSheetLines(); timeSheetLineBean.setWorkItemId("2"); timeSheetLineBean.setWorkItemSetId("1"); timeSheetLineBean.setWorkItemType("MISC"); TimeSheetLineStatus timeSheetLineStatus = timeSheetLineBean.addNewState(); timeSheetLineStatus.setCode(new BigInteger("1")); timeSheetLineStatus.setMeaning("unsubmitted");
ChargeCodeBean chargeCodeBean = timeSheetLineBean.addNewChargeCodesList(); chargeCodeBean.setChargeCodeId(30000); chargeCodeBean.setChargeCodeName("my cc name"); chargeCodeBean.setCategory("BILLABLE"); chargeCodeBean.setClientCode("CLIENT_1"); chargeCodeBean.setDepartmentCode("FINANCE"); chargeCodeBean.setDescription("my cc name"); chargeCodeBean.setEnabledFlag(true); chargeCodeBean.setPercentage(100.d);
timeSheetLineBean.setUpdateChargeCodeFlag(true); timeSheetLineBean.setRequireChargeCodeFlag(false); timeSheetLineBean.setActualApproverUserId(1); UserDataInfo ud = timeSheetLineBean.addNewUserDataBean(); ud.setUserData1("UD1"); ud.setVisUserData1("VisUD1");
TimeActualsBean timeActualsBean1 = timeSheetLineBean.addNewTimeActualsList(); timeActualsBean1.setTotalsFlag(true); timeActualsBean1.setEffortsListArray(new double[] {2,4,6,8,10,0,0,2,4,6,8,10,0,0,20});
TimeActualsBean timeActualsBean2 = timeSheetLineBean.addNewTimeActualsList(); timeActualsBean2.setTotalsFlag(false); timeActualsBean2.setEffortsListArray(new double[] {1,2,3,4,5,0,0,1,2,3,4,5,0,0,10});
TimeActualsBean timeActualsBean3 = timeSheetLineBean.addNewTimeActualsList(); timeActualsBean3.setTotalsFlag(false); timeActualsBean2.setActivityId(30000); timeActualsBean3.setEffortsListArray(new double[] {1,2,3,4,5,0,0,1,2,3,4,5,0,0,10});
CreateTimeSheetResponseDocument response = stub.createTimeSheet(createTimeSheetDocument); createdTimeSheetBean = response.getCreateTimeSheetResponse().getReturn(); System.out.println("Newly created TimeSheet with id " + createdTimeSheetBean.getTimeSheetId()); } catch(Exception e) { e.printStackTrace(); } System.out.println("testCreateTimeSheet completed"); }
Errors and Exceptions
When an error occurs during this operation, a description of the root cause will be logged and a response message generated.
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 your licenses and privileges (access grants). |
ex.resourceNotExist |
Resource does not exist |
Resource ID is invalid or resource does not exist anymore in PPM. |
Check the validity of the resource ID. |
ex.periodNotExist |
Time Period does not exist |
Time Period ID is invalid or Time Period ID does not exist anymore in the database. |
Check the validity of the time period ID. |
ex.globalPolicyNotExist |
Global timesheet policy does not exist |
Corrupt database. |
Check for an existence of the global policy; must exist in PPM. |
ex.periodTypeNotMatching |
Period type in time period does not match period type in timesheet policy |
Invalid Time Period data. |
Check for the correspondence between the time period and the period type of the policy. |
ex.timesheetExist |
Timesheet already exists for this resource and period, policy does not allow multiple timesheets |
You try to create multiple time sheets when the policy does not allow it. |
Verify that either the policy allows multiple time sheets or a time sheet does not already exist for the period and resource for which you are trying to create a new time sheet. |
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 these causes:
|
If work item type is 'PROJECT' or 'TASK', verify that he resource has access to the work item ID; or if the work item type is 'REQUEST', verify that 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 |
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. |