(Classic) CloudOS Service

The CloudOS service provides fundamental interaction points (APIs) for managing personal cloud account services. This includes the ability to manage personal clouds, personal channels, and rulesets within personal clouds. To be used, the CloudOS service must be installed in the personal cloud. In addition, any rulesets that use the CloudOS service must reference it as a module:

use module a169x625 alias CloudOS

We will discuss the following:

• Managing personal clouds
• Managing personal channels
• Managing rulesets

Managing Personal Clouds

Sometimes, one personal cloud needs to manage another. For example, a ruleset managing the physical assets of a cloud's owner might need to create a new cloud for a new asset or destroy an existing one when the asset is disposed of.

The following functions are available:

cloudCreate(email, password, apikey)

The cloudCreate() function will create a new personal cloud with the email address and password provided. Upon successful creation of the new Personal Cloud the CloudOS Ruleset will be installed into the new Personal Cloud.

The function will return a JSON structure as follows:

{
  "status" : true,
  "token" : "27329425-d750-992a-cc15-zz163e3d039d",
  "msg" : "Authentication Successful"
}

Upon successful creation of the new personal cloud, status will be true, otherwise status will be false. In addition, token will return an event channel identifier for the newly created personal cloud. Upon successful creation the CloudOS ruleset will be installed into the new personal cloud.

The following example shows the use of cloudCreate() to create a personal cloud. 

pre {
  personalCloud = CloudOS:cloudCreate("myCloud@kynetx.com", "MySecret", "MyKey");
  authStatus    = personalCloud{"status"};
  authToken     = personalCloud{"token"};
}

cloudAuth(email, password)

The cloudAuth function can be used to authenticate with an existing personal cloud. Upon successful authentication to the personal cloud the CloudOS ruleset will be installed into the new personal cloud if it is not already there.

The function returns a JSON structure as follows:

{
  "status" : true,
  "token" : "27329320-d750-992e-cc15-zz163e3da64d",
  "msg" : "Authentication Successful"
}

Upon successful authentication status will be true, otherwise status will be false. In addition, token will return an event channel Identifier for the authenticated personal cloud.

pre {
  personalCloud = CloudOS:cloudAuth("myCloud@kynetx.com", "MySecret");
  authStatus    = personalCloud{"status"};
  authToken     = personalCloud{"token"};
}

Managing Personal Channels

Personal clouds often need new channels. The following interface provides for managing the channels in a personal cloud. There are both functional and event-based interfaces for managing channels.  

Functions

channelCreate(channelName, userToken)

The channelCreate() function will create a new personal event channel in the personal cloud identified by userToken, if specified. Otherwise the channel will be created in the current personal cloud.  The channelName will simply be a label for you to identify the purpose of the channel. The function will return a JSON structure as follows:

{
  "status" : true,
  "token" : "27329444-d750-992e-cc15-zz163ea6439d",
  "msg" : "ECI creation Successful"
}

Upon successful creation of the personal channel the value of status will be true, otherwise status will be false. In addition, token will return the newly created event channel identifier.

The following code shows the use of createChannel():

pre {
  authToken       = "71760130-a8f8-012f-74b3-00163ebceedf";
  personalChannel = CloudOS:channelCreate("NewChannel", authToken);
  channelStatus   = personalChannel{"status"};
  channelToken    = personalChannel{"token"};
}

channelDestroy(channelID, userToken)

The channelDestroy() function will delete an existing personal channel for the personal cloud associated with the specified userToken, if specified. Otherwise the channel will be deleted from the current personal cloud. The function will return a JSON structure as follows:

{
  "status" : true,
  "msg" : "ECI deletion Successful"
}

Upon successful deletion of the personal channel the value of status will be true, otherwise status will be false.

The following code demonstrates the use of channelDestroy():

pre {
  authToken       = "71760130-a8f8-012f-74b3-00163ebceedf";
  channelToken    = "ef8a2534-a088-012f-7cb7-00163e64d091";
  personalChannel = CloudOS:channelDestroy(channelToken, authToken);
  channelStatus   = personalChannel{"status"};
}

channelList(userToken)

The channelList() function will retrieve a list of all of the personal channels available within the personal cloud associated with the specified userToken, if specified. Otherwise the list will be for the current Personal Cloud. The function will return a JSON structure as follows:

{
  "valid" : true,
  "channels" : [
    {
      "name": "Login_Token",
      "cid" : "27329435-d750-012e-cc15-00163e3d03zz"
    },
    {
      "name": "ReadOnly",
      "cid" : "27329435-d750-012e-cc15-00163e3d03xx"
    },
  ]
}

