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.
EngagementId/EngagementUid/EngagementCode. If specified, the identified engagement will be returned (QueryString and IncludeClosedFlag will be ignored).

Request Format

PwsGetEngagementList Request

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

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. Click here for more information.
IncludeClosedFlag	Boolean	Yes	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. EngagementId/EngagementUid/EngagementCode. If specified, the identified engagement will be returned (QueryString and IncludeClosedFlag will be ignored).	true
MaxRowsToReturn	Int32	No		The maximum number of engagements to be retrieved	5
QueryString	String	No		The engagements that are returned will contain the value in this field
LastUpdatedSinceTimestamp	DateTime	No		Only engagements that have been updated on or after the specified date/time will be retrieved	2018-01-01
PurchaseOrderNumber	String	No		The purchase order number(s) associated with the engagement(s)

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 engagements that were fetched by the service. Click here for more information.

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