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. This flag is disregarded if an engagement is specified. 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. This flag is disregarded if an engagement is specified.	5
QueryString	String	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. This value is disregarded if a cost center is specified in EngagementIdentity. Click here for more information.
LastUpdatedSinceTimestamp	DateTime	No		Only engagements that have been updated on or after the specified date/time will be retrieved. This flag is disregarded if an engagement is specified.	2018-01-01
PurchaseOrderNumber	String	No		The purchase order number(s) associated with the engagement(s). This flag 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 [0..infinity]

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 [0..infinity]	The engagement summary records 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