M3 Filter Component
The M3 Filter component narrows down the records an M3 step returns, before they are written back to the Excel sheet. It is useful when the M3 API transaction itself can't select precisely enough: you fetch a wider set, and the filter keeps only the records you want. Only records that match the conditions continue to the next component. To filter rows that do not come from M3, such as spreadsheet rows, use the Generic Filter.
Add it directly after an M3 API or M3 Fetch step, so that irrelevant records are dropped before they reach components such as Excel or Email. It is a VXL Live component: you build it in the Vince Platform workflow editor, and the workflow is used from VXL Live.
M3 Filter or Generic Filter?
| M3 Filter | Generic Filter | |
|---|---|---|
| Typical use | Filter what M3 returns before it is written back to the sheet, when the M3 transaction can't select precisely enough | Filter the spreadsheet rows coming in before they are sent to M3, for example only the rows marked for import |
| Filters | The output of an M3 API or M3 Fetch step | Incoming rows, such as the rows of the Excel sheet |
| Where it goes | Directly after the M3 API or M3 Fetch step | Before the M3 API step |
| Choosing the field | Picked from the M3 transaction's fields in the Available fields panel | Typed by name, for example a column name |
| Data type | Taken from the M3 field | Chosen per condition: String, Number or Boolean |
| Excel-input workflows | Can apply to all transactions (Global filter) or to one transaction | Applies to the rows it receives |
| Value from | Client (on the run form) or Constant | Client (on the run form) or Constant |
| Combine conditions | And / Or | And / Or |
The filter needs at least one transaction in the M3 step. Without one, it shows No filter items available without M3 API defined.
Example: only orders with status 22
An M3 API step lists customer orders, but you only want those with status 22.
- Add an M3 Filter directly after the M3 API step.
- Drag the order status field into Filter items.
- Set Comparison to Equals, Source to Constant and the value to
22. - Click Save.
Orders with any other status are dropped before they reach the next component, such as Excel.
Configure a filter
- Open the M3 Filter step. The Available fields panel on the left lists the fields of the M3 transactions. It opens by itself while the filter is empty. Otherwise click Click here to show available fields list, or use the panel's arrow.
- Drag a field from the panel into Filter items.
- For each item, choose a Comparison, a Source for the value, and a Logical operator (And or Or) that says how the item combines with the others.
- Enter the value (see the source options below). Use the trash icon to remove an item.
- Click Save.
The fields you can drag depend on the workflow. In a workflow that reads rows from an Excel file (an import), you filter on the input fields, the values being sent to M3. In other workflows you filter on the output fields M3 returns.
The step needs at least one field to filter on. If nothing is mapped, the workflow reports M3 FILTER: Map at least one field to filter. Either add a field or remove the M3 Filter step.
Filter one transaction or all of them
In a workflow that reads rows from an Excel file, a drop-down at the top right lets you choose where a filter applies: Global filter applies to all transactions, or pick one transaction to filter only that one. Each choice keeps its own list of filter items. In other workflows there is only the global filter.
Comparison types
| Comparison | The record passes when |
|---|---|
| Equals | The field value is the same as the value |
| Not equals | The field value is different |
| Less than | The field value is lower than the value |
| Greater | The field value is higher than the value |
| Less or equals | The field value is lower than or equal to the value |
| Greater or equals | The field value is higher than or equal to the value |
| Blank | The field is empty |
| Not blank | The field has a value |
| Contains | The field value includes the text |
| Does not contain | The field value does not include the text |
Contains and Does not contain are not offered for number and date fields. Blank and Not blank need no value.
Source options
| Source | Behaviour |
|---|---|
| Client | The user enters the value in the form when running the workflow. The value you type when building the filter is the default. The form lets the user skip a field with Ignore field |
| Constant | A fixed value set when you build the workflow. It is applied automatically and is required. Earlier constants are suggested as you type |
For scheduled workflows, use Constant. A Client value needs someone to type it, so it cannot be used in unattended runs.
Example: filter between two values
To keep only records between a lower and an upper value:
- Drag the same field into Filter items twice.
- Set the first item to Greater or equals with source Client.
- Set the second item to Less or equals with source Client.
- Set the logical operator to And.
When the workflow runs, the user enters the lower and upper values, and only records in that range pass.
Good to know
- If you delete a transaction from the M3 step, the filter items that used it are removed.
- If you delete the M3 Filter step, its fields are also removed from the run form.
Related
- M3 API: a component whose records M3 Filter can narrow down
- M3 Fetch: the other M3 step the filter can follow
- Generic Filter: for filtering the incoming spreadsheet rows before they are sent to M3