- 07 Sep 2022
- 19 Minutes To Read
- Print
- DarkLight
- PDF
Custom Fields
- Updated On 07 Sep 2022
- 19 Minutes To Read
- Print
- DarkLight
- PDF
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. Note that these permissions control your ability to view and modify the custom fields themselves, such as your ability to create a new custom field. Once a custom field has been created, users may or may not be able to enter values in the custom field depending on their rights. For more information, see the Configuring rights for roles section.
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 fields for transactions by type are only available for transfers. No other transactions without transaction channels are currently supported. If you would like to have custom fields on more types of transactions, please contact us through Mambu Support.
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 Entity | Optional granularity |
---|---|
Clients | Per client type. |
Groups | Per group type. |
Loan accounts | Per loan product. |
Deposit accounts | Per deposit product. |
Deposit products | Per deposit product type. |
Transaction by Channel | Per transaction channel. |
Transaction by Type | Per transaction. |
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. 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:
- On the main menu, go to Administration > Fields.
- Select the entity you would like to add a custom field set to.
- Select the Add icon .
- Enter all the necessary information. See below for more information on fields for custom field sets.
- Select Save Changes.
Fields for custom field sets
Name | Description | Required |
---|---|---|
Name | The name for the custom field set. | Yes |
ID | The 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 |
Type | Standard and Grouped. For more information, see Custom field set types. | Yes |
Notes | Notes 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 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 The only way to add or update custom fields in grouped custom field sets is by editing the entity. Custom fields 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.{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:
- On the main menu, go to Administration > Fields.
- Select the entity you would like to rearrange the custom field set for.
- Select the Custom View icon .
- Rearrange the custom field sets in the order you want.
- Select Save Changes.
Editing custom field sets
To edit a custom field set:
- On the main menu, go to Administration > Fields.
- Select the entity you would like to edit a custom field set for.
- In the Custom Field Set dropdown, select the custom field set you want to edit.
- Select the Edit icon .
- Edit the custom field set.
- Select Save Changes.
Deleting a custom field set
To delete a custom field set:
- On the main menu, go to Administration > Fields.
- Select the entity you would like to delete a custom field set for.
- In the Custom Field Set dropdown, select the custom field set you want to delete.
- Select the Delete icon .
Only custom field sets that contain no data in their custom fields can be deleted.
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:
- On the main menu, go to Administration > Fields.
- Select the entity you would like to create a custom field for.
- In the Custom Field Set dropdown select the custom field set you want your custom field to belong to.
- Select Add Custom Field.
- Enter the information in the General, Display, Usage, Rights, and Description sections (described below).
- Select Create.
Fields for custom fields
General section
Name | Description | Required |
---|---|---|
Name | The name for the custom field. | Yes |
ID | The ID used to access this custom field using the API. If this field is left blank, an ID will be auto generated. | No |
Custom Field Set | The custom field set you are creating a custom field for. | Yes |
Custom Field Set Type | The entity for which you are creating a custom field. This field will be pre-filled depending on which entity tab you selected when creating the custom field. | Yes |
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##########.
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 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:
- Next to Label, enter the option name.
- Select the Add icon .
You can create as many options as you need for a selection custom field. However, in the Mambu UI, a maximum of 20 options are displayed.
If you need to enter the value of an option that is not displayed, then you must enter the value manually in the selection custom field bar and it will come up as a search option.
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. Dependent custom fields inherit the usage settings (available/required/default) of their parent custom field. Parent custom fields must come before their dependent custom fields in the custom field order. You can change the order of custom fields 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 fields section.
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.
Custom field usage type | Available | Default | Required |
---|---|---|---|
Unavailable custom field | ✘ | ✘ | ✘ |
Available custom field | ✔ | ✘ | ✘ |
Default custom field | ✔ | ✔ | ✘ |
Required custom field | ✔ | ✔ | ✔ |
All default custom fields are also marked as Available. All required custom fields 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 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.
In both the Mambu UI and the Mambu API, a custom field set is required if you have at least one required custom field in it. This applies to both standard and grouped custom field sets. For example, if you have at least one required custom field in a grouped custom field set, then you must add at least one group with the required custom field filled in.
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.
This section only defines which roles will have access to enter information into custom fields in the relevant forms. This does not affect which users can manage the custom field itself. For more information, see Custom field permissions.
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. If a user creating an item in an entity does not belong to a role that has edit rights to a field, they will not be able to see or edit the field, even if it is required. They will, however, be able to save the item in the entity despite the missing required information.
Managing custom fields
Editing, deleting, or deactivating custom fields
To edit, delete, or deactivate a custom field:
- On the main menu, go to Administration > Fields.
- Select the entity you would like to edit/deactivate/delete a custom field for.
- If relevant, select the custom field set you would like to edit/deactivate/delete a custom field for.
- 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:
- On the main menu, go to Administration > Fields.
- Select the entity you would like to rearrange the custom fields for.
- Select Rearrange.
- Drag and drop the custom fields to the order you want.
- Select Save Changes.
Rearranging custom fields affects the order in which they appear in relevant forms. For dependent custom fields, the dependent field must always be below the parent custom field in the order.
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.