Centres Configuration
  • 21 Mar 2022
  • 7 Minutes To Read
  • Dark
    Light
  • PDF

Centres Configuration

  • Dark
    Light
  • PDF

Early Access Feature
If you would like to request early access to this feature, please get in touch with your Mambu Customer Success Manager to discuss your requirements. For more information, see Mambu Release Cycle - Feature Release Status.

A centre is Mambu's default label for a subdivision of a branch, which is the default label for an organization subdivision. A centre can be considered a sub-branch. Each branch can have multiple centres assigned to it.

If you wish, you may change the centre label. For more information, see Labels. For more information about managing your organization’s centres, see Branches and Centres. For the rest of this article we will use the terminology centre.

With Configuration as Code (CasC), you may batch configure your centre configuration via the API using YAML. For general information on CasC, see Configuration as Code Overview.

The scope of CasC for centres is limited to centres with references towards the linked objects. However, the configuration of linked objects will not be included, and they must be reconfigured separately.

Dependencies

The centres configuration has two direct dependencies:

  • The branch to which the centre is assigned.
  • The custom fields for which values can be declared. Based on the type of the custom field, there may be several addition indirect dependencies, such as clients, groups, and users.

API Operations

CasC for centres supports two operations.

Action Endpoint Description
GET /configuration/centres.yaml Get current centres configuration.
PUT /configuration/centres.yaml Write a new centres configuration to Mambu.
Please Note

If you PUT a configuration to Mambu, any current configuration settings not included in the new configuration will be deleted. PATCH requests are not currently supported.

Requests

For general information on CasC requests such as authentication and required 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.

GET configuration

curl -X GET 'https://TENANT_NAME.mambu.com/api/configuration/centres.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 configuration

curl -X PUT 'https://TENANT_NAME.mambu.com/api/configuration/centres.yaml' \
-H 'Accept: application/vnd.mambu.v2+yaml' \
-H 'Content-Type: application/yaml' \
-H 'Authorization: Basic {auth}' \
--data-binary @centres.yaml

{auth} is the base-64-encoded value of username:password. For more information, see Authentication in our API reference.

@centres.yaml represents the absolute path of the file on your device.

Use “--data-raw” if you want to specify the configuration inline.

Example configuration

centres:
  - id: "DT1"
    name: "Down Town"
    assignedBranchId: "B1"
    state: "ACTIVE"
    meetingDay: "FRIDAY"
    notes: "All clients and officers gather in the market"
    address:
      line1: "line1"
      line2: "line2"
      city: "City"
      region: "Region"
      postcode: "789456"
      country: "Country"
  - id: "MP1"
    name: "Market Place"
    assignedBranchId: "B1"
    state: "ACTIVE"
    meetingDay: "FRIDAY"
    notes: "All clients and officers gather in the market"
    address:
      line1: "line1"
      line2: "line2"
      city: "City"
      region: "Region"
      postcode: "789456"
      country: "Country"
    customFieldValueSets:
      - id: "_grouped_set_id"
        groupedCustomFieldValues:
          - index: 1
            customFieldValues:
              - customFieldId: "_cf_id_1"
                value: "value_group_1_1"
              - customFieldId: "_cf_id_2"
                value: "value_group_1_2"
              - customFieldId: "_cf_id_3"
                value: "value_group_1_3"
          - index: 2
            customFieldValues:
              - customFieldId: "_cf_id_1a"
                value: "value_group_2_1a"
              - customFieldId: "_cf_id_2a"
                value: "value_group_2_2a"
              - customFieldId: "_cf_id_3a"
                value: "value_group_2_3a"
              - customFieldId: "_cf_id_3b"
                value: "client_id"
      - id: "_non_grouped_set_id"
        standardCustomFieldValues:
          - customFieldId: "_cf_non_grouped_1"
            value: "value_non_grouped_1"
          - customFieldId: "_cf_non_grouped_2"
            value: "value_non_grouped_2"
          - customFieldId: "_cf_non_grouped_3"
            value: "value_non_grouped_3"

