To use Wrangler as a module, add use module io.picolabs.wrangler alias wrangler in your meta block.

This API documents all the information a developer needs to know to publicly interact with wrangler.

This page is an amalgamation of the API subpages, putting them all in one place.

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.
• This documentation is up to date with engine version 0.49.0

Utility

Pages

• Accessing a Function Shared by Another Pico

Functions

skyQuery

A user friendly way to make an HTTP request between picos. It provides cleanup and returns the error if the returned HTTP status was not 200.

It is mainly used to programmatically call functions inside of other picos from inside a rule. However, deadlocks are possible due to its synchronous nature (e.g. do not let two picos query each other simultaneously). See Accessing a Function Shared by Another Pico for more information.

Parameters

Returns

Success: the result of the function queried for.

Failure: a map of error information which contains:

{
	"error":"general error message",
	"skyQueryError":"The value of the 'error key', if it exists, of the function results"
	"skyQueryErrorMsg":"The value of the 'error_str', if it exists, of the function results"
	"skyQueryReturnValue":"The function call results"
}

pre {
	eci = event:attr("eci")
	wellknown = wrangler:skyQuery( eci , "io.picolabs.subscription", "wellKnown_Rx")
}
if wellknown{"error"}.isnull() then
	noop()
always {
	ent:savedWellknown := wellknown;
}
/*
Query the the function wellKnown_Rx() in the ruleset "io.picolabs.subscription" through the pico ECI given in the event attribute "eci".
*/

pre {
  eci = eci_to_other_pico;
  args = {"arg1": val1, "arg2": val2};
  answer = wrangler:skyQuery(eci,"my.ruleset.id","myFunction",args);
}
if answer{"error"}.isnull() then noop(); // Check that it did not return an error
fired {
  // process using answer
}

Picos

Pages

• Managing Pico Lifecycle

Functions

children

Returns an array of the children of the pico. Has optional parameter "name" which returns just the attributes for the children with the specific name if they exist, otherwise it returns attributes on every child if not provided. Has also optional parameter "allowRogue" which is by default true. Will not return child picos that are currently being deleted.

Parameters

Returns

An array containing a map for each returned pico. Each map contains:

parent_eci: The ECI from the pico to the respective child. Should be used for parent-child interaction.

name: The child pico's name

id: The id of the child pico

eci: The main Wrangler ECI for the child pico

children = wrangler:children()
/*
[
  {
    "parent_eci": "CyrmdG4PkiVYRUo2K69k2E",
    "name": "Section CS462-1 Pico",
    "id": "cjh6pbzun005zvde06bwy2pci",
    "eci": "JfcEBxEK5WDKA69Bvach4Y"
  },
  {
    "parent_eci": "Tg5ULPBYByJjsEoKpfsbQ2",
    "name": "Section CS462-2 Pico",
    "id": "cjh6pc28r0067vde04qd23t6o",
    "eci": "56S414r4Uq4kGx6Xi1qmSs"
	"rogue": true
  }
]
*/

childrenWithWrangler = children(null, false)
/*
[
  {
    "parent_eci": "CyrmdG4PkiVYRUo2K69k2E",
    "name": "Section CS462-1 Pico",
    "id": "cjh6pbzun005zvde06bwy2pci",
    "eci": "JfcEBxEK5WDKA69Bvach4Y"
  }
]
*/

childrenNamedRefused = children("refused")
/*
[
	{
		"parent_eci":"5ehT3zigTKhHuHL571dCF5",
		"name":"refused",
		"id":"cjxf0yqiz000o0jbz4kbrgczt",
		"eci":"TR4zpDwpKtuYAbsmBG7Wd7"
	},
	{
		"parent_eci":"8sd1pvKqy54RmdY35bpRvM",
		"name":"refused",
		"id":"cjxf1dhp300150jbz3r5v3x2f",
		"eci":"RGFe5aVgBTG4w2ix8fw52V"
	}
]
*/

myself

Returns a map giving basic meta information about the pico. This information includes the pico's ID, Wrangler ECI, and name.

Returns

A map giving basic information about a pico with the following contents:

id: The ID of the pico

eci: The main Wrangler ECI of the pico

name: The name of the pico

myself_result = wrangler:myself()
/*
{
  "id": "cjhtji2op009hpkrq35bcpodh",
  "eci": "4bUS9W4HY5S1YfsAM9Ygw5",
  "name": "This Pico"
}
*/

name

Returns the name of the pico as recorded by Wrangler

Returns

A string containing the name of the pico

name = wrangler:name()
/*
"wovyn_sensor"
*/

id

Returns the ID of the pico as recorded by Wrangler

Returns

A string containing the ID of the pico

id = wrangler:id()
/*
"cjxeypfo900070jbzes8736w2"
*/

parent_eci

