Overview

This web service is used to request and/or schedule hours on an existing role. This web service also allows users to specify a candidate for an existing role as a requester or scheduler.

Request Format

PwsRequestOrBookRoleHours Request

- PwsRequestOrBookRoleHoursRq
  - RequestId: Int32
  - SessionTicket: String
  - FinalizeOrder: PwsProjectRoleApproveFinalizeOrder
  - Mode: String
  - ProjectRoles: PwsProjectRoleHours[]
  - SubmitOrder: PwsProjectRoleSubmitOrder

Request Elements

Element	Data Type	Required?	Description	Sample Data
RequestId	Int32	No	Click here for more information	1
SessionTicket	String	Yes	Click here for more information	ATWHktwSz1Ga38IARiym4w==
FinalizeOrder	PwsProjectRoleApproveFinalizeOrder	No	The constraint, effective date, allocation notes and notification e-mails that the scheduler would like to apply to this booking. If the authenticated user is a scheduler they can utilize this operation to finalize the role.
Mode	String	Yes	"A" for Scheduler "R" for Requester	R
ProjectRoles	PwsProjectRoleHours[]	Yes	This structure represents multiple elements associated with a project role, including the candidate identity, hours and allocation notes.
SubmitOrder	PwsProjectRoleSubmitOrder	No	The constraint, effective date and allocation notes the requester would like to apply to this request. The requester can also specify the scheduler he/she would like to notify of this request here. If the authenticated user is a requester they can utilize this operation to submit the role.

Request Usage Example(s)

Requester Example

<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/" xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
   <soapenv:Header/>
   <soapenv:Body>
      <pws:PwsRequestOrBookRoleHours>
         <pws:serviceRequest>
            <req:RequestId>1</req:RequestId>
            <req:SessionTicket>ATWHktwSz1Ga38IARiym4w==</req:SessionTicket>
            <sch:Mode>R</sch:Mode>
            <sch:ProjectRoles>
               <com:PwsProjectRoleHours>
                  <com:CandidateResourceClearFlag>false</com:CandidateResourceClearFlag>
                  <com:CandidateResourceIdentity>
                     <com:ResourceDisplayName>Matt</com:ResourceDisplayName>
                     <com:ResourceReferenceSystemId>IT (USA) - 01</com:ResourceReferenceSystemId>
                  </com:CandidateResourceIdentity>
                  <com:ClearExistingHoursFlag>false</com:ClearExistingHoursFlag>
                  <com:HoursBuckets>
                     <com:PwsProjectRoleHoursBucket>
                        <com:BucketStartDate>2020-01-06T00:00:00.000Z</com:BucketStartDate>
                        <com:DailyMinutes>
                           <arr:short>480</arr:short>
                           <arr:short>480</arr:short>
                           <arr:short>480</arr:short>
                           <arr:short>480</arr:short>
                           <arr:short>480</arr:short>
                           <arr:short>0</arr:short>
                           <arr:short>0</arr:short>
                        </com:DailyMinutes>
                        <com:SchedulingMode>D</com:SchedulingMode>
                     </com:PwsProjectRoleHoursBucket>
                  </com:HoursBuckets>
                  <com:LeaveRequestOpenFlag>true</com:LeaveRequestOpenFlag>
                  <com:NotesBuckets>
                     <com:PwsProjectRoleNotesBucket>
                        <com:BucketStartDate>2020-01-06T00:00:00.000Z</com:BucketStartDate>
                        <com:Notes>
                           <arr:string>Monday</arr:string>
                           <arr:string>Tuesday</arr:string>
                           <arr:string>Wednesday</arr:string>
                           <arr:string>Thursday</arr:string>
                           <arr:string>Friday</arr:string>
                           <arr:string>Saturday</arr:string>
                           <arr:string>Sunday</arr:string>
                        </com:Notes>
                     </com:PwsProjectRoleNotesBucket>
                  </com:NotesBuckets>
                  <com:ProjectRoleIdentity>
                     <com:ProjectRoleUid>1152921504609839438</com:ProjectRoleUid>
                  </com:ProjectRoleIdentity>
               </com:PwsProjectRoleHours>
            </sch:ProjectRoles>
            <sch:SubmitOrder>
               <sch:ConstraintType>N</sch:ConstraintType>
               <sch:EffectiveDate>2020-01-06T00:00:00.000Z</sch:EffectiveDate>
               <sch:SchedulerNotes>Submitting Hours for Review</sch:SchedulerNotes>
            </sch:SubmitOrder>
         </pws:serviceRequest>
      </pws:PwsRequestOrBookRoleHours>
   </soapenv:Body>
</soapenv:Envelope>

Scheduler Example

