Channels API

Notes

For all functions, enter the parameters in the order listed.
Italicized parameters are optional.
Received Events are events of the "wrangler" domain that Wrangler will respond to
Raised Events are events that can be selected on within any ruleset in the pico when they occur
Sent Events are events that the pico will send elsewhere as a result of triggering a Wrangler event.

Functions

channel

This is a "one-stop" function for getting desired channel info. Allows grouping of channels by their attributes, or getting specific channels by their ECI/name/etc.

List a set of channels depending on what parameters are past.

If all parameters are passed as null, it will return all channels for that pico.

If the id parameter is passed then the function will always return a single channel based upon the passed value.

If the collection parameter is passed, the function will return a map with channels grouped in arrays keyed to the channel attribute passed as the parameter. That is, whatever is passed to collection will group the pico channels according to the value they have as that attribute.

If the filtered parameter is passed, the collection parameter must have been passed. The filtered parameter will return an array of channels where the value passed to filtered matches the value of the channel attribute passed to collection.

Returns

Either

A single channel map containing the information for the value passed to id parameter.

A map with values that are arrays of channel maps keyed to the channel attribute passed to the collection parameter

An array of channel maps whose value for the attribute passed to the collection parameter is the same as the value passed to filtered.

NULL if no channels found for any operation.

Parameters

Parameter

Datatype

Description

id

String

Can either be the name of a single channel or the ECI of a channel.

collection

String

VALID INPUTS: "id", "pico_id", "name", "type", "policy_id"

The channel attribute that you want the value of to be mapped to arrays of channels whose value for that attribute matches

filtered

String

The collection parameter must also be passed! This is the channel attribute value that you want to select for

Example

response = wrangler:channel(null,null,null); // all channels
response = wrangler:channel("flipper",null,null); // single channel with "flipper" name
response = wrangler:channel(null,"type",null); // collection of channels by type
response = wrangler:channel(null,"type","OAUTH"); // collection of channels with "OAUTH" as type

A "channel map" looks like this

Example

{
  "id": "4PkMF8CYq5dsh7ksn6fDKh",
  "pico_id": "cjqr0of8e003p88rq7hric28i",
  "name": "admin",
  "type": "secret",
  "policy_id": "allow-all-policy",
  "sovrin": {
    "did": "4PkMF8CYq6dsh7ksn6fDKh",
    "verifyKey": "2rEaErex4S9CD8y6a1wZuHYxbH5DTpVw7SyBVhCU2gxa",
    "encryptionPublicKey": "AmHEeV8dYHZQ69b4wqtdVDUj97KJU4dfuHVoFcZzuvmg"
  }
}

alwaysEci

Returns the ECI of the channel whose ECI or name is given to the function. Is identical to only passing one parameter to the channel function. It can be used to check if a channel with that ECI exists.

Parameters

Parameter	Datatype	Description
value	String	Can either be the name of a channel or the ECI of a channel.

Returns

Either

A string containing the ECI of the channel prompted for

NULL if no channel is found for the given parameter

Example

channelECI = wrangler:alwaysEci("wovyn_channel")

nameFromEci

Returns the name of the channel with the given name or ECI.

Parameters

Parameter	Datatype	Description
eci	String	Can either be the ECI of a channel or the name of a channel

Returns

Either

A string containing the name of the channel prompted for

NULL if no channel is found for the given parameter

Example

channelName = wrangler:nameFromEci("4PkMF8CYq5dsh7ksn6fDKh")

Actions

createChannel

Takes a pico ID, a channel name, a channel type, and optional parameter policy ID to create a new channel for that pico ID with those attributes.

Parameters

Parameter	Datatype	Description
pico_id	String	ID of the pico to add the channel to. Will default to the currently running pico.
name	String	The name for the new channel
type	String	The type of new channel This is an arbitrary string typically used to give a domain to channels.
policy_id	String	The policy ID to apply to the channel Currently defaults to an "allow-all-policy" such that any event can be received on this channel.

