/
PwsGetFroTimeCards

PwsGetFroTimeCards

Overview


For Reporting Only time cards, also known as FRO, are typically used by organizations when cutting over from their old time tracking system to Projector. Some organizations may also load FRO time cards when they enter time in another system, but want to use Projector as the system of record for measures like utilization. To learn more about FRO time cards Click Here.

This web service allows the caller to retrieve For Reporting Only (FRO) time cards satisfying any number of specified filters. You may filter FRO cards based upon:

  • One or more specified resources (PwsResourceRef). All FRO time cards associated with the specified resources will be included.
  • A specified work date range. Only FRO time cards that have work dates within the specified date range will be included.
  • A specified billed timestamp range. Only FRO time cards that were billed within the specified date and time range will be included.
  • One or more specified contract line items (PwsContractLineItemRef). All FRO time cards associated with projects underneath the specified contract line items will be included. 
  • One or more specified engagements (PwsEngagementRef). All FRO time cards associated with projects that are part of the specified engagements will be included. 
  • One or more specified projects (PwsProjectRef). All FRO time cards associated with the specified projects will be included.
  • One or more specified project rate types (PwsProjectRateTypeRef). All FRO time cards associated with the specified rate types will be included.
  • One or more specified project roles (PwsProjectRoleRef). All FRO time cards associated with the specified roles will be included.
  • One or more specified project task types (PwsProjectTaskTypeRef). All FRO time cards associated with tasks of the specified task types will be included.
  • One or more specified project tasks (PwsProjectTaskRef). All FRO time cards associated with the specified project tasks will be included.
  • One or more specified locations (PwsLocationRef). All FRO time cards associated with the specified locations will be included.
  • One or more specified time cards (PwsTimeCardRef). Only the FRO time cards specifically identified in the list will be included.
  • One or more specified external grouping identifiers. Only the FRO time cards that have an external grouping identified specifically identified in this will be included.

When multiple filters are supplied, all specified filters must be satisfied in order for an FRO time card to be retrieved.

The caller may page through results by using the MaximumResults and TimeCardUidsAfter inputs, in conjunction with the NextPageTimecardUidsAfter output, as follows:

  • The caller should start by specifying the number of records to retrieve in a single call, as MaximumResults, and null for TimeCardUidsAfter.
  • If all the FRO time cards that met the criteria were included in the response, the caller need do nothing further.
  • However, if there are more then MaxResults time cards that satisfy the criteria, the web service will only return up to MaxResults items. In this case, it will also return a non-null value for NextPageTimeCardUidsAfter. The caller should repeat the very same request, including all the same filters (in order to insure that the subsequent request properly picks up where the prior one left off), except this time pass NextPageTimeCardUidsAfter set to the UID of the last time card included in the response.
  • The caller should repeat the previous step as necessary until the service returns a null value for NextPageTimeCardUidsAfter.

MaximumResults is capped at 100K. If the caller does not specify MaximumResults or specifies a value > 100K, the cap will be set at 100K.

The caller must have appropriate permissions to view the time cards that are returned:

  • The caller can view FRO time cards that are associated with the resource linked to the caller’s user.
  • The caller can view FRO time cards if they have the browse resource time cost center permission for the time card’s resource’s cost center as of the time card work date.
  • The caller can view FRO time cards if they have the browse project time cost center permission for the time card’s project’s engagement’s cost center.
  • The caller can view FRO time cards if they are on the PM team for the time card’s project.
  • The caller can view FRO time cards if they are the designated time entry delegate for the time card’s resource.

This service will raise an error if any of the time cards specified explicitly in TimeCardIdentities do not exist, are not FRO time cards, or could not be viewed for any reason.


Rate Limiting

