Skip to content

Commit 4c8c784

Browse files
VlaquitVlaquit
committed
Refactor event filter documentation for clarity and consistency
1 parent 1aafaa1 commit 4c8c784

File tree

2 files changed

+93
-87
lines changed

2 files changed

+93
-87
lines changed

‎content/event-platform/available-filters.md

Lines changed: 92 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,14 @@ Event filters let you **focus only on the events that matter to you** by applyin
44

55
This helps you reduce noise and tailor your event subscription to your needs.
66

7-
> ℹ️ **Filters are optional**
8-
> If no filter is defined, your subscription will receive **all events** that match its type and source.
7+
::: info
8+
**Filters are optional**
9+
If no filter is defined, your subscription will receive **all events** that match its type and source.
10+
:::
911

10-
> ⚠️ **Filter behavior depends on the event type**
11-
> The `user` filter (author) works with all event types.
12-
> Filters like `attribute`, `locale`, `scope`, and `channel` can technically be used on any subscription, but they only **make sense** for `product.updated.delta` and `product_model.updated.delta` events.
13-
>
14-
> If used with other event types, these filters may silently skip events, as the necessary data (like `"changes"`) won't be present in the payload.
15-
>
16-
> **Tip**: For best results, create a dedicated subscription for delta events and apply these filters there.
12+
::: tips
13+
For best results, create a dedicated subscription for delta events and apply these filters there.
14+
:::
1715

1816
## How filters work
1917

