Labeling rules
Labeling rules are a flexible way of parameterizing the rendering of a product's label. Labeling rules can be added, for example, to change the name of one or more ingredients/components on the label, or to hide them.
These rules can be defined in several places in the application:
- the entity labelling list
- The entity model labeling list: These rules are copied to the product using the model at formulation (manual) or executed directly (model).
- The specification labeling rule list: the specification will be associated with the finished product (FP) by adding it to the FP's properties, it may be customer-specific);
- The list of regulatory categories of ingredients in government value lists: "Do not declare", "Place at the end").
Create a labeling rule
A rule is defined by:
- A name
- A type
Depending on the rule type, other fields such as Label, Expression, Components, Group Languages and Replacements are possible.
Synchronization and group management can be used to create automatisms for all rules.
The rules Declare, Format, Languages, Do not declare, Omit, Render, Rename, Declaration threshold, Ingredient type, Show percentages, Show geo origins, Show organic origins, Put at end and foot note can be applied to a specific language.
Synchronisable State
There are 3 types of synchronisation for the labelling rules.
Template
- The rule is registered on the product template : product A (FP, SF, RM);
- The rule will always be applied to all the product whose model are the product A;
- The rule isn't visible by the user when he looks at the labelling rules of his products.
Interest: the purpose is to reduce the labelling rules 'list for the finished product. The user will only find the rule on the template.
Synchronisation
- The rule is registered on the product template : product A (FP, SF, RM);
- The rule will always be applied to all the product whose template are the product A;
- The rule is visible by the user when he looks at the labelling rules of his products ;
- The rule can be changed in the product's template.
Interest: the purpose for this synchronisation is to be used by all the products and to be easily changed. It is also possible to disabled it.
Manual
- The rule is registered for each product;
- The rule is visible by the user when he looks at the labelling rules of his products;
- The rule can be changed in the labelling rules list of the product.
Interest: the purpose for this synchronisation is to stay independant from the other product.
Activate/desactivate a rule
Template" rules (at the entity model level) and "synchronized or manual" rules (at the entity level) can be activated or deactivated using the buttons below. Simply click on them and choose to enable (Yes) or disable (No) the labeling rule.
Rules defined on groups
The « Group » field is useful:
- First case: when different rules have to be applied (of type different from « Render ») to many labels. For example, let's consider a group 2 label and a group 1 label. The separator has to be changed from « , » to « ; » only on label 1. A new rule is created, with the « Preference » type. The text « defaultSeparator = " ; " » is written in the « Formula » field and the group 1 is specified.
- Second case: when the same rule has to be applied for all labels. For example, let's consider a group 2 label and group 1 label. The separator has to be changed from « , » to « ; » in all the labels. A new rule is created, with the « Preference » type. The text « defaultSeparator = " ; " » is written in the « Formula » field and the « Group » field is left blank.
WARNING: if the rule « Display percentages » is chosen by default, the case 1 won’t work.
Rules defined on languages
The “Languages” option is available in several labeling rules.
For example: the rules format, if we want to display allergens in brackets only on the English “” label.
- To enclose allergens in brackets, use :
- allergenDetailsFormat|{0} ({2})
- Select the language (English)
- Allergens on the English label are now enclosed in brackets.
Other: if we want to display the geographical origins of ingredients only for the label translated into German and English, select the “Display geographical origins” rule.
- Select the “Display geo origins” rule
- Select the language (English and German)
Geo origins of ingredients are displayed only for the label translated into English and German.
Or again: if we want to display the qauntites in % of the ingredients only for the label translated into German and English.
- Select the “Display percentages” rule
- Select the language (English and German)
Ingredient quantities are displayed in percentages only for the label translated into English and German.
Types of rules
Show percentages
That rule is used to display the quantity of elements (ingredients, sub-ingredients, semi-finished...) in percentages and in relation with the type of declaration associated to the entity. The association "Show percentages/ Type of declaration" enalbles to display the % as you want. To display percentages for ingredients, informations regarding their proportions must be added at the level of each raw materials ingredients.
Note: "#.#" gives the number of decimals e.g. After chosing show percentages as rule, enter #.## in Formula to indicate 2 decimals (if you enter #.# you will indicate 1 decimal and #.### will indicate 3 decimals and so on).
Formula: #.#
For #.#, by default, the value is rounded down from #.#0 to #.#4 and rounded up from #.#5 to #.#9. But, you can set differents rounding rules:
--> #.#%|DOWN: always rounds down (2.26% --> 2.2%)
--> #.#%|UP : always rounds up (2.21% --> 2.3%)
--> #.#%|HALF_DOWN : for the case #.#5, rounds down (2.25% --> 2.2%)
--> #.#%|HALF_UP : for the case #.#5, rounds up (2.25% --> 2.3%)
Those rules are equivalent to the ones in the Preferances section. Both methods have pros and cons:
- In the case we want a global rounding rule for all products, it's better to use Show pourcentages. Indeed, it centralises everything in a single rule (display pourcentage + format).
- In the case we want a special format for some products, it's better to use Preferances. In fact, it separates the rule to display pourcentage and the rounding rule, which you could activate or not depending on the product.
You can also, in expression, add a threshold that will apply to the rule
- "#.#||1" will apply for example to ingredients in proportion less or equal to 1%
- "#.###|HALF_UP|0.1" will apply for example to ingredients in proportion less or equal to 0.1%
By combining the rules you can create reporting intervals.
Show geographical origin
This rule displays origins of elements (ingredients, subingredients, semifinished products,...) based on the type of declaration associated to the entity.
To use this rule, you must fill the origin of your raw material elements:
- for ingredients: in the ingredient tab of your raw material, fill ""Geographical origin",
- for your raw material: in the properties of the raw material, fill "Geographical origin".
Based on the origins that you wabt to display, you will modify the field "component" of your rule and/or the type of declaration of your entity:
- if you want the origin of one or more specific elements: Associate the component(s) to the rule and choose the correct type of declaration (e.g. for an ingredient--> select "declara ingredients")
- if you want all origins, it is not necessary to save the components of your recipe in that rule. Component percentages will be displayed by default if the component field of the rule is empty.
Example 1 :
- Origine de la MP Lardon fumé,
- % pour les MP et le SF avec l'affichage en % de la recette de la composition de ce dernier.
Example 2 :
- % de l'ingrédient riz
- Origine de la MP Lardon fumé
Formulas
It is possible to filter components with a SPEL formula. Available formulas are:
- compoListDataItem : l’élément dans la composition ;
- ingListDataItem : the extracted ingredient.
For some products, it is necessary to indicate addidtional information on the origin. In the case of sea products it may be necessary to display the catch zone. In the case, of meat products you may have to declare birth, rearing and slaughter origins.
These statements can be added to the rule "Show origins". You must first create the country of origin in administration becpg--> characteristics --> geographical origins Then, in front of each country, it is possible to add a "place of activity". The potential values are: Assembly, Birth, Bottling, Catch zone, Farming, Importation, Last processing, Milking, Rearing, Slaughter.
More than one value can be added to a country
Then, you must add the country of origin to the raw material.
Back on the finished product, add the labelling rule "Show origins". That rule can be completed to indicate the place of activities by using : ASSEMBLY, BIRTH, BOTTLING, CATCH_ZONE, FARMING, IMPORTATION, LAST_PROCESSING, MILKING, REARING, SLAUGHTER, EMPTY
By default, the rule only display the country of origin if there is more than one place of activity. The indication will then be "ingredient or raw material" [country of origin]. Adding a place of activity followed by EMPTY in the rule will indicate the place of activity before the country of origin.
Finally, if more than a place of activity in a rule, the place of activities will preceed the country of origin.
e.g. BIRTH,REARING,SLAUGHTER
Show biological origins
This rule displays the organic origins of elements (ingredients, sub-ingredients, semi-finished products, etc.) according to the type of declaration associated with the entity.
Rename
This rule is executed in chosing a component to be replaced (in the « Components » drop-down box) and its substitute which is selected in the «Replacement» drop-down box (if it already exists), or it can be created by putting its name in the « Wording » field (label).
If the renaming concerns the labels generated in a certain language, this latter should be specified by selecting it in the language list as below :
Which generates the following :
Note: Contains less than 2%
As per US regulation, the descending order of predominance does not apply to ingredients present in amounts of 2 percent or less by weight when a listing of these ingredients starts with ", contains less than 2% of " beCPG takes that in account by using the "Rename" rule. Then, enter "Less than 2%" in name. And ", contains less than 2% of " in label. Formula must contain your threshold which in that case is "0.02" (2 percents).
The result will be displayed in your list of ingredients.
If that labeling rule is supposed to be applied to a specific country, you must use the rule named "Language" as shown here.
This will result in the following display:
Aggregate and detail
It is also possible to specify the parts of the ingredients in the aggregate. For example, if we want to take 100% of milk and 80% of pasteurized cow milk, you must enter « 100,80 » in the field «Expression ».The aggregate is displayed when a detail of the components as their parts in the product.
Here, only the aggregate is displayed in the list of ingredients.
Becomes:
Aggregate and do not detail
Aggregation rules enable to aggregate two ingredients as a third ingredient (Example: milk, pasteurized cow milk --> milk).
Here, only the aggregate is displayed in the labeling.
Becomes:
Each declaration can be done at « Composition » level or it can beoverloaded by a rule by indicating the statement type and the component that must be overloaded. For example, if for only one RM it’s mandatory to detail, a rule can be established in a model to force the labeling of this RM whatever has been chosen by the user in the drop menu.
Put at the end
This rule displays the RM / SF or FP legal Name at the end of the labelling, and displays its Legal Name.
Formula
It’s possible to filter the components thanks to a SPEL formula.
The available variables are :
- compoListDataItem : the element in the composition ;
- ingListDataItem : the extracted ingredient.
Aggregate and group
Same as in « Aggregate and detail » , apart from the fact that the aggregate is separated from the rest of the labeling. On top of that, the part of the aggreate in the finished product is indicated.
Becomes:
Declare
Enables the declaration of a component, even though, it should not be the case as per standard rules.
For example: water as processing aid. > Water >> Before : wheat flour, water (25%), yeast, salt... >> After : wheat flour, water (28.5%), yeast, salt...
Detail
This rule is not a duplicate of the Declaration Type rule. A declaration type's rule is used for all the label. This rule can be used for a label, a group, one product, one component or more. For example, it can display the raw material followed by its ingredients Example : Milk cream 27 % (Milk 50 , Cream 50)
Declare the legal name
This function enables the declaration of a component legal name for a label group in particular (group 1, group 2...) The declaration will the legal name or the name (cm:name) if the legal name is missing.
The type of declaration, is automatically applied to all labels.
e.g : Use the legal name for the pastry paste:
- Component field : SF Pastry paste
- Group field : Group 1
Result :
Label 1 :
Pastry paste (gluten, egg, milk) 55,28% , wheat flour 28,05%, water 8,98%, sugar 5,78%, yeast 1,12%, salt 0,56%, pasteurized whole egg 0,22%Label 2 : wheat flour 52,25%, water 16,24%, sugar 12,55%, butter 11,62%, egg yolk 3,48%, yeast 1,12%, salt 0,56%, lemon zest 0,48%, pasteurized whole egg 0,22%, natural flavors 0,15%, preservative: potassium sorbate (sa) 0,03%, lactic acid 0,01%
Omit
Omitted components won't be visible and their proportion in the recipe will be changed to zero.
- before: wheat flour 60%, butter : 30% water 9%, sel 1%
- after: butter 75%, water 22.5%, salt 2.5%
Do not declare
"Do not declare" means that the selected component won't be visible in the labeling. However, their proportion in the recipe is taken into account (unlike "Omit").
before : wheat flour 60%, butter 30%, water 9%, salt 1% after : butter 30%, water 9%, salt 1%
Declaration threshold
To set a threshold under which an ingredient is not declared.
Rule Type: Declaration threshold Name: Test Expression: [5]{style="color:blue;"} Components: lemon zeste, butter, egg yolk Group: Choose a group (If you don't choose the group, all the labels will be modified),
before : wheat flour 52.25, water 16,24, sugar 12,55,{color:blue}butter 11,62 , egg yolk 3,48, Orange blossom water 1,45, yeast 1,12, salt 0,56, [lemon zeste 0,48]{style="color:blue;"}*, liquid whole egg 0,22
after : wheat flour 52.25, water 16,24, sugar 12,55,{color:blue}butter 11,62 , Orange blossom water 1,45, yeast 1,12, salt 0,56, liquid whole egg 0,22
Only the ingredients with a proportion under [5]{style="color:blue;"}% and identified by the rule won't be declared.
Ingredient types
Labeling Rules
This rule is executed while chosing a component to be replaced (in the « Components » drop-down box) and its substitute (in the « Replacement » drop-down box). For example, the E250 additive could be used as « antifoaming » rather than a preservative. Thus, in the « Components » field, « E250-Sodium-Nitrite » will be chosen and in the « Replacements » field, « acid » will be chosen.
Becomes:
If the type change concerns the labels generated in a certain language unically, this latter should be specified by selecting it in the language list (cf. « Renaming » part).
Ingredient type specificities:
You can add labeling rules when you create or change ingredient types. It is possible to:
- not declare some types like for example processing aids,
- put an ingredient at the end of the labeling,
To create these rules you have to do the following actions: > beCPG > administration beCPG, > List of values > Types of ingredients > Click on the pencil (on the right, last column, active button)
e.g. acid/ place at the end
Before:
After:
Render
This rule type allows, for example, the creation of a new label. When you create a label, it is possible to attribuate a group (group 1, group2, ....) to the rules. You can associate another rules to the group and as the result to this label.
Many labeling formats exist and are defined by the following formulas that should be mentioned in the « Expression » field :
- render () : displays ingredients and groupings
- render(false): only displays ingredients
- renderGroupList(): ony displays the groupings
- Or any combinations: renderGroupList()+"
"+render(false)
- renderAllergens(): displays the present allergens.
- renderDetectedAllergens(): displays the detected allergens (example: if butter is detected, we will display butter and not milk).
renderAsHtmlTable(): displays a table. Optionnal parameters (styleCss, showTotal)
renderFootNotes(): display footnotes
@beCPG.join(",",locales) : display the label language
Language
« Language » enables to generate labels in different languages. In the « Expression » field, codes linked to labeling languages have to be entered.
Labelings generated into different languages are available this way:
Note : here, the three labels are written in French or in English because translations haven’t been provided. In order to display everything properly, the legal names of each ingredients/ components must be entered in the administration.
For raw materials:
For ingredients:
Format
The “Format” type is often used on the product template to manage the label format. “Format” applies to one or more ingredients or RM's. This means bolding specific words, coloring, italicizing, displaying % ... on a selection of specific words. For a more global application, we advise you to use “Preferences”.
There are 4 defaukt formats :
- Groupings : {0} ({1,number,0.#%}): {2} > Bread : wheat flour, water, yeast, salt ...
- Detailed elements : {0} {1,number,0.#%} ({2}) > icing sugar (sugar, maize starch)
- Ingredient types : {0}: {1} > Preservative : ascorbic acid
- Ingredients (default) : {0} > wheat flour, water, yeast, salt ...
Other examples:
e.g. to write "wheat flour" in red:
- Formula:
{0} {1,number,0.#%} {2} - Components: wheat flour
Result:
wheat flour 24.2 butter 14.52%, sugar 6.78%
e.g. displays ingredients origins ({3}) (also, see "Render" if you are looking for a table for the components and their origins)
- Formula : {0} ({1,number,0.#%}): {3}
- Components: wheat flour
- Result: wheat flour (24.2%) : France, Espagne, beurre, sucre
These « format codes » have to be entered in the expression field. Then, the targeted component have to be selected or the field has to be empty in order to specify the default format. Consequently, it’s possible to display percentages, to put text in bold, in red and so on. Formats can include HTMP.
Preferences
You can associate "Preference" to a group and as a result to a label. The rule will be applicated to the whole label. If you want to be more accurate, you need to use a "format" rule.
Work in volumes
useVolume = true
Display CEE ingredients codes instead of the legal name
showIngCEECode = true
Redefine the separators
defaultSeparator = "; "
groupDefaultSeparator = ", "
ingTypeDefaultSeparator = ", "
subIngsSeparator = ", "
allergensSeparator = "; "
geoOriginsSeparator = "; "
atEndSeparator=","
footNotesLabelSeparator =" <br/>"
Redefine the format
Group format
- # : indicate the number of digits after the decimal point (e.g. ##, 2 number after the decimal point),
- ... : these HTML tags are used to set the text in bold and ( ... to write the text in italic),
- Rounding rules have numbers rounded down : > 18.5% => 18% > 18.6% => 19% > -1.5% => -1% > -1.6% => -2%
groupDefaultFormat = "<b>{0} ({1,number,0.#%}):</b> {2}"
Groups lists format
groupListDefaultFormat = "<b>{0} {1,number,0.#%}</b>"
WARNING : The 4 rules Ingredient format, Ingredient type, Detail format, Ingredient format with sub-ingredient will only work if used in addition with Show origins and Show biological origins.
The following 2 rules (Ingredient format and Ingredient type) are useful if you want to have ingredient country of origin and biological origin. The first 2 rules Ingredient format and Ingredient type have to be combined and are usually set on the finished product template but can only be used directly on entites.
{0} being the ingredient {2} the name of the ingredient and the country of transformation (replaced by the country of origin if the country of transformation is missing) {3} the country of transformation {4} the biological origin
Ingredient format
ingDefaultFormat = "{0} [{3}]"
Format des ingrédient avec type
ingTypeDefaultFormat = "{0}: ({2})[{3}]"
ex: antioxydant : (ascorbique acid , tocopherol )
ingTypeSingleValueFormat="{0} : {2} [{3}]"
ex: antioxidant : ascorbique acid
"ingTypeSingleValueFormat" replace "ingTypeDefaultFormat" when only one child ingredient is present.
Detail format
detailsDefaultFormat = "{0} ({2}) [{3}]"
For compund ingredient detail.
Ingredient format with sub-ingredient
subIngsDefaultFormat = "{0} ({2}) [{3}]"
For sub-ingredient detail (ingredients of ingredients).
Ingredient type with threshold
ingTypeDecThresholdFormat = "{0} [{3}]"
It is also possible to set limits:
Capitalize (example: Water)
<ca></ca>
Have the text in capital letters (example: WATER)
<up></up>
Lower (example: water)
<lo></lo>
Percentage rounding rule
To round down (2.26% --> 2.2%)
defaultRoundingMode=T(java.math.RoundingMode).DOWN
To round up (2.21% --> 2.3%)
defaultRoundingMode=T(java.math.RoundingMode).UP
In the situation where you have 2 decimals #.#5 and wish to round down (2.25% --> 2.2%)
defaultRoundingMode=T(java.math.RoundingMode).HALF_DOWN
In the situation where you have 2 decimals #.#5, and wish to round up (2.25% --> 2.3%)
defaultRoundingMode=T(java.math.RoundingMode).HALF_UP
Show percentages (see below) can also manage rounding rules.
Allergen
Set the allergen in bold , in italic . {#labeling-rules-allergensFormat}
allergenReplacementPattern = "<b>$1</b>"
Format of the allergen when it doesn't appear in the text.
allergenDetailsFormat = "{0} ({2})";
Disable the allergen display for some languages.
disableAllergensForLocales = "ru,ja_JP,zh_CN"
Disable the allergen display for all languages.
disableAllergensForLocales = "*"
Tables
htmlTableRowFormat = '<tr><td style="border: solid 1px;padding: 5px;" >{0}</td>
<td style="border: solid 1px;padding: 5px;" >{2}</td>"
<td style="border: solid 1px;padding: 5px;" >{3}</td>"
<td style="border: solid 1px;padding: 5px;text-align:center;">{1,number,0.#%}</td>
<td style="border: solid 1px;padding: 5px;text-align:center;">{4,number,0.#%}</td></tr>'
htmlTableHeaderFormat = '<thead><tr><th style="border: solid 1px;padding: 5px;" >{0}</th>
<th style="border: solid 1px;padding: 5px;" >{2}</th>
<th style="border: solid 1px;padding: 5px;" >{3}</th>
<th style="border: solid 1px;padding: 5px;text-align:center;">{1}</th>
<th style="border: solid 1px;padding: 5px;text-align:center;">{4}</th></tr></thead>'
htmlTableFooterFormat = '<tfoot><tr><th style="border: solid 1px;padding: 5px;" ><b>{0}</b></th>
<td style="border: solid 1px;padding: 5px;"></td><td style="border: solid 1px;padding: 5px;"></td>
<td style="border: solid 1px;padding: 5px;text-align:center;"><b>{1,number,0.#%}</b></td>
<td style="border: solid 1px;padding: 5px;"></td></tr></tfoot>'
Differenciating the country of origin and the country of transformation
It is possible to differentiate the country of origin from the country of transformation. By default, the country of origin is declared if the country of transformation is not declared. Otherwise the country of transformation is declared.
To do that, you must declare the origins in table format by adding first a render rule renderAsHtmlTable("border-collapse:collapse",false,false).replaceAll("><","><")
Then, create 2 preference rules:
htmlTableRowFormat = '<tr><td style="border: solid 1px;padding: 5px;" >{0}</td>
<td style="border: solid 1px;padding: 5px;" >{2}</td>
<td style="border: solid 1px;padding: 5px;" >{5}</td>
<td style="border: solid 1px;padding: 5px;" >{3}</td>
<td style="border: solid 1px;padding: 5px;text-align:center;">{1,number,0.#%}</td>
<td style="border: solid 1px;padding: 5px;text-align:center;">{4,number,0.#%}</td></tr>'
htmlTableHeaderFormat = '<thead><tr><th style="border: solid 1px;padding: 5px;" >{0}</th>
<td style="border: solid 1px;padding: 5px;" >Transformation</td>
<td style="border: solid 1px;padding: 5px;" >Origin</td>
<th style="border: solid 1px;padding: 5px;" >{3}</th>
<th style="border: solid 1px;padding: 5px;text-align:center;">{1}</th>
<th style="border: solid 1px;padding: 5px;text-align:center;">{4}</th></tr></thead>'
You then get a new column for the country of transformation (the column 5 in the first preference rule).
Yield
The list of ingredients takes the yield in account which means that it gives the exact percentages before cooking.
ingsLabelingWithYield = true
Secondary Yield
The labeling takes into account the yield after re-implementation, i.e. gives the % exact ones implemented after cooking at the customer's premises.
useSecondaryYield = true
Precision
Threshold beyond which the ingredient isn’t displayed
qtyPrecisionThreshold = 0.001d;
When the formt specifies the percentage displays, the system automatically adapts the numbers of decimals based on the quantity. The maximum number of decimals can be configured:
maxPrecision = 4;
Example with maxPrecision = 2
- 3.5% gives 3.5%
- 0.021151% gives 0.02%
- 0.005% gives 0.00%
- 0% gives 0%
Force the sum to 100%
It is possible to configure the system so the sum of rounded values is above 100%. In that case scenario the precision is increased and the adjustement is done on the first ingredient.
force100Perc = true
Burst the type of ingredients
Enables to regroup the ingredients per category, only when ingredients are next to one another in the list of ingedients.
shouldBreakIngType = true
Default : milk, Flavors: strawberry, vanilla, water
With the preference rule : milk, Flavor: strawberry, water, Flavor: vanilla
Label relative to parents
Enables to label the percentages of ingredients in relation to the parent ingredient.
computePercByParent = true
In standard :
If the computePercByParent rule is used :
Rule to create :
Footnote
Allows you to display a footnote after an ingredient.
- in label, declare the marker and the footnote separated by | (double the apostrophes so that it appears on the label) Example:
*|* Organic ingredients
**|** Fairtrade ingredients
To display, the percentage of the ingredient concerned by a claim:
*| * {0,number,0.#%} organic ingredients
- In component, you can select the component on which to display the footnote
- In formula you can use a SPEL formula to condition the display of the footnote Labeling context
This rule must be coupled with the renderFootNotes
Add a quote
To add a quote, for example, to a footnote rule, you must add double quote otherwise it will not be taken into account in the labeling.
Ex : "Product"s label"
HTML elements list
Most of labeling rules can have HTML elements to have a specific form.
Here is the list of some HTML elements:
- Bold
<b> ... </b>
Strong (stronger than bold)
<strong> ... </strong>
Italic
<i> ... </i>
Underline
<u> ... </u>
del : strikethrough text
<del> ... </del>
br: line break
... </br> ...
Span uppercase: all the text in uppercase letters
<span style='text-transform:uppercase'> ... </span>
Span capitalize: first letter in uppecase letter
<span style='text-transform:capitalize'> ... </span>
Span lowercase: all the text in lowercase letters
<span style='text-transform:lowercase'> ... </span>
h style color: color the text
<h style='color:#DC143C'> ... </h>
Example with #DC143C (red) : For other color codes: https://htmlcolorcodes.com/
Please note that you can use these elements directly on legal name.