In order to protect our servers from inadvertent service overuse or intentional attack, and to fairly distribute services to all our customers, we have implemented a rate limiting algorithm.  When fully deployed, this new algorithm will cause services to either succeed with new warnings or fail with new errors when services are consumed at too high a rate.  Programs that consume Projector services should be enhanced to handle rate limiting errors so that they can continue functioning properly.  For more information please visit: Projector Rate Limiting Behavior.


Request Format


PwsGetFroTimeCards Request

Request Elements


Element

Data Type

Required?

Default

Description

Sample Data

RequestId

Int32

No


Click here for more information.

1

SessionTicket

String

Yes


Click here for more information.

AYInKjj1Mym8XoGH6OiEqg==

BilledTimestampRangeEnd

DateTime

No


Only FRO time cards that have a billing timestamp (in UTC) on or before this date will be retrieved. If one or both is specified, the BilledTimestampRangeStart and BilledTimestampRangeEnd together determine which FRO time cards will be retrieved.

2023-12-31T00:00:00.000Z

BilledTimestampRangeStart

DateTime

No


Only FRO time cards that have a billing timestamp (in UTC) on or after this date will be retrieved. If one or both is specified, the BilledTimestampRangeStart and BilledTimestampRangeEnd together determine which FRO time cards will be retrieved.

2023-01-01T00:00:00.000Z

ContractLineItemIdentities

No


Only FRO time cards that are associated with these Contract Line Items will be retrieved.


EngagementIdentities

PwsEngagementRef

No


Only FRO time cards that are associated with these Engagements will be retrieved.


ExternalGroupingIdentifiers

Int32[]

No


This unique identifier allows users to group multiple FRO time cards together, most commonly user for reporting purposes. Only FRO time cards with these external grouping identifiers will be retrieved.

1212023

LocationIdentities

No


Only FRO time cards with these Locations will be retrieved.


MaximumResults

Int32

Yes


The maximum number of FRO time cards to be retrieved. Maximum value is 100,000. If not specified, the 100,000 limit will be enforced.

100

ProjectIdentities

No


Only FRO time cards that are associated with these Projects will be retrieved.


ProjectRateTypeIdentities

No


Only FRO time cards that are associated with these Project Rate Types will be retrieved.


ProjectRoleIdentities

No


Only FRO time cards that are associated with these Project Roles will be retrieved.


ProjectTaskIdentities

PwsProjectTaskRef

No


Only FRO time cards that are associated with these Tasks will be retrieved.


ProjectTaskTypeIdentities

No


Only FRO time cards that are associated with these Task Types will be retrieved.


ResourceIdentities

PwsResourceRef

No


Only FRO time cards that are associated with these Resources will be retrieved.


TimeCardIdentities

PwsTimeCardRef

No


Only the specified FRO time card(s) will be retrieved.


TimecardUidsAfter

Int64

No


Only UIDs that are greater than the specified UID will be retrieved. Used in conjunction with MaximumResults and NextPageTimecardUidsAfter (response) to page through results as described above.

1

WorkDateRangeEnd

DateTime

No


Only FRO time cards that have a work date (in midnight UTC) before this date will be retrieved. If one or both is specified, the WorkDateRangeStart and WorkDateRangeStart together determine which FRO time cards will be retrieved.

2023-12-31T00:00:00.000Z

WorkDateRangeStart

DateTime

No


Only FRO time cards that have a work date (in midnight UTC) after this date will be retrieved. If one or both is specified, the WorkDateRangeStart and WorkDateRangeStart together determine which FRO time cards will be retrieved.

2023-01-01T00:00:00.000Z

Request Usage Example(s)


