Collect information

The customer is a manufacturer and uses the data source scenario, so let's have a look at "1WorldSync Item Management - Data Source 1WS XML Guide".

When we search for "Microbiological" we first find this line

What does it mean?

1WS Catalogue Request Attribute: This means, that a structure element with the name foodAndBevMicrobiological exists. The structure type is "AGM" which stands for "attribute group many" and indicates that it contains a group of attributes and can occur multiple times in the XML of the Catalogue Request file that is sent to the 1WS Pool.

1WS XML Structure Type: The structure type "AGM" corresponds to the information "FLX: Y" which means that the attribute is a flex attribute. Flex attributes are a generic way to include attributes in the XML structure.

This is an example of how a flex attribute will look like in the XML of the Catalogue Request file:

Here's a list of other structure types, just to give you an idea:

• A - attribute

• AM - attribute many

• AQ - attribute qualified

• AGM - attribute group many

For further information on flex attributes and structure types see explanations and examples in "1WorldSync Item Management - Data Source 1WS XML Guide".

1WS Item Structure Type: The "O" tells us, that the attribute group is optional.

Module: In the "Module" column it says "FoodAndBeveragePropertiesInformation", so there is no separate module for microbiological information. We should have a look at what else is contained in the "FoodAndBeveragePropertiesInformation" module in order to decide how to design our entities. We note that down and go on for now.

Next we find four lines that seem to be fields

What information do we get here?

In the group "foodAndBevMicrobiological" there are four fields

1. The attribute "organismCode" which is a simple string attribute with a max. length of 80 that is optional.

2. The qualified attribute "organismMaximumValue" which is a decimal value with a min. length of 15 and a max. length of 15. The Qualifier "uom" is an indicator that we need another field to store the value for the qualifier. In some cases, like for example the language, the qualifier can be a logical key.

3. and 4. are the qualified fields "organismReferenceValue" and "organismWarningValue", both qualified with a unit, both decimal, both optional, both with a min. length of 33 and a max. length of 2. Well, the length can't be correct. We should check that later in the Participant dictionary. Write that down and go on.

If we keep searching we find these lines

If you compare this set of fields with the ones we found before you will notice that the attribute names are the same but the paths are different. The module is different, too. It's "ComponentInformation".

Components are a MjR3 feature that we don't support at the moment, so ignore these fields. If you want to know more about components have a look at the GDSN homepage (http://www.gs1.org/gdsn).

Get a better idea of the structure

Since the fields we found are flex attributes, we won't see much of them in the IM XSDs. Sometimes it's hard to imagine the complete structure of a module based only on the textual information given in the table. But we can get a little help from the GDSN XSDs to get a better idea how the structure might look like.

If we look at the "FoodAndBeverageInformationType", marked in the green we see the occurrences are "0..*", so we can have multiple entries for "FoodAndBeverageMicrobiologicalInformation". This means we have to find a logical key for our data model. We have the organismCode. Since the rest are measurement values, it seems to make sense to have one set of values for each organism. So this is a good candidate for a logical key.

In GDSN there is only the "organismMaximumValue". We also found that field in the "1WorldSync Item Management - Data Source 1WS XML Guide" but additionally there were "organismReferenceValue" and "organismWarningValue". In the XSD we can see that there is an additional "unitOfMeasure" belonging to the "organismMaximumValue". This is no surprise, we already saw that the fields are qualified with a unit and knew that we needed to store this information somewhere.

So let's recap:

We have the "foodAndBeverageMicrobiological" module, which is an attribute group many. This sounds like an entity, doesn't it?

We have identified the fields

• organismCode

• organismMaximumValue

• organismMaximumValueUOM

• organismReferenceValue

• organismReferenceValueUOM

• organismWarningValue

• organismWarningValueUOM

We also know that "organismCode" is a candidate for a logical key.

Design the entity

You don't know yet, but it will be described in the section "Data model" that there is the entity type ArticleDomainType that is suitable for implementing new modules and that has a sub entity for measurement values. There is an additional key UOMType. Possible values are: METRIC and IMPERIAL. We need to be able to store multiple values, but since units are convertible we don't need to store each and every value we might be using in an output. That's the reason we don't use the unit as the logical key.

So what we have to do is to create an entity like this:

• Entity: ArticleMicrobiological (based on ArticleDomainType)

  • Logical key: organismCode

  • Field: organismCode

  • Entity: ArticleMicrobiologicalUOM (based on ArticleDomainUOMType)

    • Logical key: UOMType

    • Field: UOMType

    • Field: organismMaximumValue

    • Field: organismMaximumValueUOM

    • Field: organismReferenceValue

    • Field: organismReferenceValueUOM

    • Field: organismWarningValue

    • Field: organismWarningValueUOM

Now, we have the basic structure of our sub entity.

Check the details

Now, we have to check for the details. The details can be found in the Participant dictionary.

Search for the attributes we found earlier:

foodAndBevMicrobiological/organismCode

GUI Name: Organism Code

This is your English display label. By convention in Product 360, the first letter of the first word is upper case, all following words start with a lower case character except it is a name or another word which is correctly spelled with an upper case character in English.

IM XML Name: foodAndBevMicrobiological/organismCode

This is where you find the path given in the Data Source XML Guide

GDSN XML Name:

Where you find it in the XSDs of the GDSN XML structure.

Mandatory/Optional:

