UI Controllers API

1. Overview

UI Controllers provide REST API endpoints for the Angular frontend application. All endpoints use the /ui/ path prefix and require JWT authentication (except login endpoint).

1.1. Base URL

http://<API_SERVER_HOST>[:<PORT>]/prov-portal/ui/

1.2. Authentication

All UI endpoints (except /ui/auth/login) require a valid JWT token in the Authorization header:

Authorization: Bearer <jwt_token>

1.3. Controllers Summary

Controller Base Path Description

AuthController

/ui/auth

User authentication and session management

DeviceController

/ui/device

Domain management operations

ProvController

/ui/provision

Device provisioning operations

ServerController

/ui/server

Server configuration and logging

UserController

/ui/users

User CRUD operations

2. AuthController

Authentication controller for user login and logout operations.

2.1. Base Path

/ui/auth

2.2. Security

No authentication required for login endpoint.

2.3. Endpoints

Method Path Description Authorization

POST

/login

Authenticate user and get JWT token

None

POST

/logout

Logout current user

None

2.4. POST /ui/auth/login

Authenticate user credentials and return JWT token.

Request Body:

{
  "login": "admin",
  "password": "password123"
}

Response (200 OK):

{
  "token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhZG1pbiIsInVzZXJJZCI6MSwicGVybWlzc2lvbiI6ImFkbWluIiwiaWF0IjoxNzAxMTExMTExLCJleHAiOjE3MDExOTc1MTF9.signature",
  "userId": 1
}

Error Responses:

  • 401 Unauthorized - Invalid credentials

  • 500 Internal Server Error - Database connection error

2.5. POST /ui/auth/logout

Logout current user. In stateless JWT authentication, the server doesn’t maintain sessions. The client should remove the JWT token from storage.

Response (200 OK):

{
  "success": true,
  "message": "Logout successful"
}

3. DeviceController

Controller for device-related operations, primarily domain management.

3.1. Base Path

/ui/device

3.2. Security

Requires JWT authentication. User must have admin or user role.

3.3. Endpoints

Method Path Description Authorization

POST

/domains

Get all available domains

admin, user

3.4. POST /ui/device/domains

Retrieves all available domain names (ISPs) from the database.

Response (200 OK):

["Super domain", "domain1", "domain2"]
The first item is always "Super domain", followed by domains ordered by name.

Error Responses:

  • 403 Forbidden - User does not have required permissions

  • 500 Internal Server Error - Failed to retrieve domains

4. ProvController

Main provisioning controller for device operations. Handles single and multiple device provisioning, status retrieval, CPE replacement, and service deactivation.

4.1. Base Path

/ui/provision

4.2. Security

Requires JWT authentication. Most endpoints require admin or user role.

4.3. Endpoints

Method Path Description Authorization

POST

/

Get device provision data

admin, user

PUT

/

Start single device provisioning

admin, user

DELETE

/

Delete device provision data

admin only

PUT

/upload

Upload file for multiple provisioning

admin, user

PUT

/multiple

Start multiple device provisioning

admin, user

POST

/status

Get provisioning status

admin, user

PUT

/replace-cpe

Start CPE replacement process

admin, user

PUT

/deactivate

Deactivate device services

admin, user

4.4. POST /ui/provision

Retrieves complete device provisioning data by serial number or MAC address.

Request Body:

{
  "serialNumber": "ABC123456",
  "macAddress": "AA:BB:CC:DD:EE:FF",
  "oui": "001122",
  "productClass": "Router"
}
Provide either serialNumber OR macAddress. Both are optional but one is required.

Response (200 OK): Returns ProvisionDevice object with complete device data including services, parameters, and objects.

Error Responses:

  • 400 Bad Request - Neither serial number nor MAC address provided

  • 404 Not Found - Device not found

4.5. PUT /ui/provision

Initiates provisioning workflow for a single device.

Request Body: ProvisionDevice object with device configuration.

Response (200 OK):

{
  "Result": 100,
  "Message": "Operation completed successfully",
  "Bid": "batch123",
  "Status": 246
}

Result Codes:

  • 100 - Success

  • 200 - Failure

