This is the method to use for synchronous communication. It takes a payload element as an input, processes it, and returns a result payload all within one HTTP cycle. After invoking this method, the client keeps the connection open waiting for the response. If a response is not received within a predetermined timeout period, the method is considered to have failed.

In certain situations this method might return a SOAP fault element instead of a payload element. For example, if the sender could not be authenticated or the message is not well formed. Fault Codes are described in Chapter 6, Error Handling for more information. Errors related to business rules, on the other hand, MUST NOT be returned as SOAP faults, but returned using the suitable BOD.

	STAR Level 1 Requirement
	STAR1016: Application level error messages MUST NOT be returned with a SOAP Fault, and MUST be returned using the appropriate BOD.

<soapenv:Body>
   <starws:ProcessMessage> 
      <!--Optional:-->
      <starws:payload> 
         <!--Zero or more repetitions:-->
         <starws:content id="?"> 
           < !--You may enter ANY elements at this point--> 
        </starws:content>
     </starws:payload> 
  </starws:ProcessMessage>
</soapenv:Body>

<soapenv:Body>
   <starws:ProcessMessageResponse> 
     <!--Optional:-->
     <starws:payload>
       <!--Zero or more repetitions:-->
       <starws:content id="?"> 
          <!--You may enter ANY elements at this point--> 
       </starws:content>
     </starws:payload>
   </starws:ProcessMessageResponse>
</soapenv:Body>   

The following sequence diagrams show the message exchange sequences for different scenarios.

Figure 2.3. Process Message

Figure 2.4. ProcessMessage with Errors

Figure 2.5. ProcessMessage with Application System Errors

The sequence diagrams that describe the error process are the same whether the PutMessage or PullMessage operation is being implemented instead of the ProcessMessage operation. The processes work the same whether a generic transport or a BOD specific transport is being implemented.

The PutMessage web method is used for asynchronous communication. It accepts a payload element as an input parameter, and returns nothing. Typically, PutMessage is used for messages that do not generate a response or for situations where a response is not returned immediately. The response can be retrieved later by calling PullMessage. The input payload for PutMessage must contain one or more elements.

Although PutMessage does not return any value to the caller, it can return SOAP faults to indicate that the 'put' process was not successful. This typically happens in situations where the message could not be parsed or persisted on the server side. For example, if the SOAP envelope is corrupted and the server can not extract the payload or the sender information then a SOAP fault must be returned on the same connection to inform the sender of the error. Note that business level errors such as invalid values in a BOD should not be returned as SOAP faults, but instead are returned asynchronously (not on the same HTTP connection) in a response BOD that describe the error details. SOAP faults are reserved for errors that prevent the correct parsing or persistence of the message on the server.

<soapenv:Body>
   <starws:PutMessage>
      <!--Optional:-->
      <starws:payload>
         <!--Zero or more repetitions:-->
         <starws:content id="?">
             <!--You may enter ANY elements at this point-->
          </starws:content>
      </starws:payload>
   </starws:PutMessage>
</soapenv:Body>

<soapenv:Body>
  <starws:PutMessageResponse/>
</soapenv:Body>

In a one-way communication pattern, the client uses PutMessage to send a request to a service provider then sends another request using PullMessage (described in the next section) to pull the response. On the other hand, in a two-way communication pattern, the request is sent using PutMessage, and the response is returned using another PutMessage in the reverse direction.

Figure 2.6. Successful PutMessage Sequence

PullMessage is used to retrieve contents from the service provider. The contents can be:

Responses to previous contents (a BOD for example) submitted using PutMessage.

Responses to previous contents submitted using ProcessMessage but could not be delivered back to the requester due to communication or other errors.

Contents that originate from the service provider.

If the client is also a service provider, as in the two-way communication model, PullMessage is not required since both parties can communicate back and forth using PutMessage. However, the parties might choose to still use PullMessage in certain situations.

The service provider must keep track of contents that are deemed to have been received by the client to avoid resending. The client may receive duplicates during error recovery.

	STAR Level 1 Requirement
	STAR1017: The service provider must keep track of contents that are deemed to have been received by the client to avoid resending. STAR1020: The client must be able to handle duplicate messages from a service provider.

Figure 2.7. PullMessage Structure

Filter Criteria:

Beginning in 2008 the PullMessage service was extended to support filtering with the addition of the filter complex type and the maxItems attribute. The filter type allows the requesting party to specify criteria that the responding party must apply when selecting the BODs to be returned in the pull message response. The maxItems attribute can be used to limit the number of BODs that will be returned, regardless of whether or not they satisfy the filter criteria.

For example, the filter criteria and maxItems parameters could be used to to satisfy the following request:

"Retrieve all AcknowledgePartsOrder BODs queued for sending in the last 24 hours.Send a maximum of 20 BODs"

A detailed description of the filter component can be found in section 4.5.

Returns:

This operation returns a payload object that carries one or more elements. Or, it returns an empty response with no payload element if there are no queued contents to return.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tran="http://www.starstandard.org/webservices/2009/transport">
 <soapenv:Header/>
 <soapenv:Body>
    <tran:PullMessage maxItems="?">
       <!--Optional:-->
       <tran:filter>
          <!--Optional:-->
          <tran:filterConnection connectionID="?" destroy="?"/>
          <!--Optional:-->
          <tran:receiptIDs>
             <!--1 or more repetitions:-->
             <tran:receiptID>?</tran:receiptID>
          </tran:receiptIDs>
           <!--Optional:-->
           <tran:filterCriteria>
              <!--1 or more repetitions:-->
              <tran:criteriaList>
                 <!--1 or more repetitions:-->
                 <tran:criteria>
                    <!--Optional:-->
                    <tran:verb tran:operation="?">?</tran:verb>
                    <!--Optional:-->
                    <tran:noun tran:operation="?"></tran:noun>
                    <!--Optional:-->
                    <tran:applicationID tran:operation="?">?</tran:applicationID>
                    <!--Optional:-->
                    <tran:partyID tran:operation="?">?</tran:partyID>
                    <!--Optional:-->
                    <tran:startDateTime tran:operation="?">?</tran:startDateTime>
                    <!--Optional:-->
                    <tran:endDateTime tran:operation="?">?</tran:endDateTime>
                    <!--Optional:-->
                    <tran:pullStatus tran:operation="?">?</tran:pullStatus>
                    <!--Optional:-->
                    <tran:communicatorID tran:operation="?">?</tran:communicatorID>
                    <!--Zero or more repetitions:-->
                    <tran:predefined tran:operation="?">?</tran:predefined>
                 </tran:criteria>
              </tran:criteriaList>
           </tran:filterCriteria>
        </tran:filter>
      </tran:PullMessage>
   </soapenv:Body>
</soapenv:Envelope>

<soapenv:Body>
  <starws:PullMessageResponse>
     <!--Optional:-->
     <starws:payload>
       <!--Zero or more repetitions:-->
       <starws:content id="?">
           <!--You may enter ANY elements at this point-->
       </starws:content>
    </starws:payload>
 </starws:PullMessageResponse>
</soapenv:Body>

Figure 2.8. Successful PullMessage Operation