Centres Configuration
  • 26 Jun 2023
  • 7 Minutes To Read
  • Dark
    Light
  • PDF

Centres Configuration

  • Dark
    Light
  • PDF

Article summary

A centre is the 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 field definitions for which you can enter custom field values. Based on the custom field definition type, there may be several addition indirect dependencies, such as clients, groups, and users.

API operations

CasC for centres supports two operations.

ActionEndpointDescription
GET/configuration/centres.yamlGet current centres configuration.
PUT/configuration/centres.yamlWrite 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 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

NameTypeDescriptionRequired
idStringThe unique identifier of the centre configuration.YES
nameStringThe name of the centre configuration.YES
assignedBranchIdStringThe ID of the branch this centre was assigned to.NO
stateStringThe state of the centre. Can be ACTIVE or INACTIVE.YES
meetingDayStringThe day of the week the centre meeting day will be set.NO
notesStringNotes about the centre.NO
addressAddressThe address of the centre. For a list of fields, see address.NO
customFieldsValueSetsCustom Field Value SetContains a list of custom field value configuration sets. For a list of fields for each set, see customFieldsValueSets.NO

address

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

NameTypeDescriptionRequired
line1StringFirst line of address.NO
line2StringSecond line of address.NO
cityStringCity of address.NO
regionStringRegion of address.NO
postcodeStringPostcode for address.NO
countryStringCountry of address.NO

customFieldsValueSets

Every centre can have a list of custom field sets with their associated custom field values. Custom field 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.

NameTypeDescriptionRequired
customFieldValueSetsArrayA list of custom field sets and associated custom field values related to the branch.NO
idStringID for grouped custom field set.YES
groupedCustomFieldValuesarrayList of groups of custom field definition IDs and custom field values associated to grouped custom field set.NO
indexNumberIndex of group of custom field definition IDs and custom field values in grouped custom field set.YES
customFieldValuesArrayList of custom field definition IDs and custom field values in grouped custom field set.YES
customFieldIdStringID of a custom field definition in a grouped custom field value set.YES
valueStringCustom field value in a grouped custom field set.YES
idStringID for a single custom field set.YES
standardCustomFieldValuesArrayList of custom field definition IDs and custom field values in single custom field set.NO
customFieldIdStringID for custom field definition in single custom field set.YES
valueStringCustom field value in single custom field set.YES

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.

Validations

The Mambu API runs validation to verify the configuration request conforms to YAML syntax and the template for custom field definitions:

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

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

Basic fields validations

NameValidation
idThe ID must not be blank and must be unique in the entire centres configuration. The length must not exceed 32 characters.
nameThe name must not be blank or exceed 256 characters in length.
assignedBranchIdThe branch with the given ID must exist and also be active.
stateMust not be null.
meetingDaymust not be null and also must not be one of the non-working days of the organization.
addressThe address field values must not exceed 256 characters in length.

Custom field sets and custom field definition validations

NameValidation
idThe 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.
standardCustomFieldValuesThe list of standard custom field values must not be empty.
customFieldIdThe ID must be unique in the standard custom field set.
valueThe validation depends on the custom field definition type. See Custom field value validation for more details.

Custom field value validation

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

TypeValidation
NumberThe value must be a valid number.
CheckboxThe value must be a boolean.
DateThe value must be a valid date in the format DD-MM-YYYY.
SelectionThe value must be a valid selection ID.
Client LinkThe value must be a valid client ID.
Group LinkThe value must be a valid group ID.
User LinkThe 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?

ESC

Eddy, a generative AI, facilitating knowledge discovery through conversational intelligence