{"id":19755836,"url":"https://github.com/cap-js/notifications","last_synced_at":"2025-04-30T11:33:06.374Z","repository":{"id":203511871,"uuid":"665872643","full_name":"cap-js/notifications","owner":"cap-js","description":"CDS Plugin that provides support for publishing business notifications in SAP Build WorkZone.","archived":false,"fork":false,"pushed_at":"2025-02-13T13:52:49.000Z","size":21652,"stargazers_count":9,"open_issues_count":25,"forks_count":4,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-06T01:31:55.756Z","etag":null,"topics":["alert-notifications","cap","cds","nodejs","notifications","plugin","sap-btp","sap-cap"],"latest_commit_sha":null,"homepage":"https://cap.cloud.sap/docs/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cap-js.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-13T07:33:53.000Z","updated_at":"2025-02-24T04:20:54.000Z","dependencies_parsed_at":"2023-12-15T09:26:00.741Z","dependency_job_id":"a0190893-5ae9-488d-9a7e-c8e02043fbdb","html_url":"https://github.com/cap-js/notifications","commit_stats":null,"previous_names":["cap-js/notifications"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cap-js%2Fnotifications","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cap-js%2Fnotifications/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cap-js%2Fnotifications/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cap-js%2Fnotifications/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cap-js","download_url":"https://codeload.github.com/cap-js/notifications/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251691523,"owners_count":21628335,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alert-notifications","cap","cds","nodejs","notifications","plugin","sap-btp","sap-cap"],"created_at":"2024-11-12T03:13:38.181Z","updated_at":"2025-04-30T11:33:05.671Z","avatar_url":"https://github.com/cap-js.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![REUSE status](https://api.reuse.software/badge/github.com/cap-js/notifications)](https://api.reuse.software/info/github.com/cap-js/notifications)\n\n# Notifications Plugin\n\nThe `@cap-js/notifications` package is a [CDS plugin](https://cap.cloud.sap/docs/node.js/cds-plugins#cds-plugin-packages) that provides support for publishing business notifications in SAP Build WorkZone.\n\n### Table of Contents\n\n- [Setup](#setup)\n- [Send Notifications](#send-notifications)\n- [Use Notification Types](#use-notification-types)\n- [API Reference](#api-reference)\n- [Test-drive Locally](#test-drive-locally)\n- [Run in Production](#run-in-production)\n- [Advanced Usage](#advanced-usage)\n- [Contributing](#contributing)\n- [Code of Conduct](#code-of-conduct)\n- [Licensing](#licensing)\n\n## Setup\n\nTo enable notifications, simply add this self-configuring plugin package to your project:\n\n```sh\n npm add @cap-js/notifications\n```\n\nIn this guide, we use the [Incidents Management reference sample app](https://github.com/cap-js/incidents-app) as the base, to publish notifications.\n\n## Send Notifications\n\nWith that you can use the NotificationService as any other CAP Service like so in you event handlers:\n\n```js\nconst alert = await cds.connect.to('notifications');\n```\n\nYou can use the following signature to send the simple notification with title and description\n\n```js\nalert.notify({\n  recipients: [ ...supporters() ],\n  priority: \"HIGH\",\n  title: \"New high priority incident is assigned to you!\",\n  description: \"Incident titled 'Engine overheating' created by 'customer X' with priority high is assigned to you!\"\n});\n```\n\n* **priority** - Priority of the notification, this argument is optional, it defaults to NEUTRAL\n* **description** - Subtitle for the notification, this argument is optional\n\n## Use Notification Types\n\n### 1. Add notification types\n\nIf you want to send custom notifications in your application, you can add the notification types in the `srv/notification-types.json` file.\n\nSample: If you want to send the notification when the incident is resolved, you can modify the `srv/notification-types.json` as below:\n\n```json\n  [\n    {\n      \"NotificationTypeKey\": \"IncidentResolved\",\n      \"NotificationTypeVersion\": \"1\",\n      \"Templates\": [\n        {\n          \"Language\": \"en\",\n          \"TemplatePublic\": \"Incident Resolved\",\n          \"TemplateSensitive\": \"Incident '{{title}}' Resolved\",\n          \"TemplateGrouped\": \"Incident Status Update\",\n          \"TemplateLanguage\": \"mustache\",\n          \"Subtitle\": \"Incident from '{{customer}}' resolved by {{user}}.\"\n        }\n      ]\n    }\n  ]\n```\n\n### 2. Use pre-defined types in your code like that:\n\n```js\n  await alert.notify ('IncidentResolved', {\n    recipients: [ customer.id ],\n    data: {\n      customer: customer.info,\n      title: incident.title,\n      user: cds.context.user.id,\n    }\n  })\n```\n\n## API Reference\n\n* **recipients** - List of the recipients, this argument is mandatory\n* **type** - Notification type key, this argument is mandatory\n* **priority** - Priority of the notification, this argument is optional, it defaults to NEUTRAL\n* **data** - A key-value pair that is used to fill a placeholder of the notification type template, this argument is optional\n\n## Test-drive Locally\nIn local environment, when you publish notification, it is mocked to publish the nofication to the console.\n\n\u003cimg width=\"700\" alt=\"Notify to console\" style=\"border-radius:0.5rem\" src=\"_assets/notifyToConsole.png\"\u003e\n\n## Run in Production\n\n#### Notification Destination\n\nAs a pre-requisite to publish the notification, you need to have a [destination](https://help.sap.com/docs/build-work-zone-standard-edition/sap-build-work-zone-standard-edition/enabling-notifications-for-custom-apps-on-sap-btp-cloud-foundry#configure-the-destination-to-the-notifications-service) 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.\n\n#### Integrate with SAP Build Work Zone\n\nOnce application is deployed and integrated with SAP Build Work Zone, you can see the notification under fiori notifications icon!\n\n\u003cimg width=\"1300\" alt=\"Sample Application Demo\" style=\"border-radius:0.5rem;\" src=\"_assets/incidentsNotificationDemo.gif\"\u003e\n\n\n\n## Advanced Usage\n\n### Custom Notification Types Path\n\nNotifications 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` \n\n### Custom Notification Type Prefix\n\nTo 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.\n\n### Low-level  Notifications API\n\nYou can use these two signature to send the custom notification with pre-defined notification types.\n\n#### With pre-defined parameters\n\nBy using this approach you can send notifications with the predefined parameters - recipients, data, priority, type and other parameters listed in the [API documentation](https://help.sap.com/docs/build-work-zone-standard-edition/sap-build-work-zone-standard-edition/developing-cloud-foundry-applications-with-notifications) \n\n```js\nalert.notify({\n  recipients: [...supporters()],\n  type: \"IncidentResolved\",\n  priority: 'NEUTRAL',\n  data: {\n    customer: customer.info,\n    title: incident.title,\n    user: cds.context.user.id,\n  },\n  OriginId: \"Example Origin Id\",\n  NotificationTypeVersion: \"1\",\n  ProviderId: \"/SAMPLEPROVIDER\",\n  ActorId: \"BACKENDACTORID\",\n  ActorDisplayText: \"ActorName\",\n  ActorImageURL: \"https://some-url\",\n  NotificationTypeTimestamp: \"2022-03-15T09:58:42.807Z\",\n  TargetParameters: [\n    {\n      \"Key\": \"string\",\n      \"Value\": \"string\"\n    }\n   ]\n  });\n```\n\n#### Passing the whole notification object\n\nBy using this approach you need to pass the whole notification object as described in the [API documentation](https://help.sap.com/docs/build-work-zone-standard-edition/sap-build-work-zone-standard-edition/developing-cloud-foundry-applications-with-notifications)\n\n```js\nalert.notify({\n  NotificationTypeKey: 'IncidentCreated',\n  NotificationTypeVersion: '1',\n  Priority: 'NEUTRAL',\n  Properties: [\n    {\n      Key: 'name',\n      IsSensitive: false,\n      Language: 'en',\n      Value: 'Engine overheating',\n      Type: 'String'\n    },\n    {\n      Key: 'customer',\n      IsSensitive: false,\n      Language: 'en',\n      Value: 'Dave',\n      Type: 'String'\n    }\n  ],\n  Recipients: [{ RecipientId: \"supportuser1@mycompany.com\" },{ RecipientId: \"supportuser2@mycompany.com\" }]\n});\n```\n\n## Contributing\n\nThis project is open to feature requests/suggestions, bug reports etc. via [GitHub issues](https://github.com/cap-js/change-tracking/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](CONTRIBUTING.md).\n\n## Code of Conduct\n\nWe 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](CODE_OF_CONDUCT.md) at all times.\n\n## Licensing\n\nCopyright 2023 SAP SE or an SAP affiliate company and contributors. Please see our [LICENSE](LICENSE) for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available [via the REUSE tool](https://api.reuse.software/info/github.com/cap-js/change-tracking).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcap-js%2Fnotifications","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcap-js%2Fnotifications","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcap-js%2Fnotifications/lists"}