Overview

This web service retrieves a list of engagement summary records (PwsEngagementSummary), based on specified search criteria. The following parameters affect the list of engagements retrieved:

QueryString. Find all engagements matching specified string in engagement name or engagement code, client name or code (for engagement's client and any of it's parent clients) or project name or code (for projects that are part of the engagement).
IncludeClosedFlag. If true, engagements that are open or closed according to the current engagement stage settings will be returned. Otherwise, only engagements that are not considered closed will be returned.
LastUpdatedSinceTimestamp. If specified, only engagements updated after the specified timestamp will be retrieved.
PurchaseOrderNumber. If specified, only engagements with a purchase number that exactly matches the specified value will be retrieved.
EngagementId/EngagementUid/EngagementCode. If specified, the identified engagement will be returned (QueryString, IncludeClosedFlag, LastUpdatedSinceTimestamp and PurchaseOrderNumber will be ignored).

Request Format

PwsGetEngagementList Request

PwsGetEngagementList
- serviceRequest: PwsGetEngagementListRq
  - RequestId: Int32
  - SessionTicket: String
  - EngagementIdentity: PwsEngagementRef
  - IncludeClosedFlag: Boolean
  - MaxRowsToReturn: Int32
  - QueryString: String (255)
  - LastUpdatedSinceTimestamp: DateTime
  - PurchaseOrderNumber: String (50)

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	Ab54WRQ1LlgW9CoQrXhyzw==
EngagementIdentity	PwsEngagementRef	No		The unique keys used to identify the engagement(s) to be retrieved
IncludeClosedFlag	Boolean	No	false	If set to 'true', engagements that are open or closed according to the current engagement stage settings will be returned. Otherwise, only engagements that are not considered closed will be returned. This flag is disregarded if an engagement is specified in EngagementIdentity.	true
MaxRowsToReturn	Int32	No		The maximum number of engagements to be retrieved. This value is disregarded if an engagement is specified in EngagementIdentity.	5
QueryString	String (255)	No		A search string to narrow down the results. An engagement will be included in the results if the search string matches the engagement code or engagement name, or if it matches the client name or number for the engagement's client or any parent client thereof, or if it matches the contract line item name or code or project name or code of any contract line item or project contained in the engagement. This value is disregarded if an engagement is specified in EngagementIdentity.
LastUpdatedSinceTimestamp	DateTime	No		Only engagements that have been updated on or after the specified date/time will be retrieved. This value is disregarded if an engagement is specified.	2018-01-01
PurchaseOrderNumber	String (50)	No		An exact match filter on the engagement purchase order number. If specified, only engagements whose purchase order number exactly matches the specified value will be included in the response. This value is disregarded if an engagement is specified.

Request Usage Example(s)

Example 01 - Engagement is not specified

<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:PwsGetEngagementList>
         <pws:serviceRequest>
            <req:RequestId>1</req:RequestId>
            <req:SessionTicket>Ab54WRQ1LlgW9CoQrXhyzw==</req:SessionTicket>
            <sch:IncludeClosedFlag>true</sch:IncludeClosedFlag>
            <sch:MaxRowsToReturn>5</sch:MaxRowsToReturn>
            <sch:LastUpdatedSinceTimestamp>2018-01-01</sch:LastUpdatedSinceTimestamp>
         </pws:serviceRequest>
      </pws:PwsGetEngagementList>
   </soapenv:Body>
</soapenv:Envelope>

Example 02 - Engagement is specified

<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:PwsGetEngagementList>
         <pws:serviceRequest>
            <req:RequestId>1</req:RequestId>
            <req:SessionTicket>Ab54WRQ1LlgW9CoQrXhyzw==</req:SessionTicket>
            <sch:EngagementIdentity>
               <com:EngagementCode>P001320</com:EngagementCode>
            </sch:EngagementIdentity>
            <sch:IncludeClosedFlag>false</sch:IncludeClosedFlag>
         </pws:serviceRequest>
      </pws:PwsGetEngagementList>
   </soapenv:Body>
</soapenv:Envelope>

Response Format

PwsGetEngagementList Response

PwsGetEngagementListResponse
- PwsGetEngagementListResult: PwsGetEngagementListRs
  - Messages: PwsMessage[]
  - ResponseId: Int32
  - Status: RequestStatus
  - ServerTimestampUtc: DateTime
  - Engagements: PwsEngagementSummary[]

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-19T16:51:13.0252909Z
Engagements	PwsEngagementSummary[]	The engagement summary records that were fetched by the service

Response Usage Example(s)

Example 01

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body>
      <PwsGetEngagementListResponse xmlns="http://projectorpsa.com/PwsProjectorServices/">
         <PwsGetEngagementListResult 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-19T16:51:13.0252909Z</ServerTimestampUtc>
            <a:Engagements xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/">
               <b:PwsEngagementSummary>
                  <b:EngagementCode>P001320</b:EngagementCode>
                  <b:EngagementId i:nil="true"/>
                  <b:EngagementUid>1152921504607326368</b:EngagementUid>
                  <b:ClientIdentity>
                     <b:ClientId i:nil="true"/>
                     <b:ClientNumber>C000121</b:ClientNumber>
                     <b:ClientUid>1152921504606998462</b:ClientUid>
                  </b:ClientIdentity>
                  <b:EngagementName>Web Services Documentation</b:EngagementName>
               </b:PwsEngagementSummary>
            </a:Engagements>
         </PwsGetEngagementListResult>
      </PwsGetEngagementListResponse>
   </s:Body>
</s:Envelope>

PwsGetEngagementList - Common Errors and Warnings

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

ErrorNumber	ErrorCode	Description
104	RowCountExceeded	Exceeded maximum row count
10100	MaxRowsToReturnOutOfRange	Invalid value specified for MaxRowsToReturn
50045	ViewPermissionDenied	Permission denied
54024	UnexpectedErrorRetrievingEngagementList	Unexpected error retrieving engagement list
54061	EngagementNotFound	Specified engagement not found
54370	NoPermissionToViewEngagement	Permission denied to view specific engagement