Custom Fields

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 30 April 2024, 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, by 30th of April 2024:

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:

• In the Mambu UI, go to Administration > Fields.
• Via the API, use the Custom Field Configuration API v2 endpoints.

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.

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

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 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.

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.

Fields for custom field sets

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.

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}.

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 .

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.

Fields for custom field definitions

General section

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.

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.

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##########.

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 .

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 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.

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.

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.

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.

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.

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.

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.

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.

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.

Default custom field definition

Default custom field definitions are included in relevant forms 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.

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.

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.

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.

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.