Custom Fields
  • 11 Jun 2024
  • 22 Minutes To Read
  • Dark
    Light
  • PDF

Custom Fields

  • Dark
    Light
  • PDF

Article summary

Custom fields are a powerful and flexible way to extend the core functionality of Mambu to reflect your specific business needs.

A field is a value associated with a Mambu entity such as a client, group, or loan account. For example, the client entity includes several default fields for storing information about each client, such as ID, Email Address, and Created date. We refer to the fields we provide by default as native fields.

For some entities, you may create custom fields to capture additional relevant information. Most custom fields are grouped together in custom field sets, and access to custom fields can be restricted to certain roles.

Custom field definition and custom field value

When it comes to custom fields, we distinguish between the custom field definition and the custom field value.

The custom field definition is the custom field you create - using either the Mambu UI or API - which contains information such as its name, ID, type, and usage settings. For example, you can create a selection custom field for the clients entity called "Country of Residence". For more information on creating custom field definitions, see Creating a custom field definition.

The custom field value is the actual value that a custom field attached to an entity holds. For example, you may have a client called "Peter Piper" for whom the "Country of Residence" custom field definition contains the custom field value "Zimbabwe".

Introducing Custom Field Values Quotas

We are introducing limits to custom fields as a proactive measure that will safeguard system performance and effectively mitigate the potential risks of overloading it. These changes will be effective starting from end of Q2 2024 in sandbox and beginning of Q3 2024 for production, ensuring a more efficient and streamlined user experience for everyone.

This limitation only applies to the number of custom field values linked to an entity, and not to the number of custom fields definitions that can be configured. These are the technical limits that will be applied per entity:

EntityMaximum linked custom field values
Assets200
Branches200
Centres200
Clients200
Credit Arrangements200
Deposit Accounts200
Deposit Products200
Groups200
Guarantors200
Loans Accounts200
Transaction by Channel25
Transaction by Type25
Users200

What happens to the current custom field values?

The entities that already exist in the system will remain as they are and we will continue to support read operations for them. However, you won’t be able to update an entity that has exceeded the limit of custom fields values attached to it, unless you remove linked custom field values to go below the limit.

We advise that you re-audit all your entities and remove linked custom field values where your entities are linked to more than the allowed amount.

Custom field management

Custom field definitions and custom field values may be managed via the Mambu UI and Mambu API v2.

Custom field value management:

  • In the Mambu UI, you may edit custom field values in various the various forms that they show up. For example, client custom field values will appear on a client detail page.
  • Via Mambu API v2, you may retrieve and manipulate custom field values using various endpoints. For more information, see Using Custom Fields in our API Reference.

Custom field definition management:

Please Note
This element can also be configured using Configuration as Code (CasC). For more information, see Configuration as Code.

Custom field definition permissions

To view, create, edit, and delete custom field definitions, you must have the appropriate permissions:

  • View Custom Fields (VIEW_CUSTOM_FIELD)
  • Create Custom Fields (CREATE_CUSTOM_FIELD)
  • Edit Custom Fields (EDIT_CUSTOM_FIELD)
  • Delete Custom Fields (DELETE_CUSTOM_FIELD)

The Fields tab will only be visible if you have at least one of the custom field definition permissions. For more information, see Permissions.

Please Note

These permissions control your ability to view and modify the custom field definitions themselves, not the custom field values. For more information on managing which users can manage custom field values, see the Configuring rights for roles section.

Entities with custom field definitions

Custom field definitions can be created for the following entities:

  • Clients
  • Groups
  • Loan Accounts
  • Deposit Accounts
  • Deposit Products
  • Credit Arrangements
  • Guarantors
  • Assets
  • Branches
  • Centers
  • Users
  • Transaction by Channel
  • Transaction by Type
Please Note

Custom field definitions for transactions by type are only available for transfers. No other transactions without transaction channels are supported. If you would like to have custom field definitions on more types of transactions, please contact us through Mambu Support.

Administration screen with Fields tab selected

Custom field definition granularity

Some entities that support custom field definitions allow you to use granular usage settings to control in which forms they will appear based on the type of entity. For example, if you create a new custom field definition for clients called "Student ID", you may choose to make it a required custom field definition for student client types and an unavailable custom field definition for all other client types. For more information, see Usage settings.

