Configuration as Code for Custom Fields
  • 08 Oct 2020
  • 13 Minutes To Read
  • Print
  • Share
  • Dark
    Light

Configuration as Code for Custom Fields

  • Print
  • Share
  • Dark
    Light

Early Access feature
If you would like to request early access, please get in touch with your Mambu Customer Success Manager to discuss your requirements.

Overview

With Configuration as Code for custom fields you can dramatically speed up updating custom fields for new instances or migrating from one environment to the other by providing your configuration programatically.
It is an API-based solution that enables you to include Mambu’s configuration into your DevOps processes, ensuring that you can, in a programmatic way, save and load it as needed into your environment.

The scope is therefore limited to custom field sets and custom field configuration with references towards the linked objects. However, the configuration of linked objects will not be included and must be done separately.

How to work with CasC for Custom Fields

A configuration as code for custom fields YAML file contains custom field sets and the associated custom fields. For complete YAML specifications, please see YAML data serialization language.

Permission to work with Configuration as Code Endpoints

Please note that in order to work with Configuration as Code endpoints, you need to be authenticated with a user type "Administrator" or have the "Manage Configuration as Code" permission.

How to manage configurations files

1. You can keep all custom fields in a single large YAML file. This strategy is recommended if you have no more than 300 custom fields in total.
2. You can create one YAML file per type (availableFor property) of custom field.
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.

Make sure you create files with customfields configurations grouped by "availableFor=sameEntityID"
  • Splitting custom fields of the same type into multiple files will have undesired effects, such as all the sets and fields not present in the file will be automatically deactivated.
  • Sets and fields are never deleted but only deactivated when not present in the YAML file. However, selections, usages, view and edit rights of custom fields are deleted when not present in the YAML file.

Important notes:

  • The output YAML of GET /configuration/customfields.yaml should always be accepted by PUT /configuration/customfields.yaml with no changes.
  • Index in the list of sets and fields is implicitly determined by the order of objects in the YAML file.

How to download the custom fields configuration template

To use the endpoints you will need to specify the following headers

For GET - use the "Accept" header with "application/vnd.mambu.v2+yaml
For PUT - use the "Accept" header with "application/vnd.mambu.v2+yaml and "Content-Type" "application/yaml"

If you want to start a configuration from scratch, the following command will download the custom fields configuration template.

Starting with Curl

curl -X GET 'https://tenanturl.mambucloud.com/api/configuration/customfields/template.yaml' \

-H 'Accept: application/vnd.mambu.v2+yaml' \

-u user:password

Starting with API calls

GET /configuration/customfields/template.yaml

How to download the current custom fields configuration

The current custom fields configuration can be downloaded using the command below. The response of this command can be saved in a file which later can be used to update the configuration. Add /customfields.yaml to the end of the command to redirect the output to a file.

Starting with Curl

curl -X GET 'https://tenanturl.mambucloud.com/api/configuration/customfields.yaml' \

-H 'Accept: application/vnd.mambu.v2+yaml' \

-u user:password

Starting with API calls

  • To retrieve the full custom fields sets and custom fields configuration
GET  /configuration/customfields.yaml
  • To retrieve the custom fields sets and custom fields configuration for one entity only, for example "CLIENT"
GET  /configuration/customfields.yaml?availableFor=CLIENT
  • To retrieve the custom fields sets and custom fields configuration for a couple of entities, for example "CLIENT" and "GROUP"
GET  /configuration/customfields.yaml?availableFor=CLIENT&availableFor=GROUP

How to update the custom fields configuration

The following command will update the current custom fields configuration. The new configuration is loaded from a YAML file that can be name customfields.yaml, ''clientcustomfields.yaml' and so on. The recommended way of working with the update operation is the following:

  • Download the current custom fields configuration via GET
  • Make changes in the yaml file as needed: add custom fields, change existing custom fields or sets, remove custom fields.
  • Execute the command bellow, fix the validation errors if any and retry. A "200 OK" response code means that the entire configuration has been applied.
What to do if you don't receive a "200 OK" response

In the case you yaml file is valid, if more than 60 seconds have passed and you have not received a "200 OK" response, you will receive a "504 Gateway Time-out". That is known behaviour as we expect all responses to be below 60 seconds.

If you do encounter this issue, please make sure you have under 300 custom fields per yaml configuration file and proceed with contacting us directly at support@mambu.com, so we can investigate the problem.

Starting with Curl

curl -X PUT 'https://tenanturl.mambucloud.com/api/configuration/customfields.yaml' \

