Custom Fields Overview

Introduction

This article describes how to create, edit, and manage custom fields on the platform, providing a comprehensive guide for users who need to customize the Platform Custom fields to contain the data specific to their organization.

Introduction to custom fields

Custom Fields are additional details that can be added to an Organization, Subscription, Contract, or Order. They can be viewed only by users with the role that was selected during the creation of the respective field.

One useful example of using custom fields is if you need to sync additional customer profile details from your CRM and display them in the platform. You can add them as custom fields and configure how they should behave - whether the field should be required, which roles should see it, and whether anybody should be able to update it.

If you sell to partners who also work in platforms of their own, you can also set up custom fields for all your partners at once. This way, you will simplify their onboarding process, and they can still customize their own custom field settings later if needed.

How to create and edit custom fields

During creation, you can select the following options:

1. Name of the custom field

Add the Name of the Custom Field.

2. Entity selection

From the Entity dropdown, you can choose: Organization, Subscription, Contract, Order.

3. Type selection

From the Type dropdown, you can choose one of the following options:

• Text field
• Number field
• Checkbox
• Single select dropdown
• Multi-select dropdown

3.1. For the Text, Number, and Checkbox fields, you will see the option "Is required" checkbox, which signifies that the custom field must be filled.

3.2. Only allow to set value once allows you to choose whether the field can be modified after its initial configuration.

3.3. For Single-select dropdown and Multi-select dropdown, you will see the option "List options" (click "+" to add multiple list items).

3.4. Display On Reporting API - This checkbox will be available only if for Entity selection is Order. It determines if the custom field value is included in the Reporting API. Only one order custom field can be selected to be shown in the Reporting API.

For more details about the Reporting API, read the following article: Reporting API Overview.

4. Available to organizations

Have the following options:

• Only me – Distributor/Seller who's configuring this custom field. This custom field will only be available on the current platform.
• Me and Partners – Available to both the seller (distributor) and their partners (sellers). This custom field will be accessible on the current platform as well as on the platforms of all partners (sellers). 'Me' refers to the distributor, and 'Partners' refers to the 2-tier sellers under this distributor.
• Only Partners – Available only to partners (sellers) of the current platform (distributor). This custom field will be accessible only on the platforms of all direct partners (sellers). 'Partners' refers to the 2-tier sellers under the distributor.

5. Available to roles

Lets you choose which access role can view/edit the configured Custom Field; any access role can be selected.

If "Available to roles" is not set, then all roles from the list will be able to see and edit the custom field records. User access to specific sections/places may affect it (e.g., organization profile, invoices).

6. Available to vendors

When you choose the entity "Subscription," the Available to vendors option will be available, which includes vendors that offer partners can sell. Users can select one or more vendors.

If no vendors are selected, the custom field will apply to all vendors associated with the seller or distributor.

7. Display Locations

Display Locations enables you to decide where custom fields will appear within the system. Each Entity has its own set of available display locations, allowing you to tailor the visibility of custom fields to specific contexts. This flexibility ensures that relevant information is accessible exactly where it's needed, improving efficiency and user experience.

Below, you can find an overview of the entities and their corresponding display locations:

Entity: Organizations

Display Locations:

• Organization's Profile Page (default)
• Invoice Overview Page

Entity: Subscriptions

Display Locations:

• Offer & Subscription Page (default)

Entity: Contracts

Display Locations:

• Contract Page (default)

Entity: Orders

Display Locations:

• Shopping Cart and Orders Page (default)

Modifying custom field options after they are in use

You can modify the names of custom field options for Single-select dropdown and Multi-select dropdown types even after they have been applied to Organizations, Subscriptions, Contracts, or Orders.

How to modify a custom field option

1. Navigate to Settings Custom Fields
   
   
2. Click Edit on the custom field template you want to modify
   
3. Click the option you want to change
   
4. Update the option name
5. Click Save
   

Important behavior

• When you modify an option name, the old value will continue to display in all existing records until users manually update them
  