Returns

A map with the following contents

id: The new ECI for the created channel
pico_id: The pico ID of the pico the channel has been created on
name: The name of the new channel
type: The type of the channel created
policy_id: The policy that describes the channel that has been created

Example

//Returns:
{
	"id" : <new_eci>,
	"pico_id": <pico_id>,
	"name": "channel_name",
	"type": "channel_type",
	"policy_id": "1234"
}

deleteChannel

Takes a name or ECI of a channel and removes that channel. If a name is given it removes the channel from the pico it is run within. The engine will error if the channel does not exist or you attempt to delete the pico's admin channel.

Parameters

Parameter	Datatype	Description
value	String	ID of the pico to add the channel to. Will default to the currently running pico.

Returns

The channel that was removed in a channel map form:

Example

{
  "id": "4PkMF8CYq5dsh7ksn6fDKh",
  "pico_id": "cjqr0of8e003p88rq7hric28i",
  "name": "admin",
  "type": "secret",
  "policy_id": "allow-all-policy",
  "sovrin": {
    "did": "4PkMF8CYq6dsh7ksn6fDKh",
    "verifyKey": "2rEaErex4S9CD8y6a1wZuHYxbH5DTpVw7SyBVhCU2gxa",
    "encryptionPublicKey": "AmHEeV8dYHZQ69b4wqtdVDUj97KJU4dfuHVoFcZzuvmg"
  }
}

newPolicy

Creates a new policy based on a given map argument and returns the created policy. See this pico engine pull for a more in-depth explanation.

Parameters

Parameter	Datatype	Description
policy	Map	Example map: { name: "only allow foo/bar events", event: { allow: [{domain: "foo", type: "bar"}], deny: [], }, query: {allow: [], deny: []} }

Returns

The map passed to the action but with an additional "id" key mapped to the policy ID of the newly created policy.

Example

{
    id: "1234",
    name: "only allow foo/bar events",
    event: {
        allow: [{domain: "foo", type: "bar"}],
        deny: [],
    },
    query: {allow: [], deny: []}
}

Received Events

channel_creation_requested

wrangler:channel_creation_requested

Creates a new channel through an event. It first checks that the name passed to it does not exist as a current channel on the pico. If it does not, then it creates the channel. The channel is created with the type and policy given in the event attributes. If no name is passed then an error event is raised.

Attributes

Attribute	Datatype	Description
name	String	The name of the channel you want to create. Must be a unique name from any other channel on the pico.
type	String	The type of channel you want to create. This is an arbitrary string typically used to give a domain to channels. It will default to _wrangler if not given.
policy_id	String	The policy ID of the policy you want this channel to follow. Currently defaults to the allow-all-policy.

Directives Returned

Will return empty directives if the name passed already exists as a channel or no name is passed.

Example

send_directive("channel_Created", channel); 
// Channel is a channel map of the channel with its attributes keyed to their values:
/*
{
  "directives": [
    {
      "options": {
        "id": "8nHCdus2sqVmF34SshhtsF",
        "pico_id": "cjqszhxzp015fb0rq1istxqhl",
        "name": "test",
        "type": "test",
        "policy_id": "allow-all-policy",
        "sovrin": {
          "did": "8nHCdus2sqVmF34SshhtsF",
          "verifyKey": "5Exq5iXBUQ8XSctTx1156g4kQCSbK62Su2NXHSX8HFkw",
          "encryptionPublicKey": "AQwwUCGh9Ke9vKRaGhUj6XkZxfvVS8JdTYyzuaiHiqAF"
        }
      },
      "name": "channel_Created",
      "meta": {
        "rid": "io.picolabs.wrangler",
        "rule_name": "createChannel",
        "txn_id": "cjrb9ttiu0023nkrquliin4mj",
        "eid": "__testing"
      }
    }
  ]
}
*/

Corresponding Raised Events:

Wrangler Full API#channel_created

channel_deletion_requested

wrangler:channel_deletion_requested

