Implementing new Customer Extra Field Extension

From this article you will learn how to declare ERP customer extra fields so they are loaded by Sana and exposed to the webstore and add-ons.

Please use the following reference articles for more details about the extension infrastructure:

About customer extra fields and this extension point

In ERP systems, the customer entity often includes extra fields (custom attributes) beyond the standard set.

The Customer Extra Field Extension provides an extension point for declaring which Customer extra fields should be exposed. Sana matches declared field names against ERP metadata for the Customer entity, loads their values when customer data is retrieved, and makes them available through the APIs described below.

Under the hood

Here is how the flow fits together in Sana:

For each enabled add-on, Sana discovers implementations of CustomerExtraFieldExtension and collects their FieldName values.
The collected names are intersected with the Customer entity fields defined in ERP metadata. Only fields that exist in metadata are loaded.
When the current user is authenticated, the customer record is loaded including those extra fields.
The webstore client maps this data into application state; in the ADK you can read it from useAppContext under user.extraFields (see Reading values in TypeScript).
On the server, extension code that receives WebstoreUserInfo can access optional customer data including the same extra fields (see Extension context on the server).

Implementation

Use case

This guide demonstrates an end-to-end example where ERP customer field CustomerDateField is exposed and rendered in a webstore content block.

The full flow is:

Add-on declares the field via CustomerExtraFieldExtension.
Sana backend discovers enabled extensions, validates field names against Customer entity metadata, and loads field values.
ADK useAppContext(['user']) exposes user.extraFields as { name, value }[].
Content element renders the value.

Step 1: Declare the field in backend extension

Create an extension class in your add-on:

using Sana.Extensions.Customers;

public class DateCustomerExtraFieldExtension : CustomerExtraFieldExtension
{
    public override string FieldName => "CustomerDateField";
}

Reference: CustomerExtraFieldExtension reference.

Note

Replace placeholder names in samples with the actual ERP field names configured for your environment.

Step 2: Read field from ADK app context

In your content block component, read user.extraFields and find CustomerDateField:

import { useAppContext } from 'sana/context';

const { user } = useAppContext(['user']);
const dateField = user?.extraFields?.find(field => field.name === 'CustomerDateField');

Type mapping note:

In ADK, value is string | boolean | number.
Date and DateTime values are exposed as string.
For CustomerDateField, expect a string like "yyy-mm-dd".

Step 3: Render value in UI

Example content block component:

import { memo } from 'react';
import { useAppContext } from 'sana/context';

const AddCustomerExtraField = () => {
  const { user } = useAppContext(['user']);

  if (!user?.extraFields?.length)
    return null;

  const dateField = user.extraFields.find(field => field.name === 'CustomerDateField');

  if (!dateField?.value)
    return null;

  return (
    <div>
      Customer date field {dateField.name}: {dateField.value}
    </div>
  );
};

export default memo(AddCustomerExtraField);

Limitations

If the user is not authenticated or has no account id, extra fields are not returned.
Only fields that are declared by enabled CustomerExtraFieldExtension implementations and exist in ERP metadata for Customer are loaded.
Only fields with non-null values appear in the loaded set.

Table of Contents