createTimeSheet

Purpose

Create a new time sheet, including time sheet lines in PPM.

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:

• Create a Time Sheet

• Attach a Time Sheet Policy

• Create a Time Sheet Line

Create a Time Sheet

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."

Attach a Time Sheet Policy

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.

Create a Time Sheet Line

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.

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)

Parameters	Description
CreateTimeSheetDocument	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
CreateTimeSheetResponseDocument	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: 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: 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', 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.