Returns a string containing an ECI to the parent of the pico. If no parent exists then it will return the empty string.

Returns

A string with the ECI of the parent pico. If no parent exists, then the string is the empty string.

channel_to_parent = wrangler:parent_eci()
/*
"HdLRkvF2ADhMfERDScr4ng"
*/

randomPicoName

Returns a random English word that is unique among the children of the pico it is called on, if the pico has <= 200 children. Otherwise it will return a UUID.

Returns

A string that is a common English word

random_name_result = wrangler:randomPicoName()
/*
"realize"
*/

getPicoMap

Returns the same data as wrangler:myself except it includes an ECI to the parent pico.

Returns

A map containing meta information about the pico, including its Wrangler ECI, its Wrangler name, the pico ID, and an ECI for the parent pico.

thisPico = wrangler:getPicoMap()
/*
{
"name":"product",
"id":"cjxeypfo900070jbzes8736w2",
"parent_eci":"T2cuE5zaGrQzDS8NbDVs4y",
"eci":"Vn2TWkKeJYcj26gXSbiWr3"
}
*/

isMarkedForDeath

Returns true if this pico is in the process of being deleted. This function is used internally in Wrangler to lock tasks that cannot be interrupted by the pico being deleted, such as creating a new child pico. See Managing Pico Lifecycle for information on how to respond to notification of imminent pico deletion and allowing a ruleset to cleanup.

Returns

True if the pico is in the process of being deleted

False if the pico is not in the process of being deleted

picoUnsafe = wrangler:isMarkedForDeath()
/*
true
*/

timeForCleanup

Returns the maximum amount of time given to a pico for its rulesets to cleanup before it is deleted. It is given in the format of the second parameter of the time:add() function.

Returns

A map containing the set time allowed for ruleset cleanup before a pico is deleted.

timeToCleanup = wrangler:timeForCleanup()
/*
{ "minutes": 5 }
*/

getChild

 Given the pico ID of a child of Wrangler return the associated child map. Fast as it is a map access.

Parameters

Returns

Either

A child pico map for the relevant child of this pico.

NULL if the child does not exist

childInfo = wrangler:getChild("cjxf0yqiz000o0jbz4kbrgczt")
/*
{
"parent_eci":"5ehT3zigTKhHuHL571dCF5",
"name":"refused",
"id":"cjxf0yqiz000o0jbz4kbrgczt",
"eci":"TR4zpDwpKtuYAbsmBG7Wd7"}
*/

childExists = wrangler:getChild("badID")
/*
null
*/

Received Events

create_child

wrangler:child_creation or wrangler:new_child_request

Creates a new child for this pico with optional arguments for the child's name, and rulesets to install on it upon creation. It is important to note any additional attributes passed to it will also be accessible to the newly created child and its rulesets as event attributes, as long as their keys do not conflict with the keys used for the internal event chain. See Managing Pico Lifecycle for a more in-depth explanation.

Corresponding Raised Events:

• Wrangler Full API#child_initialized

delete_child

wrangler:child_deletion or wrangler:delete_children

Deletes the direct child of this pico that has either the name or ID given as an event attribute. It will also delete that child's entire subtree of children. If both name and ID are given, they both will be evaluated. Deleting a child this way allows the child time for its rulesets to do any cleanup that they may have asked time for. It also cleans up parent-child channels, etc.

Corresponding Raised Events:

• Wrangler Full API#child_deleted

force_child_deletion

wrangler:force_child_deletion or wrangler:force_children_deletion

Through engine calls forcibly removes children picos without necessary direct interaction with the children and without any opportunity for cleanup. Allows for deletion of misbehaving picos, picos that do not comply with Wrangler's deletion process, and other such issues. 

Corresponding Raised Events:

• Wrangler Full API#pico_forcibly_removed

child_sync

wrangler:child_sync

This event will both find children that Wrangler does not have recorded internally and delete children that Wrangler has recorded internally but do not exist anymore. Use this to detect any children added by rulesets other than Wrangler. Wrangler will ask the children first if they have Wrangler installed, if they do not then Wrangler will grab their admin channel through engine calls and add them to its children with a "rogue" attribute.

Corresponding Raised Events:

• Wrangler Full API#ghost_children_added
• Wrangler Full API#nonexistent_children_removed

Raised Events

child_initialized

wrangler:child_initialized

This is sent from the child to the parent once the child is done initializing. You can react to new children being created using this event. This event also guarantees that any rulesets passed to the create_child event have been installed. Note that any attributes passed to the wrangler:child_creation will also be present.

Attributes

child_deleted

wrangler:child_deleted

This event is raised within the pico when a child of this pico has been deleted through use of wrangler:child_deletion. 

Attributes

child_creation_failure

wrangler:child_creation_failure

