Skip to content

Commit 56b6d62

Browse files
RamIndiaRamIndia
committed
Updating Readme
1 parent 7dd6644 commit 56b6d62

File tree

3 files changed

+58
-104
lines changed

3 files changed

+58
-104
lines changed

‎README.md‎

Lines changed: 58 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ The `@cap-js/notifications` package is a [CDS plugin](https://cap.cloud.sap/docs
77
### Table of Contents
88

99
- [Setup](#setup)
10-
- [Send Notifications](#add-code-to-send-notifications)
10+
- [Send Notifications](#send-notifications)
1111
- [Use Notification Types](#use-notification-types)
1212
- [API Reference](#api-reference)
1313
- [Test-drive Locally](#test-drive-locally)
@@ -17,8 +17,6 @@ The `@cap-js/notifications` package is a [CDS plugin](https://cap.cloud.sap/docs
1717
- [Code of Conduct](#code-of-conduct)
1818
- [Licensing](#licensing)
1919

20-
21-
2220
## Setup
2321

2422
To enable notifications, simply add this self-configuring plugin package to your project:
@@ -29,8 +27,6 @@ To enable notifications, simply add this self-configuring plugin package to your
2927

3028
In this guide, we use the [Incidents Management reference sample app](https://github.com/cap-js/incidents-app) as the base, to publish notifications.
3129

32-
33-
3430
## Send Notifications
3531

3632
With that you can use the NotificationService as any other CAP Service like so in you event handlers:
@@ -50,63 +46,53 @@ alert.notify({
5046
});
5147
```
5248

53-
54-
5549
## Use Notification Types
5650

5751
### 1. Add notification types
5852

59-
If you want to send custom notifications in your application, you can add the notification types in the `notificationtype.json` file.
60-
61-
Sample: If you want to send the notification when the new incident is reported, you can modify the `notificationtypes.json` as below:
62-
63-
```jsonc
64-
[
65-
{
66-
"NotificationTypeKey": "IncidentResolved",
67-
"NotificationTypeVersion": "1",
68-
"Templates": [
69-
{
70-
"Language": "en",
71-
"TemplatePublic": "Incident Resolved",
72-
"TemplateSensitive": "Incident '{{title}}' Resolved",
73-
"TemplateGrouped": "Incident Status Update",
74-
"TemplateLanguage": "mustache",
75-
"Subtitle": "Incident from '{{customer}}' resolved by {{user}}."
76-
}
77-
]
78-
}
79-
]
80-
```
53+
If you want to send custom notifications in your application, you can add the notification types in the `srv/notification-types.json` file.
8154

82-
### 2. Use pre-defined types in your code like that:
55+
Sample: If you want to send the notification when the incident is resolved, you can modify the `srv/notification-types.json` as below:
8356

57+
```json
58+
[
59+
{
60+
"NotificationTypeKey": "IncidentResolved",
61+
"NotificationTypeVersion": "1",
62+
"Templates": [
63+
{
64+
"Language": "en",
65+
"TemplatePublic": "Incident Resolved",
66+
"TemplateSensitive": "Incident '{{title}}' Resolved",
67+
"TemplateGrouped": "Incident Status Update",
68+
"TemplateLanguage": "mustache",
69+
"Subtitle": "Incident from '{{customer}}' resolved by {{user}}."
70+
}
71+
]
72+
}
73+
]
74+
```
8475

76+
### 2. Use pre-defined types in your code like that:
8577

8678
```js
87-
await alert.notify ('IncidentResolved', {
88-
recipients: [ customer.id ],
89-
data: {
90-
customer: customer.info,
91-
title: incident.title,
92-
user: cds.context.user.id,
93-
}
94-
})
79+
await alert.notify ('IncidentResolved', {
80+
recipients: [ customer.id ],
81+
data: {
82+
customer: customer.info,
83+
title: incident.title,
84+
user: cds.context.user.id,
85+
}
86+
})
9587
```
9688

97-
98-
9989
## API Reference
10090

101-
102-
10391
* **recipients** - List of the recipients, this argument is mandatory
10492
* **type** - Notification type key, this argument is mandatory
10593
* **priority** - Priority of the notification, this argument is optional, it defaults to NEUTRAL
10694
* **data** - A key-value pair that is used to fill a placeholder of the notification type template, this argument is optional
10795

108-
109-
11096
## Test-drive Locally
11197
In local environment, when you publish notification, it is mocked to publish the nofication to the console.
11298

@@ -128,77 +114,52 @@ Once application is deployed and [integrated with SAP Build Work Zone](https://g
128114

129115
## Advanced Usage
130116

117+
### Custom Notification Types Path
131118

119+
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`
132120

133-
#### Custom Notification Types Path
134-
135-
When you run `cds add notifications`, it will add `notificationstype.json` file with template for a notification type in the project root folder. You can add the notification types in the `notificationtype.json` file for sending the custom notification types.
136-
137-
#### Custom Notification Type Prefix
121+
### Custom Notification Type Prefix
138122

139-
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 `prefix` if required.
123+
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.
140124

141-
#### Low-level Notifications API
125+
### Low-level Notifications API
142126

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

145-
##### With standard parameters
129+
#### With pre-defined parameters
146130

147131
By using this approach you can post a notification by providing different parts of the notification object grouped in related units
148132

149133
```js
150134
alert.notify({
151-
recipients: ["[email protected]","[email protected]"],
152-
type: "IncidentCreated"
135+
recipients: [...supporters()],
136+
type: "IncidentResolved"
153137
priority: 'NEUTRAL',
154-
properties: [
138+
data: {
139+
customer: customer.info,
140+
title: incident.title,
141+
user: cds.context.user.id,
142+
},
143+
OriginId: "Example Origin Id",
144+
NotificationTypeVersion: "1",
145+
ProviderId: "/SAMPLEPROVIDER",
146+
ActorId: "BACKENDACTORID",
147+
ActorDisplayText: "ActorName",
148+
ActorImageURL: "https://some-url",
149+
NotificationTypeTimestamp: "2022-03-15T09:58:42.807Z",
150+
TargetParameters: [
155151
{
156-
Key: 'name',
157-
IsSensitive: false,
158-
Language: 'en',
159-
Value: 'Engine overheating',
160-
Type: 'String'
161-
},
162-
{
163-
Key: 'customer',
164-
IsSensitive: false,
165-
Language: 'en',
166-
Value: 'John',
167-
Type: 'String'
152+
"Key": "string",
153+
"Value": "string"
168154
}
169-
],
170-
navigation: {
171-
NavigationTargetAction: "displayInbox",
172-
NavigationTargetObject: "WorkflowTask",
173-
}
174-
payload: {
175-
Id: "01234567-89ab-cdef-0123-456789abcdef",
176-
OriginId: "Example Origin Id",
177-
NotificationTypeId: "01234567-89ab-cdef-0123-456789abcdef",
178-
NotificationTypeVersion: "1",
179-
ProviderId: "/SAMPLEPROVIDER",
180-
ActorId: "BACKENDACTORID",
181-
ActorDisplayText: "ActorName",
182-
ActorImageURL: "https://some-url",
183-
NotificationTypeTimestamp: "2022-03-15T09:58:42.807Z",
184-
TargetParameters: [
185-
{
186-
"Key": "string",
187-
"Value": "string"
188-
}
189155
]
190-
}
191-
});
156+
});
192157
```
193158

194-
195-
196-
##### Passing the whole notification object
159+
#### Passing the whole notification object
197160

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

200-
201-
202163
```js
203164
alert.notify({
204165
NotificationTypeKey: 'IncidentCreated',
@@ -216,29 +177,22 @@ alert.notify({
216177
Key: 'customer',
217178
IsSensitive: false,
218179
Language: 'en',
219-
Value: 'John',
180+
Value: 'Dave',
220181
Type: 'String'
221182
}
222183
],
223-
Recipients: ["admin1@test.com","admin2@test.com"]
184+
Recipients: [{ RecipientId: "supportuser1@mycompany.com" },{ RecipientId: "supportuser2@mycompany.com" }]
224185
});
225186
```
226187

227-
228-
229188
## Contributing
230189

231190
This 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).
232191

233-
234192
## Code of Conduct
235193

236194
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](CODE_OF_CONDUCT.md) at all times.
237195

238-
239196
## Licensing
240197

241-
Copyright 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).
242-
243-
244-
198+
Copyright 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).

‎_assets/cdsAddNotifications.gif‎

-117 KB
Binary file not shown.

‎_assets/incidentsNotificationDemo.gif‎

-8.31 MB
Loading

0 commit comments

Comments
 (0)