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

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.

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

Custom field attributes

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: 

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: 

Replies

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.

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.

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

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 

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).