@@ -23,72 +21,73 @@ Filters are defined during the subscription configuration (more details on [the
2321

2422
## Available Filters
2523

26-
### `user`
24+
### User Filter
25+
Filters events based on the user.
2726

28-
Receive only events triggered by a specific user.
27+
**Type:** Field Match
28+
**Syntax:** `user="<user_uuid>"`
29+
**Parameter:** UUID string of the user who triggered the event.
30+
**Example:** `user="57616f6f-1a4d-490e-bc23-c5877d2b30d9"`
31+
**Supported Events:** All event types ([list](/event-platform/available-events.html))
2932

30-
- **Syntax**
31-
`user="user_identifier"`
32-
33-
- **Parameter**
34-
`user_identifier`: The UUID of the user who performed the change.
35-
36-
- **Example**
37-
`user="57616f6f-1a4d-490e-bc23-c5877d2b30d9"`
38-
39-
> 💡 Useful for: Ignoring updates by a designated user.
33+
::: tips
34+
Useful for ignoring updates from designated user like job automation.
35+
:::
4036

4137
---
4238

43-
### `attribute`
44-
45-
Receive only events where a specific attribute was modified.
46-
47-
- **Syntax**
48-
`attribute="attribute_code"`
39+
### Attribute Filter
40+
Filters events based on modified attribute codes.
4941

50-
- **Parameter**
51-
`attribute_code`: The code of the attribute you want to monitor.
42+
**Type:** Field Changed
43+
**Syntax:** `attribute="<attribute_code>"`
44+
**Parameter:** String identifier of the attribute code
45+
**Example:** `attribute="description"`
46+
**Supported Events:**
47+
- `com.akeneo.pim.v1.product-model.updated.delta`
48+
- `com.akeneo.pim.v1.product.updated.delta`
5249

53-
- **Example**
54-
`attribute="short_description"`
55-
56-
> 💡 Useful for: Tracking changes to business-critical fields like price, title, or status.
50+
::: tips
51+
Useful for tracking changes to business-critical fields like price, title, or status.
52+
:::
5753

5854
---
5955

60-
### `scope`
61-
62-
Receive only events related to a specific channel (also called *scope*).
63-
64-
- **Syntax**
65-
`scope="channel_code"` or `channel="channel_code"`
66-
67-
- **Parameter**
68-
`channel_code`: The code of the channel where the update occurred.
56+
### Scope and Channel Filter
57+
Filters events based on scope or channel.
6958

70-
- **Example**
71-
`scope="ecommerce"`
59+
**Type:** Field Exists and Match
60+
**Syntax:** `scope="<channel_code>"` or `channel="<channel_code>"`
61+
**Parameter:** String identifier of the channel
62+
**Example:** `scope="ecommerce"`
63+
**Supported Events:**
64+
- `com.akeneo.pim.v1.product-model.updated.delta`
65+
- `com.akeneo.pim.v1.product.updated.delta`
7266

73-
> 💡 Useful for: Filtering updates specific to a distribution channel like "mobile", "print", or "marketplace".
67+
::: tips
68+
Useful for filtering updates specific to a distribution channel like "mobile", "print", or "marketplace".
69+
:::
7470

7571
---
7672

77-
### `locale`
73+
### Locale Filter
74+
Filters events based on locale.
7875

79-
Receive only events related to a specific locale.
76+
**Type:** Field Exists and Match
77+
**Syntax:** `locale="<locale_code>"`
78+
**Parameter:** ISO language-region code
79+
**Example:** `locale="en_US"`
80+
**Supported Events:**
81+
- `com.akeneo.pim.v1.product-model.updated.delta`
82+
- `com.akeneo.pim.v1.product.updated.delta`
8083

81-
- **Syntax**
82-
`locale="locale_code"`
83-
84-
- **Parameter**
85-
`locale_code`: The code of the locale (e.g., language-region).
86-
87-
- **Example**
88-
`locale="en_US"`
89-
90-
> 💡 Useful for: Only processing updates in a particular language or region.
84+
::: tips
85+
Useful for filtering updates specific to a particular language or region.
86+
:::
9187

88+
::: warning
89+
If a filter field is not in the event payload, the filter may silently skip the event.
90+
:::
9291
---
9392

9493
## Filter Operators
@@ -103,47 +102,54 @@ Filters support **basic logic operators** that let you build more flexible and e
103102
|----------|-------------|
104103
| `and` | All conditions must match. |
105104
| `or` | At least one condition must match. |
106-
| `not` | Excludes matching events. |
105+
| `not` | Reverse matching condition. |
107106

108107
---
109108

110-
### Examples
111-
112-
#### "Receive only events where the **author is a specific user** **and** a specific **attribute** was updated"
113-
`user="john-uuid" and attribute="price"`
114-
115-
#### "Receive events where **either** the "description" or "title" attribute was updated"
116-
`attribute="description" or attribute="title"`
109+
## Filter Examples
117110

118-
#### "Receive all updates **except** those made by the system user"
119-
`not user="system"`
111+
| Scenario | Filter Expression | Use Case |
112+
|----------|------------------|-----------|
113+
| User and Attribute Changes | `user="john-uuid" and attribute="price"` | Track price changes made by a specific user |
114+
| Multiple Attributes | `attribute="description" or attribute="title"` | Track changes to customer-facing content |
115+
| Exclude System Updates | `not user="system"` | Focus on human-made changes only |
116+
| Complex Filtering | `(attribute="name" and locale="fr_FR") and not user="system"` | Monitor French content updates while excluding automated changes |
120117

121-
#### "Receive updates to the "name" attribute **in French** but **not** made by the system"
122-
`(attribute="name" and locale="fr_FR") and not user="system"`
118+
::: tips
119+
Remember to use parentheses to group conditions when combining multiple operators. This ensures correct evaluation order and makes the filter more readable.
120+
:::
123121

124122
## Limitations & Rules
125123

126-
To keep filters simple, readable, and fast to evaluate, a few rules and limitations apply:
127-
128-
- You can define **One filter per subscription**
129-
130-
131-
- **All values must be wrapped in double quotes**
132-
✅ `user="system"`
133-
❌ `user=system`
134-
124+
### Filter Constraints
135125

136-
- **You can use parentheses** to group conditions and clarify your logic.
137-
Example:
138-
`user="system" and (attribute="name" or attribute="description")`
126+
| Constraint | Limit | Description |
127+
|------------|-------|-------------|
128+
| Filters per subscription | 1 | Only one filter expression per subscription |
129+
| Maximum length | 500 characters | Total length of filter expression |
130+
| Maximum operators | 4 | Number of logical operators in a single filter |
139131

132+
### Syntax Rules
140133

141-
- **Maximum filter length**: 500 characters
134+
#### String Values
135+
All values must be wrapped in double quotes:
136+
- `user="system"`: ✅
137+
- `user=system`: ❌
142138

143139

144-
- **Maximum number of operators**: 4
140+
#### Grouping Conditions
141+
Use parentheses to group conditions and control evaluation order:
142+
`user="system" and (attribute="name" or attribute="description")`
145143

144+
#### Query Complexity
145+
Complex filters may be rejected if they:
146+
- Have deeply nested conditions
147+
- Use too many operators
148+
- Exceed length limits
146149

147-
- **Query complexity is limited**
148-
Deeply nested or overly complex filters may be rejected. If this happens, you’ll receive an error message.
149-
Try simplifying your expression or splitting your use case into multiple subscriptions.
150+
::: tips
151+
If your filter is rejected, try:
152+
- Splitting into multiple subscriptions
153+
- Simplifying the logic
154+
- Reducing nesting levels
155+
:::

‎content/event-platform/concepts.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -173,7 +173,7 @@ We currently use a static IP address provided by Google Cloud: `34.140.80.128`
173173

174174
**However, we cannot guarantee that this IP address will remain unchanged indefinitely.** Therefore, we strongly recommend whitelisting the `europe-west1` IP ranges from [Google Cloud's IP ranges list](https://www.gstatic.com/ipranges/cloud.json) to ensure continuous access.
175175

176-
## Subscriptions Filters
176+
## Subscription Filters
177177

178178
When configuring a subscription, you can optionally define a **filter** to receive **only the events that match specific criteria**.
179179

0 commit comments

Comments
 (0)