The table below lists which entities offer such custom field definition granularity:

Custom Field EntityOptional granularity
ClientsPer client type.
GroupsPer group type.
Loan accountsPer loan product.
Deposit accountsPer deposit product.
Deposit productsPer deposit product type.
Transaction by ChannelPer transaction channel.
Transaction by TypePer transaction.

Custom field sets

Custom field sets allow you to group custom field definitions together. Each custom field definition is grouped by its custom field set in the relevant forms.

Please Note

The guarantors and assets entities are the only entities that do not have custom field sets.

Creating a new custom field set

To create a new custom field set:

  1. On the main menu, go to Administration > Fields.
  2. Select the entity you would like to add a custom field set to.
  3. Select the Add icon .
  4. Enter all the necessary information. See below for more information on fields for custom field sets.
  5. Select Save Changes.

Create New Custom Field Set dialog

Fields for custom field sets

NameDescriptionRequired
NameThe name for the custom field set.Yes
IDThe ID used to reference this custom field set using the API. If this field is left blank, an ID will be automatically generated. The ID always starts with an underscore.No
TypeStandard and Grouped. For more information, see Custom field set types.Yes
NotesNotes about the custom field set.No

Custom field set types

There are two types of custom field sets: standard and grouped.

A standard custom field set can contain multiple custom field definitions. Each custom field definition will only appear once in the form. Therefore, you can store only one custom field value for a specific custom field definition.

A grouped custom field set can contain multiple custom field definitions. Each custom field group can appear multiple times in the form. Therefore, you can store multiple custom field values for a specific custom field definition.

Grouped custom field sets

The following is an example of a grouped custom field set. Suppose you want to track information about a client’s bank accounts. You can create a Bank Accounts Information grouped custom field set with four custom field definitions: Bank Name, Bank Branch, Account Number, and Account Type.

To add a new bank account, the user would select Add Bank Accounts Information, and a new empty subset containing the four required custom field definitions will be added.

Example of the Bank Accounts Information group custom field set in the client creation form

If a grouped custom field set contains one or more required custom field definitions, Mambu will automatically add the whole subset of custom field definitions when a new client or account is created.

Grouped custom field definitions can be used in contracts and notifications templates and can be indexed. For example, to include the first and second value for the clients custom field definition “Bank Account”, the template should contain {CF:CLIENT:Bank Account:1} and {CF:CLIENT:Bank Account:2}.

Please be Aware

Be aware of the following:

  • The only way to add or update custom field values in grouped custom field sets is by editing the entity.
  • Custom field values in grouped custom field sets cannot be used in custom views or edited directly in the Overview or Details screens or added with the Add Field option.

Rearranging custom field sets

You can rearrange all the custom field sets except for the General and Details custom field sets, which are always the first two sets in the list.

The order of custom field sets will affect the order in which these appear in forms in Mambu.

To rearrange custom field sets:

  1. On the main menu, go to Administration > Fields.
  2. Select the entity you would like to rearrange the custom field set for.
  3. Select the Custom View icon .
  4. Rearrange the custom field sets in the order you want.
  5. Select Save Changes.

Editing custom field sets

To edit a custom field set:

  1. On the main menu, go to Administration > Fields.
  2. Select the entity you would like to edit a custom field set for.
  3. In the Custom Field Set dropdown, select the custom field set you want to edit.
  4. Select the Edit icon .
  5. Edit the custom field set.
  6. Select Save Changes.

Deleting a custom field set

To delete a custom field set:

  1. On the main menu, go to Administration > Fields.
  2. Select the entity you would like to delete a custom field set for.
  3. In the Custom Field Set dropdown, select the custom field set you want to delete.
  4. Select the Delete icon .
Please note

Only custom field sets that contain no custom field values can be deleted.

Creating a custom field definition

All custom field definitions must belong to a custom field set, except for custom field definitions associated with guarantors and assets, which do not support custom field sets. Therefore, you must first create a custom field set and thereafter you may create custom field definitions.

