Custom data

You can expand the normal scope of the SCAYLE Panel by creating custom data fields. Add and manage custom data directly in the SCAYLE Panel or via the Admin API.

Use cases for custom data include:

Adding SEO information
Displaying custom content elements (for example, special banners)
Adding brand Attribute Groups, shop properties, and category properties
Sorting products in the shop front end

Overview

Manage custom data in the SCAYLE Panel Settings area: Settings > General > Custom Data.

The overview page shows different areas for which custom data can be configured. The status indicates whether custom data has already been configured for an area.

*Custom Data: areas for which custom data can be configured*

Add custom data fields

Go to Settings > General > Custom Data.
Go to the appropriate data area and click the Add criteria button.
Click Add Data Field.
Enter a Name and Data Type for each added criterion.
- Name can only contain letters, numbers, dashes, and underscores
- Data types are String, Number, Bool, and JSON
Configure Data Options: Click the gear icon to configure data options (for example, Mandatory, string Character Settings, or JSON Structure ). These depend on the selected data type and can be different validations, supported input formats, and limitations.
- You can define a string as a mandatory field with min. 5 and max. 10 characters. There is a possibility to store it in different languages.
- For translations, you can also define countries for which this information is mandatory; for example: customs information for non-EU countries.
- For store categories, it is also possible to define if a property should be inherited by its subcategories.

Custom data of type JSON can be edited only via the Admin API and not via the SCAYLE Panel due to its special structure.

After custom data fields are added they display on the corresponding pages in the SCAYLE Panel and can be filled based on the configuration.

Example

If a field Show-Header (data type Boolean) is added to the Shop Categories area of custom data, this selection option will display on the Categories page of the SCAYLE Panel.

*Custom Data field "Show Header" on the Categories page*

Delete Custom Data

Click the trash icon to delete custom data. This will also delete the associated data!

Custom data types

The follow table provides details of the custom data types and their options:

Data type	Supported validation options	Supported data	Limitation
`String`	required (bool)	String / Boolean ("true" / "false")	The maximum length is 7000 characters
	minLength (int)	number	This also applies to localized strings
	maxLength (int)
	if `localized` is `true` requiredLocales	array of locales
`Number`	String if an evaluable number is included	number (integers and float)	However, the number must not contain more than 9 digits.
	number
	Boolean (evaluated to 1/0)
`JSON`	required (bool)	JSON	Object keys may only contain letters, numbers, underscores and hyphens. It must not start with a number.
	(optional) JSON schema		- Maximum depth of a JSON object is 4 levels.
	if `localized` is `true` requiredLocales	array of locales	Although null is valid JSON, it is not allowed to set this at the root level.
			The entire JSON object (per locale) must not contain more than 7000 characters.
`Bool`	strings "true", "false", "1" and "0"
	numbers 1 and 0
	boolean

Delete criteria

Criteria can be deleted using the trash icon. This will also directly delete the associated data.

Use cases

Configured custom data is displayed in SCAYLE on appropriate pages and can be filled based on the custom data configuration.

Data fields

You can use custom data to overwrite the automatically generated SEO metadata. To do this, you would add three new fields to the Shop Category entity.

SEO title (type String)
Meta description (type String)
Allow search engines to display this category in search results? (type Boolean)

These fields define a title, description, and whether the category should be indexed.

Data Options

The data fields should not be marked as mandatory (since we would want the overwrite to be optional).
Character Settings should be added (since search engines limit the information displayed).
- The SEO title should be limited to 22 characters and the description to ~155 characters
Depending on your set up and workflow you may also select Allow Translations.
- This should be used if your country has more than one language or if you are setting up the SEO custom data on the Shop Category and not on the Shop Category Country level.

As soon as you save your settings, the custom data is active and can be used. If you navigate to the category tree, the SEO information is available and you can enter the details.

*SEO fields displayed on the Shop Category page*

When the entered data is saved, it will be provided to the shop front end via the Storefront API endpoint.

Category Object

Storefront API Get Category result:

{
    "id": 12,
    "path": "/mens",
    "name": "Men's",
    ...
    "shopLevelCustomData": {},
    "countryLevelCustomData": {
      "display": true,
      "seo-title": "Men's clothing",
      "seo-description": "All season men's clothing",
    }
}

Your frontend team has to implement this behavior in order to make it work. As soon as the custom data object is present in the API, the front end should use this object instead of the default generated one.

Product sorting

Product sorting defines which products are shown at the top of a product list in the shop or shop category. Some possible applications include defining specific product sorting based on:

Country (for example, items popular in country XYZ are placed at the top of the product list for that shop).
Season (for example, a winter sorting is used for specific months).
Campaign (for example, products area featured at the top of the list for a promotion).

With custom data you can assign product sorting entities to shop categories, price campaigns, and other applications.

Define Sorting for a Shop Category

Assign a product sorting to a shop category as follows:

Create Sorting Key: Create a sorting key to be used for the shop category via the SCAYLE Panel (see Sorting Key Creation) or the Admin API.
Add Custom Data Field: Define a custom data field on Shop Category level.
Add Sorting Key to Field: Add sorting key (name: sortingKey, type: String) to the custom data field.

When the entered data is saved, it can be provided to the shop front end via the Storefront API using the sortingKey within the ProductSortConfig parameter (see Get Multiple Products in the Storefront API Guide).

Define Sorting for a Price Campaign

Similarly, you can assign a product sorting to a price campaign. As above, you would define a sorting key and add a custom data field to the Price Campaigns level.

The parameter will then be shown as part of the price campaign creation (see image below).

*Adding a product sorting to a price campaign*

The entered data is provided to the shop front end via the Storefront API through a custom data object together with the campaign data (see Get Campaign By ID in the Storefront API Guide).

Campaign Object

Storefront API Get Campaign by ID result:

{
    "id": 68,
    "name": "Winter Sale",
    "key": "winter",
    "description": "",
    "reduction": 25,
    "start_at": "2023-02-24T11:00:00+00:00",
    "end_at": "2023-03-31T10:00:00+00:00",
    "customData": {
      "sortingKey": "winterSort"
    }
}

Display Category to a Customer Group

A custom data field can be used to display categories only to logged-in customers or specific groups of customers.

To do this, you would create a boolean custom data field in Shop Category or Shop Category Country. To activate the field, select true on the respective shop-category page.

*Adding Custom Data for customer groups*

*Activating Custom Data field for VIP customer groups*

The customer group is retrieved through the Admin API's Get Customer endpoint. In this case, the frontend logic could check if the customer is part of a group (for example, "groups": ["employee"]) or is logged in ("isGuestCustomer": false). If the custom data flag is true (for example, "vip-customer": true), the category would be displayed.

Customer Object

Admin API Get Customer result:

...
"groups": [
    "employee"
  ],
  "status": {
    "isActive": true,
    "isGuestCustomer": false
  },
  ...

Category Object

Storefront API Get Category result:

{
    "id": 12,
    ...
    "countryLevelCustomData": {
        "vip-customer": true
    }
}

Sales or seasonal items might require a custom navigation item.

To add new custom navigation item in the SCAYLE Panel:

Go to Settings > Custom Data > Navigation Item.

Custom Data set on a navigation item is not inherited by its child.