Show TOC

Alerting API on Alert EngineLocate this document in the navigation structure

Use

The API for accessing the Alert Engine is available as a Web service. This service is available both on AS ABAP and AS Java systems that support component-based message alerting. You can use the following versions of the API:

  • AlertRetrieveAPI is available both on AS ABAP and AS Java systems.

  • AlertRetrieveAPI_V2 is an extended version that features additional input and output parameters. This Web service is available only on Advanced Adapter Engine Extended (AEX) systems.

When you want to develop an alert consumer, you should implement in it a Web service client that connects to the alerting API on the Alert Engine. This way your alert consumer would be able to retrieve alerts intended for it from the corresponding local store of the Alert Engine.

You can obtain information about the available HTTP and HTTPS endpoints of the Web service using the Web service configuration tools. For more information, see Configuring a Service Provider (for AS ABAP) and Configuring Individual Web Services (for AS Java).

Prerequisites

The alert consumer should have a user account that includes the SAP_XI_ALERT_CONSUMER role to be able to retrieve alerts.

Features

Using the RetrieveSingleAlerts operation you can retrieve a set of alerts available on the Alert Engine.

The following input parameters are included in the RetrieveSingleAlertsRequest data structure (both are mandatory):

  • Use the ConsumerID input parameter to specify the name of the alert consumer that requests the alerts.

  • Use the MaxAlerts input parameter to specify the number of alerts to be retrieved.

  • On the AlertRetrieveAPI_V2 version of the API, you can additionally use the following input parameters:

    • Use the Language input parameter to enter a two-letter language code. This way you can specify the preferred language for the values you would obtain for the parameters in the DetailsValues data structure in the operation response.

    • Use the OptionalDetails data structure to specify alerting details for which you want to obtain information directly in the operation response. You should specify each alerting detail in the ParameterName input parameter. The values you can enter for this parameter are ERROR_DETAILS and IFLOW_NAME .

The operation response contains alerts intended for the requesting alert consumer. The results are provided in the RetrieveSingleAlertsResponse data structure ( RetrieveSingleAlertsResponse_V2 for the AlertRetrieveAPI_V2 version of the API), which contains the following information for each alert:

  • AlertPayload contains the alert. You can see an example of an alert below.

  • AlertRuleID contains the technical ID of the alert.

  • ComponentID contains the name of the runtime component for which the alert has been created.

  • IntegrationFlowID contains the integration flow relevant for the message for which the alert has been created.

  • AlertsDeleted shows the number of alerts that have been deleted by the alert engine during the maintenance of its queues. For more information, see Maintaining Alert Engine Processes .

  • ErrorLabelID contains the error label relevant for the message for which the alert has been created.

  • On the AlertRetrieveAPI_V2 version of the API, you can additionally obtain the following information in the DetailsValues data structure:

    • PROTOCOL_VERSION and JSON_VERSION are always provided; they contain technical information.

    • ERROR_DETAILS and IFLOW_NAME are provided only when you have specified them in the request. ERROR_DETAILS contains details about the message error, and IFLOW_NAME contains details of the integration flow associated with the message.

Example

The following sample alert has been created as a result of the FILE_PROCESSING_ERROR error during message processing:

            "AdapterType": "File",
            "Component": "af.abc.def",
            "ErrCat": "XI_J2EE_ADAPTER_FILE",
            "ErrCode": "FILE_PROCESSING_ERROR",
            "ErrLabel": "1503",
            "ErrText": "An error occurred while connecting to the FTP server \"server345:21\".
The FTP server returned the following error message: 
\"com.sap.aii.adapter.file.ftp.FTPEx: 550 Unexpected reply code/Tests/Alert/receiverNotExisting: 
The system cannot find the file specified. \". For details, contact your FTP server vendor",
            "FromParty": "",
            "FromService": "",
            "Interface": "ElementsOutbound",
            "MonitoringUrl": "https://piserver.example.com:50001/webdynpro/resources/sap.com/
tc~lm~itsam~ui~mainframe~wd/FloorPlanApp?applicationID=com.sap.itsam.mon.xi.msg
&msgid=e5c33d63-d34d-48e5-1a8f-802aab81045f",
            "MsgId": "e5c33d63-d34d-48e5-1a8f-802aab81045f",
            "Namespace": "http://xi.com/xiveri/source_amt_parametrization",
            "RuleId": "661b725dbc5d31d9882ab2c68fcb6242",
            "ScenarioId": "dir://ICO/312038ca1a0b33d880c93c460ee55bed",
            "Timestamp": "2011-03-12T19:08:01Z",
            "ToParty": "FTPParty",
            "ToService": "FTPService"
More Information