General attributes

Name Type Description Required
id String The unique identifier of the centre configuration.
name String The name of the centre configuration.
assignedBranchId String The id of the branch this centre was assigned to.
state String The state of the centre. Can be ACTIVE or INACTIVE.
meetingDay String The day of the week the centre meeting day will be set.
notes String Notes about the centre.
address Address The address of the centre. For a list of fields see below.
customFieldsValueSets Custom Field Value Set Contains a list of custom fields values configuration sets. For a list of fields for each set, see below.

address

Every centre has one address associated to it with the following fields:

Name Type Description Required
line1 String First line of address.
line2 String Second line of address.
city String City of address.
region String Region of address.
postcode String Postcode for address.
country String Country of address.

customFieldsValueSets

Every centre can have a list of custom field value sets with their associated custom field values. Custom field value sets can either be GROUPED or SINGLE.

The grouped custom field sets field is represented by an array of array of values. The single custom field sets field is represented by an array of values.

Name Type Description Required
customFieldValueSets Array A list of custom field value sets and associated custom field values related to the branch.
id String Id for grouped custom field value set.
groupedCustomFieldValues Array List of entries of custom field values associated to grouped custom field value set.
index Number Index of entry of group of custom field values in grouped custom field value set.
customFieldValues Array List of custom field values in entry in grouped custom field value set.
customFieldId String Id of a custom field in an entry in a grouped custom field value set.
value String Value of a custom field in an entry in a grouped custom field value set.
id String Id for single custom field value set.
standardCustomFieldValues Array List of custom fields in a single custom field value set.
customFieldId String Id for custom field in a single custom field value set.
value String Value for custom field in a single custom field value set.

Replies

If you do not receive a 200 OK response then fix any validation errors and make another PUT request until you receive a 200 OK response.

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.

Validations

The Mambu API runs validation to verify the configuraiton request conforms to YAML syntax and the template for custom fields:

  • References must be properly mapped and exist in the target system.
  • Custom fields and values must be accurate, including dependent custom fields.

Minimum requirements indicate the line with the syntax error. Configuration values may be provided in any order.

Basic fields validations

Name Validation
id The ID must not be blank and must be unique in the entire centres configuration. The length must not exceed 32 characters.
name The name must not be blank or exceed 256 characters in length.
assignedBranchId The branch with the given ID must exist and also be active.
state Must not be null.
meetingDay must not be null and also must not be one of the non-working days of the organization.
address The address field values must not exceed 256 characters in length.

Custom field sets and custom field validations

Name Validation
id The custom field set with the given ID must exist, the ID must not be empty, must not exceed 256 characters in length and must be unique in the configuration.
standardCustomFieldValues The list of standard custom field values must not be empty.
customFieldId The ID must be unique in the list of standard custom field values.
value The validation depends on the type of the custom field. See below for more details.

Custom field value validation

The validations for the custom field values are based on the custom field type:

Type Validation
Number The value must be a valid number.
Checkbox The value must be a boolean.
Date The value must be a valid date in the format DD-MM-YYYY.
Selection The value must be a valid selection ID.
Client Link The value must be a valid client ID.
Group Link The value must be a valid group ID.
User Link The value must be a valid user ID.

Warnings

Existing centres that are not included in configuration updates are deleted, unless the centre is assigned to a client or it has documents attached, in which case it cannot be deleted. Instead, it will be deactivated. When this occurs, the API returns a list of warning messages letting the user know which centres have been deleted and which centres were deactivated instead.

If you successfully delete a centre, you will receive the following warning message: "Centre [ id = CENTRE_ID] has been deleted".

If you try to delete a centre that is assigned to a client or that has documents attached, you will receive the following warning message: "Centre [id = CENTRE_ID] could not be deleted and was deactivated".


Was this article helpful?