diff --git a/bundles/org.openhab.automation.jsscripting/README.md b/bundles/org.openhab.automation.jsscripting/README.md index 2e9bcd521be..5bad40717dc 100644 --- a/bundles/org.openhab.automation.jsscripting/README.md +++ b/bundles/org.openhab.automation.jsscripting/README.md @@ -619,7 +619,6 @@ For example, a way to determine if today is a weekend, a public holiday, someone Additional information can be found on the [Ephemeris Actions Docs](https://www.openhab.org/docs/configuration/actions.html#ephemeris) as well as the [Ephemeris JavaDoc](https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/ephemeris). ```javascript -// Example var weekend = actions.Ephemeris.isWeekend(); ``` @@ -710,16 +709,6 @@ myTimer.reschedule(now.plusSeconds(5)); See [openhab-js : actions.ScriptExecution](https://openhab.github.io/openhab-js/actions.ScriptExecution.html) for complete documentation. -#### Semantics Actions - -See [openhab-js : actions.Semantics](https://openhab.github.io/openhab-js/actions.html#.Semantics) for complete documentation. - -#### Thing Actions - -It is possible to get the actions for a Thing using `actions.Things.getActions(bindingId, thingUid)`, e.g. `actions.Things.getActions('network', 'network:pingdevice:pc')`. - -See [openhab-js : actions.Things](https://openhab.github.io/openhab-js/actions.html#.Things) for complete documentation. - #### Transformation Actions openHAB provides various [data transformation services](https://www.openhab.org/addons/#transform) which can translate between technical and human-readable values. @@ -738,20 +727,57 @@ See [openhab-js : actions.Voice](https://openhab.github.io/openhab-js/actions.ht #### Cloud Notification Actions -Note: Optional action if [openHAB Cloud Connector](https://www.openhab.org/addons/integrations/openhabcloud/) is installed. +Requires the [openHAB Cloud Connector](https://www.openhab.org/addons/integrations/openhabcloud/) to be installed. Notification actions may be placed in rules to send alerts to mobile devices registered with an [openHAB Cloud instance](https://github.com/openhab/openhab-cloud) such as [myopenHAB.org](https://myopenhab.org/). -For available actions have a look at the [Cloud Notification Actions Docs](https://www.openhab.org/docs/configuration/actions.html#cloud-notification-actions). +There are three different types of notifications: + +- Broadcast Notifications: Sent to all registered devices and shown as notification on these devices. +- Standard Notifications: Sent to the registered devices of the specified user and shown as notification on his devices. +- Log Notifications: Only shown in the notification log, e.g. inside the Android and iOS Apps. + +To send these three types of notifications, use the `notificationBuilder(message)` method of the `actions` namespace. +It returns a new `NotificationBuilder` object, which by default sends a broadcast notification and provides the following methods: + +- `.logOnly()`: Send a log notification only. +- `.withIcon(icon)`: Sets the icon of the notification. +- `.withSeverity(link)`: Sets the severity of the notification. +- `.withTitle(title)`: Sets the title of the notification. +- `.addUserId(emailAddress)`: By adding the email address(es) of specific openHAB Cloud user(s), the notification is only sent to this (these) user(s). +- `.withOnClickAction(action)`: Sets the action to be performed when the notification is clicked. +- `.withMediaAttachmentUrl(mediaAttachmentUrl)`: Sets the URL of a media attachment to be displayed with the notification. This URL must be reachable by the push notification client. +- `.addActionButton(title, action)`: Adds an action button to the notification. Please note that due to Android and iOS limitations, only three action buttons are supported. +- `.send()`: Sends the notification. + +The syntax for the `action` parameter is described in [openHAB Cloud Connector: Action Syntax](https://www.openhab.org/addons/integrations/openhabcloud/#action-syntax). ```javascript -// Example -actions.NotificationAction.sendNotification('', ''); // to a single myopenHAB user identified by e-mail -actions.NotificationAction.sendBroadcastNotification(''); // to all myopenHAB users +// Send a simple broadcast notification +actions.notificationBuilder('Hello World!').send(); +// Send a broadcast notification with icon, severity and title +actions.notificationBuilder('Hello World!') + .withIcon('f7:bell_fill').withSeverity('important').withTitle('Important Notification').send(); +// Send a broadcast notification with icon, severity, title, media attachment URL and actions +actions.notificationBuilder('Hello World!') + .withIcon('f7:bell_fill').withSeverity('important').withTitle('Important Notification'). + .withOnClickAction('ui:navigate:/page/my_floorplan_page').withMediaAttachmentUrl('http://example.com/image.jpg') + .addActionButton('Turn Kitchen Light ON=command:KitchenLights:ON').addActionButton('Turn Kitchen Light OFF=command:KitchenLights:OFF').send(); + +// Send a simple standard notification to two specific users +actions.notificationBuilder('Hello World!').addUserId('florian@example.com').addUserId('florian@example.org').send(); +// Send a standard notification with icon, severity and title to two specific users +actions.notificationBuilder('Hello World!').addUserId('florian@example.com').addUserId('florian@example.org') + .withIcon('f7:bell_fill').withSeverity('important').withTitle('Important notification').send(); + +// Sends a simple log notification +actions.notificationBuilder('Hello World!').logOnly().send(); +// Sends a simple log notification with icon and severity +actions.notificationBuilder('Hello World!').logOnly() + .withIcon('f7:bell_fill').withSeverity('important').send(); ``` -Replace `` with the e-mail address of the user. -Replace `` with the notification text. +See [openhab-js : actions.NotificationBuilder](https://openhab.github.io/openhab-js/actions.html#.notificationBuilder) for complete documentation. ### Cache @@ -1182,7 +1208,7 @@ Operations and conditions can also optionally take functions: ```javascript rules.when().item("F1_light").changed().then(event => { - console.log(event); + console.log(event); }).build("Test Rule", "My Test Rule"); ``` diff --git a/bundles/org.openhab.automation.jsscripting/pom.xml b/bundles/org.openhab.automation.jsscripting/pom.xml index 472dfed72aa..635b7fe079a 100644 --- a/bundles/org.openhab.automation.jsscripting/pom.xml +++ b/bundles/org.openhab.automation.jsscripting/pom.xml @@ -24,7 +24,7 @@ 22.0.0.2 ${project.version} - openhab@5.2.0 + openhab@5.3.0