PwsSaveContractLineItem

Owned by Bettina Borces
Last updated: Feb 02, 2024
14 min read

Overview


This web service inserts or updates a single contract line item based on a detailed contract line item structure (PwsContractLineItemDetail). The service returns the identity (PwsContractLineItemRef) of the contract line item that has been inserted or updated. 

Request Format


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

AdDMw48w49OxnEUPGUuMSw==

ContractLineItem

PwsContractLineItemDetail

Yes 


The detailed contract line item information to be inserted or updated.


EngagementCurrencyIdentity

PwsCurrencyRef

Yes 


The currency of the engagement this contract line item resides under.


EngagementTimestamp

String

**deprecated**




StealLockFlag

Boolean

**deprecated**




ContractTypeClearFlag

Boolean

No 

false 

If set to 'true', the contract type associated with the contract line item will be set to null. This is equivalent to using a 'custom' contract type.

false

OverageProjectClearFlag

Boolean

No 

false 

If set to 'true', the overage project associated with the contract line item will be set to null.

false
NewContractLineItemCodeString (27)No
The new contract item code after update or create/insert.
LocksToStealPwsEntityLockSummary[1.100]No
The detailed information of the locks that are to be stolen. If not specified, the request will fail if any requested locks are already held. If specified, the information supplied must exactly match the current state of existing locks or the attempt to steal the existing locks will fail. Typically, this service is invoked with LocksToSteal empty or null. If there are existing locks, they will be returned in the LockHolders part of PwsFault. This data can then be sent, as is, back to the server in a second invocation of this service, as LocksToSteal, if the caller desires to steal the locks.
ProjectorLockSetIdInt32No
A projector lock set id is an identifier for a group of one or more locks held as a unit.

Request Usage Example(s)


Example 01 - insert 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pws="http://projectorpsa.com/PwsProjectorServices/" xmlns:req="http://projectorpsa.com/DataContracts/Requests/" xmlns:sch="http://projectorpsa.com/DataContracts/Shared/Scheduling/" xmlns:com="http://projectorpsa.com/DataContracts/Shared/Common/">
   <soapenv:Header/>
   <soapenv:Body>
      <pws:PwsSaveContractLineItem>
         <pws:serviceRequest>
            <req:RequestId>1</req:RequestId>
            <req:SessionTicket>AdDMw48w49OxnEUPGUuMSw==</req:SessionTicket>
            <sch:ContractLineItem>
               <com:ContractLineItemName>Phase 2</com:ContractLineItemName>
               <com:EngagementIdentity>
                  <com:EngagementCode>P001320</com:EngagementCode>
               </com:EngagementIdentity>
               <com:HoldbackAmount>5000</com:HoldbackAmount>
               <com:HoldbackType>A</com:HoldbackType>
               <com:MaxTimeContractAmount>50000</com:MaxTimeContractAmount>
               <com:MinTimeContractAmount>50000</com:MinTimeContractAmount>
               <com:RevenueEarnedByDate>2017-06-30T00:00:00.000Z</com:RevenueEarnedByDate>
               <com:RevenueRecognitionMethod>P</com:RevenueRecognitionMethod>
               <com:ContractTypeIdentity>
                  <com:ContractTypeName>Fixed Price Plus Expenses</com:ContractTypeName>
               </com:ContractTypeIdentity>
               <com:InheritPurchaseOrderNumberFlag>false</com:InheritPurchaseOrderNumberFlag>
               <com:ModelContractedHoursAndOveragesFlag>false</com:ModelContractedHoursAndOveragesFlag>
               <com:PurchaseOrderNumber>WS1320-P1</com:PurchaseOrderNumber>
            </sch:ContractLineItem>
            <sch:EngagementCurrencyIdentity>
               <com:CurrencyCode>USD</com:CurrencyCode>
            </sch:EngagementCurrencyIdentity>
            <sch:StealLockFlag>false</sch:StealLockFlag>
            <sch:ContractTypeClearFlag>false</sch:ContractTypeClearFlag>
            <sch:OverageProjectClearFlag>false</sch:OverageProjectClearFlag>
         </pws:serviceRequest>
      </pws:PwsSaveContractLineItem>
   </soapenv:Body>
