Acknowledgments 

Use

Acknowledgments enable you to confirm that an asynchronous message has been received. You must explicitly request acknowledgments in the application program and can specify what kind of confirmation you want to receive.

·        Positive or negative acknowledgments

·        System acknowledgments used by the runtime environment to confirm that an asynchronous message has reached the receiver.

·        Application acknowledgments used to confirm that the asynchronous message has been successfully processed at the receiver.

In the application program you can query and evaluate the status of an acknowledgment.

Prerequisites

The following receivers support acknowledgments:

·        ABAP and Java proxies (XI 3.0 SP1 for the latter)

·        Integration processes

·        IDocs (note that IDocs only return acknowledgments when they have been configured using the ALE audit)

·        Receiver adapters support system acknowledgments but not application acknowledgments

Features

Acknowledgment Types

To request acknowledgments you must set the corresponding fields in the PRX_ACK_REQUEST_DETAILS structure to X. The fields mean the following:

Details for Requesting Acknowledgements (Structure PRX_ACK_REQUEST_DETAILS)

Field	Requested Acknowledgment
SYSTEM_OK	Positive system acknowledgment. The receiver was reached successfully. For server proxies, this means that the implementing class for the server proxy was found and that the method for inbound processing could be called.
SYSTEM_ERROR	Negative system acknowledgment. SAP Exchange Infrastructure runtime reports that an error has occurred during transfer or processing of the message on its way to the receiver. For example, an error in a mapping program or a missing server proxy in the receiver system could trigger this acknowledgment.
APPLICATION_OK	Positive application acknowledgment The message was processed by the receiver successfully.
APPLICATION_ERROR	Negative application acknowledgment An error occurred during message processing at the receiver.

The time at which a message has been successfully processed by a receiver depends on the receiver. For a server proxy, this happens when the method executed at the receiver has not triggered an exception; for an integration process, you can send an acknowledgment explicitly in the send step (see the Sending an Acknowledgment section in Send Step).

You can set these fields individually. Furthermore, ABAP proxy runtime provides constants that you can use to make usual combinations of fields by means of a single assignment. The following table shows which fields you can set by using these constants.

Acknowledgment Constants of the Interface IF_WSPROTOCOL_ASYNC_MESSAGING

Set Field	Acknowledgement Type (Constant)
	Transport (CO_TRANSPORT_ACKNOWLEDGMENT)	Application (CO_APPLICATION_ACKNOWLEDGMENT)	Complete (CO_COMPLETE_ACKNOWLEDGMENT)
SYSTEM_OK	X		X
SYSTEM_ERROR	X	X	X
APPLICATION_OK		X	X
APPLICATION_ERROR		X	X

Querying and Evaluating Acknowledgments

Acknowledgment Methods of the Interface IF_WSPROTOCOL_ASYNC_MESSAGING

Method	Use
SET_ACKNOWLEDGMENT_REQUESTED	Acknowledgment requested by the sender. You can define the requested acknowledgments by using the interface constants or by using individual fields.
GET_ACKNOWLEDGMENT_REQUESTED	Exporting the acknowledgments that were requested.
GET_ACKNOWLEDGMENT	Real-time querying of acknowledgment status by using the instance of the client proxy. The method returns an object of type REF TO IF_WS_ACKNOWLEDGMENT.

Querying the Acknowledgment Object

In the application program, you actively query the status of the acknowledgment by querying an acknowledgment object. You have the following options:

·        If you can still access the client proxy instance, you can query an acknowledgment object in real-time by using the GET_ACKNOWLEDGMENT method.

·        It is unlikely that you will still have access to the client proxy instance when you want to query the status of the acknowledgment. If this is the case, proceed as follows (also see the example below):

...

                            a.      After the proxy call, get the message ID of the message sent (see: Accessing the Message ID).

                            b.      Using the message ID and the CL_PROXY_ACCESS=>GET_ACKNOWLEDGMENT( [Message ID] ) method you can get and evaluate the acknowledgment object.

Using the acknowledgment object you can query whether acknowledgments were received, and if so, which.

Evaluating the Acknowledgment Object

One message may have multiple acknowledgments for the following reasons:

