github.com/argoproj/argo-events@v1.9.1/docs/sensors/filters/expr.md (about)

     1  
     2  # Expr filter
     3  
     4  Expr filters are applied to the event data. A CloudEvent from Webhook event-source has payload structure as:
     5  
     6  ```json
     7  {
     8      "context": {
     9        "type": "type_of_event_source",
    10        "specversion": "cloud_events_version",
    11        "source": "name_of_the_event_source",
    12        "id": "unique_event_id",
    13        "time": "event_time",
    14        "datacontenttype": "type_of_data",
    15        "subject": "name_of_the_configuration_within_event_source"
    16      },
    17      "data": {
    18        "header": {},
    19        "body": {},
    20      }
    21  }
    22  ```
    23  
    24  Expr filters are applied on `data` within the payload.
    25  
    26  ## Fields
    27  
    28  An expr filter has following fields:
    29  
    30  ```yaml
    31  filters:
    32    exprLogicalOperator: logical_operator_applied
    33    exprs:
    34      - expr: expression_to_evaluate
    35        fields:
    36          - name: parameter_name
    37            path: path_to_parameter_value
    38  ```
    39  
    40  > ⚠️ `PLEASE NOTE` order in which expr filters are declared corresponds to the order in which the Sensor will evaluate them.
    41  
    42  ## Logical operator
    43  
    44  Expr filters can be evaluated together in 2 ways:
    45  
    46  - `and`, meaning that all expr filters returning `true` are required for an event to be valid
    47  - `or`, meaning that only one expr filter returning `true` is enough for an event to be valid
    48  
    49  Any kind of error is considered as `false` (e.g. path not existing in event body).
    50  
    51  Such behaviour can be configured with `exprLogicalOperator` field in a Sensor dependency filters, e.g.
    52  
    53  ```yaml
    54  apiVersion: argoproj.io/v1alpha1
    55  kind: Sensor
    56  metadata:
    57    name: data-filters-example
    58  spec:
    59    dependencies:
    60      - name: sample-dependency
    61        eventSourceName: webhook
    62        eventName: sample-event
    63        filters:
    64          exprLogicalOperator: "or"
    65          exprs:
    66            - expr: a == "b" || c != 10
    67              fields:
    68                - name: a
    69                  path: a
    70                - name: c
    71                  path: c
    72            - expr: e == false
    73              fields:
    74                - name: e
    75                  path: d.e
    76            # ...
    77  ```
    78  
    79  Available values:
    80  
    81  - `""` (empty), defaulting to `and`
    82  - `and`, default behaviour
    83  - `or`
    84  
    85  > ⚠️ `PLEASE NOTE` Expr logical operator values must be `lower case`.
    86  
    87  ## How it works
    88  
    89  The `expr` field defines the expression to be evaluated. The `fields` stanza defines `name` and `path` of each parameter used in the expression.
    90  
    91  `name` is arbitrary and used in the `expr`, `path` defines how to find the value in the data payload then to be assigned to a parameter.
    92  
    93  The expr filter evaluates the expression contained in `expr` using [govaluate](https://github.com/Knetic/govaluate). This library leverages an incredible flexibility and power.
    94  
    95  With govaluate we are able to define complex combination of arithmetic (`-`, `*`, `/`, `**`, `%`), negation (`-`), inversion (`!`), bitwise not (`~`), logical (`&&`, `||`), ternary conditional (`?`, `:`) operators,
    96  together with comparators (`>`, `<`, `>=`, `<=`), comma-separated arrays and custom functions.
    97  
    98  Here some examples:
    99  
   100  - `action =~ "start"`
   101  - `action == "end" && started == true`
   102  - `action =~ "start" || (started == true && instances == 2)`
   103  
   104  To discover all options offered by govaluate, take a look at its [manual](https://github.com/Knetic/govaluate/blob/master/MANUAL.md).
   105  
   106  ## Practical example
   107  
   108  1. Create a webhook event-source
   109  
   110          kubectl -n argo-events apply -f https://raw.githubusercontent.com/argoproj/argo-events/stable/examples/event-sources/webhook.yaml
   111  
   112  1. Create a webhook sensor with expr filter
   113  
   114          kubectl -n argo-events apply -f https://raw.githubusercontent.com/argoproj/argo-events/stable/examples/sensors/filter-with-expressions.yaml
   115  
   116  1. Send an HTTP request to event-source
   117  
   118          curl -d '{ "a": "b", "c": 11, "d": { "e": true } }' -H "Content-Type: application/json" -X POST http://localhost:12000/example
   119  
   120  1. You will notice in sensor logs that the event is invalid as the sensor expects `e == false`
   121  
   122  1. Send another HTTP request to event-source
   123  
   124          curl -d '{ "a": "b", "c": 11, "d": { "e": false } }' -H "Content-Type: application/json" -X POST http://localhost:12000/example
   125  
   126  1. Look for a workflow with name starting with `expr-workflow-`
   127  
   128  ## Further examples
   129  
   130  You can find some examples [here](https://github.com/argoproj/argo-events/tree/master/examples/sensors).