Branches Configuration
  • 17 Aug 2022
  • 6 Minutes To Read
  • Dark
    Light
  • PDF

Branches 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 branch in Mambu is the default label for an organization's subdivision. Often branches represent:

  • A geographical subdivision of an organization.
  • A product line.
  • Any other entity that represents a subdivision of an organization.

The terminology branch is the default label used for a subdivision. You can choose to change this label. For more information about changing this label, see Labels. For more information about managing your organization's branches, see Branches and Centres. For the rest of this article we will refer to an organization's subdivision as branch.

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

API Operations

CasC for branches supports two operations.

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

If you PUT a configuration to Mambu, any current configuration settings not included in the new YAML 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/branches.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/branches.yaml' \
-H 'Accept: application/vnd.mambu.v2+yaml' \
-H 'Content-Type: application/yaml' \
-H 'Authorization: Basic {auth}' \
--data-binary @branches.yaml

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

Configuration example

branches:
- id: "2"
  name: "Matola City"
  state: "ACTIVE"
  phoneNumber: "+7534987676"
  emailAddress: "matola@BofAlg.es"
  notes: "Is currently under construction to add an extra room that can be used for\
    \ the meetings.<p></p>Have <b>six new computers</b> for their staff."
  address:
    line1: "1 Bank Street"
    line2: "Old Town"
    city: "Matola City"
    region: "Matola"
    postcode: "10775"
    country: "Bankistan"
  holidays:
  - id: 13
    name: "joe matola only day"
    dayOfMonth: 26
    monthOfYear: 8
    year: 2020
    isAnnuallyRecurring: true
- id: "demoBranchId"
  name: "Maputo Downtown"
  state: "ACTIVE"
  phoneNumber: "0049302345678"
  emailAddress: "petula.clark@downtown.com"
  notes: "Is located in the surroundings of the local market with a <i>lot of potential</i>\
    \ to reach new clients."
  holidays:
  - id: 12
    name: "only maputo holiday day"
    dayOfMonth: 30
    monthOfYear: 7
    year: 2020
    isAnnuallyRecurring: true
  customFieldValueSets:
  - id: "_branches_grouped_cf_set"
    groupedCustomFieldValues:
     - index: 0
      customFieldValues:
      - customFieldId: "cf_group_field_1"
        value: "group field 1"
      - customFieldId: "cf_group_field_2"
        value: "2"
    - index: 1
      customFieldValues:
      - customFieldId: "cf_group_field_2"
        value: "500"
  - id: "_example_branch_custom_field_set"
    standardCustomFieldValues:
    - customFieldId: "cf_branch"
      value: "TRUE"

General attributes

Name Type Description Required
id String Id for the branch.
name String Name of the branch.
state String ACTIVE or INACTIVE
phoneNumber String Phone number associated with the branch.
emailAddress String Email address associated with the branch.
notes String Notes for the branch.
address Address Address associated with the branch. For a list of fields see dependencies below.
holidays Array List of holidays associated with the branch. For a list of fields, see dependencies below.
customFieldValueSets List of custom field value sets and associated custom field values. For a list of fields, see dependencies below

Dependencies

The CasC for branches configuration has three dependencies, address, holidays and customFieldValueSets.

address

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

holidays

Every branch has a list of holidays associated to it. Each holiday has the following fields:

Name Type Description Required
id Number Id of holiday.
name String Name of holiday.
dayOfMonth Number Day in the month of holiday.
monthOfYear Number Month in the year of holiday.
year Number The year of the holiday.
isAnnualRecurring Boolean Whether the holiday recurs every year.

customFieldValueSets

Every branch 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 set 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 single custom field value set.
customFieldId String Id for custom field in single custom field value set.
value String Value for custom field in 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 ensure the following:

  • Content is correct.
  • References are properly mapped and exist in the target system.
  • Branches properties are accurate.
Name Input requirement
id The id length must not exceed 32 characters and the id must be unique.
name The name length must not exceed 256 characters.
emailAddress The email address must be valid. A valid email address consists of an email prefix before the @ sign and an email domain after the sign. The email prefix must not exceed 64 characters. The email domain must not exceed 63 characters. The email address in total must not exceed 256 characters.
phoneNumber The phone number length must not exceed 256 characters.
address None of the address fields can exceed 256 characters.

For information on validation for the holidays fields, see Holidays Configuration.

Warnings

There are three warning messages you can receive when you attempt to update the CasC for branches configuration file.

  1. You cannot deactivate (disable) a branch that has active centres assigned to it. If you do not include a branch that has active centres assigned to it in the YAML file then you will get the following warning message: "Branch [ id - BRANCH_ID] could not be deactivated since it has active centre(s)".

  2. If a branch does not have any active centres assigned to it and you do not include it in the YAML file then the branch will be deactivated (disabled). You will receive the following warning message: "Branch [ id - BRANCH_ID] has been deactivated".

  3. If you try to deactivate a branch which is already deactivated then you will receive the following warning message: "Branch [ id - BRANCH_ID] could not be deactivated since it is already deactivated".


Was this article helpful?