...
Rulesets do not manage subscriptions directly, but rather rely on the CloudOS service to do it for them. Consequently, to use the Subscription Event Protocol, the CloudOS service ruleset must be installed in the Personal Cloud for both the originator and target. The CloudOS service listens for certain events, manages subscriptions, and provides functions for getting information about subscriptions. Developers need not be concerned with the details of how subscriptions are created between clouds, just the service interface documented here.
Events
Subscribe
The system:subscribe event is used to create a channel between two Personal Clouds.
...
The following rule would be selected upon seeing the cloudos:subscriptionRequestAdded event with appropriate values for the event attributes:
| Code Block | ||||
|---|---|---|---|---|
| ||||
rule process_subscriptionRequestAdded {
select when cloudos subscriptionRequestAdded
namespace re/MyFriends/"
channelName re/Coworkers Bob+Ted/
relationship re/friend-friend/
...
} |
Upon see the subscription, the CloudOS service in the target cloud raises the cloudos:subscriptionRequestPending to signal the receipt of a pending subscription request:
| Domain | cloudos |
|---|---|
| Type | subscriptionRequestPending |
| Attributes | eventChannel, namespace, relationship, channelName |
The following rule would be selected upon seeing the cloudos:subscriptionRequestAdded event with appropriate values for the event attributes:
| Code Block | ||||
|---|---|---|---|---|
| ||||
rule process_subscriptionRequestPending {
select when cloudos subscriptionRequestPending
namespace re/MyFriends/"
channelName re/Coworkers Bob+Ted/
relationship re/friend-friend/
...
} |
Subscription Event Flow
- The
cloudos:subscribeevent is raised by the originating personal cloud. - CloudOS will create a new channel and raise the
cloudos:subscriptionRequestAddedevent within the originating personal cloud. The main purpose for raising this event is to provide the application developer the opportunity to capture the newly created channel, backChannel. - CloudOS then raises an event to the target personal cloud over the targentChannel (typically the doorbell ECI) requesting the subscription.
- CloudOS in the target personal cloud will raise the
cloudos:subscriptionRequestPendinggiving rulesets the opportunity to respond with either an approval or rejection (see below).
Subscription Approval or Rejection
Approval
To approve the subscription request a ruleset in the the target cloud raises the cloudos:subscriptionRequestApproved event to signal the CloudOS service that the subscription is approved:
...
The following shows a rule that is selected when the cloudos:subscriptionAdded event is raised:
| Code Block | ||||
|---|---|---|---|---|
| ||||
rule process_subscriptionAdded {
select when cloudos subscriptionAdded
namespace re/MyFriends/
channelName re/Coworkers Bob+Ted/
relationship re/friend-friend/
...
} |
Subscription Approval Event Flow
- The
cloudos:subscriptionRequestApprovedevent is raised into the target personal cloud after creating a new channel. - CloudOS raises the
cloudos:subscriptionAddedevent within the target personal cloud. - CloudOS raises a event over the eventChannel to the originating personal cloud to indicate that the subscription request has been approved.
- Within the originating personal cloud CloudOS raises the
cloudos:subscriptionAddedevent.
Rejection
To reject the subscription request a ruleset in the the target cloud raises the cloudos:subscriptionRequestRejected event to signal the CloudOS service that the subscription is rejected:
| Domain | cloudos |
|---|---|
| Type | subscriptionRequestRejected |
| Attributes | eventChannel |
For example, the following postlude would raise the cloudos:subscriptionRequestRejected event:
| Code Block | ||||
|---|---|---|---|---|
| ||||
fired {
raise cloudos event subscriptionRequestRejected
with eventChannel = "3f15b820-af7f-012f-4c6e-00163ebcaaaa"
and _api = "sky";
} |
When the subscription request is rejected the CloudOS service will raise the cloudos:subscriptionRejected event within the target cloud (i.e. the cloud rejecting the subscription):
| Domain | cloudos |
|---|---|
| Type | subscriptionRejected |
| Attributes | eventChannel, namespace, relationship, channelName |
The following rule is selected when the cloudos:subscriptionRejected event is seen:
| Code Block | ||||
|---|---|---|---|---|
| ||||
rule receive_subscriptionRejected {
select when cloudos subscriptionRejected
namespace re/MyFriends/
channelName re/Coworkers Bob+Ted/
relationship re/friend-friend/
...
} |
In addition, the CloudOS service raises the cloudos:subscriptionRejected event in the originating cloud:
| Domain | cloudos |
|---|---|
| Type | subscriptionRejected |
| Attributes | backChannel, namespace, relationship, channelName |
The only difference is that the attribute backChannel is contains the value of the ECI to the target cloud.
The following rule is selected when the cloudos:subscriptionRejected event is raised:
| Code Block | ||||
|---|---|---|---|---|
| ||||
rule receive_subscriptionRejected {
select when cloudos subscriptionRejected
namespace re/MyFriends/
channelName re/Coworkers Bob+Ted/
relationship re/friend-friend/
...
} |
Subscription Rejection Event Flow
- The
cloudos:subscriptionRequestRejectedevent is raised into the target personal cloud. - CloudOS raises the
cloudos:subscriptionRejectedevent within the target personal cloud. - CloudOS raises an event over the eventChannel to the originating personal cloud to indicate that the subscription request was rejected.
- Within the originating personal cloud CloudOS raises the
cloudos:subscriptionRejectedevent.
Unsubscribe
A ruleset that wishes to remove the channels between two clouds raises the cloudos:unsubscribe event:
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
rule receive_subscriptionRemoved {
select when cloudos subscriptionRemoved
namespace re/MyFriends/
channelName re/Coworkers Bob+Ted/
relationship re/friend-friend/
...
} |
Unsubscribe Event Flow
- The
cloudos:unsubscribeevent is raised into the originating personal cloud. Note that it is also possible to raised thecloudos:unsubscribeevent in the target personal cloud as well. "Originating" and "target" are relative to where thecloudos:unsubscribeevent is raised. - CloudOS raises the
cloudos:subscriptionRemovedevent within the originating personal cloud. - CloudOS raises an event over the eventChannel to the target personal cloud to indicate that the subscription has been removed.
- CloudOS raises the
cloudos:subscriptionRemovedevent within the target personal cloud.
Functions
The CloudOS service provides the following functions. In order to use these functions, a ruleset must include the CloudOS service ruleset as a module:
| Code Block | ||||
|---|---|---|---|---|
| ||||
use module a169x625 alias CloudOS |
subscriptionList(namespace, relationship)
The subscriptionList() function will return a map of the subscriptions within the specified namespace and relationship.
...