Optimizing and mastering rules ​

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)
  • Product 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.

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

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"
  }
}

{
  "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.

🏬 Sign ​

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

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

The signList key is an array of 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 note the following structure of an item:

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

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

An itemRule is an object which may contain multiple items:

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

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

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

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

• The quantityRequired 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 equal to one of these three values:
  • 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 multiply 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. This 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 the 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.

🏷 Price ​

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

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

• The eligibleOnly key is minimum amount spent on eligible products.
• The totalAmount key is the total amount of the receipt.

How to know if a receipt is eligible? ​

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

In the following 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.

{
  "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
}

{
  "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 our 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.

• 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

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

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

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

Brandline ​

A brandline is a rather narrow line of products that belongs to a parent brand.

Opt for a brandline if its name is unique enough:

Actimel instead of Danone Actimel,

Fitness instead of Nestle Fitness

Imagine you want all Tresor cereals, and you know that they exist 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"
      }
    ]
  }
}

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

If you want only a specific taste of Tresor cereals then do:

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

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

What to avoid ​

For example the brand Président makes cheese and cream, and you only want cream: then put president creme. But if you only want the cheese put Président only. Because the main activity of Président is cheese, you will likely have only PRESIDENT in the receipt if it's cheese.

What to exclude ​

Here is a possible list 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

Step-by-step guide ​

Let's consider a campaign as an example.

The products concerned by this campaign will be toast bread ("pain de mie") of the brandline American Sandwich from the 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 specify the term like so: ams pain or/and ams mie or/and harry ams.

Some shorten abbreviations also can be useful: am sand.

3. Combinations of Brand + Product's Nature:

Sometimes american sandwich is omitted 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

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

The rules JSON should look like this:

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

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