Custom Fields Configuration

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.

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.

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

Custom field definition attributes

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:

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:

Replies

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.

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.

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

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

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.