• Users can update the value by editing the  Organization, Subscription, Contract, or Order and selecting a new option from the current list. Changed option will be greyed out and not possible to select.
  
• Once a user updates the value, the old (modified) option will no longer be available for selection

Removing custom field options

You can remove options from Single-select dropdown and Multi-select dropdown custom fields even after they have been used.

How to remove a custom field option

1. Navigate to Settings Custom Fields
   
   
2. Click Edit on the custom field template
   
3. Click the remove icon (X) next to the list option you want to delete
   
4. Click Save

Important behavior

• When you remove an option, the Platform stores historic records showing that the option was used
• The removed option will continue to display in existing records until users manually change it to a different value
  
• Users will not be able to select the removed option when creating new records or updating existing ones
  
• Once a user updates the value to a different option, the removed option will no longer be available
  

Deleting a template from custom fields

If a field is used on an existing Organization, Subscription, Contract, or Order, you will have to confirm a prompt when deleting the template. By accepting, you are choosing to delete this from the platform entirely.

The system will display a message showing how many records are affected and asking for confirmation before proceeding with the deletion.

Custom fields settings

In the Custom Fields Settings section, you can configure how custom field section titles appear throughout the Platform interface for different entities. This allows you to customize the display names to match your organization's terminology and improve user experience.

To access Custom Fields Settings, navigate to Settings → Custom Fields → Settings tab.

Configuring display names

The Settings tab allows you to define custom display names for custom field sections across five different entities:

Orders configuration

Configure how the custom fields section appears when viewing or creating Orders.

1. In the Orders Display Name field, enter your preferred section title.
   
2. The default value is "Other".

3. This name will appear in the interface wherever Orders custom fields are displayed, including:

    Create order pop-up
   
    Order cart view
   

   Expanded order view
   

Subscriptions configuration

Configure how the custom fields section appears on Subscription forms and details pages.

1. In the Subscriptions Display Name field, enter your preferred section title.
   
2. The default value is "Other".
3. This name will appear when viewing or editing Subscription details.
   

Organizations - Organization Profile Page configuration

Configure how the custom fields section appears on the Organization profile page.

1. In the Organizations - Organization Profile Page field, enter your preferred section title.
   
2. The default value is "Other".
3. This name will appear in the custom fields section on the Organization Overview page.
   

Organizations - Invoice Overview Page configuration

Configure how the custom fields section appears on the Invoice Overview page.

1. In the Organizations - Invoice Overview Page field, enter your preferred section title.
   
2. The default value is "Custom Fields".
3. This name will appear in the custom fields section when viewing invoice overview details.
   

Contracts configuration

Configure how the custom fields section appears on Invoice Contract forms and details pages.

1. In the Contracts Display Name field, enter your preferred section title.
   
2. The default value is "Other".
3. This name will appear when viewing or editing Invoice Contract details in the Custom Fields interface.
   

Saving configuration changes

After entering your preferred display names:

1. Click the Save Configuration button to apply your changes.
2. Click Cancel to discard changes and return to the previous values.

Configuration inheritance

Custom Fields Settings follow a hierarchical inheritance model:

• By default, if no configurations are saved, the system uses default values for all entities.
• Distributor configurations are automatically inherited by all 2-tier Sellers in their organization.
• 2-tier Seller configurations override any inherited Distributor settings when the Seller saves their own custom display names.
• You can configure display names for specific entities only. Entities without custom configurations will continue using their default values.
• If you delete all saved values after previously configuring them, the system will revert to showing default values for each entity.

Use cases where the custom fields can be used

Below, you can find scenarios of using custom fields.

1. The seller has the billing contact, and it should not be disclosed to the customer

This scenario involves creating a text field that can be seen only by the seller, which provides a solution for such scenarios.

2. Distributor would like to assign a credit risk score to all entities, which should not be visible to the sellers

This scenario involves creating a Multi-select dropdown field that can be viewed only by the Distributor Admin. It provides a drop-down menu to assign a credit risk score to an organization.