Notify
20 December 2020
- C10 - Remove the
clearaction parameter in favor ofremove.
1 January 2020
- C10 - added the
updatevalue for theactionparameter.
14 Octorber 2018
- C10 - removed the optional
dataparameter.
20 April 2017
- Release 9.162 - added notification URL tagging.
28 August 2015
- Release 8.49 - changed
clearto delete a notification of a given type and addedpurgeto delete all notifications.
17 August 2015
- Release 8.39 - added afterburn and custom notification data.
5 August 2015
- Release 8.29 - Re-added the
setaction.
7 June 2015
- Release 8.21 - Corrade now supports multiple URLs per notification:
setrenamed toadd,getrenamed tolistand theremoveaction was added.
The notify command can be used to install notifications for a given configured group. Once an event is raised, Corrade sends the notification to a specified URL. The URL can be the same as the callback URL or a different one.
| Command | Required Parameters | Required Corrade Permissions | Example |
|---|---|---|---|
notify | group, password, action | notifications | llInstantMessage(CORRADE, wasKeyValueEncode( [ "command", "notify", "group", wasURLEscape(GROUP), "password", wasURLEscape(PASSWORD), "action", "set", "type", wasListToCSV([ // in-world system alerts "alert", // group chat "group" ]), "URL", wasURLEscape(URL), "callback", wasURLEscape(URL) ] ) ); |
| Parameter | Possible Values | Second Parameter | Possible Value | Description |
|---|---|---|---|---|
action | add | type | Any supported notification name. | Add an URL to an already existing notification pool (or create it if it does not already exist). |
URL | The URL to send the notification to. | |||
tag | An optional CSV list of tags to assign to the URL. | |||
action | set | type | Any supported notification name. | Set all the supplied notifications to a given URL. |
URL | The URL to send the notification to. | |||
tag | An optional CSV list of tags to assign to the URL. | |||
update | type | Any supported notification name. | Update notification bindings of the given type to a given URL. | |
URL | The URL to send the notification to. | |||
tag | An optional CSV list of tags to assign to the URL. | |||
remove | type | Any supported notification name to be removed. | Remove installed notifications. | |
URL | Any URL to be removed. | |||
tag | A CSV list of tag to be removed. | |||
list | type | Any supported notification name to list. | List installed notifications optionally filtered by type or tag. |
|
tag | A CSV list of tags to list. | |||
purge | Remove all installed notifications. |
| Optional Parameter | Possible Value | Description |
|---|---|---|
afterburn | A CSV list of names by values. | When Corrade sends the notification, the names and values ( where is the index of the elements in the CSV list and ) will be sent as key-value pairs. |
Add or Set
Corrade supports multiple URLs per notification - for example, you could send the notification to one or more destinations. Adding more URLs to a notification can be done by setting the action to add. On the other hand, when you supply set to action, regardless of what URLs have been set, Corrade overrides them all with the new destination. If you are designing a large project, and you need to send the result of a notification to multiple destinations, then you would use the add action and manage your list of notifications, getting rid of dead URLs (if any). However, most of the time you would script in LSL, within the grid, and send notifications to scripts. In the latter case, URLs are treated by Linden as consumables since they can expire at any time, so you more than likely want to work with set in order to not stack dead URLs.
Note that setting the action parameter to add and sending two identical URLs one after the other will not make Corrade add the same URL twice. In that sense, if you are using Corrade's HTTP interface and you need a more permanent bind to some notification, you can safely send add from your script multiple times because Corrade will not deduplicate URLs.
Tutorial
Depending on the type of notification, Corrade will send the notification as key-value pairs to the specified URL. This URL can be different for the different types of notifications or it can be the same as the callback URL. Whenever a notification event occurs, if there exists a binding for the given notification, Corrade will send that notification to the bound URL.
For example, if you bind to the local chat notification with:
llInstantMessage(CORRADE, wasKeyValueEncode( [ "command", "notify", "group", wasURLEscape(GROUP), "password", wasURLEscape(PASSWORD), "action", "set", "type", "local", "URL", wasURLEscape(NOTIFICATION_URL), "callback", wasURLEscape(CALLBACK_URL) ] ) );
Corrade will first send a confirmation message to CALLBACK_URL that it has bound the local chat notification to the NOTIFICATION_URL.
Now, whenever local chat occurs, Corrade will send the message to NOTIFICATION_URL. For example, if Sneaky Resident writes in local chat “boo” and Corrade is in hearing range, Corrade sends the following snippet:
type=local&message=boo&firstname=Sneaky&lastname=Resident&owner=1ad33407-a792-476d-a5e3-06007c0802bf&item=1ad33407-a792-476d-a5e3-06007c0802bf
to the NOTIFICATION_URL.
Tagging
Notifications can be tagged by specifying a tag parameter to which a list (or a single string) of tags can be passed whenever a notification is bound. For instance, suppose that the following code is used to send a notify command to Corrade requesting a binding for group messages and tagging the notification with the tag my binding:
llMessageLinked(LINK_THIS, 0, wasKeyValueEncode( [ "command", "notify", "group", wasFormEncode(GROUP), "password", wasFormEncode(PASSWORD), "action", "add", "tag", "my binding", "type", "group", "URL", wasFormEncode(URL), "callback", wasFormEncode(URL) ] ), CORRADE );
Note that the command uses the add action parameter which will not overwrite other notifications in the file but rather add the notification to the already existing notifications. Since the notification is added, it is probably sane to remove the notification before adding it again, for instance, whenever the script restarts. Now, since the notification is tagged, the notification can be conveniently removed by supplying just the tag to the notify command with remove action:
llMessageLinked(LINK_THIS, 0, wasKeyValueEncode( [ "command", "notify", "group", wasFormEncode(GROUP), "password", wasFormEncode(PASSWORD), "action", "remove", "tag", "my binding", "callback", wasFormEncode(URL) ] ), CORRADE );
That being said, scripts can be written in an intuitive linear manner: first, send the remove notify command to remove any notifications with a given tag, then send the add notify command to add a notification.
In doing so, multiple scripts can be made to share the same notification without polluting the notification bindings with a bunch of URLs that may be invalidated whenever LSL scripts restart.
Examples
The following LSL templates will always be compatible and can be run alongside each other:
Both templates use tagging to remove and add tagged notifications without hijacking the group notification.
Notes
- In case a group does not have permission to bind to certain notifications passed to the
typeparameter, then Corrade will return a list of notifications passed to thedatakey that the user does not have permission to bind to. - The
tag,typeandURLparameters are used for all possible values ofactionas additive filters, such that, for instance, sending a command with theactionparameter set toremoveand some values passed totype,URLortag, would result in all notifications being removed that match one or more values passed to thetype,URLortagparameters.
where
is the index of the elements in the CSV list and
) will be sent as key-value pairs.