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
| Panel | ||
|---|---|---|
| ||
|
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 | 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.
| 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 | The engagements that are returned will contain the value in this field. This flag is disregarded if an engagement is specified. | ||
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)
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
<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> |
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
<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
| Panel | ||
|---|---|---|
| ||
|
Response Elements
Element | Data Type | Description | Sample Data |
|---|---|---|---|
Messages | 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)
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
<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 |