Raised when a pico is not able to be created. The most common cause of this is attempting to create a child pico with a duplicate name to another child pico.

Attributes

The same as the ones passed to wrangler:child_creation

pico_forcibly_removed

wrangler:pico_forcibly_removed

This event is raised within the pico when a child of this pico has been deleted through a force deletion using wrangler:force_child_deletion.

Attributes

ghost_children_added

wrangler:ghost_children_added

This event is raised as a result of a wrangler:child_sync event if any children that Wrangler did not have recorded are found. Their info is given in the attributes.

Attributes

nonexistent_children_removed

wrangler:nonexistent_children_removed

This event is raised as a result of a wrangler:child_sync event if any children that Wrangler had recorded did not actually exist. 

Attributes

Rulesets

Functions

installedRulesets

Returns an array of all of the rulesets installed on the pico

Returns

An array of strings, with each string being an RID (ruleset identifier)

installed_rulesets = wrangler:installedRulesets()
/*
  ["io.picolabs.pico", ...]
 
*/

registeredRulesets

Returns an array of all the registered rulesets on the pico engine that the pico is running on.

Returns

An array of strings, with each string being an RID (ruleset identifier)

registered_rulesets = wrangler:registeredRulesets()
/*
    ["io.picolabs.pico", "io.picolabs.logging"]
*/

rulesetsInfo

Returns an array that contains full ruleset descriptions for the requested ruleset(s)

Parameters

Returns

A an array where each entry is a requested ruleset's description.

See the example for an idea of what each description (represented as a map) looks like

wrangler_info = wrangler:rulesetsInfo("io.picolabs.wrangler")
/*
[
  {
    "rid": "io.picolabs.wrangler",
    "src": "omitted for brevity, full source would show up here",
    "hash": "7d68b3232f8d820631ab73871530648b94ab610f598cab1986d7cd666232a0a0",
    "url": "The URL that the ruleset might be installed from, if downloaded from a remote server",
    "timestamp_stored": "2019-01-12T02:17:04.044Z",
    "timestamp_enable": "2019-01-12T02:17:04.045Z",
    "meta": {
      "name": "Wrangler Core",
      "description": "\r\n      Wrangler Core Module,\r\n      use example, use module v1_wrangler alias wrangler .\r\n      This Ruleset/Module provides a developer interface to the PICO (persistent computer object).\r\n      When a PICO is created or authenticated this ruleset will be installed to provide essential\r\n      services.\r\n    ",
      "author": "BYU Pico Lab"
    }
  }
]
*/

Received Events

install_rulesets_requested

wrangler:install_rulesets_requested

Installs the given rulesets in the pico that receives this event.

Attributes

Directives Returned

send_directive("rulesets installed", { "rids": /* An array of rids that were installed*/ });

Corresponding Raised Events:

• Wrangler Full API#ruleset_added

uninstall_rulesets_requested

wrangler:uninstall_rulesets_requested

Uninstalls the given rulesets in the pico that receives this event. The directives returned will always be the same, meaning if the ruleset did not exist in the first place, the directive would still map "rids" to the RIDs given as the event attribute. Use the Wrangler Full API#installedRulesets function to programmatically check if a ruleset is installed.

Attributes

Directives Returned

send_directive("rulesets uninstalled", { "rids": /* An array of rids that were uninstalled*/ });

ruleset_needs_cleanup_period

wrangler:ruleset_needs_cleanup_period

This event is used to signal to Wrangler to register a ruleset domain to wait for before fully deleting a pico, to allow the ruleset(s) time to cleanup.

Attributes

cleanup_finished

wrangler:cleanup_finished

This event is used to signal to Wrangler that a ruleset domain previously registered for cleanup is finished.

Attributes

set_timeout_before_pico_deleted

wrangler:set_timeout_before_pico_deleted

This event is used to change the time allotted for rulesets to cleanup before it times out and the pico deletes itself anyway. By default it is set to 5 minutes.

Attributes

Raised Events

ruleset_added

wrangler:ruleset_added

Is raised within the pico when new ruleset(s) have just been installed. This can be especially useful as an entry point for code execution on any ruleset. By selecting on this event and checking if your ruleset is one of the installed ones, your ruleset can begin execution upon installation.

Attributes Added

rule on_installation{
  select when wrangler ruleset_added where rids >< meta:rid.klog("meta rid") // if this ruleset has just been installed
  pre {
  }
  noop()
  fired{
    ent:ownerPolicy := owner_policy;
    ent:owners := {"root": {"eci": new_channel{"id"}}};
    raise game event "start_game"
      attributes event:attrs;
  }
}

install_rulesets_error

wrangler:install_rulesets_error

This event is raised when there was an error installing a ruleset into a pico. This may (but not only) include giving a RID that does not exist on the engine to install.

Attributes Added

rulesets_need_to_cleanup