To create a custom field definition:

  1. On the main menu, go to Administration > Fields.
  2. Select the entity you would like to create a custom field definition for.
  3. In the Custom Field Set dropdown select the custom field set you want your custom field definition to belong to.
  4. Select Add Custom Field.
  5. Enter the information in the General, Display, Usage, Rights, and Description sections. For more on these sections, see (Fields for custom field definitions)[#fields-for-custom-field-definitions].
  6. Select Create.

Adding a custom field definition in a custom field set.

Fields for custom field definitions

General section

NameDescriptionRequired
NameThe name for the custom field definition.Yes
IDThe ID used to access this custom field definition using the API. If this field is left blank, an ID will be auto generated.No
Custom Field SetThe custom field set you are creating a custom field definition for.Yes
Custom Field Set TypeThe entity for which you are creating a custom field definition. This field will be pre-filled depending on which entity tab you selected when creating the custom field definition.Yes

Display section

This section describes the type of custom field definitions you can create.

Available for all checkbox

The Available for all checkbox allows you to set basic usage settings for entities that also support granular usage settings and it is only available for these entities. For more information, see Custom field definition granularity and Basic and granular usage settings.

Example of Available for all checkbox selected which then enables basic usage settings

Custom field type

There are nine types available for custom field definitions: free text, selection, number, checkbox, date, date and time, client link, group link, and user link.

They each have the Long Field checkbox available. This option allows the UI to display long custom field value content more elegantly. However, it does not change the maximum length of a custom field value - which is 2048 characters.

Free text custom field definitions

A custom field definition with type free text allows you to create a manually enter a custom field value.

The display section of the custom field creation form when selecting the free text type

Format

The Format field allows you to specify an input mask for format validation. If left blank, any text can be entered.

For example, if you want to collect British phone numbers, you could set the format to +44##########.

Input masks or templates are used to configure Mambu to generate alphanumeric IDs or values of a fixed, specified length, which match the specified pattern of letters and numbers.

Templates consist of the characters `#`, `@`, and `$`, where `#` specifies a number, `@` a letter, and `$` a number or a letter, chosen at random. For example, `@#@#$` will configure Mambu to generate five-character values of one letter, one number, one letter, one number, and one character that is either a letter or a number, such as `B8J4P` or `P1F62`.

Only letters and numbers may be used - special characters and punctuation are not supported. 

Note that the generated values cannot overflow. When all possible values of the specified length run out, no additional values can be generated. For example, the pattern `##` can only produce 100 unique combinations, 0-99. It is important that you specify templates that will provide as many values as you may need into the future.

Unique Value

The Unique Value checkbox allows you to specify that the custom field value must be unique. If the custom field value already exists, Mambu will return the error 926 DUPLICATE_UNIQUE_VALUE and will not allow the entity to be saved.

For example, if phone numbers are being used for multi-factor authentication, you may want to require unique phone numbers.

Selection custom field definition

A custom field definition with type selection allows you to create a dropdown with multiple predefined options. A user can then select one of the predefined options.

To add options to a selection custom field definition:

  1. Next to Label, enter the option name.
  2. Select the Add icon .
Please be Aware

You can create as many options as you need for a selection custom field definition. However, a maximum of 20 options are displayed in the Mambu UI.

If you need to enter the custom field value of an option that is not displayed, then you must enter the value manually in the selection custom field definition bar and it will come up as a search option.

A possible use case for the selection custom field definition is if you need to capture information about a loan's source of funds. You could then use a predefined selection field to enter different custom field value options, such as Local NGO, Individual Lender, and so on.

To move the options up or down according to the order you want them to be displayed, use the blue arrows.

Selection custom field definition with options that have IDs

Selection option ID

When creating a selection option, you can enter an ID value, which must only consist of alphanumeric characters, dashes, and underscores. The value is displayed in angle brackets <> next to the option in the list. If no value is entered, then the system will automatically generate a nine character numeric ID for you.

We recommend setting IDs for custom field value options if you are planning on migrating configurations across environments, such as using configuration files so your settings remain consistent. For more information, see Custom Fields Configuration.

Please Note

When using Mambu API v2, both the option value and the option ID of a selection custom field value option are returned. The option value can change; therefore, we recommend using the option ID when implementing integrations in your system.

Dependent custom field definitions

The Dependent Field dropdown is only available if your custom field set contains another custom field definition that has the selection type.

Use a dependent custom field definition if the custom field value of the selection custom field definition you are creating is dependent on a custom field value in another selection custom field definition. In this case, the custom field definition that your dependent custom field definition depends upon is called the parent custom field definition.

An example of creating a dependent custom field definition is if you have a parent custom field definition called "Country" with two custom field value options: Poland and Greece. There could be a dependent custom field definition called "City" which has custom field value options "Warsaw" and "Krakow" when Poland is selected, but "Athens" and "Mykonos" if Greece is selected.

Dependent custom field definitions inherit the usage settings - one of Available, Required, or Default - of their parent custom field definition.

Please be Aware

Parent custom field definitions must come before their dependent custom field definitions in the custom field definition order. You can change the order of custom field definition by clicking Rearrange from the custom field set list and using drag and drop to achieve the desired order. For more information, see the rearranging custom field definitions section.

Scores on custom field values

You can associate numeric values with each of the custom field value options available for selection custom field definitions including dependent custom field definitions. The score is displayed in brackets () next to the custom field value option in the list.

When adding a custom field value with a score to an entity, the score will be displayed in brackets next to the field and a total score will be provided. This score is the sum of all scores in that custom field set.

An example use case for this is calculating social performance indicators for your clients.

Selection custom field with option Yes/No and score

Number custom field definitions

A custom field definition with type number allows you to create a field in which only numbers can be entered. For example, you may wish to create a custom field definition for the number of children in a household.

Checkbox custom field definitions

A custom field definition with type checkbox allows you to create a field where there are only two possible answers which indicate whether an option is chosen or not.

For example, you may wish to create a checkbox custom field definition for loan accounts to generate a checklist of requirements needed for the approval process - such as Business data collected: (yes/no), House inspected: (yes/no), and so on.

Date custom field definitions

Allows you to store a date which will follow the format you have configured for your organization at Administration > General Setup > Organization Details. For more information, see Managing organization details using Mambu UI.

For example, you may want to store the expiration date for an identification document or you may want to store the date of birth for your individual clients.

Date and Time custom field definitions

Allows you to store both a date and time which will follow the format you have configured for your organization at Administration > General Setup > Organization Details. For more information, see Managing organization details using Mambu UI.

For example, you may want to create a custom field definition to capture the exact date and time that a loan officer contacts a client to follow up on a loan account's status.

Client, Group, and User Link custom field definitions

These custom field definition types allow for the selection of a client, group, or user that is already created in the system. The field allows you to search for any existing client, group, or user by name or ID.

For example, if you have a client that was referred by another client, you could use the client link to store this information.

Usage section

This section describes usage settings available when creating a custom field definition.

Usage setting parameters

Available, Default, and Required are three adjustable usage settings which allow you to create four custom field definition usage types: unavailable custom field definitions, available custom field definitions, default custom field definitions, and required custom field definitions.

Custom field definition usage typeAvailableDefaultRequired
Unavailable custom field definitionNoNoNo
Available custom field definitionYesNoNo
Default custom field definitionYesYesNo
Required custom field definitionYesYesYes
Please Note

All default custom field definitions are also marked as Available. All required custom field definitions are marked as Default and Available.

Basic and granular usage settings

Entities can either have basic usage settings or granular usage settings. For more information, see the Custom field definition granularity section.

The following entities support either basic usage settings or granular usage settings:

  • Clients
  • Groups
  • Loan accounts
  • Deposit accounts
  • Deposit products
  • Transaction by Channel
  • Transaction by Type

The following entities only support basic usage settings:

  • Credit Arrangements
  • Guarantors
  • Assets
  • Branches
  • Centres
  • Users

Basic usage settings

Basic usage settings allow you to set the usage type of a custom field definition for an entity as a whole. All custom field definitions for these entities are available upon creation; therefore, you only have to edit the Default and Required usage setting. The credit arrangements, guarantors, assets, branches, centres, and users entities use basic usage settings.

Usage for an entity with basic usage settings

To enable them to have basic usage settings you must select the Available for all checkbox in the Display section. After enabling basic usage settings for a custom field definition, any granular usage settings you may have set previously are not saved.

Granular usage settings

Granular usage settings allow you to specify the usage settings for certain item types within an entity. For example, a custom field definition for clients may be available for Prospect client types, but not for Student client types.

Usage for a client custom field definition

If you select the checkbox right under either of these settings - one of Available, Required, or Default - then this selects that setting for all the item types of that entity.

Entities that use granular usage settings also allow you to filter custom field definitions in the custom field definitions list page by selecting an item type using either the Filter for or Available For dropdowns.

Filter for dropdown allows you to filter custom fields by item type

Custom field definition example

In the example, we use an example custom field definition for the client entity called Student ID Number - which belongs to a custom field set called Student Profile. We will cover all the different usage setting configurations.

Unavailable custom field definition

Unavailable custom field definitions will not be visible on any relevant forms and you will not be able to add them to those forms.

Custom field definition does not have any settings selected

The Student ID Number custom field definition is not available in the form

Available custom field definitions

Available custom field definitions may be added to any relevant forms by selecting Add Field in the appropriate custom field set section.

Custom field definition has available setting selected

The Student ID Number custom field definition is available in the form to be added

Default custom field definition

Default custom field definitions are included in relevant forms by default.

Custom field definition has available and default setting selected

The Student ID Number custom field definition is included in the form by default

Required custom field definitions

Required custom field definitions are included in relevant forms by default and have a green outline indicating they are mandatory.

Custom field definition has available, default, and required setting selected

The Student ID Number custom field definition is a required field in the form

Please Note

In both the Mambu UI and the Mambu API, a custom field set is required if you have at least one required custom field definition. This applies to both standard and grouped custom field sets. For example, if you have at least one required custom field definition in a grouped custom field set, then you must add at least one group with the required custom field definition filled in.

Configuring rights for roles

In the Rights configuration section, you can define the roles with the right to enter custom field values for a particular custom field definition. These roles will be able to enter information for a custom field in the forms it appears in.

Please Note
Access is controlled at the role level, not at the user level. For more information, see Access managed by role.

Please be Aware

This section only defines which roles will have access to enter custom field values.

This does not affect which users can manage the custom field definition itself. For more information, see Custom field definition and custom field value and Custom field permissions.

Example of rights section with list of user roles

Selecting the checkbox under either the View or the Edit options will select those options for all the roles in the list. If a new role is created then this new role will also have view and/or edit rights to the custom field value.

If the checkboxes under either the View or Edit options are not selected then you can select the specific roles for which you would like to assign view or edit rights for the custom field value. New roles will not have view or edit rights automatically assigned to them.

If a role has edit rights then it automatically has view rights. The reverse is not true, you may grant view rights to a custom field value without assigning edit rights.

Please be Aware

If a user creating an item in an entity does not belong to a role that has edit rights to a custom field value, they will not be able to see or edit the custom field value, even if it is required. They will be able to save the item in the entity despite the missing required information.

Managing custom field definitions

Editing, deleting, or deactivating custom field definitions

To edit, delete, or deactivate a custom field definition:

  1. On the main menu, go to Administration > Fields.
  2. Select the entity you would like to edit, deactivate, or delete a custom field definition for.
  3. If relevant, select the custom field set you would like to edit, deactivate, delete a custom field definition for.
  4. In the list of custom field definitions, find the custom field definition you would like to edit, deactivate, or delete and select Actions and then the relevant action.

Editing a custom field definition will bring up the custom field definition form. Make any necessary changes and select Save Changes.

Deactivating a custom field definition will not affect any existing custom field values entered for the custom field definition. You will no longer be able to enter any additional custom field value for this custom field definition.

To view all the deactivated custom field definitions, select the Show Disabled Fields checkbox.

You may only delete custom field definitions for which no custom field value has been entered.

Rearranging custom field definitions

To rearrange the order of custom field definitions:

  1. On the main menu, go to Administration > Fields.
  2. Select the entity you would like to rearrange the custom field definitions for.
  3. Select Rearrange.
  4. Drag and drop the custom field definitions to the order you want.
  5. Select Save Changes.

Rearranging custom field definitions affects the order in which they appear in relevant forms.

Please Note

For dependent custom field definitions, the dependent field must always be below the parent custom field definition in the order.

Rearrange custom field definitions. Change the order of the custom field definitions.

Custom field definitions as placeholders

The custom field definitions you create are also available as placeholders which you can include in your contracts, statements, or receipts.

For example, if you create a custom field definition for "Occupation" and you want to include the stored custom field value in the client's contract. When creating the contract's template you will be able to choose the placeholder Occupation from the list and the corresponding custom field value will be automatically filled when the contract is printed for that specific client.

For more information on how to use the placeholders in contract templates, see Product Documents.


Was this article helpful?