Custom Fields

Custom fields are a powerful, flexible, and commonly-used 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 fields by default 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 several 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 fields are robustly supported throughout the Mambu UI and API. Values stored in custom fields may be retrieved and manipulated via API v2. For more information, see Using Custom Fields in our API Reference.

To manage custom fields in the Mambu UI, go to Administration > Fields.

Custom fields permissions

In order to view, create, edit, and delete custom fields, 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 fields permissions. For more information, see Permissions.

Entities with custom fields

Custom fields 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 granularity

Some entities that support custom fields allow you to use granular usage settings to control access to the field based on the type of entity. For example, if you create a new custom field for loans, you may configure a user's access to that field so they may access the field for some loan products but not others. For more information, see Usage settings.

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

Custom field sets

Custom field sets allow you to group custom fields together. Each custom field 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 fields. Each custom field will appear only one time in the form. Therefore you can store only one value for a custom field that is part of a standard custom field set.

A grouped custom field set can contain multiple custom fields. Each custom field group can appear multiple times in the form. Therefore you can store multiple values for custom field groups that are part of a grouped custom field set.

Grouped custom field sets

Below 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 fields: 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 fields will be added.

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

Grouped custom fields 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 “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

All custom fields must belong to a custom field set, except for custom fields associated with guarantors and assets, which do not support custom field sets.

If no custom field set exists for the relevant entity when you are creating a new custom field, you must create one before creating any custom fields.

To create a custom field:

1. On the main menu, go to Administration > Fields.
2. Select the entity you would like to create a custom field for.
3. In the Custom Field Set dropdown select the custom field set you want your custom field to belong to.
4. Select Add Custom Field.
5. Enter the information in the General, Display, Usage, Rights, and Description sections (described below).
6. Select Create.

Fields for custom fields

General section

Display section

This section describes what type of custom field 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 granularity and Basic and granular usage settings.

Custom field type

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

All of them have the Long Field check box available. This option allows the user interface to display fields in a better way when the field content is long. However, it doesn't change the maximum length of a field, which is 2048 characters.

Free text custom fields

A custom field with type free text allows you to create a field where you can manually enter a 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 create a field to collect British phone numbers, you could set the format to +44##########.

Unique Value

The Unique Value checkbox allows you to specify that the value of this custom field must be unique for each entity containing the field. If upon saving, the value for a unique custom field already exists, Mambu will return 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 (dropdown) custom fields

A custom field 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:

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

A use case for a custom field with selection 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 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 consist of alphanumeric characters, dashes, and underscores only. 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 fields 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 fields

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

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

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

Scores on custom fields

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

When adding custom fields with scores to an entity, the score will be displayed in brackets next to the field and a total score will be provided, which 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 fields

A custom field 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 for the number of children in a household.

Checkbox custom fields

A custom field 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 checkbox custom fields 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 fields

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 fields

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 to capture the exact date and time that a loan officer contacts a client to follow up on a loan account status.

Client / Group / User Link custom fields

These custom field types allow for the selection of a client/group/user that is already created in the system. The field allows searching for any existing client/group/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.

Usage setting parameters

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

Basic and granular usage settings

Entities can either have basic usage settings or granular usage settings. For more information, see the Custom field 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 support basic usage settings only:

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

Basic usage settings

Basic usage settings allow you to set the usage type of a custom field for an entity as a whole. All custom fields 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 fields, 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 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 (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 fields in the custom fields list page by selecting an item type using either the Filter for or Available For dropdowns.

Custom field example

In the below example, we use an example custom field 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

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

Available custom field

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

Default custom field

Default custom fields are included in relevant forms by default.

Required custom field

Required custom fields 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 which roles will have the right to enter information for the 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.

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. 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. However the reverse is not true, you may grant view rights to a custom field without assigning edit rights.

Managing custom fields

Editing, deleting, or deactivating custom fields

To edit, delete, or deactivate a custom field:

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

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

Deactivating a custom field will not affect any existing data entered for the custom field. It will simply no longer allow you to enter any additional data for this custom field.

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

You may only delete custom fields for which no data has been entered.

Rearranging custom fields

To rearrange the order of custom fields:

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

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

Custom fields as placeholders

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

If, for instance, you create a custom field for Occupation and you want to include that information 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 information will be automatically filled when the contract is printed for a specific client.

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