Skip to main content
Version: Current

Deep Dive: Field Manager and Custom Fields (Staff/Advanced Focus)

Introduction​

Zudello's platform includes a wide range of standard fields across its various modules and submodules. However, specific business processes or integration requirements often necessitate customizing the behaviour of these standard fields or adding entirely new, custom fields. The Field Manager provides a centralized interface (primarily for Staff/Advanced users) to manage these customizations.

This guide covers using the Field Manager to adjust standard field properties and the process for creating, configuring, and utilizing custom fields throughout Zudello.

See also: Use the Field Manager, Create Custom Fields

Field Manager Overview​

  • Access: Settings > Field Manager (Requires specific Staff/Admin permissions).
  • Purpose:
    • View all available standard and custom fields across the platform.
    • Customize certain properties of standard fields on a per-module/submodule basis (e.g., change labels, control visibility in filters/exports).
    • Create and manage custom fields.
  • Interface: Typically displays a list of fields, allowing filtering by module/submodule and searching. Selecting a field opens its configuration options.

Customizing Standard Fields​

While core properties of standard fields (like data type or relationships) are fixed, the Field Manager allows customization of certain display and behaviour aspects:

  • Labels: Override the default display label for a field. This change reflects across the UI (forms, tables, filters) for the specified module/submodule.
    • Example: Change the label "Cost Centre" to "Job Code" for the Purchasing module if that's the client's terminology.
  • Visibility (Filters/Exports): Control whether a standard field appears as an option in filter dropdowns or when building export templates for a specific module/submodule.
    • Example: Hide the "Batch Number" field from filters in the Sales module if it's never used there.
  • Placeholder Text: Customize the placeholder text displayed within the field on forms.
  • Help Text: Add or modify help text that appears as a tooltip or info icon next to the field on forms.

Limitations: You cannot change the fundamental data type, relationships, or core backend logic associated with standard fields using the Field Manager. Form-specific settings (like making a standard field required or read-only) are still managed within the Document Type (Form) configuration.

Custom Fields​

When standard fields aren't sufficient, custom fields allow capturing additional, client-specific data.

Creating Custom Fields​

  1. Navigate: Settings > Field Manager.
  2. New Custom Field: Click the "New Custom Field" button.
  3. Define Properties:
    • Label: The user-facing name for the field.
    • Key: The unique system identifier (API name) for the field (e.g., vehicle_registration, internal_audit_code). Must be unique, typically lowercase with underscores. Cannot be changed after creation.
    • Type: Select the data type for the field. Common types include:
      • Text: Simple text input.
      • Number: Numeric input (integer or decimal).
      • Date: Date picker.
      • DateTime: Date and time picker.
      • Boolean: True/False toggle.
      • Dropdown: Select a single value from a predefined list (requires linking to a Dataset or Dimension).
      • Multi-Select: Select multiple values from a predefined list (requires linking to a Dataset or Dimension).
      • User Lookup: Select a Zudello User.
      • JSON: Store arbitrary JSON data (advanced use).
    • Scope (Module/Submodule): Define which Module(s) and Submodule(s) this custom field applies to. This determines where it can be added to forms and potentially used in reporting/filtering.
    • Related Model (for Dropdown/Multi-Select): If the type is Dropdown or Multi-Select, specify the related model (e.g., DIMENSIONS:COST_CENTRE, DATASETS:YOUR_CUSTOM_DATASET) that provides the list of options.
    • Other Options: Depending on the type, additional options might appear (e.g., min/max length for Text, decimal places for Number).
  4. Save: Create the custom field.

Managing Custom Fields​

  • Editing: You can typically edit the Label, Scope, and some type-specific options after creation. The Key and Type generally cannot be changed.
  • Deleting: Custom fields can usually be deleted, but use caution, especially if the field has been used on forms or contains data. Deleting a field will remove it and any associated data permanently.

Using Custom Fields​

Once created, custom fields need to be integrated into the relevant parts of Zudello:

  1. Forms (Document Types):
    • Edit the relevant Document Type (Form) in Settings > Document Types.
    • Go to the Form tab.
    • Find the "Custom Fields" section or use the field search.
    • Drag the custom field onto the form layout.
    • Configure form-specific settings (Required, Read-Only, Default Value, Visibility Rules) just like standard fields.
  2. Sentences:
    • Custom fields appear in the field selection dropdowns for Conditions (e.g., custom.vehicle_registration | Equals | ABC-123).
    • Custom fields can be updated using the Set Field action.
  3. Imports/Exports:
    • Custom fields are available for selection when mapping columns in the Import Tool.
    • Custom fields can be included when building templates in the Export Tool.
  4. Reporting (Future):
    • Custom fields should become available as dimensions or measures within the custom reporting engine.
  5. API/Integrations:
    • Custom fields are typically accessible via the API within the custom JSON object of the resource (e.g., transaction.custom.internal_audit_code). Integrations need to be aware of these custom keys to read or write data.

Integration Considerations​

  • Mapping: When integrating with external systems (like ERPs), ensure custom fields in Zudello are correctly mapped to corresponding fields in the external system.
  • Data Types: Ensure data types are compatible between Zudello custom fields and the target system fields.
  • API Access: Custom field data is usually nested within the custom object in API payloads. Integration logic needs to account for this structure.
  • Changes: Modifying or deleting custom fields after integrations are built can break the integration flow. Plan changes carefully and coordinate with integration developers.

The Field Manager and Custom Fields provide essential flexibility for tailoring Zudello to specific business needs, but require careful planning and management, especially regarding integrations and data consistency.