- 03 May 2023
- 13 Minutes To Read
- Print
- DarkLight
- PDF
Custom Fields Configuration
- Updated On 03 May 2023
- 13 Minutes To Read
- Print
- DarkLight
- PDF
Custom fields are additional fields you can create in order to capture any additional information required for your business processes. Every custom field must be a part of a custom field set. For more information, see Custom Fields.
With Configuration as Code (CasC), you may batch configure your custom fields configuration via the API using YAML. For general information on CasC, see Configuration as Code Overview.
API Operations
CasC for custom fields supports three operations.
Action | Endpoint | Description |
---|---|---|
GET | /configuration/customfields.yaml | Get current custom fields configuration. |
PUT | /configuration/customfields.yaml | Write a new configuration for your custom fields to Mambu. |
GET | /configuration/customfields/template.yaml | Get your custom fields configuration template in YAML. This is useful when configuring from scratch. For formatting information for the fields, see General Attributes below for an example. |
Requests
For general information on CasC requests such as authentication and general headers, see Configuration as Code Overview.
The following section shows sample requests using curl and basic authentication. For all examples, replace TENANT_NAME
with your actual tenant name.
Additional headers
You may send synchronous or asynchronous PUT
requests. To use the endpoint asynchronously, you must provide two additional headers:
X-Mambu-Async
with a value oftrue
.X-Mambu-Callback
with the callback URL.
You may wish to make asynchronous calls for unusally large requests, such as requests that include more than 300 custom fields. Note that we generally do not recommend making individual requests of that size, as a response may take 60 seconds or more.
The expected status code in case of a successful asynchronous request is 202 Accepted
. When the update configuration operation is completed, a message will be posted to the provided URL with information about whether the updated request completed successfully or not.
GET requests
Get custom field sets and custom fields for all entities
curl -X GET 'https://TENANT_NAME.mambu.com/api/configuration/customfields.yaml' \
-H 'Accept: application/vnd.mambu.v2+yaml' \
-H 'Authorization: Basic {auth}'
{auth} is the base-64-encoded value of username:password
. For more information, see Authentication in our API reference.
Get custom field sets and custom fields specified entities
To retrieve custom field sets and custom fields for specific entities, specify the desired entities using the availableFor
query parameter. You may specify more than one entity.
For a list of available values to pass to this parameter, see the relevant table in the Custom Fields Configuration endpoint in our API v2 Reference.
The following example returns all clients and groups:
curl -X GET 'https://TENANT_NAME.mambu.com/api/configuration/customfields.yaml?availableFor=CLIENT&availableFor=GROUP' \
-H 'Accept: application/vnd.mambu.v2+yaml' \
-H 'Authorization: Basic {auth}'
{auth} is the base-64-encoded value of username:password
. For more information, see Authentication in our API reference.
Get your custom fields template
curl -X GET 'https://TENANT_NAME.mambu.com/api/configuration/customfields/template.yaml' \
-H 'Accept: application/vnd.mambu.v2+yaml' \
-H 'Authorization: Basic {auth}'
{auth} is the base-64-encoded value of username:password
. For more information, see Authentication in our API reference.
PUT requests
curl -X PUT 'https://TENANT_NAME.mambu.com/api/configuration/customfields.yaml' \
-H 'Accept: application/vnd.mambu.v2+yaml' \
-H 'Content-Type: application/yaml' \
-H 'Authorization: Basic {auth}' \
--data-binary @customfields.yaml
“@customfields.yaml” represents the absolute path of the file on your device.
Use “--data-raw” if you want to specify the YAML body inline.
{auth} is the base-64-encoded value of When custom field sets or custom fields are not present in the YAML file, they are deactivated, they are not deleted. However when selections, usages, view, and edit rights of custom fields are not present in the YAML file, they are deleted.username:password
. For more information, see Authentication in our API reference.
Custom field set and custom field example
The following example shows a complete request for a custom field set and custom field of the free text type.
customFieldSets:
- id: "_set_id"
name: "set name"
description: "set description"
type: "SINGLE"
availableFor: "CLIENT"
customFields:
- id: "field_id"
type: "FREE_TEXT"
state: "ACTIVE"
validationRules:
unique: false
validationPattern: "##@@"
displaySettings:
displayName: "field name"
description: "field description"
fieldSize: "SHORT"
usage:
- id: "client"
required: false
default: false
viewRights:
roles: []
allUsers: true
editRights:
roles:
- role_id
allUsers: false
Custom field set attributes
Name | Type | Description | Required |
---|---|---|---|
id | String | User-defined ID, globally unique | ✔ |
name | String | User-defined name of the custom field set, unique for each set type. | ✔ |
description | String | User-defined description of the custom field set. | ✘ |
type | String | Defines how the custom field set will be used in the UI and how the custom field values will be stored. For SINGLE set type the custom field set is displayed in the UI and can be used only once on one entity. For GROUPED set type the custom field set is allowed multiple times for the same entity. | ✔ |
availableFor | String | Indicates the entity associated with the custom field set. The options are CLIENT , GROUP , CREDIT_ARRANGEMENT , LOAN_ACCOUNT , GUARANTOR , ASSET , DEPOSIT_ACCOUNT , TRANSACTION_CHANNEL , BRANCH , CENTRE , orUSER . | ✔ |
customFields | List | This section lists the custom fields associated with the custom field set. | ✘ |
Custom field attributes
Name | Type | Description | Required |
---|---|---|---|
id | String | User-defined ID, globally unique. | ✔ |
type | String | Supported input type. The options are FREE_TEXT , SELECTION , NUMBER , CHECKBOX , DATE , DATE_TIME , CLIENT_LINK , GROUP_LINK , or USER_LINK . | ✔ |
state | String | Indicates whether the field is active or inactive | ✔ |
validationRules | ValidationRules | Settings for field input validation. Available only if the type is FREE_TEXT . | ✘ |
validationRules.unique | Boolean | Indicates whether this field allows duplicate values or not. | ✘ |
validationRules. validationPatttern | String | Indicates if a validation is set in terms of expected character type/format. | ✘ |
displaySettings | DisplaySettings | Custom field display settings. | ✔ |
displaySettings. displayName | String | User-provided name of the custom field | ✔ |
displaySettings. description | String | User-provided description of the custom field. | ✘ |
displaySettings. fieldSize | String | Field display size in the UI. The options are LONG or SHORT . | ✔ |
usage | Usage | Information on what record types the custom field is available for. Defines the usage at record type level. The custom field is going to be available only for the record types that are referenced in the list by ID. Mutually exclusive with usage defined on custom field level by required and default fields. For selection custom fields that have a dependentFieldId set, the usage is inherited from the dependent field and must not be defined. For more information, see Usage below. | ✘ |
usage.id | String | Indicates the user defined ID of the associated entity. Must be an already existing id. | ✘ |
usage.required | Boolean | Defines if a custom field is required. | ✘ |
usage.default | Boolean | Defines if a custom field is used as a default. | ✘ |
viewRights | AccessRights | Response representation of the access rights for a custom field configuration. If access rights are not specified, the field will be deactivated. | ✘ |
viewRights.roles | Array | Lists the IDs of the roles that have view rights for this field when it's not accessible by all users. The IDs must be already existing. | ✘ |
viewRights.allUsers | Boolean | Indicates whether the field can be viewed/edited by all users if true or by the roles indicated by rolesIds if false. | ✘ |
editRights | AccessRights | Response representation of the access rights for a custom field configuration. If access rights are not specified, the field will be deactivated. | ✘ |
editRights.roles | Array | Lists the IDs of the roles that have edit rights for this field when it's not accessible by all users. The IDs must be already existing. If a role ID is specified for edit rights, it will automatically be added for view rights as well. | ✘ |
editRights.allUsers | Boolean | Indicates whether the field can be viewed/edited by all users if true or by the roles indicated by rolesIds if false. | ✘ |
Selection custom fields
If the type
of a custom field is SELECTION
then it is a special kind of custom field called a selection custom field. Selection custom fields have additional fields in the YAML file.
There are two kinds of selection custom fields. Regular selection custom fields and dependent selection custom fields.
For more information about selection custom fields, see Custom Fields - Selection Custom Fields.
Example
The following complete example shows a request for two fields of type selection, with the second one depending on the first.
customFieldSets:
- id: "_set1_Users"
name: "set1"
description: "set 1 description"
type: "SINGLE"
availableFor: "USER"
customFields:
- id: "selection_1"
type: "SELECTION"
state: "ACTIVE"
displaySettings:
displayName: "selection 1"
description: "selection without any dependent field"
fieldSize: "SHORT"
viewRights:
roles:
- "role_1_id"
allUsers: false
editRights:
roles: []
allUsers: false
selectionOptions: # this selection field doesn't depend on another selection, 'dependentFieldId' and 'selectionId' are not specified
- availableOptions:
- selectionId: "selection_1_option_1_id"
value: "selection 1 option 1"
- selectionId: "selection_1_option_2_id"
value: "selection 1 option 2"
score: 5
required: true
default: true
- id: "selection_2"
type: "SELECTION"
state: "ACTIVE"
displaySettings:
displayName: "selection 2"
description: "selection field dependent on another selection field"
fieldSize: "SHORT"
viewRights:
roles:
- "role_3_id"
- "role_2_id"
allUsers: false
editRights:
roles:
- "role_3_id"
allUsers: false
dependentFieldId: "selection_1" # id of the selection field that this field depends on
selectionOptions:
- forSelectionId: "selection_1_option_1_id" # id of the selection option from the dependent field
availableOptions:
- selectionId: "952379149"
value: "option A"
score: 5
- forSelectionId: "selection_1_option_2_id" # id of the selection option from the dependent field
availableOptions:
- selectionId: "487822627"
value: "option B"
score: 10
- selectionId: "215308065"
value: "option C"
score: 3
Regular selection custom fields
Custom fields of type selection include additional fields:
selectionOptions:
- availableOptions:
- selectionId:
value:
score:
- selectionId:
value:
score:
Name | Type | Description | Required |
---|---|---|---|
selectionOptions | CustomFieldSelectionOptions | Indicates that the field has predefined selections and only those can be used to populate it | ✘ |
availableOptions | CustomFieldAvailableOptions | List of values that can be used in the saved field based on current master selection. | ✘ |
selectionId | String | System-generated ID of the predefined value. | ✘ |
value | String | Predefined value name. | ✘ |
score | Number | Selection score. | ✘ |
Dependent selection custom fields
Dependent selection custom fields have all the fields that a regular selection custom field has as well as a couple additional fields.
dependentFieldId:
selectionOptions:
- forSelectionId:
availableOptions:
- selectionId:
value:
score:
- forSelectionId:
availableOptions:
- selectionId:
value:
- selectionId:
value:
score:
Name | Type | Description | Required |
---|---|---|---|
dependentFieldId | String | The ID for the parent selection custom field that the dependent selection custom field depends on. | ✘ |
forSelectionId | String | The ID of a custom field selection option from the dependent field. It is not mandatory, if the field doesn't depend on another field. | ✘ |
The usage
for a dependent selection custom field is inherited from the parent selection custom field.
If you try to specify a usage
for a dependent selection custom field, you will get a validation error.
Replies
If you do not receive a If you If you encounter this issue, please contact us through Mambu Support so we can investigate it.200 OK
status code then fix any validation errors and make another PUT
request until you receive a 200 OK
status code.PUT
a valid YAML configuration to the API and you do not receive a 200 OK
status code within 60 seconds, you may receive a 504 Gateway Timeout
status code. We expect all responses to be below 60 seconds.
Managing configuration files
There are two approaches with regards to how you manage your configuration file(s) in the CasC for custom fields feature.
- You can keep all custom fields in a single large YAML file. This strategy is recommended if you have less than 300 custom fields.
- You can create one YAML file per entity. This can be specified with the
availableFor
parameter when you make your API call. For example, you can have one file for client custom fields, one for group custom fields and so on. This is the most granular way of organizing custom fields.
Splitting custom fields of the same entity into multiple YAML configuration files will have undesired effects, such as all the sets and fields not present in the file will be automatically deactivated.
Built-in custom fields and custom field sets
Built-in custom fields and custom field sets are excluded from the configuration for the time being because they are created with the tenant provisioning and are not fully customisable.
For example, in the clients entity there are some custom field sets and custom fields that are not fully configurable. These particular custom field sets and custom fields are not included in the CasC feature and therefore they will not appear on the YAML file.
Entities without additional custom field sets
The guarantors and assets entities do not have custom field sets in the Mambu UI. Therefore in the YAML configuration file there will only be one default custom field set for each of these entities.
You cannot add more custom field sets to these entities. You can only add, edit, and remove custom fields to the default custom field set.
Usage
There are two types of entities: those with dependencies, and those without dependencies.
Entities with dependencies | Entities without dependencies |
---|---|
Clients Groups Loan account Deposit account Deposit Product Transaction channel Transaction by Type | Asset Centre Credit arrangement Guarantor Branch User |
The entities that have dependencies can either define usage
at the resource level or the custom field level.
The entities that do not have dependencies can only define usage
at the custom field level.
Usage defined at the resource level
For entities that have dependencies you can define the usage for each type of the entity.
For example:
- Clients: there can be multiple client types within the clients entity.
- Groups: there can be multiple group roles within the groups entity.
- Loan account: there can be multiple loan products within a loan account.
- Deposit account: there can be multiple savings products within a savings account.
- Deposit product: there can be different usage settings per product type.
- Transaction channel: there can be multiple options for transaction channels specified.
- Transaction by Type: there can different usage settings per transaction type.
Example
The following example shows a set available for clients that have a custom field with usage defined. The custom field is not available for client types not included in the usage list
customFieldSets:
- id: "_set_id"
name: "set name"
description: "set description"
type: "SINGLE"
availableFor: "CLIENT"
customFields:
- id: "field_id"
type: "FREE_TEXT"
state: "ACTIVE"
validationRules:
unique: false
displaySettings:
displayName: "field name"
description: "field description"
fieldSize: "SHORT"
usage: # usage defined on entity level, for each referenced entity id
- id: "client_type_1_id"
required: true
default: true
- id: "client_type_2_id"
required: false
default: true
viewRights:
roles: []
allUsers: true
editRights:
roles: []
allUsers: true
Usage defined at the custom field level
For entities that do not have dependencies you can only define usage at the custom field level. For entities with dependencies you can choose to define usage at the custom field level. To define usage at the custom field level you use the required
and default
fields.
Example for an entity with dependencies
The following example shows a set available for clients that has a custom field available for all existing client types, with the same usage settings.
Considering that you only have two client types defined, the above example will look like this:
customFieldSets:
- id: "_set_id"
name: "set name"
description: "set description"
type: "SINGLE"
availableFor: "CLIENT" # has dependent entities: client types
customFields:
- id: "field_id"
type: "FREE_TEXT"
state: "ACTIVE"
validationRules:
unique: false
displaySettings:
displayName: "field name"
description: "field description"
fieldSize: "SHORT"
viewRights:
roles: []
allUsers: true
editRights:
roles: []
allUsers: true
required: false # usage settings defined on custom field level for all existing client types
default: true # usage settings defined on custom field level for all existing client types
We will detect automatically if you have the same usage settings for a custom field that is available for all record types, and will replace the usage list with the usage settings at custom field level and vice versa.
Example for an entity without dependencies
The following example shows a set available for branches that has a custom field with usage defined.
customFieldSets:
- id: "_set_users_id"
name: "set users name"
description: "set description"
type: "SINGLE"
availableFor: "BRANCH"
customFields:
- id: "field1_users"
type: "NUMBER"
state: "ACTIVE"
displaySettings:
displayName: "field1"
description: "field description"
fieldSize: "SHORT"
viewRights:
roles: []
allUsers: false
editRights:
roles: []
allUsers: false
required: true # usage defined on the custom field level
default: true # usage defined on the custom field level
- If a field is required, it must also be default.
- If usage is not specified or empty, the field will be deactivated.
Validations
Your input will be validated according to the same rules employed by the Mambu UI. During upload of a new configuration file, the following areas will be validated:
- Syntax is correct as per YAML standards and the template for Custom Fields.
- Content is correct.
- References to dependencies are all properly mapped (and exist in the target system).
- Custom field properties are accurate and correct (including dependent custom fields).