@cap-js/notifications

Notifications Plugin

The @cap-js/notifications package is a CDS plugin that provides support for publishing business notifications in SAP Build WorkZone.

Table of Contents

• Setup
• Send Notifications
• Use Notification Types
• API Reference
• Test-drive Locally
• Run in Production
• Advanced Usage
• Contributing
• Code of Conduct
• Licensing

Setup

To enable notifications, simply add this self-configuring plugin package to your project:

 npm add @cap-js/notifications

In this guide, we use the Incidents Management reference sample app as the base, to publish notifications.

Send Notifications

With that you can use the NotificationService as any other CAP Service like so in you event handlers:

const alert = await cds.connect.to('notifications');

You can use the following signature to send the simple notification with title and description

alert.notify({
  recipients: [ ...supporters() ],
  priority: "HIGH",
  title: "New high priority incident is assigned to you!",
  description: "Incident titled 'Engine overheating' created by 'customer X' with priority high is assigned to you!"
});

• priority - Priority of the notification, this argument is optional, it defaults to NEUTRAL
• description - Subtitle for the notification, this argument is optional

Use Notification Types

1. Add notification types

If you want to send custom notifications in your application, you can add the notification types in the srv/notification-types.json file.

Sample: If you want to send the notification when the incident is resolved, you can modify the srv/notification-types.json as below:

  [
    {
      "NotificationTypeKey": "IncidentResolved",
      "NotificationTypeVersion": "1",
      "Templates": [
        {
          "Language": "en",
          "TemplatePublic": "Incident Resolved",
          "TemplateSensitive": "Incident '{{title}}' Resolved",
          "TemplateGrouped": "Incident Status Update",
          "TemplateLanguage": "mustache",
          "Subtitle": "Incident from '{{customer}}' resolved by {{user}}."
        }
      ]
    }
  ]

2. Use pre-defined types in your code like that:

  await alert.notify ('IncidentResolved', {
    recipients: [ customer.id ],
    data: {
      customer: customer.info,
      title: incident.title,
      user: cds.context.user.id,
    }
  })

API Reference

• recipients - List of the recipients, this argument is mandatory
• type - Notification type key, this argument is mandatory
• priority - Priority of the notification, this argument is optional, it defaults to NEUTRAL
• data - A key-value pair that is used to fill a placeholder of the notification type template, this argument is optional

Test-drive Locally

In local environment, when you publish notification, it is mocked to publish the nofication to the console.

Run in Production

Notification Destination

As a pre-requisite to publish the notification, you need to have a destination configured to publish the notification. In the package.json by default destination name SAP_Notifications is added, you can modify the destination name that you are configuring.

Integrate with SAP Build Work Zone

Once application is deployed and integrated with SAP Build Work Zone, you can see the notification under fiori notifications icon!

Advanced Usage

Custom Notification Types Path

Notifications plugin configures srv/notification-types.json as default notification types file. If you are using different file, you can update the file path in cds.env.requires.notifications.types

Custom Notification Type Prefix

To make notification types unique to the application, prefix is added to the type key. By default, application name is added as the prefix. You can update the cds.env.requires.notifications.prefix if required.

Low-level Notifications API

You can use these two signature to send the custom notification with pre-defined notification types.

With pre-defined parameters

By using this approach you can send notifications with the predefined parameters - recipients, data, priority, type and other parameters listed in the API documentation

alert.notify({
  recipients: [...supporters()],
  type: "IncidentResolved",
  priority: 'NEUTRAL',
  data: {
    customer: customer.info,
    title: incident.title,
    user: cds.context.user.id,
  },
  OriginId: "Example Origin Id",
  NotificationTypeVersion: "1",
  ProviderId: "/SAMPLEPROVIDER",
  ActorId: "BACKENDACTORID",
  ActorDisplayText: "ActorName",
  ActorImageURL: "https://some-url",
  NotificationTypeTimestamp: "2022-03-15T09:58:42.807Z",
  TargetParameters: [
    {
      "Key": "string",
      "Value": "string"
    }
   ]
  });

Passing the whole notification object

By using this approach you need to pass the whole notification object as described in the API documentation

alert.notify({
  NotificationTypeKey: 'IncidentCreated',
  NotificationTypeVersion: '1',
  Priority: 'NEUTRAL',
  Properties: [
    {
      Key: 'name',
      IsSensitive: false,
      Language: 'en',
      Value: 'Engine overheating',
      Type: 'String'
    },
    {
      Key: 'customer',
      IsSensitive: false,
      Language: 'en',
      Value: 'Dave',
      Type: 'String'
    }
  ],
  Recipients: [{ RecipientId: "[e-mail]" },{ RecipientId: "[e-mail]" }]
});

Contributing

This project is open to feature requests/suggestions, bug reports etc. via GitHub issues. Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our Contribution Guidelines.

Code of Conduct

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its Code of Conduct at all times.

Licensing

Copyright 2023 SAP SE or an SAP affiliate company and contributors. Please see our LICENSE for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available via the REUSE tool.