Skip to content

Commit bc2e78f

Browse files
JulienVerbruggeJulienVerbrugge
committed
Merge branch 'master' into DXIM-rework_ui_ext_doc
2 parents 20f2861 + 9f3a3be commit bc2e78f

File tree

4 files changed

+191
-1
lines changed

4 files changed

+191
-1
lines changed

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

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
# Event Filters
2+
3+
Event filters let you **focus only on the events that matter to you** by applying simple, readable conditions. Instead of receiving every single event, you can choose to receive just a subset—like changes made by a specific user or updates to a specific attribute.
4+
5+
This helps you reduce noise and tailor your event subscription to your needs.
6+
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+
:::
11+
12+
::: tips
13+
For best results, create a dedicated subscription for delta events and apply these filters there.
14+
:::
15+
16+
## How filters work
17+
18+
Filters are defined during the subscription configuration (more details on [the Subscriptions page](/event-platform/concepts.html)) and are automatically evaluated when an event is processed. If the event **matches your filter**, it is forwarded to your destination. If not, it is silently skipped.
19+
20+
---
21+
22+
## Available Filters
23+
24+
### User
25+
Filters events based on the user.
26+
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))
32+
33+
::: tips
34+
Useful for ignoring updates from designated user like job automation.
35+
:::
36+
37+
---
38+
39+
### Attribute
40+
Filters events based on modified attribute codes.
41+
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`
49+
50+
::: tips
51+
Useful for tracking changes to business-critical fields like price, title, or status.
52+
:::
53+
54+
---
55+
56+
### Scope and Channel
57+
Filters events based on scope or channel.
58+
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`
66+
67+
::: tips
68+
Useful for filtering updates specific to a distribution channel like "mobile", "print", or "marketplace".
69+
:::
70+
71+
---
72+
73+
### Locale
74+
Filters events based on locale.
75+
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`
83+
84+
::: tips
85+
Useful for filtering updates specific to a particular language or region.
86+
:::
87+
88+
::: warning
89+
If a filter field is not in the event payload, the filter may silently skip the event.
90+
:::
91+
---
92+
93+
## Filter Operators
94+
95+
Filters support **basic logic operators** that let you build more flexible and expressive conditions. This means you can combine or exclude criteria in a single filter expression.
96+
97+
---
98+
99+
### Supported Operators
100+
101+
| Operator | Description |
102+
|----------|-------------|
103+
| `and` | All conditions must match. |
104+
| `or` | At least one condition must match. |
105+
| `not` | Reverse matching condition. |
106+
107+
---
108+
109+
## Filter Examples
110+
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 |
117+
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+
:::
121+
122+
## Limitations & Rules
123+
124+
### Filter Constraints
125+
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 |
131+
132+
### Syntax Rules
133+
134+
#### String Values
135+
All values must be wrapped in double quotes:
136+
- `user="system"`: ✅
137+
- `user=system`: ❌
138+
139+
140+
#### Grouping Conditions
141+
Use parentheses to group conditions and control evaluation order:
142+
`user="system" and (attribute="name" or attribute="description")`
143+
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
149+
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: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -173,6 +173,31 @@ 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+
## Subscription Filters
177+
178+
When configuring a subscription, you can optionally define a **filter** to receive **only the events that match specific criteria**.
179+
180+
You can find the list of currently available filters and the correct syntax to use [here](/event-platform/available-filters.html).
181+
182+
### Example
183+
Let’s say you want to receive only the events triggered by a specific user, identified by the UUID `ea0fe94f-417e-4078-a40b-38645ba90ebe`.
184+
You can configure your subscription with the following filter:
185+
186+
```json[snippet:Filtered subscription]
187+
{
188+
"source": "pim",
189+
"subject": "https://my-pim.cloud.akeneo.com",
190+
"events": [
191+
"com.akeneo.pim.v1.product.updated"
192+
],
193+
"type": "https",
194+
"config": {
195+
"url": "https://your_webhook_url",
196+
}
197+
"filter": "user=\"ea0fe94f-417e-4078-a40b-38645ba90ebe\""
198+
}
199+
```
200+
176201
## Events Format
177202

178203
Our platform standardises event data across services using the [CloudEvents specification](https://github.com/cloudevents/spec). CloudEvents provides a consistent structure for event data, ensuring interoperability and simplifying event handling. Each event includes essential metadata such as the event type, source, ID, and timestamp.
@@ -220,4 +245,4 @@ Example of an event payload for a productDeleted event
220245
For more information, consult the [CloudEvents spec attributes](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md).
221246

222247
::: panel-link Authorization and authentication requirements [Next](/event-platform/authentication-and-authorization.html)
223-
:::
248+
:::

‎content/extensions/ui-extensions.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -202,6 +202,11 @@ You can add a placeholder anywhere in your url as soon as they're surrounded by
202202
Examples:
203203
- `https://www.google.com/search?q=%name%`
204204
- `https://yourwebsite.com/%sku%`
205+
- `%base_url%/sub-url`
206+
207+
::: warning
208+
If the URL begins with a placeholder, we won't verify its validity. The link might not work when used.
209+
:::
205210

206211
### Iframe
207212
An **iframe** UI extension allows to open your external content inside the PIM thanks to an iframe.

‎src/partials/layout.handlebars

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -151,6 +151,11 @@ height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
151151
<li><a href="/event-platform/available-events.html">Available events</a></li>
152152
</ul>
153153
</li>
154+
<li>
155+
<ul>
156+
<li><a href="/event-platform/available-filters.html">Available filters</a></li>
157+
</ul>
158+
</li>
154159
<!--
155160
<li>
156161
<ul>

0 commit comments

Comments
 (0)