·        You have requested multiple acknowledgments for a single message. For example, if you have requested all acknowledgements and the message was processed and transferred successfully, a positive system acknowledgment (SYSTEM_OK) is sent before the positive application acknowledgment (APPLICATION_OK).

·        If the sender message has multiple receivers in logical routing, the Integration Server copies the inbound message and sends a copy to each receiver (message branching). If the receiver requests acknowledgments for the message that the Integration Server has received, this request then applies for all new messages. These new messages can in turn trigger acknowledgments if multiple acknowledgments were requested for the original message.

To simplify the procedure for requesting acknowledgments, they are aggregated for each receiver. If a new acknowledgment renders an older one obsolete, the latter is ‘overwritten' by the former. For example, when a positive application acknowledgment is received, it is clear that the receiver was reached successfully and therefore the positive system acknowledgment received previously is overwritten. The GET_STATUS_DETAIL method does not aggregate acknowledgments.

Acknowledgments are saved on the database. For the following three methods, you must set the READ_AGAIN parameter to read the current status from the database. To read a queried status again, do not set this parameter.

Acknowledgment Methods of the Interface IF_WS_ACKNOWLEDGMENT

Method	Use
GET_STATUS	Query the aggregated status for a receiver. If there is no acknowledgment, the method triggers the NO_ACK_ARRIVED exception. If the message was branched, the method returns the constant CO_STAT_ACK_SYS_BRANCH for the field ACK_STATUS. In this case, you can query the status by using either of the following methods: GET_STATUS_TREE or GET_STATUS_DETAIL.
GET_STATUS_TREE	Query the aggregated status for multiple receivers. If there is only one receiver, one row in the table corresponds to the return value of GET_STATUS. If the table is empty, no acknowledgment has been received.
GET_STATUS_DETAIL	Detailed tree with status information about the requested acknowledgments, which has not been aggregated.

The report SXI_DEMO_ACK_READ has an example of acknowledgment evaluation.

Example

Requesting an Acknowledgment

Method sendWithACK.

DATA:

* Reference variables for proxy and exception class
 lo_clientProxy     TYPE REF TO [Generated Proxy Class],
 lo_sys_exception   TYPE REF TO cx_ai_system_fault,
 lo_async_messaging TYPE REF TO if_wsprotocol_async_messaging,
 lo_msg_id_protocol TYPE REF TO if_wsprotocol_message_id,
 l_msg_id           TYPE SXMSGUID,
 l_ack_request      TYPE PRX_ACK_REQUEST_DETAILS.

* Structures to set and get message content
 ls_request         TYPE [Output Message Type],

TRY.

* create proxy client

  CREATE OBJECT lo_clientProxy.

* get protocol for asynchronous messaging

  lo_async_messaging ?=
   lo_clientProxy->get_protocol( if_wsprotocol=>async_messaging ).

* Ask for transport acknowledgment

  clear l_ack_request.
  l_ack_request =
    IF_WSPROTOCOL_ASYNC_MESSAGING=>CO_TRANSPORT_ACKNOWLEDGMENT.
  lo_async_messaging->set_acknowledgment_requested( l_ack_request ).

* do asynchronous client proxy call

  CALL METHOD lo_clientProxy->execute_asynchronous
     EXPORTING output  = ls_request.

* get message id of sent message

  lo_msg_id_protocol ?=
    lo_clientProxy->get_protocol( if_wsprotocol=>message_id ).
  l_msg_id = lo_msg_id_protocol->get_message_id( ).

* send message

  COMMIT WORK.

  CATCH cx_ai_system_fault INTO lo_sys_exception.

*   Error handling

ENDTRY.

* Somehow pass the message ID to the caller for an evaluation
* at a later point in time

Return lo_msg_id.

Endmethod.

Querying an Acknowledgment

You can query the acknowledgment object later by using the message ID:

Data:

lo_ack                   TYPE REF TO if_ws_acknowledgment,
l_ack_status_simple type PRX_ACK_STATUS,
l_ack_status_detail type PRX_ACK_STATUS_DETAIL_TABLE.

* read ack
lo_ack = cl_proxy_access=>get_acknowledgment( l_msg_id ).
l_ack_status_simple = lo_ack->get_status( ).
l_ack_status_detail = lo_ack->get_status_detail( ).