ArticleDomainType

If you create a new module, this entity type should be your first choice when searching for an entity type to build your entity on.

It contains lots of field types of various data types. There are two main types:

• ArticleDomainType<Subentity>.Std_<datatype>_<fieldNumber>

• ArticleDomainType<Subentity>.Res_<datatype>_<fieldNumber>

The existing fields for GDSN modules in the standard are using the ArticleDomainType<Subentity>.Std_<datatype>_<fieldNumber> fields for GDSN attributes. Whereas the ArticleDomainType<Subentity>.Res_<datatype>_<fieldNumber> can be used for enriching those GDSN modules by customizings.

If you create an entirely new module, you are allowed to use ArticleDomainType<Subentity>.Std_<datatype>_<fieldNumber>. If you enhance an existing module, please only use the ArticleDomainType<Subentity>.Res_<datatype>_<fieldNumber> fields.

There is a sub entity called ArticleIngredientLangType. Don't use it. It is a special purpose sub entity only used by the standard.

If your running out of fields, you either create another entity or file a request via Product360 Support for the necessary changes.

ArticleMarketExtensionType

In contrast to the ArticleDomainType the ArticleMarketExtensionType has a different set of logical keys. It has a PartyProxy logical key, but misses the two <entity>.LK.Std_LK_<datatype>_<keyNumber> logical keys. It depends on your module which entity type to choose.

ArticleDomainExtensionType

Don't use this entity type. It is deprecated.

Available ArticleDomainType sub entity types

ArticleDomainType has several sub entity types commonly used in GDSN for different purposes

• ArticleDomainLangType
  Entities based on this entity type contain language specific data. It is similar to ArticleLang and has logical keys EntityId and Language.

• ArticleDomainUOMType
  Entities based on this entity type usually contain measurement values - a numeric value combined with a unit. The key UOMType can have the one of the values "metric" and "imperial". It is based on the assumption that different metric units like gram and kilogram can be converted in each other and therefore it would be an error source to store values for both units. But it may not be possible to automatically convert from metric units into imperial units.
  Example:ArticlePackagingUOM.PackagingWeight and ArticlePackagingUOM.PackagingWeightUOM

• ArticleDomainPartyType
  Entities based on this entity type usually contain data related to a party like customer specific data.

• ArticleSubDomainType
  Entities based on this entity type usually contains data that together forms a list.
  There are subentities supporting language specific data and measurement values for each list entry.
  Example: ArticlePackagingMaterial contains a list of different packaging materials. A bottle of wine may be packaged in a hardwood box, padded with hemp fibers and surrounded by a cardboard box.

Wizard

Included in the Repository Manager are wizards helping you to create sub entities, fields, logical keys etc.

Create the entity of your module

There is nothing special to a GDSN module entity. It should support standard functionality like:

• Import

• Export

• Merge

• Clone

• Search

• Data Quality

• Service API

Mandatory properties

First of all you need an identifier for your field. If there is no reason not to comply to the rule, this will be the same name as in the GDSN documentation. A Product 360 convention is that all fields of type Boolean start with the prefix "Is", e. g. "IsBaseUnit", "IsService", "IsConsumerUnit". As you can see in the examples, another convention is to use camel case for field identifier consisting of multiple words.

Next you have to choose a field type. Make sure the field type is not in use already. If you're using ArticleDomainType, you have to be careful with text field types. ArticleDomainType.Std_Text100_01 to ArticleDomainType.Std_Text100_10 have upper bound -1 meaning these are list types. Please always try to use a type field which is already configured as list/single value according to your needs.
If you have a list of values, choose a string field type so that the whole list can be put in the single database field. To choose the correct length for a field, multiply the length of a single value including a separator between the values with the number of expected values.

Example: If you have a field with an enumeration with four entries and the key of each enum entry is a single character, then it is safe to use a Std_Text10_<number> field.

Make sure the chosen field type is activated in the types area (Inactive = false).

If this field does not correspond to a non editable logical key, you should check that Editable = true is set.

Language specific properties

In order to see the field in the UI, it needs at least a name. You can define a name from top which is for example shown in the main table and normally includes the logical key values. For more information see section "Referencing on logical keys in field names" of the above mentioned documentation.

The description will be displayed as a tool tip in the field selection dialog and in the import. In general there is an English description in the GDSN documentation which should be used.