4.6. DELETE /ui/provision

Deletes all provisioning data for a device.

Requires admin role only.

Request Body:

{
  "serialNumber": "ABC123456"
}

OR

{
  "macAddress": "AA:BB:CC:DD:EE:FF"
}

Response (200 OK):

{
  "result": 100,
  "message": "Provision data deleted successfully"
}

4.7. PUT /ui/provision/upload

Uploads XML or CSV file containing multiple device configurations for preview.

Content-Type: multipart/form-data

Request Parameter:

  • file - Uploaded file (XML or CSV)

Supported Formats:

  • .xml - XML file with <devices> root element containing <device> elements

  • .csv - CSV file following CSVSettings.xml configuration

Response (200 OK):

{
  "devices": [
    {
      "serialNumber": "SN001",
      "macAddress": "AA:BB:CC:DD:EE:01",
      "services": [...]
    },
    {
      "serialNumber": "SN002",
      "macAddress": "AA:BB:CC:DD:EE:02",
      "services": [...]
    }
  ]
}

4.8. PUT /ui/provision/multiple

Starts provisioning workflow for multiple devices.

Request Body:

{
  "devices": [
    {
      "serialNumber": "SN001",
      "macAddress": "AA:BB:CC:DD:EE:01",
      "services": [...]
    }
  ]
}
The devices list should be obtained from the /upload endpoint response.

Response (200 OK):

{
  "Bid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "Result": 100,
  "Message": "Provisioning started successfully"
}

4.9. POST /ui/provision/status

Retrieves provisioning status for devices based on search criteria.

Request Body:

{
  "serialNumber": "ABC123456",
  "macAddress": "AA:BB:CC:DD:EE:FF",
  "operationCode": "246",
  "bId": "process-123"
}

Search Options:

  • By BID (Batch ID) - All CPEs included in the batch

  • By Operation Code - All CPEs with specific final operation code

  • By CPE S/N - A specific serial number

  • By CPE MAC address - A specific MAC address

  • Combinations are also supported

Response (200 OK):

[
  {
    "BId": "process-123",
    "Sn": "ABC123456",
    "Mac": "AA:BB:CC:DD:EE:FF",
    "OperationCode": 246,
    "Description": "Provisioning Completed Successfully",
    "Created": "2025-04-15T12:28:21.224Z",
    "Fault": {}
  }
]

Common Operation Codes:

Code Description

246

Provisioning Completed Successfully

300

Error while setting parameters to CPE

424

CPE Replacement Completed

522

Deactivation Completed

4.10. PUT /ui/provision/replace-cpe

Initiates CPE replacement workflow to transfer configuration from source device to target device.

Request Body:

{
  "fromSn": "SOURCE_SN",
  "fromMac": "AA:BB:CC:DD:EE:01",
  "fromOui": "001122",
  "fromProductClass": "Router",
  "toSn": "TARGET_SN",
  "toMac": "AA:BB:CC:DD:EE:02",
  "toOui": "001122",
  "toProductClass": "Router"
}

Response (200 OK):

{
  "Result": 100,
  "Message": "CPE replacement completed successfully",
  "Bid": "12345",
  "Status": 424
}

4.11. PUT /ui/provision/deactivate

Deactivates selected services for a device.

Request Body:

{
  "serialNumber": "SN123456789",
  "macAddress": "00:11:22:33:44:55",
  "serviceNames": ["VoIP", "WiFi"]
}

Response (200 OK):

{
  "Bid": "12345",
  "Result": 100,
  "Message": "Deactivation completed successfully",
  "Status": 522
}

5. ServerController

Controller for server configuration and log file management.

5.1. Base Path

/ui/server

5.2. Security

Requires JWT authentication. User must have admin or user role.

5.3. Endpoints

Method Path Description Authorization

POST

/configuration

Get application configuration

admin, user

POST

/logs

Get all log files

admin, user

5.4. POST /ui/server/configuration

Retrieves application configuration from Configuration.xml file.

Response (200 OK): Returns DeviceConfiguration object containing:

  • Single device configuration (deviceInfo, domain settings)

  • Multiple device configuration (multithreading settings)

  • Service deactivation settings

  • General application settings

