Page Comparison

...

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 attributes have the following semantics:

...

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  subAttr       = {"name": "Ed Orcutt", "age": "43"}
    and  _api = "sky";
}

subscriptionRequestAdded

targetChannel, backChannel, namespace, relationship, channelName

rule process_subscriptionRequestAdded {
  select when cloudos subscriptionRequestAdded
    namespace re/MyFriends/"
    channelName re/Coworkers Bob+Ted/
    relationship re/friend-friend/
  ...
}

subscriptionRequestPending

eventChannel, namespace, relationship, channelName, subAttrs

rule process_subscriptionRequestPending {
  select when cloudos subscriptionRequestPending
    namespace re/MyFriends/"
    channelName re/Coworkers Bob+Ted/
    relationship re/friend-friend/
  pre {
    subAttrs = event:attr("subAttrs").decode();
  }
  ...
}

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:

subscriptionRequestApproved

eventChannel, approveAttrs

The approveAttrs attribute is an optional parameter that can be used to pass a JSON hash of key/value pairs to the originating personal cloud.

For example, the following postlude would raise the cloudos:subscriptionRequestApproved event:

fired {
  raise cloudos event subscriptionRequestApproved
    with eventChannel = "3f15b820-af7f-012f-4c6e-00163ebcaaaa"
    and  approveAttrs = {"name": "Fred Wilson" , "age": "22" }
    and  _api = "sky";
}

...

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:

subscriptionAdded

eventChannel, backChannel, namespace, relationship, channelName, approveAttrs

Note: The approvalAttrs attribute is encoded, you will want to decode() it prior to use.

rule process_subscriptionAdded {
  select when cloudos subscriptionAdded
    namespace re/MyFriends/
    channelName re/Coworkers Bob+Ted/
    relationship re/friend-friend/
  pre {
    approveAttrs = event:attr("approveAttrs").decode();
  }
  ...
}

subscriptionRequestRejected

eventChannel

fired {
  raise cloudos event subscriptionRequestRejected
    with eventChannel = "3f15b820-af7f-012f-4c6e-00163ebcaaaa"
    and  _api = "sky";
}

subscriptionRejected

eventChannel, namespace, relationship, channelName

rule receive_subscriptionRejected {
  select when cloudos subscriptionRejected
    namespace re/MyFriends/
    channelName re/Coworkers Bob+Ted/
    relationship re/friend-friend/
  ...
}

subscriptionRejected

backChannel, namespace, relationship, channelName

rule receive_subscriptionRejected {
  select when cloudos subscriptionRejected
    namespace re/MyFriends/
    channelName re/Coworkers Bob+Ted/
    relationship re/friend-friend/
  ...
}

Unsubscribe

A ruleset that wishes to remove the channels between two clouds raises the cloudos:unsubscribe event:

unsubscribe

targetChannel

The targetChannel attribute uniquely identifies the channel to be unsubscribed. The backChannel is one of the results provided by the subscriptionList() function.

The following postlude shows this event being raised:

fired {
  raise cloudos event unsubscribe
    with targetChannel = "3f15b820-7aff-012f-4c6e-00163ebcfddfd"
    and  _api = "sky";
}

The CloudOS service in both the originating and target clouds raises the cloudos:subscriptionRemoved event so that rulesets within the respective clouds can take any appropriate action:

subscriptionRemoved

eventChannel, backChannel, namespace, relationship, channelName, approveAttrs

Note: The approvalAttrs attribute is encoded, you will want to decode() it prior to use.

The following rule is selected when the cloudos:CloudOS_subscriptionRemoved event is raised:

rule receive_subscriptionRemoved {
  select when cloudos subscriptionRemoved
    namespace re/MyFriends/
    channelName re/Coworkers Bob+Ted/
    relationship re/friend-friend/
  pre {
    approveAttrs = event:attr("approveAttrs");
  }
  ...
}

Unsubscribe Event Flow

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:

use module a169x625 alias CloudOS

subscriptionList(namespace, relationship)

The subscriptionList() function will return a map of the subscriptions within the specified namespace and relationship. 

pre {
  friendsList = CloudOS:subscriptionList("myConnections", "friend");
}

getAllSubscriptions()

The getAllSubscriptions() function will return a map of all active subscriptions within the current Personal Cloud. The subscription sample application provides an example of using this function.

pre {
  allSubscriptions = CloudOS:getAllSubscriptions();
}

getAllPendingApproval()

The getAllPendingApproval() function returns a map of all subscription request that are pending your approval. The subscription sample application provides an example of using this function.

pre {
  allSubscriptionsPendingApproval = CloudOS:getAllPendingApproval();
}

getAllPendingSubscriptions

The getAllPendingSubscriptions() function returns a map of all subscription request that have been generated within this Personal Cloud. The subscription sample application provides an example of using this function.

pre {
  allSubscriptionRequest = CloudOS:getAllPendingSubscriptions();
}

...