github.com/simpleiot/simpleiot@v0.18.3/docs/user/notifications.md (about)

     1  # Notifications
     2  
     3  Notifications are sent to users when a [rule](rules.md) goes from inactive to
     4  active and contains a notification action. This notification travels up the node
     5  graph. At each parent node, users potentially listen for notifications. If a
     6  user is found, then a message is generated. This message likewise travels up the
     7  node graph. At each parent node, messaging service nodes potentially listen for
     8  messages and then process the message. Each node in Simple IoT that generates
     9  information is not concerned with the recipient of the information or how the
    10  information is used. This decoupling is the essence of a messaging based system
    11  (we use [NATS](https://nats.io/)) and is very flexible and powerful. Because
    12  nodes can be aliased (mirrored) to different places, this gives us a lot of
    13  flexibility in how points are processed. The node tree also gives us a very
    14  visual view of how things are connected as well as an easy way to expand or
    15  narrow scope based on high in the hierarchy a node is placed.
    16  
    17  ## Example
    18  
    19  There is hierarchy of nodes in this example system:
    20  
    21  - Company XYZ
    22    - Twilio SMS
    23    - Plant A
    24      - Joe
    25      - Motor overload Rule
    26      - Line #1
    27        - Motor Overload
    28    - Plant B
    29  
    30  The node hierarchy is used to manage scope and permissions. The general rule is
    31  that a node has access to (or applies to) its parent nodes, and all of its
    32  parents dependents. So in this example, Joe has access to everything in Plant A,
    33  and likewise gets any Plant A notifications. The Motor overload rule also
    34  applies to anything in Plant A. This allows us to write one rule that could
    35  apply to multiple lines. The Twilio SMS node processes any messages generated in
    36  Company XYZ including those generated in Plant A, Line #1, Plant B, etc. and can
    37  be considered a company wide resource.
    38  
    39  The process for generating a SMS notification to a user is as follows:
    40  
    41  1. **Line #1** contains a **Motor Overload** sensor. When this value changes, a
    42     point (blue) gets sent to its parent **Line #1** and then to **Plant A**.
    43     Although it is not shown below, the point also gets sent to the **Company
    44     XYZ** and root nodes. Points always are rebroadcast on every parent node back
    45     to the root.
    46  1. **Plant A** contains a rule (**Motor Overload**) that is then run on the
    47     point, which generates a notification (purple) that gets sent back up to its
    48     parent (**Plant A**).
    49  1. **Plant A** contains a user **Joe** so a notification + user generates a
    50     message (green), which gets sent back upstream to **Plant A** and then to
    51     **Company XYZ**.
    52  1. **Company XYZ** contains a messaging service (**Twilio SMS**), so the message
    53     gets processed by this service a SMS message gets sent to **Joe**.
    54  
    55  The Motor Overload sensor node only generates what it senses. The Motor Overload
    56  rule listens for points in Plant A (its parent) and processes those points. The
    57  Joe user node listens for points at the Plant A node (its parent) and processes
    58  any points that are relevant. The Twilio SMS node listens for point changes at
    59  the Company XYZ node and processes those points. Information only travels
    60  upstream (or up the node hierarchy).
    61  
    62  ![message process](images/msg-process.png)
    63  
    64  In this example, the admin user does not receive notifications from the Twilio
    65  SMS [messaging service](messaging.md). The reason is that the Twilio SMS node
    66  only listens for messages on its parent node. It does not have visibility into
    67  messages sent to the root node. With the node hierarchy, we can easily partition
    68  who gets notified. Additional group layers can be added if needed. No explicit
    69  binding is required between any of the nodes -- the location in the graph
    70  manages all that. The higher up you go, the more visibility and access a node
    71  has.