wrangler:rulesets_need_to_cleanup

This event is raised when a pico is now getting ready to delete. Rulesets that have registered for a cleanup period should do any necessary cleanup on this event and then raise wrangler:cleanup_finished with their domain to signal their completion. Will have passed through attributes given to wrangler:child_deletion.

Channels

Pages

• Managing Channels

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

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

{
  "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

Returns 

Either

A string containing the ECI of the channel prompted for

NULL if no channel is found for the given parameter 

channelECI = wrangler:alwaysEci("wovyn_channel")

nameFromEci

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

Parameters

Returns 

Either

A string containing the name of the channel prompted for

NULL if no channel is found for the given parameter 

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

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

//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

Returns

The channel that was removed in a channel map form:

{
  "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

Returns

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

{
    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

Directives Returned

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

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

Directives Returned

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

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

A channel map has the structure:

{
  "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.

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

A channel map has the structure:

{
  "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.

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]);
  }
}

Subscriptions

Pages

• Managing Subscriptions
• Pico to Pico Subscriptions Lesson
• Developer UI -- Subscriptions tab

See Managing Subscriptions for an in-depth explanation on the subscription process.

Functions

established

Returns all of the established subscriptions for this pico in an array

Returns

NO ARGS: An array of subscription maps

key and value passed: The array will be filtered according to if the value at the key subscription attribute matches the value parameter

Parameters

Returns 

An array of established subscriptions. Possibly filtered.

establishedArray = subscription:established()
/*
[
  {
    "Tx_host": "http://10.37.68.7:8080", // The host of the other pico
    "Id": "cjrcuow1a001q04rqu6h7ihit", // The ID of the subscription
    "Tx": "5V8ks8hmirW8MfE96aNaHn", // The transmitting channel to send events to on the other pico
    "Rx": "5N8EnBfeCA3ajsniKDZdkQ", // The receiving channel to receive events on this pico
	"Tx_role": "sensor", // The role of the pico on the other end of the subscription
	"Rx_role": "manager", // This pico's role from its own perspective
    "Tx_verify_key": "3SnLikfRD8Cm5JtHaWe26byvcn4f7bQAVVZM2zWEEgUm", // The key used for verifying signed messages sent through the subscription
    "Tx_public_key": "FzkwstPeu7jQamcsY4HycW6f4RmNNPynqCveTiGbsVHy" // The public key used for encrypting messages to send to the other pico
  },
  {
    "Id": "cjrcv4dwt003004rqdonu3ulx",
    "Rx": "E8Ei7TFbUNs4VSqsYHBWhb",
    "Tx": "T7wRhAvKNJocFezx2QCUpY",
    "Tx_verify_key": "FEhBwJFRy9WGx3QQPaKWXSvxB9YRQDNk6QVmX1GW9e6y",
    "Tx_public_key": "5UENb6pXGw5W9Vmz9uKmkzoMWifxWfeDLHsnFhMvkCYK"
  }
]
*/

outbound

Returns the pending outbound subscription requests in an array

Returns

NO ARGS: An array of pending outbound subscription maps

key and value passed: The array will be filtered according to if the value at the key map attribute matches the value parameter

Parameters

Returns 

An array of outbound subscriptions. Possibly filtered.

pendingOutboundSubs = subscription:outbound()
/*
[
  {
    "Id": "cjrcv6tzl003g04rqlri0vqqw",
    "wellKnown_Tx": "HLy15B5xmws3avFpbS6beZ",
    "Rx": "AgZKbAHa47RYytKBAK31DF"
  }
]
*/

inbound

Returns the pending inbound subscription requests in an array

Returns

NO ARGS: An array of pending inbound subscription maps

key and value passed: The array will be filtered according to if the value at the key map attribute matches the value parameter

Parameters

Returns 

An array of inbound subscriptions. Possibly filtered.

pendingInboundSubs = subscription:inbound()
/*
[
  {
    "Id": "cjrcv6tzl003g04rqlri0vqqw", // The ID of the subscription
    "Tx": "AgZKbAHa47RYytKBAK31DF", // The channel to transmit events to on the other pico
    "Rx": "GTh2ZdE6tpWqQQQ3jHL1Dv", // The channel to receive events on for this pico
    "Tx_verify_key": "6H4w3JV3VktkV1hAkYXFbba1d1dYSTQfZ7PgdcBtrnGs", // signing key for sending signed messages
    "Tx_public_key": "GaTt4ChY1Fre39szbRGLVE4waVGJ3qqo1NQWg1nutugN" // public key for encrypting messages
  },
  {
    "Id": "cjrcvvq0e004104rq8obn20e0",
    "Tx": "X9o6b6dhGevQGNZCyg3AEx",
    "Rx": "Rj6ACgfzVhU6PNgbjHhNTz",
    "Tx_verify_key": "HS9rJbPdQjsgY4q18eVxv7QPQkJcTdN14aiorDHeEEhu",
    "Tx_public_key": "DxbYXzoj9ozkHUz2NtWm7aXgGUSuRR8BbQTZeT1aKAni"
  }
]
*/

wellKnown_Rx

Returns the channel map of the WellKnown_Rx for this pico

Returns

A map in the channel map structure, describing the channel for the WellKnown_Rx on this pico.

wellKnownChannel = subscription:wellKnown_Rx()
/*
{
  "id": "Cv1x3ufMEemxoYwFZ41WKb",
  "pico_id": "cjrb850we001cnkrq4in3pd37",
  "name": "wellKnown_Rx",
  "type": "Tx_Rx",
  "policy_id": "cjrcuog6b001l04rqfxz9lnei",
  "sovrin": {
    "did": "Cv1x3ufMEdmxoYwFZ41WKb",
    "verifyKey": "7VddbRHoDdxGBvqL6iYMi83T3QoKxxCLjNijMFawXbcV",
    "encryptionPublicKey": "BX1eddj7carru3KEd4CrAwmxG6S7A16hbpDCSoUXaGdw"
  }
}
*/

autoAcceptConfig

Returns the current autoAccept configuration for subscriptions. This map represents a configuration that you can set for auto accepting subscription requests with the added attribute value.

Returns

A map with the auto accept configuration of the pico's subscriptions ruleset.

subscriptionConfig = subscription:autoAcceptConfig()
/*
{
  "password": [
    "1234"
  ]
}
*/

Received Events

subscription

wrangler:subscription

When a pico receives or raises this event, it initiates the subscription protocol. Through the protocol, a wrangler:inbound_pending_subscription_added event will be raised within the other pico. A wrangler:outbound_pending_subscription_added event will be raised in the pico which received the initial wrangler:subscription event.

Attributes

Directives Returned

Will return empty directives. 

Corresponding Raised Events:

• Wrangler Full API#inbound_pending_subscription_added in the other pico

pending_subscription_approval

wrangler:pending_subscription_approval

Should be raised by the developer as a response to wrangler:inbound_pending_subscription_added. The pico which received a wrangler:inbound_pending_subscription_added event should review the attributes and raise the wrangler:pending_subscription_approval event if the pico accepts the incoming subscription. See the example code for how this can be easily signaled using the "attributes" keyword.

Attributes

Must provide any one of the attributes.

Directives Returned

Will return empty directives. 

An example of a rule that raises wrangler:pending_subscription_approval to accept an inbound subscription request.

/*
  rule auto_accept {
    select when wrangler inbound_pending_subscription_added
    pre {
      attributes = event:attrs.klog("inbound subscription attributes: ")
    }
    always {
      raise wrangler event "pending_subscription_approval"
        attributes attributes);
    }
*/

Corresponding Raised Events:

• Wrangler Full API#subscription_added in the other pico

send_event_on_subs

wrangler:send_event_on_subs

This event can be used to send an arbitrary event to one or many subscriptions. Given a subscription ID, it will send the event on that subscription. Given a Tx_role or Rx_role it will send an event to all subscriptions that have that Tx_role or Rx_role recorded.

Attributes

Must provide any one of the attributes.

Directives Returned

Will return empty directives. 

outbound_cancellation

wrangler:outbound_cancellation

Raise this within the pico that initiated the subscription creation exchange to cancel an outbound subscription request.

Attributes

Must provide any one of the attributes.

Directives Returned

Will return empty directives. 

Corresponding Raised Events:

• Wrangler Full API#outbound_subscription_cancelled
• Wrangler Full API#inbound_subscription_cancelled in the other pico

inbound_rejection

wrangler:inbound_rejection

Raise this within the pico that has received an inbound_pending_subscription_added event to cancel an an inbound subscription request.

Attributes

Must provide any one of the attributes.

Directives Returned

Will return empty directives. 

/*
  rule auto_deny {
    select when wrangler inbound_pending_subscription_added
    pre {
      attributes = event:attrs.klog("inbound subscription attributes: ")
    }
    always {
      raise wrangler event "inbound_rejection" 
        attributes event:attrs);
    }
*/

Corresponding Raised Events:

• Wrangler Full API#outbound_subscription_cancelled in the other pico
• Wrangler Full API#inbound_subscription_cancelled

subscription_cancellation

wrangler:subscription_cancellation

Raise this within a pico to cancel its subscription to another pico. 

Attributes

Provide any one of the attributes. 

If none of these attributes are given it will try to cancel the subscription associated with the channel the event was received on.

Directives Returned

Will return empty directives. 

/*
{
  "directives": []
}
*/

Corresponding Raised Events:

• Wrangler Full API#subscription_removed in both picos in the subscription relationship

Raised Events

subscription_added

wrangler:subscription:added

Fired within a pico whenever a new subscription has been added.

Attributes Added

The event attributes look like the following structure:

{
  "Id": "cjrl7rbbh005kksrqle152lji",
  "Tx": "DWkbD6URr3JuQWtq9FjzQH",
  "Tx_public_key": "DWbUgvRLhtrp6Zv4CbuMLCZnV9qShsB2bXfW4E5EbEYh",
  "Tx_verify_key": "7pZSMfshJjPhjDbspNgko2KkmfET3pgW733UAZkbKxSX",
  "_headers": { // These were appended from the HTTP communication between the two picos
    "content-type": "application/json",
    "host": "10.37.155.96:8080",
    "content-length": "585",
    "connection": "close"
  },
  "bus": {
    "Tx_host": "http://localhost:8080",
    "Id": "cjrl7rbbh005kksrqle152lji",
    "Rx": "UGRZHTfz5P9AXFb4WXkJF8",
    "Tx": "DWkbD6URr3JuQWtq9FjzQH",
    "Tx_verify_key": "7pZSMfshJjPhjDbspNgko2KkmfET3pgW733UAZkbKxSX",
    "Tx_public_key": "DWbUgvRLhtrp6Zv4CbuMLCZnV9qShsB2bXfW4E5EbEYh"
  }
}

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

rule get_peer_ids {
  select when wrangler subscription_added
  foreach subscription:established() setting (subscription)
  pre {
  }
  if (subscription{"Rx_role"}.klog("RX_ROLE: ") == "node") then
    event:send({
      "eci":subscription{"Tx"},
      "eid":"getting_info",
      "domain":"gossip",
      "type":"get_peer_id",
      "attrs":{
        "channel":subscription{"Tx"}
    }
  }, subscription{"Tx_host"}.defaultsTo(meta:host))
  fired {
    ent:subscription_result := event:attrs
  }
}

subscription_removed

wrangler:subscription_removed

Raised within the pico when a subscription has been removed.

Attributes Added

The event attributes look like the following structure:

{
  "Id": "cjrmo1pox002fvkrq36wbu7tk",
  "_headers": { // These were appended from the HTTP communication between the two picos
    "host": "localhost:8080",
    "connection": "keep-alive",
    "accept": "application/json, text/javascript, */*; q=0.01",
    "x-requested-with": "XMLHttpRequest",
    "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.81 Safari/537.36",
    "referer": "http://localhost:8080/",
    "accept-encoding": "gzip, deflate, br",
    "accept-language": "en-US,en;q=0.9"
  },
  "bus": {
    "Rx_role": "10",
    "Tx_role": "2",
    "Tx_host": "http://10.37.184.244:8080",
    "Id": "cjrmo1pox002fvkrq36wbu7tk",
    "Tx": "BcAgD4DVKfmhsxKPhi55dz",
    "Rx": "QWEuQaqCP7pdeLR4riPfEs",
    "Tx_verify_key": "6nHdu1Ygf8GZaS2DnFHqjjv5psVvJsPnQfeBV8A6Tqxk",
    "Tx_public_key": "CmLjRfsPrxARqQCUWshDxLosQudvfDBV4iSReHU8qQyr"
  }
}

An example of a rule selecting on a subscription removal.

rule remove_node_entry_after_sub_removal {
  select when wrangler subscription_removed
  pre {
	sub_id = event:attr("Id")
  }
  if (subscription{"Rx_role"}.klog("RX_ROLE: ") == "node") then
  noop()
  fired {
    ent:node_list := ent:node_list.delete([sub_id]);
  }
}

inbound_pending_subscription_added

wrangler:inbound_pending_subscription_added

This event is raised within the pico when a new inbound subscription request has been sent to the pico, and the developer needs to approve it. Typical use is to use the event attributes to determine whether the subscription is one you are expecting, and then raising wrangler:pending_subscription_approval if they are. 

Attributes Added

The event attributes look like the following structure, depending on the arguments given to wrangler:subscription on the other pico:

{
  "Id": "cjrmog0gd0030vkrqu0eeqax5",
  "Rx": "AQM7aFvb2Yp33pjypNcBhM",
  "Rx_role": "10",
  "Tx": "3naK2ZUH6a4vaWzLvU5cfn",
  "Tx_host": "http://10.37.184.244:8080",
  "Tx_public_key": "6G1fmv3KQd7hXpokesKFKrHE8dJJYpiew4eEAZwWbEKa",
  "Tx_role": "2",
  "Tx_verify_key": "2X4gcL8FGA4qrCniyBmYnfdKN5fitDu843mJtFFR5kBi",
  "_headers": { // These were appended from the HTTP communication between the two picos
    "content-type": "application/json",
    "host": "localhost:8080",
    "content-length": "981",
    "connection": "close"
  },
  "channel_name": "cool",
  "channel_type": "cool sub channel",
  "name": "cool",
  "password": "",
  "public_key": "6G1fmv3KQd7hXpokesKFKrHE8dJJYpiew4eEAZwWbEKa",
  "verify_key": "2X4gcL8FGA4qrCniyBmYnfdKN5fitDu843mJtFFR5kBi",
  "wellKnown_Tx": "5qMBoPpNh2fBnfG7JNk5yD"
}

An example of a rule accepting new subscription requests by selecting on wrangler:inbound_pending_subscription_added:

rule auto_accept {
  select when wrangler inbound_pending_subscription_added
  pre {
  }
  always {
    raise wrangler event "pending_subscription_approval"
      attributes event:attrs
  }
}

outbound_pending_subscription_added

wrangler:outbound_pending_subscription_added

This is raised within the pico that has just initiated a subscription request using wrangler:subscription. This allows manipulation of the outgoing request, including cancelling it if necessary.

Attributes Added

These are currently identical to the attributes passed to wrangler:subscription.

The event attributes look like the following structure, depending on the arguments given to wrangler:subscription:

{
  "Rx_role": "2",
  "Tx_host": "http://localhost:8080",
  "Tx_role": "10",
  "_headers": { // These were appended from the HTTP communication between the two picos
    "host": "localhost:8080",
    "connection": "keep-alive",
    "accept": "application/json, text/javascript, */*; q=0.01",
    "x-requested-with": "XMLHttpRequest",
    "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.81 Safari/537.36",
    "referer": "http://localhost:8080/",
    "accept-encoding": "gzip, deflate, br",
    "accept-language": "en-US,en;q=0.9",
    "if-none-match": "W/\"11-cFrA0CClfKTQMohnyK0tNW5C4dU\""
  },
  "channel_type": "cool sub channel",
  "name": "cool",
  "password": "",
  "wellKnown_Tx": "5qMBoPpNh2fBnfG7JNk5yD"
}

An example of a rule selecting on wrangler:oubound_pending_subscription_added to prepare for the subscription.

rule auto_accept {
  select when wrangler outbound_pending_subscription_added
  pre {
	other_pico_host = event:attr{"Tx_host"}
  }
  if other_pico_host then
    noop()
  fired {
    ent:attempted_hosts := ent:attempted_hosts.append(other_pico_host);
  }
}

outbound_subscription_cancelled

wrangler:outbound_subscription_cancelled

Raised when an outbound subscription has been cancelled through the use of wrangler:outbound_cancellation or the inbound request rejected on the other pico using wrangler:inbound_rejection.

Attributes Added

An example of a rule selecting on wrangler:outbound_subscription_cancelled:

rule sub_request_cancelled_or_rejected {
  select when wrangler outbound_subscription_cancelled
  always {
    ent:sub := event:attrs
  }
}

The structure of the bus when the oubound subscription has been cancelled:

{
  "bus": {
    "Id": "cjs51fu2a006kksrq7av62ttd", // the ID of the cancelled subscription request
    "wellKnown_Tx": "5qMBoPpNh2fBnfG7JNk5yD", // The well known of the other pico
    "Rx": "AiPhhS6Tkz7QqmqbRZujEM" // The receiving channel that no longer exists that was created for this pico for the subscription
  }
}

inbound_subscription_cancelled

wrangler:inbound_subscription_cancelled

Raised when an inbound subscription has been cancelled through the use of wrangler:inbound_rejection or the outbound request was rejected on the other pico using wrangler:outbound_cancellation.

Attributes Added

An example of a rule selecting on wrangler:inbound_subscription_cancelled:

rule inbound_sub_req_cancelled {
  select when wrangler inbound_subscription_cancelled
  always {
    ent:sub := event:attrs
  }
}

The structure of the bus when the inbound subscription has been cancelled:

{
  "bus": {
    "Id": "cjs51fu2a006kksrq7av62ttd", // the ID of the cancelled subscription request
    "Tx": "AiPhhS6Tkz7QqmqbRZujEM", // The transmitting channel that no longer exists that was created for the other pico for the subscription
    "Rx": "8UVQvmstjx7C35D3sKHRy6", // The receiving channel that no longer exists that was created for this pico for the subscription
    "Tx_verify_key": "6J4uxarQkQGc43KZkUhmHwowPAc3Hb5oezLnyoJgvM5k", // The signing key that had been created to allow signing of future subscription events
    "Tx_public_key": "9xvw5iYsPjGirBofxAniXU8w1bZ4CfT6pfmcigZpzGkQ" // The encryption key that had been created to allow encrypted communication of future subscription events
  }
}​_

Collections

Pages

• Wrangler Collections

Functions

members

Returns all of the established subscriptions that belong to the collection

Returns

An array of subscription maps

Parameters

None

Returns 

An array of established subscriptions.

membersArray = collection:members()
[
  {
    "Rx_role": "collection",
    "Tx_role": "member",
    "Tx_host": "http://10.37.94.198:8080",
    "Id": "cjyf4v8hd00vuokbz0oz2eb1z",
    "Tx": "YVreELgbGjjFhQYqgGcRKm",
    "Rx": "VQDgK9YF1FPvj7fkwgt94H",
    "Tx_verify_key": "JAhWwk19WqBysronQPD6zbbncLDo7UHT22oaKcZ2dheB",
    "Tx_public_key": "5iArABfAiG8u4SNBhaCzcwtXpauLULfhMkJfHWTkMhe2"
  },
  {
    "Rx_role": "collection",
    "Tx_role": "member",
    "Tx_host": "http://10.5.164.58:8080",
    "Id": "cjygcdpqs0010q3bz05gc68gb",
    "Tx": "RrS9tyHwt8mBuTe7e33BMY",
    "Rx": "CuGaocn4tR2Q32tgBvmBjt",
    "Tx_verify_key": "EYdZVZhZ5cWwWtwCLuUpAnYXjXgFjRDphg1fCxNJVvBc",
    "Tx_public_key": "74Hmo86S5ifVtSyJaCr4wBy6j4sFeJiHSFLaGSUEV5WF"
  }
]
*/

Received Events

send_event_to_collection_members

wrangler:send_event_to_collection_members

This event relies on the internal Rx_role of the collection to send an event to all the members in the collection across the subscription from the collection pico to the members.

Attributes

Directives Returned

Will return empty directives. 

new_role_names

collection:new_role_names

Can be used to create a different Rx_role - Tx_role pairing for the collection. By default the collection pico's Rx_role is "collection" and member picos have "member" roles. It will only be successful if the collection has no members.

Attributes

Directives Returned

Will return empty directives. 

Datastore

Pages

• Datastore

Functions

getItem

Returns the value mapped to the key under the given domain.

Returns

A KRL value. Can be NULL.

Parameters

Returns 

The value located for the key-value combination under that domain. Can be null if the value does not exist.

item = getItem(meta:rid, numUsers)
/*
3723
*/

allDomainData

Returns all the key-value mappings for a certain datastore domain as a KRL map.

Parameters

viewStore

Returns the entire datastore as a KRL map.

Parameters

None

Returns 

A KRL map representing the entire datastore. Domains are mapped to maps of key-value pairs.

Received Events

ds_update

wrangler:ds_update

This event is used to update the datastore asynchronously.

Attributes

Directives Returned

Will return empty directives.

Corresponding Raised Events

• wrangler:ds_updated 

ds_clear_data

wrangler:ds_clear_data

Used to clear a value in the datastore. Has the same effect as passing nothing to the value attribute in wrangler:ds_update.

Attributes

Directives Returned

Will return empty directives.

ds_assign_map_to_domain

wrangler:ds_assign_map_to_domain

This event is used to update all data under a given domain. It takes a KRL map of key-value pairings to use as the new data for that domain. wrangler:ds_domain_updated is raised as a response. This event should be used sparingly, such as for migration purposes.

Corresponding Raised Events

• wrangler:ds_domain_updated

Raised Events

ds_updated

wrangler:ds_updated

Raised as a response to wrangler:ds_update. It informs the listener of the new value in the datastore for the given domain and key.

ds_updated

wrangler:ds_domain_updated

Raised as a response to wrangler:ds_assign_map_to_domain. It informs the listener that all values for a domain have been updated with an entirely new map.

Prototypes

Pages

• Prototypes

Received Events

prototype_instance_requested

wrangler:prototype_instance_requested

Attributes

Any extra attributes provided are propagated to the wrangler:prototype_initialized event.

Here is an example of raising this event:

rule examplePrototype {
	select when example prototype
	pre {
		prototype = {
			"new_picos": [{
				"name": "examplePico",
				"rids": []
			}],
			"subscriptions": []
		}
	}
	always {
		raise wrangler event "prototype_instance_requested"
			attributes { "prototype": prototype }
	}
}

Directives Returned

No directives are returned.

Raised Events

prototype_initialized

wrangler:prototype_initialized

This event is raised after all of the new picos and subscriptions are created in the system. Any subscriptions defined via a tuple are guaranteed to be established, but subscriptions defined via an external event (a map) are not guaranteed to be established because the prototypes ruleset has no guarantee of authority over the accepting pico.

Here is what the event attributes of this raised event will look like:

{
	"__prototypeCorrelationID": <the event correlation ID>,
	//all the other original attributes passed into the wrangler:prototype_instance_requested event.
}