APF provides a message handler with a method sap.apf.putMessage. This method can be used to display messages on the UI. In more detail, sap.apf.putMessage calls a registered callback function.
The UI uses the APF function sap.apf.setCallbackForMessageHandling to register the callback function at the message handler.
The callback function receives a message object of type sap.apf.core.MessageObject, which describes the message and has the following attributes:
getCode
Returns a unique message code.
getSeverity
Returns the category that defines how critical the message is.
getMessage
Returns the message text.
The following message categories are supported and defined as constants of sap.apf.core.messageConstants:
Category | Description |
---|---|
fatal | Can be used to notify a user of a critical error. The user is notified immediately and any further execution of the application is blocked. |
error | Can be used to notify a user of an error. |
warning | Can be used to notify a user of an uncritical problem. The user can continue without taking action. |
technError | Can be used for messages that are not displayed on the UI. Technical messages can be displayed in the browser console, for example, when an ID has been defined twice. Technical messages do not use a key referencing a text resource file. Instead, they contain the message text itself, which cannot be translated. |
Messages of the categories warning, error, and fatal use a text key that references the message text in the related text resource file, for example, apfMessages.hdbtextbundle. The message handler resolves the key and provides the related text in the message object.
When APF starts, the message handler is the first component to be initialized by the startup file sap/apf/startup.js. During the initialization of the message handler, no error messages can be raised.
During startup of the application, method sap.apf.loadApplicationConfig is called. This method loads the application configuration file, which defines the locations of the following resource files that are relevant for message handling:
Message definition file of APF
Contains the preconfigured APF messages along with their category and a text or text key.
Message definition file of the application
Text files of type *.hdbtextbundle
Contain the message texts that are referenced from the message definition files using a text key.
If an error occurs while these resource files are loading, the message handling component does not yet have access to the messages and their texts. For these cases, coded error messages exist that are raised automatically.
As soon as all resource files have loaded, the message handler can raise messages defined in the message definition files, and send the corresponding texts to the UI.