Lesson 3 of 5
Side effects
9 min
Listen to this lesson
In the first demo of the agreement app, Maria changed the quantity on an item from 10 to 12. A determination recalculated the item's deposit amount in the draft, correctly. The screen still showed the old amount until she pressed Enter twice and refreshed. The back end was right; the UI did not know it had to reload. Side effects close that gap.
What side effects are
A RAP side effect declares that when a trigger changes, certain targets must be reloaded in the UI. Side effects are defined in the behavior definition in a side effects { ... } block per entity, need no implementation in the behavior pool, and are translated into OData metadata annotations that Fiori elements reads. SAP's documentation describes them as especially helpful in draft-enabled BOs, where the UI must know when a change requires recalculating other values, permissions or messages.
| Trigger | Fires when | Contoso example |
|---|---|---|
| field Quantity | The field changes in the UI | Item quantity changes; deposit amount must reload |
| action closeAgreement | The action is executed in the UI | Closing an agreement changes status and what is editable |
| determine action | Any listed source field changes (a field group fires when the user leaves the group) | Recalculate totals when quantity or deposit rate change |
| $self | The entity undergoes a create, update or delete | Adding or deleting an item changes the agreement total on the root |
| event | A business event declared for side effects occurs | Refresh when a background process updates the agreement |
Side effect triggers, following SAP's behavior definition language reference.
| Target | What reloads | Contoso example |
|---|---|---|
| field DepositAmount | Specific fields, or field * for all fields of the instance | The item's deposit amount |
| entity _Items | An associated entity | All items after a mass action |
| permissions(...) | Feature and authorization control for fields, actions or operations | Edit and close buttons after the status changes |
| messages | Reported messages | A warning that the deposit rate is above the standard rate |
Side effect targets.
For Kenji's app the block on the item entity reads, in words: field Quantity affects field DepositAmount; field DepositRate affects field DepositAmount and messages. On the root: action closeAgreement affects field Status and permissions for update, delete and closeAgreement; and, on the item entity, $self affects the agreement total on the root through the parent association, so adding or deleting an item refreshes the total.
- Maria changes Quantity to 12The UI sends the change to the draft
- Determination on modifyThe back end recalculates DepositAmount in the draft
- Side effect annotationThe UI knows Quantity affects DepositAmount and the root total
- Targeted reloadOnly those properties are re-read and shown
- ResultMaria sees 540.00 at once, without refreshing the page
Designing side effects well
- Start from determinations and feature control. Every determination on modify that changes a visible field, and every state change that changes what is allowed, is a candidate.
- Be specific. field * and whole-entity reloads are convenient but cost round trips; name the fields that actually change.
- Reload permissions after state changes. If closing an agreement disables Edit, the action needs a permissions target or the button stays active until refresh.
- Reload messages where validations run early. Otherwise users see warnings late.
- Remember the projection. Projection behavior definitions can reuse the base BO's side effects or define their own; the UI service uses the projection.
What would you do?
After Kenji adds side effects, a tester reports that closing an agreement updates the status on screen, but the Edit button stays active until the page is refreshed. Pressing Edit then fails with a message. What is missing?
- Side effects tell the UI which properties to reload when a trigger changes; no ABP code is needed.
- Triggers: field, action, determine action, $self, event. Targets: fields, entities, permissions, messages.
- They become OData metadata annotations and matter most in draft-enabled Fiori elements apps.
- Be precise; reload permissions after state changes and messages where validations run early.
Check your understanding · not graded
Lesson check
1. Where are RAP side effects implemented?
2. Which target makes the UI re-read whether actions such as Edit are enabled?
3. Who benefits from side effects?
4. How should a team verify that a side effect works?