</soapenv:Envelope>
Example 02 - update 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pws="http://projectorpsa.com/PwsProjectorServices/" xmlns:req="http://projectorpsa.com/DataContracts/Requests/" xmlns:sch="http://projectorpsa.com/DataContracts/Shared/Scheduling/" xmlns:com="http://projectorpsa.com/DataContracts/Shared/Common/">
   <soapenv:Header/>
   <soapenv:Body>
      <pws:PwsSaveContractLineItem>
         <pws:serviceRequest>
            <req:RequestId>1</req:RequestId>
            <req:SessionTicket>ATQ16iJ8SpUnyYfRDdqPsA==</req:SessionTicket>
            <sch:ContractLineItem>
            	<com:ContractLineItemCode>P001125-CL2-2</com:ContractLineItemCode>
               <com:ContractLineItemName>P001125-CL2-2N</com:ContractLineItemName>
               <com:EngagementIdentity>
                  <com:EngagementCode>P001125</com:EngagementCode>
               </com:EngagementIdentity>
               <com:ContractTypeIdentity>
                  <com:ContractTypeName>Time and Materials</com:ContractTypeName>
               </com:ContractTypeIdentity>
               <com:InheritPurchaseOrderNumberFlag>false</com:InheritPurchaseOrderNumberFlag>
               <com:ModelContractedHoursAndOveragesFlag>false</com:ModelContractedHoursAndOveragesFlag>
               <com:PurchaseOrderNumber>P001125-PO</com:PurchaseOrderNumber>
            </sch:ContractLineItem>
            <sch:EngagementCurrencyIdentity>
               <com:CurrencyCode>USD</com:CurrencyCode>
            </sch:EngagementCurrencyIdentity>
            <sch:ContractTypeClearFlag>false</sch:ContractTypeClearFlag>
            <sch:OverageProjectClearFlag>false</sch:OverageProjectClearFlag>
            <sch:NewContractLineItemCode>P001125-CL2-3</sch:NewContractLineItemCode>
            <sch:LocksToSteal>
               <!--Zero or more repetitions:-->
               <com:PwsEntityLockSummary>
                  <!--Optional:-->
                  <com:EntityIdentity>
                     <com:EntityCode>P001125-CL2-2</com:EntityCode>
                      <com:LockType>C</com:LockType>
                  </com:EntityIdentity>
                  <!--Optional:-->
                  <com:EntityLockSummary>
                     <!--Zero or more repetitions:-->
                     <com:PwsEntityLockSummaryItem>
                        <!--Optional:-->
                        <com:LockCount>1</com:LockCount>
                        <!--Optional:-->
                        <com:LockHolderUserIdentity>
                           <!--Optional:-->
                           <com:UserDisplayName>Krakauer, Larry</com:UserDisplayName>
                           <com:UserReferenceSystemId>097</com:UserReferenceSystemId>
                        </com:LockHolderUserIdentity>
                        <!--Optional:-->
                        <com:MostRecentLockAcquisitionTimestamp>2019-01-02T15:49:16.367Z</com:MostRecentLockAcquisitionTimestamp>
                     </com:PwsEntityLockSummaryItem>
                  </com:EntityLockSummary>
               </com:PwsEntityLockSummary>
            </sch:LocksToSteal>
         </pws:serviceRequest>
      </pws:PwsSaveContractLineItem>
   </soapenv:Body>
</soapenv:Envelope>

Response Format


PwsSaveContractLineItem Response

Response Elements


Element

Data Type

Description

Sample Data

Messages

PwsMessage[]

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


ResponseId

Int32

Click here for more information

1

Status

RequestStatus

Click here for more information

Ok

ServerTimestampUtc

DateTime

Click here for more information

2018-01-22T15:02:41.6835065Z

ContractLineItemIdentity

PwsContractLineItemRef

The unique keys used to identify the contract line item.


EngagementTimestamp

String

**deprecated**


LockStolenFromUserIdentity

PwsUserRef

**deprecated**


ContractLineItemTimestampStringThis is an optimistic locking timestamp that, if provided on update request, will cause the request to fail when the timestamp stored in the database does not match the provided value.
StolenLocksPwsEntityLockSummaryThis structure contains information about the locks that were stolen in order to complete this request, Will be included only when LocksToSteal is specified in the request.