PwsGetFroTimeCardsRq
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pws="http://projectorpsa.com/PwsProjectorServices/" xmlns:req="http://projectorpsa.com/DataContracts/Requests/" xmlns:tim="http://projectorpsa.com/DataContracts/Shared/TimeAndCost/" xmlns:com="http://projectorpsa.com/DataContracts/Shared/Common/" xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
   <soapenv:Header/>
   <soapenv:Body>
      <pws:PwsGetFroTimeCards>
         <pws:serviceRequest>
            <req:RequestId>1</req:RequestId>
            <req:SessionTicket>AYInKjj1Mym8XoGH6OiEqg==</req:SessionTicket>
            <tim:BilledTimestampRangeEnd>2023-12-31T00:00:00.000Z</tim:BilledTimestampRangeEnd>
            <tim:BilledTimestampRangeStart>2023-01-01T00:00:00.000Z</tim:BilledTimestampRangeStart>
            <tim:ContractLineItemIdentities>
               <com:PwsContractLineItemRef>
                  <com:ContractLineItemCode>E001046-CL1</com:ContractLineItemCode>
               </com:PwsContractLineItemRef>
            </tim:ContractLineItemIdentities>
            <tim:EngagementIdentities>
               <com:PwsEngagementRef>
                  <com:EngagementCode>E001046</com:EngagementCode>
               </com:PwsEngagementRef>
            </tim:EngagementIdentities>
            <tim:ExternalGroupingIdentifiers>
               <arr:int>1212023</arr:int>
            </tim:ExternalGroupingIdentifiers>
            <tim:LocationIdentities>
               <com:PwsLocationRef>
                  <com:LocationName>USA - Illinois</com:LocationName>
               </com:PwsLocationRef>
            </tim:LocationIdentities>
            <tim:MaximumResults>100</tim:MaximumResults>
            <tim:ProjectIdentities>
               <com:PwsProjectRef>
                  <com:ProjectCode>E001046-P001</com:ProjectCode>
               </com:PwsProjectRef>
            </tim:ProjectIdentities>
            <tim:ProjectRateTypeIdentities>
               <com:PwsProjectRateTypeRef>
                  <com:ProjectRateTypeUid>1152921504607818384</com:ProjectRateTypeUid>
               </com:PwsProjectRateTypeRef>
            </tim:ProjectRateTypeIdentities>
            <tim:ProjectRoleIdentities>
               <com:PwsProjectRoleRef>
                  <com:ProjectRoleUid>1152921504611115473</com:ProjectRoleUid>
               </com:PwsProjectRoleRef>
            </tim:ProjectRoleIdentities>
            <tim:ProjectTaskIdentities>
               <com:PwsProjectTaskRef>
                  <com:ProjectTaskUid>1152921504610341347</com:ProjectTaskUid>
               </com:PwsProjectTaskRef>
            </tim:ProjectTaskIdentities>
            <tim:ProjectTaskTypeIdentities>
               <com:PwsProjectTaskTypeRef>
                  <com:ProjectTaskTypeUid>1152921504609305356</com:ProjectTaskTypeUid>
               </com:PwsProjectTaskTypeRef>
            </tim:ProjectTaskTypeIdentities>
            <tim:ResourceIdentities>
               <com:PwsResourceRef>
                  <com:ResourceDisplayName>Matt</com:ResourceDisplayName>
               </com:PwsResourceRef>
            </tim:ResourceIdentities>
            <tim:TimecardUidsAfter>1</tim:TimecardUidsAfter>
            <tim:WorkDateRangeEnd>2023-12-31T00:00:00.000Z</tim:WorkDateRangeEnd>
            <tim:WorkDateRangeStart>2023-01-01T00:00:00.000Z</tim:WorkDateRangeStart>
         </pws:serviceRequest>
      </pws:PwsGetFroTimeCards>
   </soapenv:Body>
</soapenv:Envelope>


Response Format


PwsGetFroTimeCards Response

Response Elements


Element

Data Type

Description


Messages

PwsMessage

The web service response status and message. Click here for more information.


ResponseId

Int32

Click here for more information.

1
StatusRequestStatus

Click here for more information.


ServerTimestampUtc

DateTime

Click here for more information.


NextPageTimecardUidsAfter

Int64

If all of the FRO time cards that could have been retrieved were not returned, this field will be populated with the UID of the first FRO Time Card that was not retrieved with the current batch.

