[Advanced] Optimizing and mastering rules – Kweeri Help Center

This feature is not available during the free trial

Working with Rules

Rules work as a group set.

These groups are:

🗓 Date
- min date
- max date
🏷 Prices
- Total amount of the receipt
- Minimum amount spent on a given product(s)
🏬 Signs
🛍 Items (aka Products)
- Products names and brands to be found in the receipt
- Minimum number of items to find in a receipt

Each group is checked separately one by one by our validation system.

A receipt will only be considered valid (or eligible) if it complies with all rule groups.

These groups allow our system to give you detailed report about which rules have matched for the receipt and which haven't.

Let's take a closer look at the JSON format of each of the rule group

🗓 Date

"dateRule": {
    "min": "2019-01-01",
    "max": "2019-11-01"
}

Here the min key corresponds to the minimum date allowed for the receipt and the max key is the maximum date.

Date format must respect the ISO8601 standard without time.

🏬 Sign

"signRule": {
    "signList": [
        "Cora",
        "Auchan",
        "Carrefour"
    ]
}

The signList key is an arrayof string. Where each string corresponds to a store sign.

A sign is the name of a retailer. The rule will be validated only if the receipt's store is in the list of signs (aka signList).

You can retrieve here the list of possible value to pass in this array, as we have a fixed list of signs that can be detected by our system.

🛍 Item

Before using an itemRule please take care of the following structure of an item:

{
    "term": "Sodebo",
    "quantityRequired": 2,
    "strategy": "QUANTITY"
}

An itemRule is an object which contains many item:

"itemRule": {
    "or": [{
        "term": "Tarama"
    },{
        "term": "Blini"
    }],
    "quantityRequired": 2,
    "strategy": "QUANTITY",
    "not": [{
        "term": "Boursin"
    },{
        "term": "Sodebo"
    }]
}

WARNING
The or and and keys are mutually exclusive. You can't have an or key with an and key.

"itemRule": {
    "and": [{
        "term": "Labeyrie"
    }],
    "quantityRequired": 2,
    "strategy":"QUANTITY",
    "not": [{
        "term": "Sodebo"
    },{
        "term": "Bordeaux chesnel"
    }]
}

The simplest key is quantityRequired which corresponds to the minimum number of item required for this eligible products.
The strategy key correspond to the strategy used to count item for the key quantityRequired, this key can only have those three value (QUANTITY, BUNDLE, QUANTITY_TIMES_BUNDLE):
- QUANTITY will only check for the quantity of an item
  - Example : 1 pack of 6 beers, quantity is 1
- BUNDLE will only check for the bundle size of an item
  - Example : 1 pack of 6 beers, bundle will be 6
- QUANTITY_TIMES_BUNDLE will check and multiple the two previous values, quantity multiplied by bundle to get the number of products bought
  - Example : 2 packs of 6 beers, the quantity will be 6x2 => 12
The not key is an array of item with each item corresponding to a product label to be excluded from the list of eligible products.

The not key is useful in the case where a competitor's brand owns a product whose name is too similar to the one we want to detect.

The or is the most important and useful key. It's an array of item. A term has a string value. Each value represents a potential product label that we want to detect.

The receipt will be considered valid if any of the label has been detected according to required quantity

The and key : It's also an array of item. A term has a string value. Each value represents a product label that must be present at least once per label in the receipt.

All fields in the 'and' key must be present at least once in the receipt.

🏷 Price

"priceRule": {
    "eligibleOnly": 20.25,
    "totalAmount": 40
}

The eligibleOnly key is minimum amount spent on eligible products.

totalAmount is the total amount of the receipt.

How to know if a receipt is eligible?

As mentioned above each rules group is checked separately. In each group there is a isMatched key. If this key is true then the value in the field has been found in the receipt.

In this example the terms Labeyrie and Blini in the or group have been found which is one of the conditions to make a receipt eligible. But we also found Auchan in the not group which removes the matched item from the list of eligible items.

To see if the receipt is eligible at a glance, you just need to check the key allRulesMatched. If the value is true then the receipt is eligible.

{
  "name": "Labeyrie",
  "uid": "123",
  "itemRule": {
    "quantityRequired": 2,
    "strategy": "QUANTITY",
    "or": [
      {
        "term": "Labeyrie",
        "quantityRequired": 1,
        "itemsMatched": [
          "3"
        ],
        "isMatched": true,
        "quantityMatched": 1
      },
      {
        "term": "Blini",
        "quantityRequired": 1,
        "itemsMatched": [
          "1",
          "2"
        ],
        "quantityMatched": 2,
        "isMatched": true
      }
    ],
    "not": [
      {
        "isMatched": true,
        "term": "Auchan",
        "itemsMatched": [
          "2"
        ],
        "quantityMatched": 1
      },
      {
        "isMatched": false,
        "term": "Cora",
        "itemsMatched": [],
        "quantityMatched": 0
      }
    ],
    "itemsMatched": [
      "3",
      "1"
    ],
    "quantityMatched": 2,
    "isMatched": true
  },
  "dateRule": {
    "min": "2019-01-01",
    "max": "2019-11-01",
    "isMatched": true
  },
  "priceRule": {
    "eligibleOnly": 15,
    "totalAmount": null,
    "isMatched": false
  },
  "signRule": {
    "signList": [
      "Cora",
      "Auchan",
      "Carrefour"
    ],
    "isMatched": true
  },
  "allRulesMatched": false,
  "totalPriceOfMatchedItems": 9.74
}

How to select terms for `ItemRule`

This is the key step to a successful promotion campaign. The heart of any campaign is the terms that should be validated in a receipt that correspond to eligible products.