• Make sure the description is really a description of the data that should go in this field. Read the description before you add it to Product 360. Delete meaningless information like "0 to 80 character text field" or "Choose value from the drop down". This information is stored elsewhere in the repository.

• Use a meaningful description or leave it empty.

• If the description is a complete sentence, end it with a '.', if not don't use a '.'.

All labels have to be externalized in your client languages. For more information see section "Multi-language support of the repository" in the above mentioned documentation.

There is also a field documentation in the repository. The value of this field does not appear in the UI and does not need to be internationalized. It can be used for any documentation purpose and will be visible in the Repository Manager .

Support different functionalities

There are some properties defining if a certain field supports a specific functionality which are self explaining like "Cloneable", "Mergeable", "Searchable" and "Supports Data Quality".

Constraints

Occurrences: The properties "Upper Bound" and "Lower Bound" define how many values can be stored here.

• For a mandatory value set both properties to 1.

• For a non-mandatory field with one value set lower bound = 0 and upper bound = 1.

• For a list of values set lower bound = 0 and upper bound = -1.

You can define if it should be an INFO, a WARNING or an ERROR in case the upper or lower bound is not met. Normally this should be set to ERROR, otherwise the system will store these values regardless of the field configuration.

Valid value lists: There are two places where you can add an enumeration to the field.

• Enumeration - The value of this field must be one of this enumeration. Otherwise the user will get an error and the value won't be stored. If the database already contains values not contained in the enumeration these will no longer be displayed in the UI.

• Proposal Enum - Use the proposal list if the user is allowed to store values which are not contained in the list.

Since the enumeration keys are stored as the values for this field, the chosen field type has to have a matching data type with the key class of the enumeration.

Field length: GDSN often defines the max. field length.

• For string values use the properties "Min Length" and "Max Length". Make sure the values you choose here are not lower resp. higher than the min. and max. length in the types area for the corresponding field type. If the field contains a list of values (upper bound = -1), the min. and max. length refer to a single entry, not the entire list.

• For numeric values the "Min Length" and "Max Length" are not used. If you want to restrict a numeric value you have to use "Range Min" and "Range Max". Make sure the values are not lower resp. higher than the min. and max. range defined for the corresponding field type. The decimal separator used here is '.'.
  You can define how many decimal places should be displayed in the UI by using the property "Scale". The displayed value will be rounded. Note that this is only a matter of presentation. In the database all decimal places given in the UI are stored.
  To ensure that only values in the defined range will be stored, set "Validation Severity Range" to ERROR. The default value is WARNING.

• For dates also use "Range Min" and "Range Max". This is an example of the pattern you have to use: "yyyy-MM-dd HH:mm:ss". For example: 9999-12-31 23:59:59

If you don't restrict the values in the custom area the default values from the corresponding field type will be used.

Transitions: If you store a proxy in the field and you want to make fields of the proxy available (for example in the field selection dialog) you can set the matching root entity to the property "Proxy Transition Entity". More information about transition fields can be found in the knowledge base article at chapter "Transition fields - Group name" of the Product 360 Documentation.

Presentation

"Visible" and "Visible From Top":

• Your field belongs to a deactivated logical key: Set "Visible" and "Visible From Top" to false. The field should not appear in the UI.

• Your field belongs to an activated logical key: Set "Visible" to true, so it will be visible in the sub entity views. Set "Visible From Top" to false since we don't want fields which have to be qualified with the value they contain in the main table.

• Your field doesn't belong to a logical key: By default set "Visible" and "Visible From Top" to true. The field should be available in the main table as well as in the sub entity views.

In order to have a display name in the UI, don't forget to fill in the property "Name" if "Visible" is set to true and property "Name From Top" if "Visible From Top" is true.

View configuration:

You can configure that a field is present in the default configuration of the corresponding sub entity view. Set "Display By Default" = true. This configuration will be overwritten by the layout stored in the client's workspace. You can also configure in which order the fields should appear in the table using "Default Column Order". The index is 0 based.

You can do the same for the main table using "Display By Default From Top" and "Display Column Order From Top". However this is not recommended for GDSN modules.

Miscellaneous

Default value: In case you create a field belonging to a logical key that is not editable, not only the logical key needs a default value but the field needs the same default value. The default value may also make sense for other fields, especially for mandatory fields.

Repository.repository vs. EnumFragment.repository

