Document Tree
Document Properties
Kbid
3M1102
Last Modified
20-Dec-2023
Added to KB
20-Dec-2023
Public Access
Everyone
Status
Online
Doc Type
Concepts
Product
  • ICM 11
  • ICM 12
Concept - Pre-integrated Custom Fields

Introduction

In modern software development, adaptability and customization are of great importance. In response to this requirement, Intershop introduced pre-integrated custom fields.
These serve as a dynamic solution that allows developers to easily define new attribute fields that can be seamlessly integrated into the checkout process.

To manage these custom fields, Intershop provides a versatile key-value entry system within a property file.
Each of the configured custom field contents is stored in the parent object's AV table by default, and an admin user can disable or enable it depending on the channel application.

References

Glossary

Term

Description

scope

Area or subject to which the custom fields will be added. Currently only basket, basket line item, order and order line item are supported.

application

See Concept - Application.

Configuration of Custom Fields

A dynamic mechanism allows developers to configure custom fields and add them to the checkout process by adding key/value pairs to a configuration file.

The configured fields are available to all channels in the environment and are not enabled by default. How to enable them for a specific application is described in the next section. The required configuration can be provided to the configuration framework as key/value pair content via property file. This document uses a property file named customfields.properties as an example.

The configuration file customfields.properties is a simple resource bundle and uses the following structure:

intershop.checkout.customfield.<name>.type=<type>
intershop.checkout.customfield.<name>.position=<position>
intershop.checkout.customfield.<name>.scope.<scope>.isEditable=<true|false>
intershop.checkout.customfield.<name>.scope.<scope>.isVisible=<true|false>

The names of the fields are supported by property files that manage the localization text for the user display, as shown in the following example:

customfield.<name>.displayName=<A label displayed on the UI to identify the attribute>
customfield.<name>.description=<Textual information aiding user comprehension>

Key Definition Parameters of Configuration

Term

Description

intershop.checkout

Prefix that indicates that the key-value is to be used in the basket checkout.

.customfield

Indicates that it is key-value for custom field functionality.

<name>

This is the developer-defined identifier name of the custom field. It will be used as the property name in the database and for REST APIs (no whitespaces allowed) and has to be unique.

<type>

This is the data type for the custom field (e.g., "String"). Currently only 'String' is supported.

<position>

This is an integer specifying the display order position of the custom field in the UI, to allow a consistent arrangement of custom fields.

<scope>

This is the scope of the custom field; multiple scopes can be configured for one custom field; currently supported scopes are 'Basket', 'BasketLineItem', 'Order', 'OrderLineItem'.

.isEditable

If "true", indicates that the custom field should be editable in the UI and it can be changed using the Rest API.

.isVisible

If "true", indicates that the custom field should be visible in the UI.

Naming Pattern for Localization File

Term

Description

customfield.<name>.displayName

Specifies the custom field label that should be visible in the UI (for localization purposes, this key value should be added to the resource bundle).

customfield.<name>.description

Specifies the custom field description that should be visible in the UI (for localization purposes, this key-value should be added to the resource bundle).

Back Office Custom Fields Configuration

After the custom fields are defined they can be enabled/disabled by a system admin user in the application of a channel.

In the back office system of any channel application, under the "Cart and Checkout" tab, there is a configuration area to enable or disable predefined fields.

To access the configuration area where you can enable or disable predefined fields, do the following:

  1. Open Intershop Commerce Management.

  2. Switch to your channel.

  3. Open Applications from the navigation bar and open your application.

  4. Switch to the Shopping Cart & Checkout tab.

Here you can find a configuration section Custom Field Settings where you can enable or disable custom fields. Furthermore, the localized texts for the custom fields are displayed here.

Orders with Custom Fields Configured

Custom fields for orders and line items can be configured to be displayed on the corresponding detail page in the storefront. Furthermore, they are presented in the Custom Fields section of an order’s details in Intershop Commerce Management.

Rest API and Custom Fields

Retrieving Configured and Enabled Custom Fields

For a REST client to be able to access the fields in the storefront, the configured custom field definitions must be published.

For registered customers, custom fields can be accessed via the Customer REST API. For users who do not have a customer profile (anonymous users), the Configurations REST API enables access to fields that are available for the selected shop.

 {baseUrl}/customers/<customer-id>
 
 {baseUrl}/configurations