How algorithm works

all words of a term should be present.

Our algorithm requires all words in a term to be found in the label for it to be validated. Thus if the term is Nestle Fitness Bio Cereales, then all 4 words should be present in the label exactly the way they are written.

Label in receipt	Validation result	Words found	Explanation
`Fitness Bio`	No match 🚫	2 words out of 4
`Fitn Bio Cer`	No match 🚫	1 word out of 4	abbreviations are not matched.

The order of words in a term does not matter -> Bio Fitness is equivalent to Fitness Bio
Alternative names are not considered/created by default. They should be present as another term.

KLGS written in a receipt will not match term Kelloggs, you have to add the term KLGS.

👍 Good practices

Here are some good practices to be implemented when creating terms for a promotion campaign.

What to include:

Entire name of the main brand: Kellogg

Without the apostrophe and s at the end

Possible abbreviations of the main brand: KLGS
If there is a brandline with rather unique name (confusion with another product is not likely) add only the name of the brand line.

"itemRule": {
        "or": [{
                "term": "Kellogg"
            },
            {
                "term": "KLGS"
            }
        ]
    }

Brandline

Brandline - is a rather narrow line of products Tresor that belongs to a parent brand Kelloggs. Opt for a brandline if its name is unique enough:

Actimel instead of Danone Actimel,
Fitness instead of Nestle Fitness

Add only necessary words

Imagine you want all Tresor cereals and you know that they exists with different taste:

Tresor Dark
Tresor choco
Tresor white

Then add only necessary words for products to distinguish them from the same brand line. In other words, if you want all Tresor cereals just add:

"itemRule": {
        "or": [{
                "term": "Kellogg"
            },
            {
                "term": "KLGS"
            },
            {
                "term" : "Tresor"
            }
        ]
    }

Conversely, if you want only a specific taste of Tresor cereals then do:

    "itemRule": {
        "or": [{
                "term": "Kellogg"
            },
            {
                "term": "KLGS"
            },
            {
                "term" : "Tresor Dark"
            }
        ]
    }

Be careful when adding some general terms without a brand : Yaourt nature will match all natural flavoured yogurts no brand consideration.

What to avoid

Term of ItemRule	✅ Do	🚫 Don't	Explanation
Do not use plural forms	✅ Thé vert	🚫 Thés verts
Avoid duplicates	✅ Activia	🚫 Activia Nature	all labels with the term `activia` (nature or not) are already matched by the first term.
Avoid one-letter words in term	✅ carte noire	🚫 c noire	any word with letter `c` will match like `chaussette noire`.
Avoid 4 words and longer terms	✅ Grand Mere Espresso	🚫 Grand Mere Espresso Coffee

Special cases

Don't add product's nature - the essence of this product: bread, coffee, yogurt. Only include these words if no brand is present OR if the brand covers several groups of product.

For example Président make cheese and cream, you only want cream do president creme, but if you only want the cheese do Président only. Because the main activity of Président is the cheese, you will be likely to have only PRESIDENT in the receipt if it's cheese.

What to exclude

Warning

Try to avoid special characters, articles and any other short words that are not unique to an item and can be omitted in a receipt line due to its limited length.

Possible lists of words to exclude:

Any special characters (hyphen -, colon, &, apostrophe) - use a space instead.
No accents: é è à â...
Articles : the, a, an
Prepositions and Conjunctions: of, with, and, or, but ...
Pronouns : I, me, he, she, this, that, these, those
Quantifiers and Numbers : one, thirty, much, many, some, any, enough, all, both, half
Determiners: other, another, such, what, rather, quite

Bad Term	Reason
`Les deux vaches \- yaourts nature`	article, plural forms, hyphen, too many words
`Pim's Biscuits Lu à l'orange`	apostrophe, article and preposition, parent brand `Lu` and brandline at the same time (`Pims` is enough), too precise (`à l'orange`)
`Café`	accent, too short and generic

Step-by-step guide

Let's consider an example campaign.

The products concerned by this campaign will be toast bread (pain de mie) of brandline American Sandwich of parent brand Harry's.

1. Brand or Brandline:

The easiest term would be the brandline itself american sandwich.

2. Abbreviations:

The most common abbreviation of this brandline is ams. It is unique enough to be added as a term although it's a rather short word. If you are doubting that it could validate false-positive items you can precise the term as follows ams pain or/and ams mie or/and harry ams.
Some shorten abbreviations also can be useful: am sand.

Important: keep the complete term american sandwich as it can be matched with a detected brand of an item.

3. Combinations of Brand + Product's Nature:

Sometimes american sandwich is ommited and the desired item can be described as bread of brand Harry's. Let's develop this possibility:

harry pain instead of harry's pain de mie
harry mie instead of harry's pain de mie
100% mie - it's a unique product of brand harry's so can it be used without the parent brand.

Notice that we removed 's from harry's - the unique name of the brand is still preserved.

4. Abbreviations + Product's characteristics.

When using abbreviations (especially short ones) a characteristic of a product can be added: ams nat (nat for nature)

Finally the possible list of terms for such a campaign would be:

american sandwich
ams pain
ams mie
ams nat
harry ams
harry mie
harry pain
100% mie
am sand

    ...
    "itemRule": {
        "or": [{
                "term": "am sand"
            },
            {
                "term": "100% mie"
            },
            {
                "term" : "harry pain"
            },
            {
                "term" : "harry mie"
            },
            {
                "term" : "harry ams"
            },
            {
                "term" : "ams nat"
            },
            {
                "term" : "american sandwich"
            },
        ]
    }
    ...