Upon successful completion the value of status will be true, otherwise status will be false.

The following code demonstrates the use of channelList():

pre {
  authToken        = "71760130-a8f8-012f-74b3-00163ebceedf";
  personalChannels = CloudOS:channelList(authToken);
  channelStatus    = personalChannel{"status"};
  channelList      = PersonalChannels.pick("$.channels", true).head();
}

Events

Channels can also be managed by event. The CloudOS service listens for the following channel-related events:

Create a Channel

Create a new Personal Channel within a Personal Cloud.

Event:

• domain: system
• type: channelCreate
• attributes: 
  • channelName - The channelName should be bound to an identifier that conveys the purpose of the personal channel being created.

The following code shows how the system:channelCreate event can be raised:

fired {
  raise system event channelCreate
    with channelName = "NewChannel"
    and  _api = "sky";
}

Delete a Channel

Delete an existing channel within a personal Cloud.

Event:

• domain: system
• type: channelDestroy
• attributes: 
  • channelID - The channelID must be an existing channel GUID within the personal cloud.

The following code sample shows how the system:channelDestroy event can be raised:

fired {
  raise system event channelDestroy
    with channelID = "71760130-a8f8-012f-74b3-00163ebceedf"
    and  _api = "sky";
}

List Channels

Retrieve a list of all channels within a personal cloud.

Event: 

• domain: system
• type: channelList
• attributes: none

Managing Rulesets

A personal cloud needs to manage its own rulesets and the rulesets of clouds that it controls. 

There are both functional and event-based interfaces for managing rulesets.  

Functions

rulesetAdd(rulesetID, userToken)

The rulesetAdd() function will install a ruleset in the personal cloud associated with userToken, if specified. Otherwise the ruleset will be installed in the current personal cloud. Upon successful installation of the ruleset the function will return true, otherwise false will be returned.

The following code sample shows rulesetAdd() in use:

pre {
  authToken     = "71760130-a8f8-012f-74b3-00163ebceedf";
  rulesetStatus = CloudOS:rulesetAdd("a169x404", authToken);
}

rulesetRemove(rulesetID, userToken)

The rulesetRemove() function will uninstall a ruleset from the personal cloud associated with userToken, if specified. Otherwise the ruleset will be removed from the current personal cloud. Upon successful removal of the ruleset from the personal cloud, the function will return true, otherwise false will be returned.

The following code sample shows rulesetRemove() in use:

pre {
  authToken     = "71760130-a8f8-012f-74b3-00163ebceedf";
  rulesetStatus = CloudOS:rulesetRemove("a169x404", authToken);
}

rulesetList(userToken)

The rulesetList() function will retrieve the list of all rulesets installed the the personal cloud associated with userToken, if specified. Otherwise the list will be for the current personal cloud. The function will return a JSON structure as follows:

{
  "valid" : true,
  "rids" : [
    {
      "name": "PersonalBlock",
      "rid" : "a169x230"
    },
    {
      "name": "CloudOS",
      "rid" : "a169x625"
    },
  ]
}

Upon successful completion the value of valid will be true, otherwise valid will be false.

The following code sample shows rulesetList() in use:

pre {
  authToken       = "71760130-a8f8-012f-74b3-00163ebceedf";
  rulesetResponse = CloudOS:rulesetList(authToken);
  rulesetStatus   = resultsetResponse{"status"};
  rulesetList     = rulesetResponse{"rids"}
}

Events

Rulesets can also be managed by event. The CloudOS service listens for the following ruleset-related events:

Install a Ruleset

Install a new ruleset into a personal cloud.

Event:

• domain: system
• type: rulesetAdd
• attributes: 
  • rulesetID - The rulesetID must be a valid Kynetx ruleset identifier (e.g. a169x22).

The following code sample shows system:rulesetAdd being raised:

fired {
  raise system event rulesetAdd
    with rulesetID = "a169x404"
    and  _api = "sky";
}

Uninstall a Ruleset

Uninstall a ruleset from a personal cloud.

Event:

• domain: system
• type: rulesetRemove
• attributes: 
  • rulesetID - The rulesetID must be a valid Kynetx ruleset identifier (e.g. a169x22).

fired {
  raise system event rulesetRemove
    with rulesetID = "a169x404"
    and  _api = "sky";
}

List the Rulesets

Retrieve a list of all of the rulesets installed in a personal cloud.

Event:

• domain: system
• type: rulesetList
• attributes: none