Retrieve Allowable Branches

Overview

The Retrieve Allowable Branches API returns a list of branches that a specific user has permission to access based on their role and assigned branch access rights. This is useful for filtering dropdown selections and ensuring users only see branches they're authorized to work with.

Command Details

Command Name: RetrieveAllowableBranchesQuery

Operation Type: Query (Read Operation)

Use Cases

• User-Specific Branch Lists: Show only branches accessible to a specific user
• Transaction Forms: Populate branch dropdowns with allowed branches only
• Access Control: Enforce branch-level security in the application
• Multi-Branch Operations: Enable users to select from their authorized branches
• Administrative Management: View branch access rights for user management

API Endpoint

POST /api/bpm/qry
Content-Type: application/json
Authorization: Bearer {access_token}

Request Structure

Request Body

{
  "queryName": "RetrieveAllowableBranchesQuery",
  "data": {
    "userId": 456,
    "excludeAllBranches": false,
    "pageSize": 100
  }
}

Request Fields

Field Name	Type	Mandatory	Description
userId	Integer	Yes	User ID to retrieve allowable branches for
excludeAllBranches	Boolean	No	If true, excludes the "All Branches" option (default: false)
pageSize	Integer	No	Maximum number of branches to return

Sample Requests

1. Get Allowable Branches for Specific User

{
  "queryName": "RetrieveAllowableBranchesQuery",
  "data": {
    "userId": 456
  }
}

2. Get Allowable Branches Without "All Branches" Option

{
  "queryName": "RetrieveAllowableBranchesQuery",
  "data": {
    "userId": 456,
    "excludeAllBranches": true
  }
}

3. Get Limited Number of Branches

{
  "queryName": "RetrieveAllowableBranchesQuery",
  "data": {
    "userId": 456,
    "pageSize": 50
  }
}

Response Structure

Success Response (User with Specific Branch Access)

{
  "isSuccessful": true,
  "statusCode": "00",
  "message": "Allowable branches retrieved successfully.",
  "data": [
    {
      "id": 123,
      "encodedKey": "8a8e87e87d1234567890abcd",
      "key": "BR001",
      "name": "Main Branch"
    },
    {
      "id": 456,
      "encodedKey": "8a8e87e87d0987654321efgh",
      "key": "BR002",
      "name": "Downtown Branch"
    }
  ]
}

Success Response (User with All Branch Access)

{
  "isSuccessful": true,
  "statusCode": "00",
  "message": "Allowable branches retrieved successfully.",
  "data": [
    {
      "id": -999,
      "encodedKey": "ALL_BRANCHES_KEY",
      "key": "ALL_BRANCHES",
      "name": "All Branches"
    },
    {
      "id": 123,
      "encodedKey": "8a8e87e87d1234567890abcd",
      "key": "BR001",
      "name": "Main Branch"
    },
    {
      "id": 456,
      "encodedKey": "8a8e87e87d0987654321efgh",
      "key": "BR002",
      "name": "Downtown Branch"
    }
  ]
}

Response Fields

Field Name	Type	Description
id	Integer	Branch ID
encodedKey	String	Unique encoded identifier
key	String	Branch code
name	String	Branch name

Special Values

"All Branches" Entry

When a user has CanAccessAllBranches permission and excludeAllBranches is false, the response includes a special entry:

Field	Value	Description
id	-999	Special ID for "All Branches"
encodedKey	"ALL_BRANCHES_KEY"	Special encoded key
key	"ALL_BRANCHES"	Special branch code
name	"All Branches"	Display name

User Access Types

1. Restricted Access

User has specific branch assignments via UserBranchAccessRights. Only returns assigned branches.

2. All Branch Access

User has CanAccessAllBranches = true. Returns all branches in the system, optionally including the "All Branches" entry.

Error Handling

Common Error Responses

1. User Not Found

{
  "isSuccessful": false,
  "statusCode": "CBS_404",
  "message": "User not found."
}

2. No Branch Access

{
  "isSuccessful": true,
  "statusCode": "00",
  "message": "User has no branch access configured.",
  "data": []
}

3. Missing User ID

{
  "isSuccessful": false,
  "statusCode": "CBS_400",
  "message": "userId is required."
}

Error Codes

Status Code	Message	Cause
CBS_400	Invalid request	Missing required userId parameter
CBS_401	Unauthorized	Invalid authentication token
CBS_403	Forbidden	Insufficient permissions
CBS_404	User not found	Invalid user ID
CBS_500	Internal server error	System error

Code Examples

cURL

curl -X POST https://api.example.com/api/bpm/qry \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "queryName": "RetrieveAllowableBranchesQuery",
    "data": {
      "userId": 456,
      "excludeAllBranches": false
    }
  }'

C# Example

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = 
    new AuthenticationHeaderValue("Bearer", accessToken);

var request = new
{
    queryName = "RetrieveAllowableBranchesQuery",
    data = new
    {
        userId = 456,
        excludeAllBranches = false
    }
};

var response = await client.PostAsJsonAsync(
    "https://api.example.com/api/bpm/qry", 
    request
);
var result = await response.Content.ReadFromJsonAsync<ApiResponse>();

JavaScript/TypeScript Example

const response = await fetch('https://api.example.com/api/bpm/qry', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${accessToken}`
  },
  body: JSON.stringify({
    queryName: 'RetrieveAllowableBranchesQuery',
    data: {
      userId: 456,
      excludeAllBranches: false
    }
  })
});

const result = await response.json();
console.log('Allowable Branches:', result.data);

Implementation Notes

• User Branch Rights: Query checks UserBranchAccessRights table for specific branch assignments
• All Branch Access: Users with CanAccessAllBranches = true see all branches
• Ordering: Results are ordered alphabetically by branch name
• Performance: Branch data is typically cached for performance
• Active Branches: Only returns active branches (ObjectState = 0)

Usage Scenarios

Scenario 1: Populate Branch Dropdown

// Get branches for dropdown in transaction form
const branches = await getBranchesForUser(currentUserId);
const dropdown = branches.map(b => ({
  value: b.id,
  label: b.name
}));

Scenario 2: Validate Branch Access

// Check if user can access specific branch
const allowableBranches = await getAllowableBranches(userId);
const hasAccess = allowableBranches.some(b => b.id === targetBranchId);

Scenario 3: Admin View (Include All Branches)

// For admin users, include "All Branches" option
const branches = await getAllowableBranches(adminUserId, false);
// First item will be "All Branches" if user has full access

Best Practices

1. Cache Results: Cache allowable branches per user to reduce API calls
2. Exclude "All Branches": Use excludeAllBranches: true for transaction forms where specific branch is required
3. Validation: Always validate user's branch access before processing transactions
4. Real-time Updates: Refresh cache when user permissions change
5. Error Handling: Handle empty branch lists gracefully in UI

Related APIs

• Retrieve Branch List - Get all branches with filters
• Retrieve Branch By ID - Get specific branch details
• Create Branch - Create new branch
• Update Branch - Update branch information

---

Handler: AdministrationBranchCommandHandlers