PwsFroTimeCards

/wiki/spaces/AD/pages/379977729[]

The details of the retrieved FRO Time Card(s).


Response Usage Example(s)


PwsGetFroTimeCardsRs
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body>
      <PwsGetFroTimeCardsResponse xmlns="http://projectorpsa.com/PwsProjectorServices/">
         <PwsGetFroTimeCardsResult xmlns:a="http://projectorpsa.com/DataContracts/Shared/TimeAndCost/" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
            <Messages xmlns="http://projectorpsa.com/CommonServices/" xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/">
               <b:PwsMessage>
                  <b:AdditionalErrorText>Message 136: This request was executed against the Development [appdevrc.projectorpsa.com] environment.</b:AdditionalErrorText>
                  <b:ErrorCode>NonProductionEnvironment</b:ErrorCode>
                  <b:ErrorNumber>136</b:ErrorNumber>
                  <b:ErrorText>This web service request was executed against a non-production instance of Projector.</b:ErrorText>
                  <b:Type>Information</b:Type>
                  <b:ReferenceId1 i:nil="true"/>
                  <b:ReferenceId2 i:nil="true"/>
               </b:PwsMessage>
            </Messages>
            <ResponseId xmlns="http://projectorpsa.com/CommonServices/">1</ResponseId>
            <Status xmlns="http://projectorpsa.com/CommonServices/">Ok</Status>
            <ServerTimestampUtc xmlns="http://projectorpsa.com/CommonServices/">2023-12-01T22:01:20.448959Z</ServerTimestampUtc>
            <a:NextPageTimecardUidsAfter i:nil="true"/>
            <a:PwsFroTimeCards>
               <a:PwsFroTimecardElement>
                  <a:ApprovedByUser xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/">
                     <b:UserDisplayName>Bettina</b:UserDisplayName>
                     <b:UserId i:nil="true"/>
                     <b:UserReferenceSystemId>QA - BB</b:UserReferenceSystemId>
                     <b:UserUid>1152921504607011056</b:UserUid>
                     <b:EmailAddress>bettina@projectorpsa.com</b:EmailAddress>
                     <b:FirstName>Bettina</b:FirstName>
                     <b:LastName>Borces</b:LastName>
                     <b:MiddleName i:nil="true"/>
                  </a:ApprovedByUser>
                  <a:ApprovedTimestamp>2023-12-01T22:00:58.987Z</a:ApprovedTimestamp>
                  <a:BilledTimestamp>2023-12-01T22:00:58.987Z</a:BilledTimestamp>
                  <a:BillingAdjustmentAmount>0</a:BillingAdjustmentAmount>
                  <a:ContractLineItemIdentity xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/">
                     <b:ContractLineItemCode>E001046-CL1</b:ContractLineItemCode>
                     <b:ContractLineItemId i:nil="true"/>
                     <b:ContractLineItemUid>1152921504607303649</b:ContractLineItemUid>
                  </a:ContractLineItemIdentity>
                  <a:ContractLineItemName>Engagement: For Reporting Only (A)</a:ContractLineItemName>
                  <a:CreatedByUser xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/">
                     <b:UserDisplayName>Bettina</b:UserDisplayName>
                     <b:UserId i:nil="true"/>
                     <b:UserReferenceSystemId>QA - BB</b:UserReferenceSystemId>
                     <b:UserUid>1152921504607011056</b:UserUid>
                     <b:EmailAddress>bettina@projectorpsa.com</b:EmailAddress>
                     <b:FirstName>Bettina</b:FirstName>
                     <b:LastName>Borces</b:LastName>
                     <b:MiddleName i:nil="true"/>
                  </a:CreatedByUser>
                  <a:CreatedTimestamp>2023-12-01T22:00:58.987Z</a:CreatedTimestamp>
                  <a:DayFraction>0</a:DayFraction>
                  <a:EngagementCurrencyIdentity xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/">
                     <b:CurrencyCode>USD</b:CurrencyCode>
                     <b:CurrencyId i:nil="true"/>
                     <b:CurrencyUid>1152921504606851838</b:CurrencyUid>
                  </a:EngagementCurrencyIdentity>
                  <a:EngagementIdentity xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/">
                     <b:EngagementCode>E001046</b:EngagementCode>
                     <b:EngagementId i:nil="true"/>
                     <b:EngagementUid>1152921504607761114</b:EngagementUid>
                  </a:EngagementIdentity>
                  <a:EngagementName>Engagement: For Reporting Only (A)</a:EngagementName>
                  <a:FroTimecardDetail>
                     <ReferenceId i:nil="true" xmlns="http://projectorpsa.com/DataContracts/Shared/Common/"/>
                     <TimecardId i:nil="true" xmlns="http://projectorpsa.com/DataContracts/Shared/Common/"/>
                     <TimecardType xmlns="http://projectorpsa.com/DataContracts/Shared/Common/">T</TimecardType>
                     <TimecardUid xmlns="http://projectorpsa.com/DataContracts/Shared/Common/">1152921504749719168</TimecardUid>
                     <a:AdjustedRevenueAmount>100</a:AdjustedRevenueAmount>
                     <a:ContractRevenueAmount>100</a:ContractRevenueAmount>
                     <a:Description>PwsSaveFroTimeCards</a:Description>
                     <a:DescriptionClearFlag i:nil="true"/>
                     <a:ExternalGroupingIdentifier>1212023</a:ExternalGroupingIdentifier>
                     <a:ExternalGroupingIdentifierClearFlag i:nil="true"/>
                     <a:LocationClearFlag i:nil="true"/>
                     <a:LocationIdentity xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/">
                        <b:LocationId i:nil="true"/>
                        <b:LocationName>USA - Illinois</b:LocationName>
                        <b:LocationUid>1152921504606863508</b:LocationUid>
                     </a:LocationIdentity>
                     <a:ProjectIdentity xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/">
                        <b:ProjectCode>E001046-P001</b:ProjectCode>
                        <b:ProjectId i:nil="true"/>
                        <b:ProjectUid>1152921504607686008</b:ProjectUid>
                     </a:ProjectIdentity>
                     <a:ProjectRateTypeIdentity xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/">
                        <b:ExternalSystemIdentifier i:nil="true"/>
                        <b:ProjectRateTypeId i:nil="true"/>
                        <b:ProjectRateTypeUid>1152921504607818384</b:ProjectRateTypeUid>
                     </a:ProjectRateTypeIdentity>
                     <a:ProjectRoleIdentity xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/">
                        <b:ExternalSystemIdentifier i:nil="true"/>
                        <b:ProjectRoleId i:nil="true"/>
                        <b:ProjectRoleUid>1152921504611115473</b:ProjectRoleUid>
                     </a:ProjectRoleIdentity>
                     <a:ProjectTaskIdentity xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/">
                        <b:ExternalSystemIdentifier i:nil="true"/>
                        <b:ProjectTaskId i:nil="true"/>
                        <b:ProjectTaskUid>1152921504610341347</b:ProjectTaskUid>
                     </a:ProjectTaskIdentity>
                     <a:ResourceIdentity xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/">
                        <b:ResourceDisplayName>Matt</b:ResourceDisplayName>
                        <b:ResourceId i:nil="true"/>
                        <b:ResourceReferenceSystemId>Dev Manager - MJ</b:ResourceReferenceSystemId>
                        <b:ResourceUid>1152921504607057128</b:ResourceUid>
                     </a:ResourceIdentity>
                     <a:SystemRevenueAmount>100</a:SystemRevenueAmount>
                     <a:Timestamp>AAAAADKCBmU=</a:Timestamp>
                     <a:Udf1ClearFlag i:nil="true"/>
                     <a:Udf1Value xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/">
                        <b:UdfId i:nil="true"/>
                        <b:UdfName>TC-Text List</b:UdfName>
                        <b:UdfUid>1152921504606864090</b:UdfUid>
                        <b:BooleanValue i:nil="true"/>
                        <b:DataType>L</b:DataType>
                        <b:DateValue i:nil="true"/>
                        <b:IntegerValue i:nil="true"/>
                        <b:ResourceIdentityValue i:nil="true"/>
                        <b:TextValue i:nil="true"/>
                        <b:UdfTreatment>A</b:UdfTreatment>
                        <b:StoplightValues/>
                        <b:NumericValue i:nil="true"/>
                        <b:RelationValue i:nil="true"/>
                        <b:StoplightValuesClearFlag>false</b:StoplightValuesClearFlag>
                     </a:Udf1Value>
                     <a:Udf2ClearFlag i:nil="true"/>
                     <a:Udf2Value xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/">
                        <b:UdfId i:nil="true"/>
                        <b:UdfName>TC-Numeric</b:UdfName>
                        <b:UdfUid>1152921504606864086</b:UdfUid>
                        <b:BooleanValue i:nil="true"/>
                        <b:DataType>I</b:DataType>
                        <b:DateValue i:nil="true"/>
                        <b:IntegerValue i:nil="true"/>
                        <b:ResourceIdentityValue i:nil="true"/>
                        <b:TextValue i:nil="true"/>
                        <b:UdfTreatment>A</b:UdfTreatment>
                        <b:StoplightValues/>
                        <b:NumericValue i:nil="true"/>
                        <b:RelationValue i:nil="true"/>
                        <b:StoplightValuesClearFlag>false</b:StoplightValuesClearFlag>
                     </a:Udf2Value>
                     <a:WorkDate>2023-11-06T00:00:00Z</a:WorkDate>
                     <a:WorkMinutes>45</a:WorkMinutes>
                  </a:FroTimecardDetail>
                  <a:LastUpdatedByUser xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/">
                     <b:UserDisplayName>Bettina</b:UserDisplayName>
                     <b:UserId i:nil="true"/>
                     <b:UserReferenceSystemId>QA - BB</b:UserReferenceSystemId>
                     <b:UserUid>1152921504607011056</b:UserUid>
                     <b:EmailAddress>bettina@projectorpsa.com</b:EmailAddress>
                     <b:FirstName>Bettina</b:FirstName>
                     <b:LastName>Borces</b:LastName>
                     <b:MiddleName i:nil="true"/>
                  </a:LastUpdatedByUser>
                  <a:LastUpdatedTimestamp>2023-12-01T22:00:58.987Z</a:LastUpdatedTimestamp>
                  <a:ProjectName>Engagement: For Reporting Only (A)</a:ProjectName>
                  <a:ProjectTaskFullWbsCode>1</a:ProjectTaskFullWbsCode>
                  <a:ProjectTaskTypeIdentity xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/">
                     <b:ExternalSystemIdentifier i:nil="true"/>
                     <b:ProjectTaskTypeId i:nil="true"/>
                     <b:ProjectTaskTypeUid>1152921504609305356</b:ProjectTaskTypeUid>
                  </a:ProjectTaskTypeIdentity>
                  <a:RevRecAdjustmentAmount>0</a:RevRecAdjustmentAmount>
               </a:PwsFroTimecardElement>
            </a:PwsFroTimeCards>
         </PwsGetFroTimeCardsResult>
      </PwsGetFroTimeCardsResponse>
   </s:Body>
</s:Envelope>


PwsGetFroTimeCards - Common Errors and Warnings

ErrorNumber

ErrorCode

ErrorText

10119ValueBelowMinimumThe value specified in the field "MaximumResults" in the class "PwsGetFroTimeCardsRq" is out of range. The value must not be less than 1.
50024EntityNotFoundA specified filter item was not found (context-dependent).