-H 'Accept: application/vnd.mambu.v2+yaml' \

-H 'Content-Type: application/yaml' \

-u user:password \

--data-binary @customfields.yaml

“@/Users/ …. /customfields.yaml” represents the absolute path of the file on your device.

(Use “--data-raw” if you want to specify the YAML body inline).

Starting with API calls

PUT  /configuration/customfields.yaml

Custom field set configuration input specification

Custom field sets have the following attributes:

  1. ID - unique identifier, must start with the MBU prefix "_" such as "_CustomFieldID"
  2. Name
  3. Description
  4. Type: SINGLE or GROUPED
  5. Availability: indicates the entity associated with the custom field set. Can be : CLIENT, GROUP, CREDIT_ARRANGEMENT, LOAN_ACCOUNT, GUARANTOR, ASSET, DEPOSIT_ACCOUNT, TRANSACTION_CHANNEL, BRANCH, CENTRE, USER.
  6. List of custom fields
customFieldSets:
  - id: "_set_1_id"
    name: "set_1_name"
    description: "set 1 description"
    type: "SINGLE"
    availableFor: "CLIENT"
    customFields: [] # empty list of fields
  - id: "_set_2_id"
    name: "set_2_name"
    description: "set 2 description"
    type: "GROUPED"
    availableFor: "ASSET"
    customFields: [] # empty list of fields

Custom fields configuration input specification

Custom fields have the following attributes:

Rights

is used to set for which specific Roles will the Custom Fields be available, in read or edit mode. To read more on this, please see Custom Fields Rights by Role.

In the YAML configuration file, the usage rights will need to be specified using the following parameters:

  • Specific roleIDs - to set viewRight and editRights by roleID per custom field, already present into the system
  • allUser: true/false - if no particular roles are specified
   viewRights:
     roles: [] # empty list of roles
     allUsers: true
   editRights:
     roles: 
       - roleID 
       - roleID2
     allUsers: false
Please Note
  • If "access rights" are not specified, the field will be deactivated.
  • If a "roleID" is specified for edit rights, it will automatically be added for view rights as well.
# complete example of a set available for clients that have access rights defined
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:  [] 
    viewRights:
      roles:
      - "role_3_id"
      - "role_2_id"
      allUsers: false
    editRights:
      roles:
      - "role_3_id"
      allUsers: false

Usage

Usage can be defined on 2 levels which are mutually exclusive.

  1. On record type level via the ‘usage’ field for custom fields that have dependencies. This is applicable for clients, groups, loan accounts, savings accounts and transaction channels and is dictated by set availability. To read more, please go to Custom Field Usage.

In the YAML configuration file, the usage will need to be specified using the following parameters:

 usage: [] # empty usage
 usage:  
    - id: "RelatedEntityID1" 
      required: true
      default: true
    - id: "RelatedEntityID2" 
      required: false
      default: true

"RelatedEntityID" can be, based on the "availableFor" field on the set, a:

  • ClientTypeID - "availableFor"=CLIENT
  • GroupRoleID - "availableFor"=GROUP
  • LoanProductID - "availableFor"=LOAN_ACCOUNT
  • DepositProductID - "availableFor"=DEPOSIT_ACCOUNT
  • TransactionChannelID - "availableFor"=TRANSACTION_CHANNEL
    that must be already present into the system.
# complete example of a set available for clients that has a custom field with usage defined
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
  1. On custom field level via the ‘required' and ‘default’ fields, for entities that don’t have any dependencies, such as asset, center, credit arrangement, guarrantor, branch and user. This means that the usage is not defined via the 'usage' field since there is no entity id to reference, and only the ‘required' and ‘default’ fields are used.
# complete example of a set available for users that has a custom field with usage defined
customFieldSets:
- id: "_set_users_id"
  name: "set users name"
  description: "set description"
  type: "SINGLE"
  availableFor: "USER"
  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
  • Usage for custom fields of type selections that are dependent on another custom field (have "dependentFieldId" field set) is inherited from the dependent field and must not be defined

General attributes

  • Id - unique identifier
  • Type: the data types allowed for custom fields, can be: "FREE_TEXT", "SELECTION", "NUMBER", "CHECKBOX", "DATE", "CLIENT_LINK", "GROUP_LINK", "USER_LINK"
  • Validation rules: available only if the type is "FREE_TEXT"
  • Display settings
    • display name
    • description
    • field size: can be "LONG" or "SHORT"
  • State: can be "ACTIVE" or "INACTIVE"
# complete example of a custom field set and custom field of type free text
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