Response Usage Example(s)


Example 01 - insert 
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body>
      <PwsSaveContractLineItemResponse xmlns="http://projectorpsa.com/PwsProjectorServices/">
         <PwsSaveContractLineItemResult xmlns:a="http://projectorpsa.com/DataContracts/Shared/Scheduling/" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
            <Messages xmlns="http://projectorpsa.com/CommonServices/" xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/"/>
            <ResponseId xmlns="http://projectorpsa.com/CommonServices/">1</ResponseId>
            <Status xmlns="http://projectorpsa.com/CommonServices/">Ok</Status>
            <ServerTimestampUtc xmlns="http://projectorpsa.com/CommonServices/">2018-01-22T15:02:41.6835065Z</ServerTimestampUtc>
            <a:ContractLineItemIdentity xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/">
               <b:ContractLineItemCode>P001320-CL2</b:ContractLineItemCode>
               <b:ContractLineItemId i:nil="true"/>
               <b:ContractLineItemUid>1152921504607083624</b:ContractLineItemUid>
            </a:ContractLineItemIdentity>
            <a:EngagementTimestamp>AAAAAA9/RYg=</a:EngagementTimestamp>
            <a:LockStolenFromUserIdentity xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/">
               <b:UserDisplayName>Betty Smith</b:UserDisplayName>
               <b:UserId i:nil="true"/>
               <b:UserReferenceSystemId>Partner - 01</b:UserReferenceSystemId>
               <b:UserUid>1152921504607011056</b:UserUid>
            </a:LockStolenFromUserIdentity>
         </PwsSaveContractLineItemResult>
      </PwsSaveContractLineItemResponse>
   </s:Body>
</s:Envelope>
Example 02 - update 
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body>
      <PwsSaveContractLineItemResponse xmlns="http://projectorpsa.com/PwsProjectorServices/">
         <PwsSaveContractLineItemResult xmlns:a="http://projectorpsa.com/DataContracts/Shared/Scheduling/" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
            <Messages xmlns="http://projectorpsa.com/CommonServices/" xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/"/>
            <ResponseId xmlns="http://projectorpsa.com/CommonServices/">1</ResponseId>
            <Status xmlns="http://projectorpsa.com/CommonServices/">Ok</Status>
            <ServerTimestampUtc xmlns="http://projectorpsa.com/CommonServices/">2019-01-02T16:00:21.6805087Z</ServerTimestampUtc>
            <a:ContractLineItemIdentity xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/">
               <b:ContractLineItemCode>P001125-CL2-3</b:ContractLineItemCode>
               <b:ContractLineItemId i:nil="true"/>
               <b:ContractLineItemUid>1152921504607095669</b:ContractLineItemUid>
            </a:ContractLineItemIdentity>
            <a:EngagementTimestamp>AAAAABFSqY4=</a:EngagementTimestamp>
            <a:LockStolenFromUserIdentity xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/">
               <b:UserDisplayName>Krakauer, Larry</b:UserDisplayName>
               <b:UserId i:nil="true"/>
               <b:UserReferenceSystemId>097</b:UserReferenceSystemId>
               <b:UserUid>1152921504606944254</b:UserUid>
            </a:LockStolenFromUserIdentity>
            <a:ContractLineItemTimestamp>AAAAABGd2U8=</a:ContractLineItemTimestamp>
            <a:StolenLocks xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/">
               <b:EntityIdentity>
                  <b:EntityCode>P001125-CL2-2</b:EntityCode>
                  <b:EntityId i:nil="true"/>
                  <b:EntityUid>1152921504607095669</b:EntityUid>
                  <b:LockType>C</b:LockType>
               </b:EntityIdentity>
               <b:EntityLockSummary>
                  <b:PwsEntityLockSummaryItem>
                     <b:LockCount>1</b:LockCount>
                     <b:LockHolderUserIdentity>
                        <b:UserDisplayName>Krakauer, Larry</b:UserDisplayName>
                        <b:UserId i:nil="true"/>
                        <b:UserReferenceSystemId>097</b:UserReferenceSystemId>
                        <b:UserUid>1152921504606944254</b:UserUid>
                     </b:LockHolderUserIdentity>
                     <b:MostRecentLockAcquisitionTimestamp>2019-01-02T15:49:16.367Z</b:MostRecentLockAcquisitionTimestamp>
                  </b:PwsEntityLockSummaryItem>
               </b:EntityLockSummary>
            </a:StolenLocks>
         </PwsSaveContractLineItemResult>
      </PwsSaveContractLineItemResponse>
   </s:Body>
