PERS SDK - v2.3.26 / Exports / CustomFieldDefinitionManager
Custom Field Definition Manager - Manage tenant-specific custom fields
Provides CRUD operations for custom field definitions that extend the built-in user profile fields. Custom fields are defined per-tenant and can be used for additional user data collection, redemption requirements, and form validation.
Example
// List all user custom fields
const fields = await sdk.customFields.getDefinitions();
// Create a new custom field
const field = await sdk.customFields.createDefinition({
key: 'employee_id',
label: 'Employee ID',
fieldType: 'text',
validation: { required: true, pattern: '^E[0-9]{5}$' }
});
// Update a field
await sdk.customFields.updateDefinition(field.id, {
label: 'Company Employee ID'
});
// Delete a field
await sdk.customFields.deleteDefinition(field.id);Example
// Validate user custom data against definitions
const definitions = await sdk.customFields.getDefinitions();
const errors = sdk.customFields.validateUserData(
{ employee_id: 'INVALID' },
definitions
);
if (errors.length > 0) {
console.log('Validation errors:', errors);
}- getDefinitions
- getDefinition
- createDefinition
- updateDefinition
- deleteDefinition
- resolveSelectOptions
- validateUserData
- validateFieldValue
• new CustomFieldDefinitionManager(apiClient, events?): CustomFieldDefinitionManager
| Name | Type |
|---|---|
apiClient | PersApiClient |
events? | PersEventEmitter |
managers/custom-field-definition-manager.ts:83
▸ getDefinitions(options?): Promise<CustomFieldDefinitionDTO[]>
List all custom field definitions for the tenant
Retrieves all custom field definitions, optionally filtered by entity type. Results are sorted by sortOrder (ascending).
| Name | Type | Description |
|---|---|---|
options? | CustomFieldQueryOptions | Query options including entity type filter |
Promise<CustomFieldDefinitionDTO[]>
Array of custom field definitions
Example
const fields = await sdk.customFields.getDefinitions();
console.log(`Found ${fields.length} custom fields`);
fields.forEach(field => {
console.log(`${field.key}: ${field.label} (${field.fieldType})`);
});Example
// Get only business custom fields
const businessFields = await sdk.customFields.getDefinitions({
entityType: 'business'
});managers/custom-field-definition-manager.ts:117
▸ getDefinition(id): Promise<CustomFieldDefinitionDTO>
Get a single custom field definition by ID
| Name | Type | Description |
|---|---|---|
id | string | The UUID of the custom field definition |
Promise<CustomFieldDefinitionDTO>
The custom field definition
Throws
When definition not found (404)
Example
try {
const field = await sdk.customFields.getDefinition('uuid-here');
console.log('Field:', field.label);
} catch (error) {
if (error.statusCode === 404) {
console.log('Field not found');
}
}managers/custom-field-definition-manager.ts:142
▸ createDefinition(data): Promise<CustomFieldDefinitionDTO>
Create a new custom field definition
Creates a new custom field for the tenant. The field key must be unique within the tenant and entity type combination.
| Name | Type | Description |
|---|---|---|
data | CreateCustomFieldDefinitionDTO | The field definition data |
Promise<CustomFieldDefinitionDTO>
The created custom field definition
Throws
When key already exists (409) or validation fails (400)
Example
const employeeIdField = await sdk.customFields.createDefinition({
key: 'employee_id',
label: 'Employee ID',
description: 'Your company employee ID (E + 5 digits)',
fieldType: 'text',
validation: {
required: true,
pattern: '^E[0-9]{5}$',
patternMessage: 'Must be E followed by 5 digits'
},
sortOrder: 1
});Example
const checkOutField = await sdk.customFields.createDefinition({
key: 'check_out',
label: 'Check-out Date',
fieldType: 'date',
validation: {
required: true,
comparisons: [
{ field: 'check_in', operator: '>', message: 'Must be after check-in' }
]
},
sortOrder: 2
});Example
const departmentField = await sdk.customFields.createDefinition({
key: 'department',
label: 'Department',
fieldType: 'select',
selectOptions: [
{ value: 'engineering', label: 'Engineering' },
{ value: 'sales', label: 'Sales' },
{ value: 'hr', label: 'Human Resources' }
],
validation: { required: true }
});Example
const hotelField = await sdk.customFields.createDefinition({
key: 'preferred_hotel',
label: 'Preferred Hotel',
fieldType: 'select',
selectOptionsSource: {
entity: 'business',
valueField: 'id',
labelField: 'name',
filter: { tags: ['hotel'], isActive: true }
},
validation: { required: true }
});managers/custom-field-definition-manager.ts:219
▸ updateDefinition(id, data): Promise<CustomFieldDefinitionDTO>
Update an existing custom field definition
Updates a custom field definition. Note that key and entityType cannot be changed after creation.
| Name | Type | Description |
|---|---|---|
id | string | The UUID of the custom field definition to update |
data | UpdateCustomFieldDefinitionDTO | The fields to update (partial update supported) |
Promise<CustomFieldDefinitionDTO>
The updated custom field definition
Throws
When definition not found (404) or validation fails (400)
Example
const updated = await sdk.customFields.updateDefinition('uuid-here', {
label: 'Employee ID (Required)',
validation: {
required: true,
minLength: 6,
maxLength: 6
}
});Example
await sdk.customFields.updateDefinition('uuid-here', {
sortOrder: 5
});managers/custom-field-definition-manager.ts:265
▸ deleteDefinition(id): Promise<void>
Delete a custom field definition (soft delete)
Soft deletes a custom field definition. Existing user data in customData is preserved, but the field will no longer appear in forms or validation.
⚠️ Consider the impact on existing user data before deleting.
| Name | Type | Description |
|---|---|---|
id | string | The UUID of the custom field definition to delete |
Promise<void>
Throws
When definition not found (404)
Example
try {
await sdk.customFields.deleteDefinition('uuid-here');
console.log('Field deleted');
} catch (error) {
console.log('Failed to delete:', error.message);
}managers/custom-field-definition-manager.ts:303
▸ resolveSelectOptions(id): Promise<CustomFieldSelectOption[]>
Resolve dynamic select options for a field
For fields with selectOptionsSource (dynamic options from entities), this resolves the actual options by querying the source entity.
| Name | Type | Description |
|---|---|---|
id | string | The UUID of the custom field definition |
Promise<CustomFieldSelectOption[]>
Array of select options
Example
const field = await sdk.customFields.getDefinition('hotel-field-id');
if (field.selectOptionsSource) {
// Options come from entity - need to resolve
const options = await sdk.customFields.resolveSelectOptions(field.id);
console.log('Available hotels:', options);
} else {
// Static options
console.log('Options:', field.selectOptions);
}managers/custom-field-definition-manager.ts:338
▸ validateUserData(data, definitions): ValidationErrorDetail[]
Validate user custom data against field definitions
Client-side validation using the same rules as the backend. Use this to validate form data before submission.
| Name | Type | Description |
|---|---|---|
data | Record<string, unknown> | User's custom data (key-value pairs) |
definitions | CustomFieldDefinitionDTO[] | Custom field definitions to validate against |
ValidationErrorDetail[]
Array of validation errors (empty if valid)
Example
const definitions = await sdk.customFields.getDefinitions();
const formData = {
employee_id: 'E123', // Missing a digit
department: 'engineering'
};
const errors = sdk.customFields.validateUserData(formData, definitions);
if (errors.length > 0) {
errors.forEach(err => {
console.log(`${err.field}: ${err.message}`);
});
return; // Don't submit
}
// No errors, safe to submit
await sdk.users.updateCurrentUser({ customData: formData });managers/custom-field-definition-manager.ts:373
▸ validateFieldValue(value, definition): null | ValidationErrorDetail
Validate a single field value
Validates a single value against a field's rules. Useful for real-time validation as the user types.
| Name | Type | Description |
|---|---|---|
value | unknown | The value to validate |
definition | CustomFieldDefinitionDTO | The field definition |
null | ValidationErrorDetail
Validation error or null if valid
Example
const employeeIdField = definitions.find(d => d.key === 'employee_id');
const handleBlur = (value: string) => {
const error = sdk.customFields.validateFieldValue(value, employeeIdField);
if (error) {
setFieldError('employee_id', error.message);
} else {
clearFieldError('employee_id');
}
};