Introduction

Supplier Portal already comes with a fix set of attributes for suppliers and users like supplier name or a user's first and last name. In order to be able to improve supplier communication and manage data at a central place, Supplier Portal offers the possibility since PIM 7.1.01 to add and manage additional data fields. This could be user data like:

Contact information, e.g. phone, messenger
Address data
General remarks, e.g. reason for deactivation

User data resides within the Supplier Portal. Data of a supplier is directly linked to repository fields in PIM Core, which also means that metadata like field types are retrieved from there. Supplier fields are for example:

Duns
Iln
or any arbitrary customized reserved field

Persistence of supplier data is managed within PIM Core.

Custom field data are available at multiple places in the UI, e.g. in registration forms or in details views.

Adding User and Supplier fields

Additional fields are managed by configuring the file <INSTALLATION_ROOT>/configuration/dataModelCustomization.json. This is the default path of the customization file. It may be changed via the configuration property dataModelCustomization.file.

Here is an example of a customized data model:

{
    "customUserFields": [
        {
        	"_comment": "Required unique identifier. Has no particular pattern, but we use the same identifier pattern as PIM Service API fieldIdentifiers as a convention.",
            "identifier": "User.Phone",
            "_comment": "for custom supplier user fields you need to add the labels within this configuration file. Add a locale/value tuple for each language you want to support.",
            "labels": [
                {
                    "locale": "de_DE",
                    "value": "Telefon"
                },
                {
                    "locale": "en_US",
                    "value": "Phone"
                }
            ],
            "_comment": "4 different custom field types are supported at the moment: java.lang.String, java.lang.Boolean, java.sql.Date, java.lang.Integer",
            "type": "java.lang.String",
            "_comment": "custom supplier user fields can have a maxLength definition from 1 to 255. If none is defined the default value will be 255. A maximum length restriction is only effective in the ui for java.lang.String types. In such cases entering more characters than the defined maximum will be prevented by ignoring the key press.",
            "maxLength": "255"
        },
        {
        	"identifier": "User.DateOfBirth",
            "labels": [
                {
                    "locale": "de_DE",
                    "value": "Geburtsdatum"
                },
                {
                    "locale": "en_US",
                    "value": "Date of Birth"
                }
            ],
            "type": "java.sql.Date",
        }
    ],
    "_comment": "Supplier data is located in PIM server and need to be contributed there. Don't forget to make the custom field available over the Service API, cause the supplier portal is fetching all the custom supplier fields over the Service API. Only the field identifiers need to be specified, all other information are taken from the PIM Repository.",
    "customSupplierFields": [
        {
        	"_comment": "to add an custom supplier field to the supplier portal, just add it's Service API compatible field identifier within this configuration section.",
            "fieldIdentifier": "Party.Duns"
            
        },
        {
            "fieldIdentifier": "Party.Iln"
        }
    ]
}

The JSON file consists of two sections, one for user data ("customUserFields") and one for supplier data ("customSupplierFields"). Each section contains a list of field definitions.

In general all such custom fields have the same attributes, but the value of some of them cannot be specified via the json file but is determined dynamically. For example whether a field is editable or not is always determined dynamically.

Below is a definition of a well-formed json file for customized fields:

Json Attribute

Mandatory

Definition

customUserFields

No

Contains a json array whereas each element describes a custom user field element.
Such a field element contains following attributes

Json Attribute

Mandatory

Example

Definition

identifier

Yes

User.Phone

Required unique identifier. Has no particular pattern, but we use the same identifier pattern as PIM Service API fieldIdentifiers as a convention.

labels

No, but should contain
entries for each desired
localized language

[ { "locale": "de_DE",
"value": "Telefon" },

{ "locale": "en_US",
"value": "Phone" }

]

Contains a json array whereas each element describes a locale key / value pair for localization of field labels.
Such a pair contains following attributes

Json Attribute	Example	Mandatory	Definition
locale	de_DE	Yes	Locale of the localized field label in the conventional Java pattern - Language in ISO 639 + "_" + country code in ISO 3166-1
value	Telefon	No, but then will contain only field identifier as field label	Contains the field label text that is visible at UI in case user is logged in with that locale.

type

Yes

java.sql.Date

4 different custom field types are supported at the moment: java.lang.String, java.lang.Boolean, java.sql.Date, java.lang.Integer.
The types are displayed in the UI with corresponding widgets, f.e. String as text input field or Boolean as checkboxes. Fields with unsupported types are ignored.

maxLength

No

25

User fields can have a maxLength definition from 1 to 255. If none is defined the default value will be 255. A maximum length restriction is only effective in the ui for java.lang.String types.
In such cases entering more characters than the defined maximum will be prevented by ignoring the key press.

customSupplierFields

No

Contains a json array whereas each element describes a custom supplier field element.
Such a field element contains following attributes

Json Attribute	Mandatory	Example	Definition
identifier	Yes	Party.Duns	Service API compatible field identifier.

Field Permissions

Field permissions have a fix logic for custom user fields and for supplier fields permissions are managed and retrieved within PIM Core. For portal administrator users, the corresponding field permission for the logged in users are respected. For supplier users, the permissions for the configured REST user are used. That means, that all supplier users will share the same field permissions.

User Fields

Visible: Always visible
Editable: Portal admins can always edit such fields, supplier admins can edit data of users of the same organization and other users may only edit their own data.

Supplier Fields

Visible and Editable: A supplier field is only visible or editable when the corresponding user with which the Service API call is made has the appropriate permission (managed in the field rights section in PIM Core).