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

PwsSaveContractLineItem
- serviceRequest: PwsSaveContractLineItemRq
  - RequestId: Int32
  - SessionTicket: String
  - ContractLineItem: PwsContractLineItemDetail
  - EngagementCurrencyIdentity: PwsCurrencyRef
  - EngagementTimestamp: String **deprecated**
  - StealLockFlag: Boolean **deprecated**
  - ContractTypeClearFlag: Boolean
  - OverageProjectClearFlag: Boolean
  - NewContractLineItemCode: String (27)
  - LocksToSteal: PwsEntityLockSummary[1.100]
  - ProjectorLockSetId: Int32

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
NewContractLineItemCode	String (27)	No		The new contract item code after update or create/insert.
LocksToSteal	PwsEntityLockSummary[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.
ProjectorLockSetId	Int32	No		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>Ade8vXDjCIr0kcDpdVTbCw==</req:SessionTicket>
            <sch:ContractLineItem>
            	<com:ContractLineItemCode>P001125-CL2</com:ContractLineItemCode>
               <com:ContractLineItemName>P001125-CL2 Name</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-2</sch:NewContractLineItemCode>
         </pws:serviceRequest>
      </pws:PwsSaveContractLineItem>
   </soapenv:Body>
</soapenv:Envelope>

Response Format

PwsSaveContractLineItem Response

PwsSaveContractLineItemResponse
- PwsSaveContractLineItemResult: PwsSaveContractLineItemRs
  - Messages: PwsMessage []
  - ResponseId: Int32
  - Status: RequestStatus
  - ServerTimestampUtc: DateTime
  - ContractLineItemIdentity: PwsContractLineItemRef
  - EngagementTimestamp: String **deprecated**
  - LockStolenFromUserIdentity: PwsUserRef **deprecated**
  - ContractLineItemTimestamp: String
  - StolenLocks: PwsEntityLockSummary

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
ContractLineItemTimestamp	String	This 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.
StolenLocks	PwsEntityLockSummary	This 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

<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/">2018-11-12T16:27:41.3088062Z</ServerTimestampUtc>
            <a:ContractLineItemIdentity xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/">
               <b:ContractLineItemCode>P001125-CL2-2</b:ContractLineItemCode>
               <b:ContractLineItemId i:nil="true"/>
               <b:ContractLineItemUid>1152921504607095669</b:ContractLineItemUid>
            </a:ContractLineItemIdentity>
            <a:EngagementTimestamp>AAAAABE+AqI=</a:EngagementTimestamp>
            <a:LockStolenFromUserIdentity i:nil="true" xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/"/>
            <a:ContractLineItemTimestamp>AAAAABFCno4=</a:ContractLineItemTimestamp>
            <a:StolenLocks i:nil="true" xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/"/>
         </PwsSaveContractLineItemResult>
      </PwsSaveContractLineItemResponse>
   </s:Body>
</s:Envelope>

PwsSaveContractLineItem - Common Errors and Warnings

For all errors and warnings please refer to the Complete List of Errors and Warnings

ErrorNumber	ErrorCode	ErrorText
12005	InvalidValueForTimeContractTerms	The 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.
12010	TimeContractAmountsCannotBeSpecified	Minimum and maximum time contract amounts may not be specified if time contract terms are not specified.
12011	InvalidValueForCostContractTerms	The 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.
12016	CostContractAmountsCannotBeSpecified	Minimum and maximum cost contract amounts may not be specified if cost contract terms are not specified.
54248	SpecifiedContractLineItemNotUnderSpecifiedEngagement	The specified contract line item is not under the specified engagement.
54607	HoldbackPercentMissingOrInvalid	The holdback percent is required when the holdback type is P, and it must be between 0 and 100.
54608	HoldbackAmountMissingOrInvalid	The holdback amount is required when the holdback type is A, and it must be between 0 and the time contract amount.
54609	InvalidValueForHoldbackType	The value specified for holdback type is invalid. Valid values are N for none, P for percent and A for amount.
54620	InvalidFixedPriceContractAmounts	For fixed price contract terms, both the minimum and maximum contract amounts must be specified and must be equal.
54621	InvalidNotToExceedContractAmounts	For not to exceed contract terms, the minimum contract amount may not be specified and the maximum contract amount must be specified.
54622	InvalidTimeAndMaterialsContractAmounts	Neither minimum nor maximum contract amounts may be specified for time and materials contract terms.
54625	HolbackAmountCannotBeSpecifiedForFpEngagement	The holdback amount may only be specified for fixed price contract line items
54631	NoPermissionToUpdateContractTerms	You do not have appropriate permission to update contract terms for this contract line item.
54948	SpecifiedContractLineItemNotFound	Specified contract line item not found.
54949	ContractLineItemMustBeSpecified	A contract line item identity must be specified.
54965	InvalidContractInfoForNonbillableEngagement	Invalid contract line item properties requested for non-billable engagement.
54967	RevenueScheduleBucketsInvalidForRevRecMethodP	Revenue schedule buckets only be specified on revenue schedules and service contracts.
54968	RevenueSchedulesAreForFixedPriceContractsOnly	Revenue recognition method may be specified for fixed price time contract terms only.
54970	ContractLineItemCodeIsRequired	Contract line item code is required for new contract line items because account is configured to use manual contract line item numbering.
54971	ContractLineItemCodeUnexpected	Contract line item code may not be specified because account is configured to use automatic contract line item numbering.
54972	ContractLineItemCodeAlreadyInUse	Specified contract line item code already in use.
54985	ContractLineItemCodeOrNameInvalidForNonbillableEngagement	Contract line item name and code cannot be specified for non-billable engagements.
55043	CliPurchaseOrderSpecifiedWithoutInheritFlag	Purchase order number may not be specified without inherit flag.
55044	CliPurchaseOrderSpecifiedWhenInheriting	Purchase order number may not be specified when inheriting purchase order number.
55045	CliSpecifiedContractTypeIsInactive	Specified contract type is not active.
55046	CannotSpecifyContractAttributesWhenContractTypeSpecified	For contract line items of a specific contract type, individual contract terms settings may not be specified.
55047	CliInvalidValueForTimeContractTerms	Invalid 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.
55048	CliInvalidValueForCostContractTerms	Invalid 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.
55049	CliInvalidValueForRevRecMethod	Invalid value for revenue recognition method. Valid values are P for percent complete and R for revenue schedule.
55050	CliInvalidContractAmountsForSpecifiedTerms	Minimum and maximum contract amounts must be NULL for non-chargeable contract terms.
55051	CliHoldbackAmountOrPercentMayNotBeSpecifiedForHoldbackTypeN	Holdback percent and holdback amount may not be specified when holdback type is N.
55052	CliSpecifyOnlyHoldbackPercentForHoldbackTypeP	Holdback percent must be specified and holdback amount may not be specified when holdback type is P.
55053	CliSpecifyOnlyHoldbackAmountForHoldbackTypeA	Holdback amount must be specified and holdback percent may not be specified when holdback type is A.
55054	CliCannotModelContractHoursForCurrentContractTerms	Service contracts are not compatible with selected time contract terms.
55055	CliOverageProjectCannotBeSpecifiedNotModelingContractedHours	Overage project cannot be specified if not modelling contracted hours and overages.
55056	ScheduledRevenueCannotBeSpecifiedForRevRecMethodP	Scheduled revenue is required on and limited to revenue schedules.
55057	ContractedHoursCannotBeSpecifiedWhenNotModelingContractedHours	Contracted hours are required on and limited to service contracts.
55058	CliInheritPONumberFlagRequiredForNewContractLineItems	Inherit purchase order number flag is required for new contract line items.
55101	OverageProjectNotInSameEngagement	The project specified as the overage project must be a part of the same engagement.
55102	OverageProjectMayNotBeOnSameCli	The project specified as the overage project may not be on the same contract line item.
55103	OverageProjectMayNotBeDtm	The project specified as the overage project may not have the project management module enabled.
55104	InvalidOverageProjectContractTerms	Overage projects must be part of a contract line item with time contract terms of non-chargeable, time and materials or not to exceed.
55105	OverageProjectCannotBeServiceContract	Overage projects may not be part of another service contract.
55106	MultipleServiceContractsCannotShareOverageProject	Multiple service contracts may not refer to the same overage project.
55107	RevenueScheduleDataNotAllowed	Revenue schedule data may only be specified on contract line items that are revenue schedules or service contracts
55108	SpecifiedContractTermsNotComplete	Specified contract terms are incomplete.
55109	CannotModelContractedHoursPmEnabled	Model 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
55110	CliCannotIncludeDtmProjects	Projects under a contract line item that is configured to model contracted hours and overages may not have the project management module enabled.
55111	DtmCannotBeEnabledForOverageProject	Projects designated as overage projects may not have the project management module enabled.
55128	CannotDeleteOverageProject	Project cannot be deleted because it has been designated as the overage project for a service contract.
55129	TimeContractTermsCannotBeSetNonchargeable	The time contract terms may not be changed for this contract line item because there are approved time cards associated with the contract line item.
55130	CostContractTermsCannotBeSetNonchargeable	The cost contract terms may not be changed for this contract line item because there are approved cost cards associated with the contract line item.
55131	ServiceContractHasInvoicedPeriods	Cannot disable modeling of contracted hours and overages because at least one service period has been invoiced.
55130	CostContractTermsCannotBeSetNonchargeable	The cost contract terms may not be changed for this contract line item because there are approved cost cards associated with the contract line item.
55131	ServiceContractHasInvoicedPeriods	Cannot disable modeling of contracted hours and overages because at least one service period has been invoiced.
56004	CannotConvertContractToRevenueSchedule	On 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.
56005	CannotModifyScheduledBucketPriorToRevRecCutoffDate	Revenue schedule buckets prior to the revenue recognition cutoff date cannot be modified.