Selection custom fields

Custom fields of type selection have 2 additional fields:

  • Dependent field ID
    • ID of a custom field of type selection that is present in the yaml file, can not reference an existing custom field present in the system but not on the configuration file
    • not mandatory, to be specified only when the currrent field depends on another custom field of type selection and you want to define selection options for the options present on the dependent field
  • Selection options
    • For selection ID
      • ID of a custom field selection option from the dependent field
      • not mandatory, if the field doesn't depend on another field, this is not required
    • Available options—list all the selection options for a selection custom field
      • Selection ID
      • Value
      • Score
# complete example of a set that has 2 fields of type selection, the second one depending on the first one
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

Validations

With all use cases, a validation of the uploaded file will be done, ensuring the following:

  • Syntax is correct as per YAML standards and the template for Custom Fields.
  • Content is correct.
  • References are all properly mapped (and exist in the target system).
  • Custom fields properties are accurate and correct (including dependent custom fields).

Usage particularities

Depending to your current configuration of Mambu, there are some specific expected behaviour:

Your Mambu instance is new. No custom fields have been created.

  1. Create the desired configuration of custom fields sets and fields in the YAML config file.
  2. Upload the configuration file.
  3. After a successful validation, the configuration is created in Mambu.

You want to add custom fields on top of an existing structure

If you already have some custom fields created in Mambu and want to add more custom fields or custom fields sets via configuration as code, without impacting the existing structure:

  1. Export current configuration using GET /configuration/customfields.yaml
  2. Edit the configuration in the YAML file as needed, to add more custom field entries.
  3. Upload file via PUT /configuration/customfields.yaml
  4. Configuration is updated and new custom fields are added.

You want to change the existing structure—update existing field

  1. Export current configuration using GET /configuration/customfields.yaml
  2. Edit the configuration in the YAML file and update values for the custom fields you want to change
  3. Upload file via PUT /configuration/customfields.yaml
  4. Configuration for the changed field is updated

You want to change the existing structure—deactivate existing field

  1. Export current configuration using GET /configuration/customfields.yaml
  2. Edit the configuration in the YAML file and remove the details for the custom fields you want to deactivate.
  3. Upload file via PUT /configuration/customfields.yaml
  4. Configuration is updated. The fields removed for the config file will be deactivated. The remaining existing fields indexes will be updated.

You want to migrate custom fields structure from one environment to another

In the case you already have a custom field configuration defined and want to migrate the same configuration to a different environment:

  1. Export current configuration using GET /configuration/customfields.yaml
  2. Using the same customfields.yaml or after making updates as needed, call PUT /configuration/customfields.yaml on your new environment.
  3. The custom fields configuration will not be present in your new environment as well.

You want to change the existing structure—update configuration for a specific entity

In the case you want to update the custom fields configuration only for Entity (such as Clients):

  1. Export current configuration using GET /configuration/customfields.yaml and edit the configuration in the YAML file and only keep the custom fields available for Entity. OR use GET /configuration/customfields.yaml?availableFor=Entity
  2. Upload file via PUT /configuration/customfields.yaml
  3. Configuration is updated only for custom fields available for Entity.

Notes & Recommendations

  • If there is no change between the existing configuration and the new configuration, no update is performed.
  • We recommend you to only update the configuration outside of working hours, as to avoid anomalies in the system. The custom field configuration should not be changed from the UI concurrently with the API call.
  • Built-in fields and sets are excluded from the configuration for the time being because they are created with the tenant provisioning and are not fully customisable.
  • Existing customs fields that are not present in the YAML file for the given entities will be deactivated. For example, a custom field available for clients that is not present in the yaml file, but the yaml file has other custom fields defined for clients, will be deactivated.
  • All dependencies must exist the in the database before updating the custom fields configuration and the mapping is made via the unique ID (read/access rights : roles ID; usage: product IDs, client roles ID, or transaction channels IDs).
  • The order of the custom field and sets that can be seen on the UI is given by the YAML file order.
  • There is no altered behavior compared to the custom fields/custom field set UI behavior. The UI has these constraints implicitly done by the UI interface (for example, validation rules are hidden on the UI if the custom field type is not FREE_TEXT), but the API needs to enforce the same constraints via validations.

Ask the Mambu Community

If you have a question about how anything works or have come across something you haven't seen explained here, get in touch with our community of fellow users and Mambuvians where someone will lend a hand.

Ask a question about Configuration as Code

* If you don't already have an account you will be prompted to create one when you first visit the site.

Was This Article Helpful?