</s:Envelope>

PwsSaveContractLineItem - Common Errors and Warnings


ErrorNumber

ErrorCode

ErrorText

12005InvalidValueForTimeContractTermsThe value specified for time contract terms is invalid. Valid values are T for time and materials, F for fixed price, C for not to exceed and N for non-chargeable.
12010TimeContractAmountsCannotBeSpecifiedMinimum and maximum time contract amounts may not be specified if time contract terms are not specified.
12011InvalidValueForCostContractTermsThe value specified for cost contract terms is invalid. Valid values are T for time and materials, F for fixed price, C for not to exceed and N for non-chargeable.
12016CostContractAmountsCannotBeSpecifiedMinimum and maximum cost contract amounts may not be specified if cost contract terms are not specified.
33000RevenueScheduleGapOrOverlapA gap or overlap was detected in the specified revenue schedule date ranges. The revenue schedule must start at the beginning of time and have no overlaps.
50469EntityAlreadyLockedOne or more existing locks prevent acquisition of requested lock.
54248SpecifiedContractLineItemNotUnderSpecifiedEngagementThe specified contract line item is not under the specified engagement.
54607HoldbackPercentMissingOrInvalidThe holdback percent is required when the holdback type is P, and it must be between 0 and 100.
54608HoldbackAmountMissingOrInvalidThe holdback amount is required when the holdback type is A, and it must be between 0 and the time contract amount.
54609InvalidValueForHoldbackTypeThe value specified for holdback type is invalid. Valid values are N for none, P for percent and A for amount.
54620InvalidFixedPriceContractAmountsFor fixed price contract terms, both the minimum and maximum contract amounts must be specified and must be equal.
54621InvalidNotToExceedContractAmountsFor not to exceed contract terms, the minimum contract amount may not be specified and the maximum contract amount must be specified.
54622InvalidTimeAndMaterialsContractAmountsNeither minimum nor maximum contract amounts may be specified for time and materials contract terms.
54625HolbackAmountCannotBeSpecifiedForFpEngagementThe holdback amount may only be specified for fixed price contract line items
54631NoPermissionToUpdateContractTermsYou do not have appropriate permission to update contract terms for this contract line item.
54948SpecifiedContractLineItemNotFoundSpecified contract line item not found.
54949ContractLineItemMustBeSpecifiedA contract line item identity must be specified.
54965InvalidContractInfoForNonbillableEngagementInvalid contract line item properties requested for non-billable engagement.
54966EngagementCurrencyMismatchCurrency specified does not match engagement currency.
54967RevenueScheduleBucketsInvalidForRevRecMethodPRevenue schedule buckets only be specified on revenue schedules and service contracts.
54968RevenueSchedulesAreForFixedPriceContractsOnlyRevenue recognition method may be specified for fixed price time contract terms only.
54969RevenueScheduleIntegrityErrorThe specified revenue schedule is not valid.
54970ContractLineItemCodeIsRequiredContract line item code is required for new contract line items because account is configured to use manual contract line item numbering.
54971ContractLineItemCodeUnexpectedContract line item code may not be specified because account is configured to use automatic contract line item numbering.
54972ContractLineItemCodeAlreadyInUseSpecified contract line item code already in use.
54985ContractLineItemCodeOrNameInvalidForNonbillableEngagementContract line item name and code cannot be specified for non-billable engagements.
55043CliPurchaseOrderSpecifiedWithoutInheritFlagPurchase order number may not be specified without inherit flag.
55044CliPurchaseOrderSpecifiedWhenInheritingPurchase order number may not be specified when inheriting purchase order number.
55045CliSpecifiedContractTypeIsInactiveSpecified contract type is not active.
55046CannotSpecifyContractAttributesWhenContractTypeSpecifiedFor contract line items of a specific contract type, individual contract terms settings may not be specified.
55047CliInvalidValueForTimeContractTermsInvalid value for time contract terms. Valid values are F for fixed price, T for time and materials, C for time and materials with cap and N for non0chargeable.
55048CliInvalidValueForCostContractTermsInvalid value for cost contract terms. Valid values are F for fixed price, T for time and materials, C for time and materials with cap and N for non0chargeable.
55049CliInvalidValueForRevRecMethodInvalid value for revenue recognition method. Valid values are P for percent complete and R for revenue schedule.
55050CliInvalidContractAmountsForSpecifiedTermsMinimum and maximum contract amounts must be NULL for non-chargeable contract terms.
55051CliHoldbackAmountOrPercentMayNotBeSpecifiedForHoldbackTypeNHoldback percent and holdback amount may not be specified when holdback type is N.
55052CliSpecifyOnlyHoldbackPercentForHoldbackTypePHoldback percent must be specified and holdback amount may not be specified when holdback type is P.
55053CliSpecifyOnlyHoldbackAmountForHoldbackTypeAHoldback amount must be specified and holdback percent may not be specified when holdback type is A.
55054CliCannotModelContractHoursForCurrentContractTermsService contracts are not compatible with selected time contract terms.
55055CliOverageProjectCannotBeSpecifiedNotModelingContractedHoursOverage project cannot be specified if not modelling contracted hours and overages.
55056ScheduledRevenueCannotBeSpecifiedForRevRecMethodPScheduled revenue is required on and limited to revenue schedules.
55057ContractedHoursCannotBeSpecifiedWhenNotModelingContractedHoursContracted hours are required on and limited to service contracts.
55058CliInheritPONumberFlagRequiredForNewContractLineItemsInherit purchase order number flag is required for new contract line items.
55101OverageProjectNotInSameEngagementThe project specified as the overage project must be a part of the same engagement.
55102OverageProjectMayNotBeOnSameCliThe project specified as the overage project may not be on the same contract line item.
55103OverageProjectMayNotBeDtmThe project specified as the overage project may not have the project management module enabled.
55104InvalidOverageProjectContractTermsOverage projects must be part of a contract line item with time contract terms of non-chargeable, time and materials or not to exceed.
55105OverageProjectCannotBeServiceContractOverage projects may not be part of another service contract.
55106MultipleServiceContractsCannotShareOverageProjectMultiple service contracts may not refer to the same overage project.
55107RevenueScheduleDataNotAllowedRevenue schedule data may only be specified on contract line items that are revenue schedules or service contracts
55108SpecifiedContractTermsNotCompleteSpecified contract terms are incomplete.
55109CannotModelContractedHoursPmEnabledModel contracted hours and overages flag cannot be enabled because one or more projects associated with this contract line item have the PM module enabled, or the designated overage project has the PM module enabled
55110CliCannotIncludeDtmProjectsProjects under a contract line item that is configured to model contracted hours and overages may not have the project management module enabled.
55111DtmCannotBeEnabledForOverageProjectProjects designated as overage projects may not have the project management module enabled.
55128CannotDeleteOverageProjectProject cannot be deleted because it has been designated as the overage project for a service contract.
55129TimeContractTermsCannotBeSetNonchargeableThe time contract terms may not be changed for this contract line item because there are approved time cards associated with the contract line item.
55130CostContractTermsCannotBeSetNonchargeableThe cost contract terms may not be changed for this contract line item because there are approved cost cards associated with the contract line item.
55131ServiceContractHasInvoicedPeriodsCannot disable modeling of contracted hours and overages because at least one service period has been invoiced.
55130CostContractTermsCannotBeSetNonchargeableThe cost contract terms may not be changed for this contract line item because there are approved cost cards associated with the contract line item.
55131ServiceContractHasInvoicedPeriodsCannot disable modeling of contracted hours and overages because at least one service period has been invoiced.
55138IncompleteContractTypeAttributesWhen creating a contract line item with a custom contract type, all contract type attributes must be specified.
56004CannotConvertContractToRevenueScheduleOn conversion from percent complete to a revenue schedule, there must be a single bucket for revenue through the existing cutoff date for recognized revenue to date.
56005CannotModifyScheduledBucketPriorToRevRecCutoffDateRevenue schedule buckets prior to the revenue recognition cutoff date cannot be modified.