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

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