An example of the custom fields element of a JSON response can be found below. The JSON example shows a configuration for two custom fields named commissionNumber and deliveryNote:

...
"customFieldDefinitions": [
    {
        "description": "Information for the Commission Number",
        "displayName":"Commission Number"
        "name": "commissionNumber",
        "position": 1,
        "type": "String",
        "scopes":[
            "isEditable": true,
            "isVisible": true,
            "name": "BasketLineItem"
        ]
    },
    {
        "description": "Information for the Commission Number",
        "displayName":"Commission Number"
        "name": "commissionNumber",
        "position": 1,
        "type": "String",
        "scopes":[
            "isEditable": false,
            "isVisible": true,
            "name": "OrderLineItem"
        ]
    },
    {
        "description": "Information for the Delivery Note",
        "displayName": "Delivery Note"
        "name": "deliveryNote",
        "position": 42,
        "type": "String",
        "scopes":[
            "isEditable": true,
            "isVisible": true,
            "name": "Basket"
        ]
    },
    {
        "description": "Information for the Delivery Note",
        "displayName": "Delivery Note"
        "name": "deliveryNote",
        "position": 42,
        "type": "String",
        "scopes":[
            "isEditable": false,
            "isVisible": true,
            "name": "Order"
        ]
    },
    ...
],
...

Within this configuration, custom field definitions closely resemble the checkout settings. These definitions are crucial for the implementation of REST clients, as they provide descriptive names and specify where these fields should be displayed.

As shown in the example, the "Delivery Note" refers to the basket, and the "Commission Number" refers to the items in the basket. The same fields are also assigned as read-only elements to the order and its items.

The following section shows how to integrate these configurations in a checkout process.

Integrations into the Checkout Process

As soon as the fields are enabled they can be used in the checkout. This means that the fields at the basket and their line items can be viewed/edited there. The values are automatically transferred to the order/item if the configured fields are also enabled for the order and its items with the same name. This way, they can be accessed later using the same key.

Adding and Updating Custom Fields

Once the configuration is ready, when creating or patching a basket using the POST /baskets endpoint, it is possible to include specific custom field user values by adding a body JSON as shown below. Note that the custom fields basketNote and deliveryNote are configured as editable, visible, and part of the scope basket.

{
  "customFields": [
      {
          "name": "deliveryNote",
          "value": "my note for the supplier",
          "type": "String"
      },
      {
          "name": "commissionNumber",
          "value": "CN.123",
          "type": "String"
      }
  ]
}

Element

Description

customFields

Lists the custom fields attributes.

name

The name of the custom field.

value

The value to be persisted for the custom field referenced by the attribute name

type

The type of the custom field value. At the moment only String is allowed.

This means that a new basket is created and contains values for two custom fields available for the basket scope. The handling for the other resources with the option to attach custom fields works in a similar way.

Error Handling

In case a custom field cannot be edited or is not available for the scope given in the payload of the create/edit request, the response will contain a JSON element named info with a code and a message. The request itself will not fail.

If the above basket request had an additional custom field named commissionNumber that was not available for scope 'basket', the response would contain an element similar to the one below:

...
"infos": {
  "causes": [
      {
          "code": "commissionNumber_not_found_info",
          "message": "The custom field with the name commissionNumber does not exist or is not editable in the current scope",
          "parameters":[
              "name": "commissionNumber",
              "scope": "Basket"
          ]          
      }
  ]
}
...

In a similar way, the behavior described above is also applied to the creation of basket line items.

Integration into After-Checkout Processes

Note that the custom fields and their values entered during the checkout process are automatically included by the export services in the ICM and in the checkout confirmation email.

Disclaimer
The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.
The Intershop Knowledge Portal uses only technically necessary cookies. We do not track visitors or have visitors tracked by 3rd parties. Please find further information on privacy in the Intershop Privacy Policy and Legal Notice.
Home
Knowledge Base
Product Releases
Log on to continue
This Knowledge Base document is reserved for registered customers.
Log on with your Intershop Entra ID to continue.
Write an email to supportadmin@intershop.de if you experience login issues,
or if you want to register as customer.