Deletes the channel given as either an ECI or channel name. The engine errors and nothing happens if the channel does not exist.

Attributes

Attribute	Datatype	Description
eci	String	The ECI of the channel you want to delete on this pico.
name	String	The name of the channel you want to delete on this pico.

Directives Returned

Will return empty directives if no channel was found to be deleted.

Example

send_directive("channel_deleted", channel);
// Channel is a channel map of the channel with its attributes keyed to their values:
/*
{
  "directives": [
    {
      "options": {
        "id": "8nHCdus2sqVmF34SshhtsF",
        "pico_id": "cjqszhxzp015fb0rq1istxqhl",
        "name": "test",
        "type": "test",
        "policy_id": "allow-all-policy",
        "sovrin": {
          "did": "8nHCdus2sqVmF34SshhtsF",
          "verifyKey": "5Exq5iXBUQ8XSctTx1156g4kQCSbK62Su2NXHSX8HFkw",
          "encryptionPublicKey": "AQwwUCGh9Ke9vKRaGhUj6XkZxfvVS8JdTYyzuaiHiqAF"
        }
      },
      "name": "channel_deleted",
      "meta": {
        "rid": "io.picolabs.wrangler",
        "rule_name": "deleteChannel",
        "txn_id": "cjrba64ud0024nkrqm4wp8w4v",
        "eid": "__testing"
      }
    }
  ]
}
*/

Corresponding Raised Events:

Wrangler Full API#channel_deleted

Raised Events

channel_created

wrangler:channel_created

Raised when a new channel has been created on this pico by using the wrangler:channel_creation_requested event.

Attributes Added

Attribute	Datatype	Description
channel	Map	Channel Map describing the created channel's attributes.

A channel map has the structure:

Example

{
  "id": "4PkMF8CYq5dsh7ksn6fDKh",
  "pico_id": "cjqr0of8e003p88rq7hric28i",
  "name": "admin",
  "type": "secret",
  "policy_id": "allow-all-policy",
  "sovrin": {
    "did": "4PkMF8CYq6dsh7ksn6fDKh",
    "verifyKey": "2rEaErex4S9CD8y6a1wZuHYxbH5DTpVw7SyBVhCU2gxa",
    "encryptionPublicKey": "AmHEeV8dYHZQ69b4wqtdVDUj97KJU4dfuHVoFcZzuvmg"
  }
}

An example of a rule selecting on a new channel creation.

Example

rule on_new_channel{
  select when wrangler channel_created where event:attr("channel"){["type"]} == "test" // If a channel of type test has been created
  pre {
  }
  noop() // Do some operation
  fired{
    klog("my channel has been created!");
  }
}

channel_deleted

wrangler:channel_deleted

Raised when a channel has been deleted from this pico using the wrangler:channel_deletion_requested event.

Attributes Added

Attribute	Datatype	Description
channel	Map	Channel Map describing the created channel's attributes.

A channel map has the structure:

Example

{
  "id": "4PkMF8CYq5dsh7ksn6fDKh",
  "pico_id": "cjqr0of8e003p88rq7hric28i",
  "name": "admin",
  "type": "secret",
  "policy_id": "allow-all-policy",
  "sovrin": {
    "did": "4PkMF8CYq6dsh7ksn6fDKh",
    "verifyKey": "2rEaErex4S9CD8y6a1wZuHYxbH5DTpVw7SyBVhCU2gxa",
    "encryptionPublicKey": "AmHEeV8dYHZQ69b4wqtdVDUj97KJU4dfuHVoFcZzuvmg"
  }
}

An example of a rule selecting on a channel deletion.

Example

rule on_channel_deletion{
  select when wrangler channel_deleted where event:attr("channel"){["type"]} == "test" // If a channel of type test has been deleted
  pre {
  	channelName = event:attr("channel"){["name"]};
  }
  doCleanup() // Do some operation
  fired{
    klog("my channel has been deleted!");
	ent:channels := ent:channels.delete([channelName]);
  }
}