Catenis Flow Guide

Check Effective Permission Right Node

The “Check Effective Permission Right” node works across a pair of devices; the subject device and the device attempting to execute the permissioned event with the subject device.  It runs through the permission hierarchy evaluating at each level and returns whether or not the device has “allow” or “deny” permission to interact with your subject device for the requested permissioned event. This is an easy way to evaluate permissions set on the subject device.

How permissions are evaluated

Setting permission rights at a higher level will affect how all virtual devices within the context of that level and levels below it can or cannot interact with the subject device. For example, permissions set at the node level will affect all devices across all clients within that node. However, the system evaluates permissions giving precedent to  the more granular virtual device levels over the very broad system level. The system first looks to see if a device is allowed or denied permission for a premissoned event. If there are no permissions set then it evaluates the next level which is the Client level, then the Catenis node level, and finally the System level. Keep in mind that within this hierarchy  it is possible to set what seems to be (yet are not) conflicting permissions. This is because permissions that are set at a more granular level will always override what is set at a higher level

Let’s review an example: You may set the “receive-asset-from” permission event for virtual device A to “deny” for all devices at the Catenis node level. This means virtual device A will not be able to receive any assets from any device that is part of that Catenis node.  However, if you had previously set the same “receive-asset-from” permission event for virtual device B at the Virtual Device Level to “allow”, then device A will be allowed to receive assets from device B even though device B is part of the same Catenis node you recently denied access to all devices. Always review granular permissions for each event before setting permissions broadly. If ever in doubt use the “check effective permission right” node using the subject device to connect and supply the device ID of the device that is attempting to execute a permission event with the subject device.

Permission Rights Levels

All rights across permission events can be set at four levels; permission events can be set to either “allow”, “deny” or once set they can be unset or cleared. The System Level is unique because permissions can only be toggled from “allow” to “deny” or vice versa. The permission at this level  cannot be cleared. Setting permission rights at a higher level will affect how all virtual devices within the context of that level and levels below it can or cannot interact with the subject device. For example, permissions set at the node level will affect all devices across all clients within that node if there are not other, more granular permissions set. 

  1. System Level: controls permissions rights across the entire Catenis network where the default permission rights are defined.
  2. Catenis Node Level: controls the permission rights for all devices that belong to all clients defined for that Catenis node. Catenis nodes are computers referred to as either “hubs” or “gateways”.  Each hub or gateway has a specific index number. If you are using our cloud implementation the index number is always 0 .
  3. Client Level: controls the permission rights for all devices that belong to this client. Clients are Catenis system entities within a Catenis node.  A hub or gateway for instance may have one or more clients.
  4. Virtual Device Level: controls the permission rights for specific virtual device.
Image of the Check Effective Permission Right Node

Node Properties Panel Field Description

Node property configuration slide-out panel (this panel is accessed by double-clicking on the node).

2020-07-27_21-18-52
Properties configuration Panel of the Check Effective Permissions Right Node

Node-RED Specific Fields

  1. Name Field:  Add a descriptive name of your choice that will help differentiate this node from others of the same type on the Node-RED workspace (not required).
  2. Connection Field: This drop-down selection is required.  Set a previously configured Catenis connection (virtual device). If you need to configure a new virtual device click the pencil button to the right of the field and follow the direction on setting up a new virtual device that can be found here.

Catenis Flow Setting Fields

  1. Event – from the dropdown list select the permission event for which you wish to view how rights are set (Required). Options include:
    1. receive-notify-new-msg: Receive notification of new message from a device
    2. receive-notify-msg-read: Receive notification of message read by a device
    3. receive-notify-asset-of: Receive notification of asset received for assets issued by a device
    4. receive-notify-asset-from: Receive notification of asset received from a device
    5. receive-notify-confirm-asset-of: Receive notification of confirmation of pending asset issued by a device
    6. receive-notify-confirm-asset-from: Receive notification of confirmation of pending asset transferred by a device
    7. send-read-msg-confirm: Send read message confirmation to a device
    8. receive-msg: Receive message from a device
    9. disclose-main-props: Disclose device’s main properties (name, product unique ID) to a device
    10. disclose-identity-info: Disclose device’s basic identification information to a device
    11. receive-asset-of: Receive an amount of an asset issued by a device
    12. receive-asset-from: Receive an amount of an asset from a device

