getActualTime

Purpose

Read actual time data of the work items between a specific time range in PPM.

Function

This operation filters for actual data of the work items in Time Management in PPM.

The user performing this operation must have the Time Mgmt: View Time Sheets access grant.

Input

An object of TimeFilter, which holds all the fields described in the TimeFilter data type.

Return

An array of WorkItemActualTime objects.

Java Interface

GetActualTimeResponseDocument getActualTime(GetActualTimeDocument in)

Parameters	Description
GetActualTimeDocument	Wrapper for a TimeFilter object. See the following example for the construction. The TimeFilter object includes the following fields: Date startDate Date endDate String periodTypeName String workItemType String workItemName String workItemID List resources List timeSheetStatuses List timeSheetLineStatuses boolean includeActualCost
GetActualTimeResponseDocument	Wrapper for an array of WorkItemActualTime objects. See the following example for retrieving the array. Each WorkItemActualTime includes the following fields: Date startDate Date endDate String workItemName String workItemTypeCode String workItemID String activityName String chargeCode String hours String resource String timeSheetLineStatus String cost

Parameters

Description

GetActualTimeDocument

Wrapper for a TimeFilter object.

See the following example for the construction.

The TimeFilter object includes the following fields:

Date startDate
Date endDate
String periodTypeName
String workItemType
String workItemName
String workItemID
List resources
List timeSheetStatuses
List timeSheetLineStatuses
boolean includeActualCost

GetActualTimeResponseDocument

Wrapper for an array of WorkItemActualTime objects.

See the following example for retrieving the array.

Each WorkItemActualTime includes the following fields:

Date startDate
Date endDate
String workItemName
String workItemTypeCode
String workItemID
String activityName
String chargeCode
String hours
String resource
String timeSheetLineStatus
String cost

Java Examples

Example: get actual time data.

public void testGetActualTime() throws Exception {
         System.out.println("testGetActualTime started ...");

         // get stub
      TimeServiceStub stub = new TimeServiceStub(ctx, WSURL);

     // create input message
     GetActualTimeDocument getActualTimeDoc =
GetActualTimeDocument.Factory.newInstance();

     // set filter
     TimeFilter filter =
getActualTimeDoc.addNewGetActualTime().addNewParam0();

     // setup the filters
     Calendar startDate = Calendar.getInstance();
     Calendar endDate = Calendar.getInstance();
     endDate.add(Calendar.DATE, 14);
     filter.setStartDate(startDate);
     filter.setEndDate(endDate);
     filter.setPeriodTypeName("Semi-Monthly");
     filter.setIncludeActualCost(true);
     filter.addResources("admin");

     // invoke the service
     GetActualTimeResponseDocument response =
stub.getActualTime(getActualTimeDoc);

     // process response
     System.out.println("Read " +
response.getGetActualTimeResponse().sizeOfReturnArray() + "
work item rows");
     WorkItemActualTime[] workItems =
response.getGetActualTimeResponse().getReturnArray();
     if (workItems.length > 0) {
     WorkItemActualTime workItem = workItems[0];
     System.out.println("total hours for misc. item = " +
workItem.getHours());
     }
          System.out.println("testGetActualTime 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.cannotViewTimesheet	User cannot view Timesheet	You may not have the required access grant or Time Management License.	Check the user licenses and privileges (access grants).