Custom Fields Configuration
  • 26 Jun 2023
  • 14 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.

A custom field consists of 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. The custom field value is the actual value that a custom field attached to an entity holds. For more information, see Custom Fields.

With Configuration as Code (CasC), you may batch configure your configuration containing custom field definitions 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 configuration of custom field definitions.
PUT/configuration/customfields.yamlWrite a new configuration for your custom field definitions to Mambu.
GET/configuration/customfields/template.yamlGet your custom field definition 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 unusually large requests, such as requests that include more than 300 custom field definitions. 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 field definitions 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 field definitions for specified entities

To get custom field sets and custom field definitions 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 field definition 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 field definitions are not present in the YAML file, they are deactivated, they are not deleted. However when selections, usages, view, and edit rights of custom field definitions are not present in the YAML file, they are deleted.

Custom field set and custom field definition example

The following example shows a complete request for a custom field set and custom field definition 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 uniqueYES
nameStringUser-defined name of the custom field set, unique for each set type.YES
descriptionStringUser-defined description of the custom field set.NO
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.YES
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.YES
customFieldsListThis section lists the custom field definitions associated with the custom field set.NO

Custom field definition attributes

NameTypeDescriptionRequired
idStringUser-defined ID, globally unique.YES
typeStringSupported input type. The options are FREE_TEXT, SELECTION, NUMBER, CHECKBOX, DATE, DATE_TIME, CLIENT_LINK, GROUP_LINK, or USER_LINK.YES
stateStringIndicates whether the field is active or inactiveYES
validationRulesValidationRulesSettings for field input validation. Available only if the type is FREE_TEXT.NO
validationRules.uniqueBooleanIndicates whether this field allows duplicate values or not.NO
validationRules.
validationPatttern
StringIndicates if a validation is set in terms of expected character type/format.NO
displaySettingsDisplaySettingsCustom field definition display settings.YES
displaySettings.
displayName
StringUser-provided name of the custom field definitionYES
displaySettings.
description
StringUser-provided description of the custom field definition.NO
displaySettings.
fieldSize
StringField display size in the UI. The options are LONG or SHORT.YES
usageUsageInformation on what record types the custom field definition is available for. Defines the usage at record type level. The custom field definition 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 definition level by required and default fields. For selection custom field definitions that have a dependentFieldId set, the usage is inherited from the dependent field and must not be defined. For more information, see Usage below.NO
usage.idStringIndicates the user defined ID of the associated entity. Must be an already existing id.NO
usage.requiredBooleanDefines if a custom field definition is required.NO
usage.defaultBooleanDefines if a custom field definition is used as a default.NO
viewRightsAccessRightsResponse representation of the access rights for viewing custom field values for this custom field definition. If access rights are not specified, the custom field definition will be deactivated.NO
viewRights.rolesArrayLists the IDs of the roles that have view rights for the custom field values of this custom field definition when it's not accessible by all users. The IDs must already exist.NO
viewRights.allUsersBooleanIndicates whether the custom field values for this custom field definition can be viewed or edited by all users if true or by the roles indicated by role IDs if false.NO
editRightsAccessRightsResponse representation of the access rights for editing custom field values for this custom field definition. If access rights are not specified, the custom field definition will be deactivated.NO
editRights.rolesArrayLists the IDs of the roles that have edit rights for the custom field values of this custom field definition when it's not accessible by all users. The IDs must already exist. If a role ID is specified for edit rights, it will automatically be added for view rights as well.NO
editRights.allUsersBooleanIndicates whether the custom field values for this custom field definition can be viewed/edited by all users if true or by the roles indicated by roles IDs if false.NO

Selection custom field definitions

A custom field definition with type SELECTION is referred to as a selection custom field and it has additional fields in the YAML file.

There are two kinds of selection custom field definitions: regular selection custom field definitions and dependent selection custom field definitions.

For more information about selection custom fields, see Custom Fields - Selection custom field definition.

Example

The following complete example shows a request for two selection custom field definitions, 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 field definitions

Selection custom field definitions 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 as custom field valuesNO
availableOptionsCustomFieldAvailableOptionsList of custom field values that can be used in the saved field based on current master selection.NO
selectionIdStringSystem-generated ID of the predefined custom field value.NO
valueStringPredefined custom field value name.NO
scoreNumberCustom field value selection score.NO

Dependent selection custom field definitions

Dependent selection custom field definitions have all the fields that a regular selection custom field definition 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 definition that the dependent selection custom field definition depends on.NO
forSelectionIdStringThe ID of a custom field value option from the dependent field. It is not mandatory, if the field does not depend on another field.NO
Please Note

The usage for a dependent selection custom field definition is inherited from the parent selection custom field definition.

If you try to specify a usage for a dependent selection custom field definition, 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 field definitions feature.

  1. You can keep all custom field definitions in a single large YAML file. This strategy is recommended if you have less than 300 custom field definitions.
  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 field definitions, one for group custom field definitions and so on. This is the most granular way of organizing custom field definitions.
Please be Aware

Splitting custom field definitions of the same entity into multiple YAML configuration files will have undesired effects. For example, all the sets and fields not present in the file will be automatically deactivated.

Built-in custom field definitions and custom field sets

Built-in custom field definitions 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 customizable.

For example, in the clients entity there are some custom field sets and custom field definitions that are not fully configurable. These particular custom field sets and custom field definitions are not included in the CasC feature and they will not appear in the YAML file.

Entities without additional custom field sets

The guarantors and assets entities do not have custom field sets in the Mambu UI; 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 field definitions 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 definition level.

The entities that do not have dependencies can only define usage at the custom field definition level.

Usage defined at the resource level

For entities that have dependencies you can define the usage for each entity type.

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 be different usage settings per transaction type.

Example

The following example shows a set available for clients that have a custom field definition with usage defined. The custom field definition 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 definition level

For entities that do not have dependencies you can only define usage at the custom field definition level. For entities with dependencies you can choose to define usage at the custom field definition level by using 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 definition available for all existing client types, with the same usage settings.

Considering that you only have two client types defined, the 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 definition level for all existing client types
    default: true   # usage settings defined on custom field definition level for all existing client types
Please Note

We will detect automatically if you have the same usage settings for a custom field definition that is available for all record types, and will replace the usage list with the usage settings at custom field definition level and vice versa.

Example for an entity without dependencies

The following example shows a set available for branches that has a custom field definition 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 definition level
    default: true  # usage defined on the custom field definition level
Please Note

If a field is required, it must also be default and 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 field definitions.
  • Content is correct.
  • References to dependencies are all properly mapped and exist in the target system.
  • Custom field definition properties are accurate and correct, including dependent custom field definitions.

Was this article helpful?