The "Repository.repository" file contains all enumerations used by repository fields. For GDSN or food and beverage enumerations the repository only contains the definition of the enumeration. The actual enumeration entries are contained in a second file called "EnumFragment.repository". This will keep the repository more organized because there are some GDSN valid value lists with high numbers of entries.

Create enumeration

Use the Repository Wizard of the Repository Manager to create a new enumeration.

Use an identifier that makes it easy to find the corresponding field.

Usually you need to use the key class "string" when creating an enumeration for GDSN.

Enter the properties identifier in the fields "Name" and "Description", shown in the third screen. They should have the pattern %enum.<identifier without substring 'Enum.'>.<name|description> as can be seen in the screenshot above. There is no "Name from top", but name and description should be provided at least in English. In case you are using more client languages, please maintain those names in the according "repository.properties" file for your language.

Copy the enumeration into "EnumFragment.repository" in order to add entries in the next step.

For a good trace-ability of your enumeration definition, it is recommended to add a documentation to your enumeration in the "Repository.repository" file: "Enumeration entries are defined in EnumFragment.repository".

Add enumeration entries

Key synonyms come in handy if there are multiple different values in the data source which should result in the same value in Product 360.

Example: Enum.Language contains enum entries with synonyms. For example you can import "deu", "ger", "de" or "de_DE" and either value will result in the language key 7 in the system.

Make sure the label is externalized and available in English and your required client languages.

Delete enumeration entries

In a customizing, it is allowed to delete enumeration entries.

Example: If your customer is a manufacturer of vegan food, you may want to delete the enumeration entry "MEAT" in Enum.DietTypeSubcode in order to reduce false data entered by accident.

Be aware that if the keys of the entries you delete are already in the database or could be imported from another system, these values won't be displayed anymore.

Scopes on enumerations and enumeration entries

You may have seen parameters at enumerations or enumeration entries named "scope".

You should not change it or create such parameters at your enumerations or enumeration entries. Those parameters are needed for internal purposes only; they are used to make automatic repository adjustments during startup according to the configuration defined in "application_modules.properties" file.

Create enumerations with optional code

If you have to enable a mandatory field with a valid value list to get "no value" for an entry (such fields are usually logical key fields), you have to use an enumeration with optional code(s). Such enumerations provide all values of the corresponding valid value list and one or more values that will not be transferred to the GDSN pool.

First you create an enumeration as described above, the empty enumeration definition in "Repository.repository" and the entries in "EnumFragment.repository". Then you create a second enumeration with an identifier like "<Identifier of first enumeration>.WithOptionalCode". That second enumeration gets an entry standing for "no code". All other enumeration entries will be used from the "parent" enumeration.

Define the enumeration using a base enumeration

If you have to adjust the corresponding export template to transfer item data to the GDSN pool you should use the EnumerationKeyStandard export function. Details on that function can be found in the "Technical details" chapter of this GDSN documentation.

Use export function to output only valid GDSN values

GDSN unit categories

The GDSN units are separated into categories. One unit can be in different categories and one field can have valid values of multiple categories.

A list of units and their category can be seen in the Units perspective of Product 360. Select the GDSN unit system and add the field "Category" with the field selection dialog. Make sure to qualify the "Category" field with the GDSN parameter.

Use an existing unit enumeration

In order to use a category at a specific field it is necessary to use an unit enumeration. Product 360 has predefined enumerations named after the categories for the IM data pool. In order to map a unit enumeration to a specific field it is best practice to use the Repository Manager.

Creating new unit enumerations

When the predefined unit enumerations do not meet the requirements of the field you want to add, it is possible to create a new enumeration in the repository by using the Repository Manager and include all categories which are needed separated by a ",".

It is important that the unitSystem property matches the unit system which should be used for the enumeration. The standard GDSN unit system is 70.

After creating the unit enumeration it can be referenced as enumeration at a field as shown above.

Creating a custom unit system

When the predefined unit categories are insufficient or not usable for your project, it is possible to create a custom unit system based on the GDSN unit system. To do this simply copy the GDSN unit system in the Units perspective.

After that it is possible to add or modify units and their categories for your needs in the Unit maintenance view.

To use the unit system created this way some additional steps have to be done in order to use it in the whole application:

Create a new unit

If a unit is missing in the GDSN unit system and is available in the official GDSN documents please contact the support as they will provide a database script to add the unit.