Most of the fields are optional, some of the fields are "M within O group" which means they are mandatory if you form the group. These fields can be set to mandatory in the repository (upper and lower bound = 1). Check if these fields are suitable as logical keys.

Definition:

This is your description in English. Read it, correct it, if it is a whole sentence add a '.' at the end and if there is no valuable descriptive content in there, don't use it.

Datatype: VV/FNBOrganismCode

"VV" means there is a valid value list. "FNBOrganismCode" is the name of the list. The values will be found on the tab "IM Valid Values". Valid value lists most likely contain strings.
Other common data types apart from valid value lists are dateTime, uinteger and ufloat.
→ We need to add an enumeration to the repository as well.

Min. length and max. length:

The field can have values of strings with a length up to 80. Even they say the min. length is 1, since the value is optional I would use a lower bound of 0.

Global/Target market specific: Target Market

Defines if it is possible to maintain different values for different target markets.
→ We need an additional target market key.

Occurrence: 0..1

This can be a problem if we want to use organism code as a logical key. Logical keys are mandatory.

foodAndBevMicrobiological/organismMaximumValue

Most of the information is similar to the above.

The data type is ufloat and the columns of the min./max. length are called "Length (All floats), Min. Length (All non-float Data Types)" and "Precision (All floats), Max. Length (All non-float)". This explains the values 33/2 which made no sense earlier.

Example: Imagine an attribute defined with 15/15. What this means is that 1234567890,12345 is valid and 12345,1234567890 is valid but 12345678,12345678 is not valid because the complete length is greater than 15.

Product 360 can't persist such huge numbers. A BigDecimal16/6 is always used which means the complete number is at most 16 places long - 10 places before the decimal separator and 6 decimal places. However, if the definition is for example 5/2 the max. range should be set to 99999,99 with scale 2. Be aware that this means you can store 88888,888888 in the database anyway because the scale is just a matter of formatting.

foodAndBevMicrobiological/organismReferenceValue and foodAndBevMicrobiological/organismWarningValue

Most of the information is similar to the above.

Have a look at the length and precision. Here in the Participant dictionary it says 15/15 not 33/2 as it did in the Data Source XML Guide. This is an example of conflicting documentation. Note this on your test list and send dummy data to the data pool later. Determine what is correct on the error messages you get back from the data pool.

UOM

We know we need the unit fields as well. We won't find them as separate lines in the participant dictionary, only as qualifier in the line of the attribute they belong to. At a first glance you might wonder how you will be able to create the field with so little information. However since units will always be stored as UnitProxies and corresponding field types are already provided in the ArticleDomainUOMType, there is not much left to be configured.

The only question we have to answer is, which units should be available to the user or in other words which enumeration do we need to add to the unit field. If we go back to the Participant dictionary there is no VV entry in the datatype column, which makes sense because this line is about the measurement value that is a numeric value.

But there are two other columns which will give us the answer we need. There is the qualifier type "uom" and "Qual Valid Value List" "uom". If you go to the tab "IM Valid Values" you will find a list with that name. In the" Attribute Name" column of that tab you will also find the "organismWarningValue" attribute and the other value fields. Check the existing enumerations if there is already one with the matching values or create your own. See section "Data model" for information how to do that.

Logical keys

Let's come back to the hardest decision. What do we use as logical key(s)?

• Do we need a logical key?
  Yes, foodAndBevMicrobiological is AGM, so we need to be able to store more than one set of values per target market.

• Why should we use organismCode as logical key?
  It makes sense to have one set of measurement values per organism. It doesn't make much sense to have multiple warning values for the same organism from a business point of view.

• Why shouldn't we use organismCode as logical key?
  Because organismCode is optional. This means GDSN allows to have measurement values not belonging to one of the organisms in the valid values list.

• Is there an alternative?
  Can't think of one.

What is the solution then?

The solution is to use "organismCode" as logical key but tweak the valid values a little. Make an enumeration "with optional code". This enumeration has one or more additional values. Most standard enumerations with optional code have one additional value, for example "NONE". This allows the user to store additional value sets, it works with all the generic mechanisms in Product 360 and in the export there is a mechanism which will ensure that this value is not sent to the GDSN data Pool. How many additional entries (if at all) you need depends on the requirements of the customer.

See how to create an enumeration with optional code in the chapter "Data model".

See how to handle enumerations with optional codes in the export in section "Technical details".

Compacting the structure

At the beginning we saw that the attributes related to microbiological information belong to the module "FoodAndBeveragePropertiesInformation". We ignored that up to now. But you might ask yourself if you have to fit a complete module into one Article sub entity.

The answer is definitely 'no'.

Let's see what else is contained in the module "FoodAndBeveragePropertiesInformation": What we find are physiochemical properties.

Does this information have a relation to microbiological information?
No. So we probably can implement the physiochemical properties in its own sub entity. When we look at the GDSN XSDs, we get a confirmation of our assumption. FoodAndBeverageMicrobiologicalInformationType and FoodAndBeveragePhysioChemicalCharacteristicType are two separate types on the same level as FoodAndBeverageAllergyRelatedInformation and FoodAndBeverageDietRelatedInformation.

Ways to ensure data consistency

In the course of creating the data model, you should start thinking about data consistency or in other words validations.

There are two sources for information about validations. The Participant dictionary contains a lot of basic validations like the max. field length. Complex validations, you have to take into account for the design of your entity, are listed in the "IM Validations Document".