Business Keys - Recommendations

A business key (also called a primary key) is a column (or a set of columns) that uniquely identifies each row in the data. For example, it can be a customer number in a CRM system or an SKU number for a product. The business key value can come from a single column or can be composed of several columns (to achieve uniqueness).

General Requirements for a Business Key

• It is unique.

• It is always present in the data (i.e., no null values).

• It does not change over time.

Pricefx Recommendations for Business Keys

• Do not use values with national special characters. For details, see Encoding. Also avoid using other uncommon special characters like %, $, " etc.

• Do not use values with leading (or trailing) spaces or other whitespace characters like tabs.

Handling Date / DateTime Attributes in Business Keys

When using PX attributes of type Date or DateTime as part of a business key, be aware of how values are stored and compared when data is created or modified via calculation logics (for example, using api.add()):

• api.add() does not normalize values by attribute type before storing them.

• If you pass a String value for a Date-typed attribute, that exact string is stored, even if the attribute is configured as Date.

• If you pass a Date value, it is converted to a String using the standard ISO 8601 format: yyyy-MM-dd.

Example

Consider a PX attribute attribute2 of type Date, which is part of the business key:

• First row is created with attribute2 passed as a String: "01.01.2026".

• Second row is created with attribute2 passed as a Date object representing 1 January 2026.

In this case:

• The first row stores "01.01.2026".

• The second row stores "2026-01-01" (ISO 8601).

Although both values represent the same logical date, they are different strings, so the system treats them as two distinct business key values and allows two separate rows.

Recommendations

To avoid unexpected duplicates when using Date or DateTime attributes in business keys:

• Always use a consistent date format for business key components.

• For logic-based inserts/updates (e.g., via api.add()), prefer:

  • Passing Date/DateTime values as actual Date objects, or

  • Passing formatted Strings that match the internal ISO 8601 representation (yyyy-MM-dd for dates).

• Do not mix arbitrary date-formatted Strings with Date objects for the same business key attribute.

This behavior is by design and has been relied on in existing implementations. Changing it to auto-normalize values could introduce breaking changes. Therefore, you should handle normalization on the integration / logic side and ensure a consistent representation before writing data.