Skip to content
This repository was archived by the owner on May 22, 2026. It is now read-only.

Commit 9838f83

Browse files
dskarzhdskarzh
authored
[WIP] Rule node docs (#2282)
* New doc for 'message type switch' rule node * New doc for 'calculated fields' rule node * Correct description of 'calculated fields' search result * New doc for 'change owner' rule node * New doc for 'remove from group' rule node * New doc for 'create alarm' rule node * New doc for 'clear alarm' rule node * Update summary for 'create alarm' and 'clear alarm' rule nodes on index page * New doc for 'copy to view' node * New doc for 'assign to customer' node * Update description of 'assign to customer' and 'unassign from customer' rule nodes * New doc for 'unassign from customer' rule node * New doc for 'create relation' rule node * New doc for 'delay (deprecated)' rule node * Add summary paragraph for filter nodes; improve one-line summary of filter nodes * Add summary paragraph for enrichment nodes * Improve summaries for enrichment nodes * Improve search result previews for enrichment nodes * Add summary paragraph for transformation nodes * Improve summaries for transformation rule nodes * Add summaries for actions nodes * Make search result descriptions for filter nodes consistent with summaries * New doc for 'delete attributes' rule node * New doc for 'delete relation' rule node * Small correction for 'delete key-value pairs` search result description
1 parent 4b4601e commit 9838f83

73 files changed

Lines changed: 3063 additions & 505 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎_includes/docs/user-guide/rule-engine-2-0/nodes/action/add-to-group.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ The configuration allows you to specify how entities are added to groups and how
5252

5353
1. The node identifies the **owner** of the message originator entity (tenant or customer).
5454
2. It resolves any templates in the **Group name pattern** using values from the message data and metadata.
55-
3. The node searches for an existing entity group matching the resolved group name and entity type.
55+
3. The node searches for an existing entity group matching the resolved group name, entity type and owner of the originator.
5656
4. If **Remove from current groups** is enabled:
5757
- The node retrieves all entity groups that currently contain the originator entity
5858
- It removes the entity from all groups except the target group and the special "All" group

‎_includes/docs/user-guide/rule-engine-2-0/nodes/action/assign-to-customer.md‎

Lines changed: 227 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,238 @@
1-
<table style="width:250px;">
2-
<thead>
3-
<tr>
4-
<td style="text-align: center"><strong><em>Since TB Version 2.2</em></strong></td>
5-
</tr>
6-
</thead>
7-
</table>
1+
Assigns the message originator to a specified customer.
82

9-
![image](/images/user-guide/rule-engine-2-0/nodes/action-assign-to-customer-node.png)
3+
## Configuration
104

11-
Assign Message Originator Entity to [Customer](/docs/{{docsPrefix}}user-guide/ui/customers/).
5+
- **Customer title** - The name of the target customer. Supports templatization using `${metadataKey}` or `$[dataKey]` to substitute values from the message metadata or data.
6+
- **Create new customer if it doesn't exist** - When enabled, creates a new customer if no customer matching the title is found. When disabled, the processing fails if the target
7+
customer doesn't exist.
128

13-
Following Message Originator types are allowed: **Asset**, **Device**, **Entity View**, **Dashboard**.
9+
### JSON Schema
1410

15-
Finds target Customer by customer name pattern and then assign Originator Entity to this customer.
11+
```json
12+
{
13+
"$schema": "https://json-schema.org/draft/2020-12/schema",
14+
"title": "TbAssignToCustomerNodeConfiguration",
15+
"type": "object",
16+
"properties": {
17+
"customerNamePattern": {
18+
"type": "string",
19+
"description": "Target customer name, supports templatization"
20+
},
21+
"createCustomerIfNotExists": {
22+
"type": "boolean",
23+
"description": "Whether to create a new customer if the target doesn't exist"
24+
}
25+
},
26+
"required": [
27+
"customerNamePattern"
28+
],
29+
"additionalProperties": false
30+
}
31+
```
1632

17-
Will create new Customer if it doesn't exists and **Create new Customer if not exists** is set to **true**.
33+
## Message processing algorithm
1834

19-
Configuration:
35+
1. Resolves any templates in the **Customer title** using values from the message data and metadata.
36+
2. Searches for an existing customer with the resolved title within the tenant.
37+
3. If the customer doesn't exist and **Create new customer if it doesn't exist** is enabled:
38+
- Creates a new customer with the resolved title
39+
- Generates a `ENTITY_CREATED` lifecycle event for the newly created customer
40+
4. If the customer doesn't exist and creation is disabled, the processing fails.
41+
5. Assigns the originator to the target customer.
42+
6. If the entity is already assigned to the target customer, no change is made but the processing is still considered successful.
43+
7. On successful completion, the message is forwarded to the `Success` connection. If an error occurs, the message is routed to the `Failure` connection.
2044

21-
![image](/images/user-guide/rule-engine-2-0/nodes/action-assign-to-customer-node-configuration.png)
45+
## Output connections
2246

23-
- **Customer name pattern** - can be set direct customer name or pattern can be used, that will be resolved to the real customer name using Message metadata.
24-
- **Create new customer if not exists** - if checked will create new customer if it doesn't exist.
25-
- **Customers cache expiration time** - specifies maximum time interval is seconds allowed to store found customers records. 0 value means that records will never expire.
47+
- `Success`
48+
- The entity was successfully assigned to the customer or the entity was already assigned to the target customer.
49+
- `Failure`
50+
- An error occurred during processing, such as the target customer not existing when creation is disabled.
2651

27-
Message will be routed via **Failure** chain in the following cases:
52+
## Examples
2853

29-
- When Originator entity type is not supported.
30-
- Target customer doesn't exist and **Create customer if not exists** is unchecked.
54+
### Example 1 — Assigning to existing customer
3155

32-
In other cases Message will be routed via **Success** chain.
56+
**Incoming message**
57+
58+
Originator: `DEVICE`.
59+
60+
**Node configuration**
61+
62+
```json
63+
{
64+
"customerNamePattern": "My Customer",
65+
"createCustomerIfNotExists": false
66+
}
67+
```
68+
69+
**State of the system**
70+
71+
- A customer named "My Customer" exists under the tenant.
72+
- Originator device is not assigned to any customer.
73+
74+
**Outgoing message**
75+
76+
The outgoing message is identical to the incoming one. Routed via the `Success` connection.
77+
78+
**Result**
79+
80+
The device is assigned to "My Customer".
81+
82+
### Example 2 — Using pattern for customer name
83+
84+
**Incoming message**
85+
86+
Data:
87+
88+
```json
89+
{
90+
"region": "North"
91+
}
92+
```
93+
94+
Metadata:
95+
96+
```json
97+
{
98+
"customerType": "Premium"
99+
}
100+
```
101+
102+
Originator: `ASSET`.
103+
104+
**Node configuration**
105+
106+
```json
107+
{
108+
"customerNamePattern": "${customerType} - $[region] Region",
109+
"createCustomerIfNotExists": false
110+
}
111+
```
112+
113+
**State of the system**
114+
115+
- A customer named "Premium - North Region" exists under the tenant.
116+
- Originator asset is not assigned to any customer.
117+
118+
**Outgoing message**
119+
120+
The outgoing message is identical to the incoming one. Routed via the `Success` connection.
121+
122+
**Result**
123+
124+
The pattern `${customerType} - $[region] Region` is resolved by substituting values from metadata and data, resulting in "Premium - North Region". The asset is assigned to this
125+
customer.
126+
127+
### Example 3 — Creating customer if it doesn't exist
128+
129+
**Incoming message**
130+
131+
Originator: `DEVICE`.
132+
133+
**Node configuration**
134+
135+
```json
136+
{
137+
"customerNamePattern": "New Customer",
138+
"createCustomerIfNotExists": true
139+
}
140+
```
141+
142+
**State of the system**
143+
144+
- No customer named "New Customer" exists.
145+
- Originator device is not assigned to any customer.
146+
147+
**Outgoing message**
148+
149+
The outgoing message is identical to the incoming one. Routed via the `Success` connection.
150+
151+
**Result**
152+
153+
Since the customer "New Customer" doesn't exist and `createCustomerIfNotExists` is true, a new customer is created at the tenant level with the title "New Customer". The device is
154+
then assigned to this newly created customer. A `ENTITY_CREATED` lifecycle event for the newly created customer is generated.
155+
156+
### Example 4 — Entity already assigned to target customer
157+
158+
**Incoming message**
159+
160+
Originator: `ASSET`.
161+
162+
**Node configuration**
163+
164+
```json
165+
{
166+
"customerNamePattern": "Target Customer",
167+
"createCustomerIfNotExists": false
168+
}
169+
```
170+
171+
**State of the system**
172+
173+
- "Target Customer" exists under the tenant.
174+
- Originator asset is already assigned to "Target Customer".
175+
176+
**Outgoing message**
177+
178+
The outgoing message is identical to the incoming one. Routed via the `Success` connection.
179+
180+
**Result**
181+
182+
Since the asset is already assigned to "Target Customer", no assignment change is performed, but the processing is considered successful.
183+
184+
### Example 5 — Customer doesn't exist and creation disabled
185+
186+
**Incoming message**
187+
188+
Originator: `DEVICE`.
189+
190+
**Node configuration**
191+
192+
```json
193+
{
194+
"customerNamePattern": "Non-existent Customer",
195+
"createCustomerIfNotExists": false
196+
}
197+
```
198+
199+
**State of the system**
200+
201+
- No customer named "Non-existent Customer" exists.
202+
- Originator device is not assigned to any customer.
203+
204+
**Outgoing message**
205+
206+
The outgoing message is identical to the incoming one. Routed via the `Failure` connection.
207+
208+
**Result**
209+
210+
The processing fails with an error because the target customer doesn't exist and `createCustomerIfNotExists` is false.
211+
212+
### Example 6 — Reassigning from one customer to another
213+
214+
**Incoming message**
215+
216+
Originator: `ENTITY_VIEW`.
217+
218+
**Node configuration**
219+
220+
```json
221+
{
222+
"customerNamePattern": "New Customer",
223+
"createCustomerIfNotExists": false
224+
}
225+
```
226+
227+
**State of the system**
228+
229+
- "Old Customer" and "New Customer" both exist under the tenant.
230+
- Originator entity view is currently assigned to "Old Customer".
231+
232+
**Outgoing message**
233+
234+
The outgoing message is identical to the incoming one. Routed via the `Success` connection.
235+
236+
**Result**
237+
238+
The entity view is reassigned from "Old Customer" to "New Customer".

0 commit comments

Comments
 (0)