Catenis Flow Guide

Retrieve Permission Rights Node

The “Retrieve Permission Rights” node retrieves the permission rights set for a specific permission event. Permission events are specific actions that can be set to either “allow” or “deny” at four different levels.  All permissions events are set on the device you want to allow or deny interactions with. This device is referred to as being the subject device or controlling device (the device that controls what can or cannot be done to it) and sets it’s permission as to which other virtual devices can or cannot interact with it.   

All rights across permission events can be set at 4 different levels to either “allow” or “deny”. 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.

  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.

Note: Ensure you understand how permissions work and how the permissions hierarchy gets evaluated. You can learn how permissions get evaluated by reading more abut permissions here: https://blockchainofthings.com/docs/permissioning-rights-model/

Image of the Retrieve Permission Rights 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 for the Retrieve Permission Rights 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 (the device for which you want to receive permission event rights for).
  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  “Retrieve Permissions Rights” 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.

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).
  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 “Retrieve permission events” node. A JSON object containing the permission rights set at each level should now be printed onto the debug sidebar. Please read how permissions are evaluated here.

Example string that can be passed to this node


disclose-main-props

Note: Inputs injected into this node via a JSON object 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":"fdb9b6cd.bbcc98","type":"retrieve permission rights","z":"a0a74096.3535e","name":"","device":"","eventName":"receive-asset-of","x":550,"y":160,"wires":[["95753991.424db8"]]},{"id":"95753991.424db8","type":"debug","z":"a0a74096.3535e","name":"","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"payload","targetType":"msg","x":790,"y":160,"wires":[]},{"id":"9a22f9e6.4262f8","type":"inject","z":"a0a74096.3535e","name":"inject","topic":"","payload":"receive-notify-new-msg","payloadType":"str","repeat":"","crontab":"","once":false,"onceDelay":0.1,"x":290,"y":160,"wires":[["fdb9b6cd.bbcc98"]]},{"id":"a0bf4560.3045f8","type":"comment","z":"a0a74096.3535e","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":550,"y":100,"wires":[]},{"id":"8a1f2c94.4ee11","type":"comment","z":"a0a74096.3535e","name":"Double click for instructions","info":"In the Payload field select the string type and enter one of the permission events. \n\n1.receive-notify-new-msg: Receive notification of new message from a device\n2.receive-notify-msg-read: Receive notification of message read by a device\n3.receive-notify-asset-of: Receive notification of asset received for assets issued by a device\n4.receive-notify-asset-from: Receive notification of asset received from a device\n5.receive-notify-confirm-asset-of: Receive notification of confirmation of pending asset issued by a device\n6.receive-notify-confirm-asset-from: Receive notification of confirmation of pending asset transferred by a device\n7.send-read-msg-confirm: Send read message confirmation to a device\n8.receive-msg: Receive message from a device\n9.disclose-main-props: Disclose device's main properties (name, product unique ID) to a device\n10.disclose-identity-info: Disclose device's basic identification information to a device\n11.receive-asset-of: Receive an amount of an asset issued by a device\n12.receive-asset-from: Receive an amount of an asset from a device\n\nNote: 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.\n\n","x":290,"y":200,"wires":[]}]

Note: After importing the sample flow you will need to set the “Retrieve permission events” node to your own previously configured virtual device. 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.