Versions Compared

Old Version 38

changes.mady.by.user Phil Windley

Saved on

compared with

New Version 39

changes.mady.by.user Ed Orcutt

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Domaincloudos
Typesubscribe
AttributeschannelName, namespace, relationship, targetChannel, subAttrs

The attributes have the following semantics:

  • The channelName attribute is a label associated with the subscription that should convey meaning to developer. The channelName is only used as a component in the creation of the event channel identifier. If no channelName is specified the value of "orphan" will be used.
  • The namespace attribute is provided as a means for the developer to group subscriptions within a single, or group, or applications. The namespace is used to filter the list of subscriptions returned by the subscriptionList() function. If no namespace is specified the value of "shared" will be used.
  • The relationship attribute allows the developer to characterize the relationship between the originator and target clouds. The relationship attribute should be specified as a pair of values separated by a dash (e.g. parent-child, peer-peer, master-slave). The first value of the relationship attribute will be stored with the originating Personal Cloud subscription, the second value will be stored with the target Personal Cloud subscription. The relationship attribute values are used to filter the list of subscriptions returned by the subscriptionList() function. If no relationship is specified the value of "peer-peer" will be used.
  • The targetChannel attribute is the event channel identifier (ECI) for the target cloud to which the subscription is to be made. Usually, this is the well-known ECI (doorbell) for the target cloud. The well-known ECI provides a means for bootstrapping subscriptions between clouds. .
  • The subAttrs is an optional attribute that you can use to pass a JSON hash for key/value pairs to the target personal cloud.

Any ruleset wishing to create the subscription signals the CloudOS to do so by raising the system:subscribe event. This is most often done in a rule postlude as shown in the following example:

Code Block
themeConfluence
languagejavascript
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";
}

The CloudOS service raises the cloudos:subscriptionRequestAdded to the originating cloud:

Domaincloudos
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
themeConfluence
languagejavascript
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:

Domaincloudos
Type
subscriptionRequestPending
Attributes
eventChannel, namespace, relationship, channelName, subAttrs

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

The following rule would be selected upon seeing the cloudos:subscriptionRequestAdded event with appropriate values for the event attributes:

Code Block
themeConfluence
languagejavascript
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();
  }
  ...
}

Subscription Event Flow

  1. The cloudos:subscribe event is raised by the originating personal cloud.
  2. 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.
  3. CloudOS then raises an event to the target personal cloud over the targentChannel (typically the doorbell ECI) requesting the subscription.
  4. CloudOS in the target personal cloud will raise the cloudos:subscriptionRequestPending giving rulesets the opportunity to respond with either an approval or rejection (see below).

Subscription Approval or Rejection

...