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

• Cookbook - Pre-integrated Custom Fields

Glossary

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

Naming Pattern for Localization File

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"
      }
  ]
}

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.