...
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.
...
Any ruleset wishing to create the subscription signals the CloudOS to do so by raising the system:subscribe subscribe event. This is most often done in a rule postlude as shown in the following example:
| Code Block | ||||
|---|---|---|---|---|
| ||||
fired {
raise cloudos event subscribe
with channelName = "Coworkers Bob+Ted"
and namespace = "MyFriends"
and relationship = "friend-friend"
and targetChannel = "3f15b820-fa7f-012f-4c6e-00163ebccdcd"
and _api = "sky";
} |
The CloudOS service raises the cloudos:subscriptionRequestAdded to the originating cloud:
| Domain | cloudos |
|---|---|
| Type | subscriptionRequestAdded |
| Attributes | targetChannel, backChannel, namespace, relationship, channelName |
The backChannel attribute contains an ECI for the originating cloud that the CloudOS service has created and will pass to the target cloud.
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/
...
} |
The CloudOS services 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:subscribe event is raised by the originating personal cloud.
- CloudOS will create a new channel and raise the cloudos:subscriptionRequestAdded event 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.
- Lastly, the CloudOS in the target personal cloud will raise the cloudos:subscriptionRequestPending providing the application developer the opportunity to respond with either an approval or rejection.
Subscription Approval or Rejection
...
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:
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
fired {
raise cloudos event subscriptionRequestApproved
with eventChannel = "3f15b820-af7f-012f-4c6e-00163ebcaaaa"
and _api = "sky";
} |
For example, this postlude might be in a rule that has received input from the user indicating the user has approved the request. For some requests in some clouds, you may want to create a rule that rule that automatically approves the request.
Once the subscription request is approved, the CloudOS service in both the orginating and target clouds will raise the cloudos:subscriptionAdded event so that a ruleset can take additional actions once the subscription has been created:
...