How to use

  1. Drag and drop this node from the Catenis Flow pallet area to the Node-RED workspace. Double click it to display its properties slide out panel.
  2. On the “Device” drop-down field of the properties slide out panel choose the Catenis virtual device you previously configured. The virtual device is a configuration node containing the Catenis Virtual device information (device ID and API Secret key). This should be the controlling device This should be the controlling device (the subject device). The device for which you are checking how permissions have been set on it.
  3. Click on the “🔔 Event” drop-down menu and then select the event for which you wish to receive event permissions rights for. 
  4. Wire this node to a debug node if you wish to see the output of the node printed on the debug sidebar. Otherwise, the output from this node can be passed into another node on this flow. 
  5. Next, drag and drop an “inject” node to the Node-RED workspace.
  6. Wire the “inject” node to the  “Check Effective Permissions Right” node, then double click the “inject” node to open its properties slide out panel. 
  7. Alter the information in the “inject” node’s properties slide out panel by selecting the drop-down “Payload” field and choose the “String” Type. Enter the Permission event type in the blank field (i.e.  “receive-msg” or “Disclose-main-props”). Click the OK button.
  8. Click the red Deploy button on the upper right hand side of the Node-RED dashboard to deploy this flow.
  9. Now let’s test the flow: Click the button on the left attached to the “inject” node to send the input from the “inject” node to the flow.
  10. The debug sidebar should display the returned JSON object containing the API call results to the right side of the workspace. Teh result will display what permissions are set for that given event.

How to use Interactively

  1. Drag and drop this node from the Catenis Flow pallet area to the Node-RED workspace. Double click it to display its properties slide out panel.
  2. On the “Device” drop-down field of the properties slide out panel choose the Catenis virtual device you previously configured. The virtual device is a configuration node containing the Catenis Virtual device information (device ID and API Secret key). This should be the controlling device (the subject device) you are checking permissions on.
  3. Click on the “🔔 Event” drop-down menu and then select the event for which you wish to receive event permissions rights for. 
  4. Wire this node to a debug node.
  5. Click the red “Deploy” button on the upper right hand side of the Node-RED dashboard to deploy this flow. 
  6. To test the flow: click the square gray box to the left of the “list permission events” node. A JSON object containing all possible permission events should now be printed onto the debug sidebar.

Example string that can be passed to this node


disclose-main-props

Inputs injected into this node via a String containing alternate node properties will override the properties set on this node's slide out properties panel.

Example Flow - Import Into Node-Red to Get Started


[{"id":"ff46a46.56e2f58","type":"tab","label":"Flow 5","disabled":false,"info":""},{"id":"91e72a4.400d5d8","type":"check effective permission right","z":"ff46a46.56e2f58","name":"","device":"a8a49fbf.602ef","eventName":"receive-notify-new-msg","deviceId":"","isProdUniqueId":false,"x":570,"y":180,"wires":[["48b616c5.abb368"]]},{"id":"48b616c5.abb368","type":"debug","z":"ff46a46.56e2f58","name":"","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"false","x":838,"y":180,"wires":[]},{"id":"b35c92e.d81597","type":"inject","z":"ff46a46.56e2f58","name":"","topic":"","payload":"{\"eventName\":\"receive-asset-from\",\"deviceId\":\"Enter Device ID here\",\"isProdUniqueId\":false}","payloadType":"json","repeat":"","crontab":"","once":false,"onceDelay":0.1,"x":90,"y":180,"wires":[["91e72a4.400d5d8"]]},{"id":"d3b58c24.862cd","type":"comment","z":"ff46a46.56e2f58","name":"Set virtual device for this Catenis node","info":"All Catenis nodes require that you set the proper virtual device on its slideout property panel on the device field.\n\nNot setting the device properly will result in a \"TypeError: Cannot read property 'ctnApiClient' of null\" ","x":590,"y":140,"wires":[]},{"id":"433b4927.b32148","type":"comment","z":"ff46a46.56e2f58","name":"Set the device ID and desired event in this JSON object","info":"","x":205,"y":140,"wires":[]},{"id":"a8a49fbf.602ef","type":"catenis device","z":"","name":"Demo Device","deviceId":"dyRqBbvzozxGk6zuZavZ","apiAccessSecret":"fcde160c33ffb990b732d55ff823f580fcc697bc20e2f3dba467d3a4c25fe89069f771bde70bdcf0e079a6adb2e83e3deaf2c04ba7f84758a054f28646366981","host":"","environment":"sandbox","secure":true,"version":"","useCompression":true,"compressThreshold":""}]

Note: After importing this flow you will need to set the Catenis Flow node(s) in this flow to use a previously configured virtual devices. Instructions on how to set up your virtual device on Node-RED can be found here: https://blockchainofthings.com/docs/configure-your-first-virtual-device-on-catenis-flow/

Related Articles

CompanyElement_SM_LightBackgrounds
How can we make things Better for you?
  • Accepted file types: jpg, gif, png, pdf.
  • This field is for validation purposes and should be left unchanged.