Developing Draft-Enabled Applications
A typical example for a state message could be "The order date &1 lies in the past" which relates to an invalid value in a field and an inconsistent state of the business object instance.
State messages are defined when the %state_area component in the REPORTED structure is filled with a string value. Messages with are empty %state_area are treated as transition messages. Note that this means all our messages so-far were transition messages.
Transition messages can either be bound to an RAP BO entity instance or be more general, that is, entered in component %others of the REPORTED structure. State messages must always be bound to an entity instance. They are not allowed in the component %others.
The most important difference between state messages and transition messages is the message lifetime and the visualization on the UI in draft scenarios.
In draft scenarios, a transition message appears as a pop-up message and is gone once the pop-up window is closed.
State messages are displayed in a message pop-over until the state of the business object changes. If a message is assigned to a field in %ELEMENT, the respective field is framed in the severity color to illustrate the link between the field values and a message in order to improve the user experience. For a business object with draft capabilities, state messages are persisted until the state that caused the message is changed and in a managed scenario, the messages are buffered until the end of the session.
Example: Transition Message in Draft-enabled SAP Fiori Apps
The example shows the display of a transition message in a draft-enabled SAP Fiori application. The message is displayed in a pop-up window that blocks the application until closed by the user. When closing the window, the messages are deleted. Even though the message is connected to a field, because the application logic reported it with a non-initial structure %element, this connection is not visualized, neither is there a link to navigate from the message to the field nor is the field highlighted, for example with a red border.
State Message in Draft-enabled SAP Fiori Apps
This next example shows the display of the same message, but this time it was reported as a state message.
The message is displayed in a pop-over window that does not block the application. The user can close the window but this does not delete the message. The connection to the assigned field is visualized by a navigation link on the message text and a red border to highlight the field.
Creating and Invalidating State Messages
A message becomes a state message when the %state_area component in the REPORTED structure is filled with a non-initial value. You can choose any string value but it is recommended that you stick to ASCII characters.
In draft scenarios, state messages are persisted with the draft data and, in managed scenarios, they are buffered until the end of the session. If the same request, for example, a validation, is triggered multiple times on the same instance, the same messages will be added to the message table again and again. To avoid this, you have to invalidate state messages explicitly.
In managed scenarios, it is sufficient to add a special row to the related component of REPORTED. This row should only contain a value for the key (%tky) of the entity instance and the state area ID (%state_area). All other components like %msg, %element, and so on, remain initial. With this entry, you delete all messages of the same state area for the specified entity instance.
The value for %state_area is only used to group state messages that are related and should be invalidated together. The value is not displayed on the UI nor is it contained in the OData metadata.