5.5. POST /ui/server/logs

Retrieves all log files from the log directory, categorized into debug logs and custom logs.

Response (200 OK):

{
  "debugLogs": [
    {
      "name": "DebugLog_2025-04-15.txt",
      "url": "https://server:8448/prov-portal/Log/DebugLog_2025-04-15.txt",
      "updatedDate": "2025-04-15T10:30:00Z"
    }
  ],
  "customLogs": [
    {
      "name": "CustomLog_SN12345_2025-04-15.txt",
      "url": "https://server:8448/prov-portal/Log/CustomLog_SN12345_2025-04-15.txt",
      "updatedDate": "2025-04-15T11:45:00Z"
    }
  ]
}

6. UserController

Controller for user management operations (CRUD).

6.1. Base Path

/ui/users

6.2. Security

Requires JWT authentication. Read operations require admin or user role. Write operations require admin role only.

6.3. Endpoints

Method Path Description Authorization

POST

/

Get paginated users list

admin, user

POST

/{id}

Get user by ID

admin, user

POST

/by-name/{username}

Get user by username

admin, user

POST

/exists/{username}

Check if username exists

admin only

PUT

/

Create or update user

admin only

DELETE

/{id}

Delete user by ID

admin only

DELETE

/bulk

Delete multiple users

admin only

6.4. POST /ui/users

Retrieves paginated and sorted list of users.

Query Parameters:

Parameter Type Default Description

page

int

0

Page number (0-indexed)

size

int

15

Page size

sortBy

string

id

Sort field: id, name, permission

sortDir

string

ASC

Sort direction: ASC or DESC

excludeAdmin

boolean

true

Exclude admin user from results

Response (200 OK):

{
  "content": [
    {"id": 2, "name": "user1", "permission": "user"},
    {"id": 3, "name": "user2", "permission": "admin"}
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 15
  },
  "totalElements": 25,
  "totalPages": 2,
  "last": false
}

6.5. POST /ui/users/{id}

Retrieves user details by user ID. Password is excluded from response.

Path Parameter:

  • id - User ID

Response (200 OK):

{
  "id": 1,
  "name": "admin",
  "permission": "admin"
}

6.6. POST /ui/users/by-name/{username}

Retrieves user details by username.

6.7. POST /ui/users/exists/{username}

Checks if a user with the given username exists.

Requires admin role only.

Response (200 OK):

{
  "exists": true
}

6.8. PUT /ui/users

Creates or updates a user.

Requires admin role only.

Request Body (Create):

{
  "name": "newuser",
  "password": "securePassword123",
  "permission": "user"
}

Request Body (Update):

{
  "id": 5,
  "name": "updateduser",
  "password": "newPassword123",
  "permission": "admin"
}
If id is null or not provided, a new user is created. If id is provided, the existing user is updated.

Response (200 OK / 201 Created):

{
  "id": 5,
  "name": "newuser",
  "permission": "user",
  "message": "User created successfully"
}

Error Responses:

  • 400 Bad Request - Validation error (create: name and password required)

  • 404 Not Found - User not found (update only)

  • 409 Conflict - Username already exists

6.9. DELETE /ui/users/{id}

Deletes a single user by ID.

Requires admin role only.

Response (200 OK):

{
  "success": true,
  "message": "User deleted successfully"
}

6.10. DELETE /ui/users/bulk

Deletes multiple users in a single request.

Requires admin role only.

Request Body:

{
  "userIds": [2, 3, 5, 7]
}

Response (200 OK):

{
  "success": true,
  "deletedCount": 4,
  "message": "4 users deleted successfully"
}

7. Common Error Responses

All UI endpoints return standardized error responses:

{
  "errorCode": 400,
  "message": "Description of the error"
}

7.1. HTTP Status Codes

Code Description

400

Bad Request - Invalid input parameters

401

Unauthorized - Missing or invalid JWT token

403

Forbidden - User lacks required permissions

404

Not Found - Resource not found

409

Conflict - Resource already exists

500

Internal Server Error - Server-side error