Custom Fields Configuration
  • 03 May 2023
  • 13 Minutes To Read
  • Dark
    Light
  • PDF

Custom Fields Configuration

  • Dark
    Light
  • PDF

Article Summary

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.

ActionEndpointDescription
GET/configuration/customfields.yamlGet current custom fields configuration.
PUT/configuration/customfields.yamlWrite a new configuration for your custom fields to Mambu.
GET/configuration/customfields/template.yamlGet 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 of true.
  • 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 username:password. For more information, see Authentication in our API reference.

Please Note

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.

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

NameTypeDescriptionRequired
idStringUser-defined ID, globally unique
nameStringUser-defined name of the custom field set, unique for each set type.
descriptionStringUser-defined description of the custom field set.
typeStringDefines 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.
availableForStringIndicates 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.
customFieldsListThis section lists the custom fields associated with the custom field set.

Custom field attributes

NameTypeDescriptionRequired
idStringUser-defined ID, globally unique.
typeStringSupported input type. The options are FREE_TEXT, SELECTION, NUMBER, CHECKBOX, DATE, DATE_TIME, CLIENT_LINK, GROUP_LINK, or USER_LINK.
stateStringIndicates whether the field is active or inactive
validationRulesValidationRulesSettings for field input validation. Available only if the type is FREE_TEXT.
validationRules.uniqueBooleanIndicates whether this field allows duplicate values or not.
validationRules.
validationPatttern
StringIndicates if a validation is set in terms of expected character type/format.
displaySettingsDisplaySettingsCustom field display settings.
displaySettings.
displayName
StringUser-provided name of the custom field
displaySettings.
description
StringUser-provided description of the custom field.
displaySettings.
fieldSize
StringField display size in the UI. The options are LONG or SHORT.
usageUsageInformation 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.idStringIndicates the user defined ID of the associated entity. Must be an already existing id.
usage.requiredBooleanDefines if a custom field is required.
usage.defaultBooleanDefines if a custom field is used as a default.
viewRightsAccessRightsResponse representation of the access rights for a custom field configuration. If access rights are not specified, the field will be deactivated.
viewRights.rolesArrayLists 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.allUsersBooleanIndicates whether the field can be viewed/edited by all users if true or by the roles indicated by rolesIds if false.
editRightsAccessRightsResponse representation of the access rights for a custom field configuration. If access rights are not specified, the field will be deactivated.
editRights.rolesArrayLists 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.allUsersBooleanIndicates 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: 
NameTypeDescriptionRequired
selectionOptionsCustomFieldSelectionOptionsIndicates that the field has predefined selections and only those can be used to populate it
availableOptionsCustomFieldAvailableOptionsList of values that can be used in the saved field based on current master selection.
selectionIdStringSystem-generated ID of the predefined value.
valueStringPredefined value name.
scoreNumberSelection 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: 
NameTypeDescriptionRequired
dependentFieldIdStringThe ID for the parent selection custom field that the dependent selection custom field depends on.
forSelectionIdStringThe ID of a custom field selection option from the dependent field. It is not mandatory, if the field doesn't depend on another field.
Please Note

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 200 OK status code then fix any validation errors and make another PUT request until you receive a 200 OK status code.

Please Note

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

If you encounter this issue, please contact us through Mambu Support so we can investigate it.

Managing configuration files

There are two approaches with regards to how you manage your configuration file(s) in the CasC for custom fields feature.

  1. You can keep all custom fields in a single large YAML file. This strategy is recommended if you have less than 300 custom fields.
  2. 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.
Please be Aware

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 dependenciesEntities 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
Please Note

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 
Please Note
  • 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).

Was this article helpful?