<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/" xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
   <soapenv:Header/>
   <soapenv:Body>
      <pws:PwsRequestOrBookRoleHours>
         <pws:serviceRequest>
            <req:RequestId>1</req:RequestId>
            <req:SessionTicket>ARwMngBGKwdzQCzOjMwz0w==</req:SessionTicket>
            <sch:FinalizeOrder>
               <sch:ConstraintType>N</sch:ConstraintType>
               <sch:EffectiveDate>2020-01-06T00:00:00.000Z</sch:EffectiveDate>
               <sch:ProjectManagerNotes>Scheduling Hours</sch:ProjectManagerNotes>
               <sch:SendBookingEmailFlag>true</sch:SendBookingEmailFlag>
               <sch:SendPmBookingEmailFlag>false</sch:SendPmBookingEmailFlag>
            </sch:FinalizeOrder>
            <sch:Mode>A</sch:Mode>
            <sch:ProjectRoles>
               <com:PwsProjectRoleHours>
                  <com:CandidateResourceClearFlag>false</com:CandidateResourceClearFlag>
                  <com:ClearExistingHoursFlag>false</com:ClearExistingHoursFlag>
                  <com:CopyRequestedHoursFlag>true</com:CopyRequestedHoursFlag>
                  <com:LeaveRequestOpenFlag>false</com:LeaveRequestOpenFlag>
                  <com:ProjectRoleIdentity>
                     <com:ProjectRoleUid>1152921504609839438</com:ProjectRoleUid>
                  </com:ProjectRoleIdentity>
                  <!--com:Timestamp>?</com:Timestamp-->
               </com:PwsProjectRoleHours>
            </sch:ProjectRoles>
         </pws:serviceRequest>
      </pws:PwsRequestOrBookRoleHours>
   </soapenv:Body>
</soapenv:Envelope>

Response Format

PwsRequestOrBookRoleHours Response

- PwsRequestOrBookRoleHoursRs
  - Messages: PwsMessage[]
  - ResponseId: Int32
  - Status: RequestStatus
  - ServerTimestampUtc: DateTime
  - ApprovedProjectRoles: PwsProjectRoleApprovalResult[]
  - SubmittedProjectRoles: PwsProjectRoleSubmissionResult[]

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.	2020-02-05T18:32:37.2718391Z
ApprovedProjectRoles	PwsProjectRoleApprovalResult[]	The response to a scheduler's submission to book hours and/or a candidate
SubmittedProjectRoles	PwsProjectRoleSubmissionResult[]	The response to a requester's submission to request hours and/or a candidate

Response Usage Example(s)

Requester Example

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body>
      <PwsRequestOrBookRoleHoursResponse xmlns="http://projectorpsa.com/PwsProjectorServices/">
         <PwsRequestOrBookRoleHoursResult 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/">2020-02-05T18:32:37.2718391Z</ServerTimestampUtc>
            <a:ApprovedProjectRoles xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/"/>
            <a:SubmittedProjectRoles xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/">
               <b:PwsProjectRoleSubmissionResult>
                  <b:OverallocationFlag>false</b:OverallocationFlag>
                  <b:ProjectRoleIdentity>
                     <b:ExternalSystemIdentifier i:nil="true"/>
                     <b:ProjectRoleId i:nil="true"/>
                     <b:ProjectRoleUid>1152921504609839438</b:ProjectRoleUid>
                  </b:ProjectRoleIdentity>
               </b:PwsProjectRoleSubmissionResult>
            </a:SubmittedProjectRoles>
         </PwsRequestOrBookRoleHoursResult>
      </PwsRequestOrBookRoleHoursResponse>
   </s:Body>
</s:Envelope>

Scheduler Example

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body>
      <PwsRequestOrBookRoleHoursResponse xmlns="http://projectorpsa.com/PwsProjectorServices/">
         <PwsRequestOrBookRoleHoursResult 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/">2020-02-05T18:40:35.4908317Z</ServerTimestampUtc>
            <a:ApprovedProjectRoles xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/">
               <b:PwsProjectRoleApprovalResult>
                  <b:OverallocationFlag>false</b:OverallocationFlag>
                  <b:ProjectRoleIdentity>
                     <b:ExternalSystemIdentifier i:nil="true"/>
                     <b:ProjectRoleId i:nil="true"/>
                     <b:ProjectRoleUid>1152921504609839438</b:ProjectRoleUid>
                  </b:ProjectRoleIdentity>
                  <b:TotalApprovedOrFinalizedMinutes>2400</b:TotalApprovedOrFinalizedMinutes>
               </b:PwsProjectRoleApprovalResult>
            </a:ApprovedProjectRoles>
            <a:SubmittedProjectRoles xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/"/>
         </PwsRequestOrBookRoleHoursResult>
      </PwsRequestOrBookRoleHoursResponse>
   </s:Body>
</s:Envelope>

PwsRequestOrBookRoleHoursResponse - Common Errors and Warnings

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

Error Number	Error Code	Error Text
50024	EntityNotFound	Error 50024, State 3: Entity not found ### [context:][entityName:Resource][refStructureName:PwsResourceRef]
50406	InvalidParametersForWebService	Parameter values provided are invalid.
55048	CannotChangeRequestedResourceAllocatedCriteria	Error 55048, State 1: Requested resource may not be changed because the role has allocated criteria ### [roleName:Developer]
55209	NoPermissionToBookHours	Error 55209, State 1: No permission to book hours (user = 207246, project role = 2992462) ### [roleName:Developer]