60 · SAP Alert Notification Service

Set up ANS, use @cap-js/notifications, configure condition-based routing, and integrate with Fiori Notification Hub.

Episode 60 — SAP Alert Notification Service

What you'll learn

• What SAP Alert Notification Service (ANS) does
• Sending events from CAP to ANS
• Configuring delivery channels: email, Slack, SAP Fiori, Microsoft Teams
• Condition-based filtering
• Alerting for system events (app crashes, DLQ overflow)

Why this matters

console.error doesn't page the on-call engineer at 3am. ANS connects your CAP app to real notification channels — email, Slack, PagerDuty via webhooks — with filtering and routing so the right people get the right alerts.

What ANS provides

CAP App → ANS → Routing Engine (conditions) → Delivery Channels
                                               ├── Email (SMTP)
                                               ├── Slack webhook
                                               ├── Microsoft Teams
                                               ├── SAP Fiori Launchpad notification
                                               └── Custom webhook

Binding ANS

# mta.yaml
resources:
  - name: alert-notification
    type: org.cloudfoundry.managed-service
    parameters:
      service:      alert-notification
      service-plan: standard

modules:
  - name: bookshop-srv
    requires:
      - name: alert-notification

Connecting from CAP

// .cdsrc.json
{
  "requires": {
    "notifications": {
      "[production]": {
        "kind": "alert-notification",
        "vcap": { "label": "alert-notification" }
      },
      "[development]": {
        "kind": "@cap-js/notifications",
        "impl": "@cap-js/notifications/lib/console-logger"  // logs to console in dev
      }
    }
  }
}

npm install @cap-js/notifications

Sending a notification from a handler

const notif = await cds.connect.to('notifications')

this.on('submitOrder', async (req) => {
  const { orderId } = req.data
  const order = await SELECT.one.from('Orders').where({ ID: orderId })

  // Business notification to the buyer
  await notif.notify({
    NotificationTypeKey:     'OrderConfirmed',
    NotificationTypeVersion: '1',
    Priority:                'MEDIUM',
    Properties: [
      { Key: 'orderId',    Value: order.ID   },
      { Key: 'orderTotal', Value: String(order.total) }
    ],
    Recipients: [{ RecipientId: order.buyer_email }]
  })

  return order
})

System alerts from CAP errors

// Global error handler — alert on 5xx errors
this.on('error', async (err, req) => {
  if (err.status >= 500) {
    await notif.notify({
      NotificationTypeKey: 'SystemError',
      Priority:            'HIGH',
      Properties: [
        { Key: 'errorMessage', Value: err.message },
        { Key: 'operation',    Value: `${req.event} ${req.target?.name}` },
        { Key: 'user',         Value: req.user?.id || 'anonymous' }
      ],
      Recipients: [{ RecipientId: 'ops-team@company.com' }]
    })
  }
})

Notification types (defined in ANS admin)

In ANS Cockpit (BTP → Instances → alert-notification → Manage):
1. Notification Types → Create:
- Key: OrderConfirmed
- Version: 1
- Template for email subject: "Order {{orderId}} confirmed"
- Template for email body: "Your order total: {{orderTotal}}"

1. Actions → Create:
2. Type: EMAIL
3. Email address: buyer's email
4. Condition: NotificationTypeKey = 'OrderConfirmed'

Condition-based routing

Conditions in ANS:
  Priority == 'HIGH'                        → PagerDuty webhook
  NotificationTypeKey == 'SystemError'      → Slack #ops-alerts
  NotificationTypeKey == 'OrderConfirmed'   → Email to buyer
  Region == 'EMEA'                          → EMEA support team

Fiori Notification Hub integration

// Fiori notifications appear in the Fiori Shell notification bell
await notif.notify({
  NotificationTypeKey: 'ApprovalRequired',
  Priority:            'HIGH',
  Properties: [
    { Key: 'documentId', Value: req.data.ID },
    { Key: 'amount',     Value: String(req.data.amount) }
  ],
  Recipients:          [{ RecipientId: req.data.approver_email }],
  // NavigationTargetObject: target Fiori app to open on click
  NavigationTargetObject:   'PurchaseOrder',
  NavigationTargetAction:    'approve',
  NavigationTargetParams: [{ Key: 'documentId', Value: req.data.ID }]
})

Hands-on exercise

1. Install @cap-js/notifications and configure it for development (console logger)
2. Send a notification when an order is submitted — verify the console output
3. In BTP trial ANS, create a notification type and an email action
4. Deploy and trigger the notification — verify the email arrives

Checkpoint ✓

• [ ] ANS decouples the notification concern from the CAP handler — no SMTP code in handlers
• [ ] Notification types defined in ANS admin control the template; handler provides the data
• [ ] Condition-based routing in ANS sends different events to different channels
• [ ] @cap-js/notifications in dev mode logs to console — no ANS service needed locally