Platform Modules

This document describes every functional module of the OneIoT ACS platform — its database schema, table purposes, workflows, and integration points. Use the anchors in each section heading to deep-link from navigation or external references.

1. Overview

The platform is composed of the following modules:

Module Purpose

Bootstrap

Device profiles, provisioning queues, and file transfer definitions

Device Information

Core device records, parameters, logging, diagnostics, and software inventory

Device Software Management

ChangeDUState operations — install, uninstall, and update of Deployment Units

Events

Event and parameter monitoring campaigns with device enrollment

Hardcoded Events

System-defined event codes, SOAP/HTTP delivery, JWT OAuth, and per-domain configuration

QoE Monitoring

Quality-of-Experience parameter sampling campaigns

FCC

FCC speed and latency compliance testing via Update Groups

Security

Device authentication, blacklist/whitelist, serial registry, and licensing

Subscription API

Parameter value-change subscriptions with callback delivery

System Metrics

ACS and Hazelcast node health, task execution statistics, and audit logs

Update Group

Automated mass-operations on devices with scheduling and task dependency resolution

IoT Configuration

ACS configuration properties and security profiles per protocol

Custom Parameters Mapping

Custom column-to-parameter mappings for the device list view

Custom View Filtering

Saved SQL filter queries for device list views

2. Bootstrap

The Bootstrap module manages device profiles and per-device provisioning queues. A profile is a named configuration template that bundles parameter values, access-list overrides, notification attributes, file downloads/uploads, and object definitions. Provision records queue individual parameter changes, file transfers, and custom RPCs for delivery during the next device session.

2.1. Profile

2.1.1. Database Schema

schema-profile

2.1.2. Table Descriptions

Table Description

profile

Device profile definition — a named configuration template scoped to a model group and domain. send_provision triggers provisioning on apply; send_backup triggers a backup upload; condition_id links to an optional activation condition

profile_parameter

Scalar parameter values to set when the profile is applied — parameter name + value pairs

profile_parameter_access

Parameter access list overrides applied by the profile — sets the access list string for specified parameters

profile_parameter_notification

Parameter notification attribute overrides — sets the notification level (0=off, 1=passive, 2=active) for specified parameters

profile_object

Multi-instance object definitions within a profile — supports hierarchical nesting via parent_id with copies controlling how many instances to create

profile_object_parameter

Parameter values within a profile object instance — name/value pairs set when the object is created on the device

profile_file

Download file tasks attached to a profile — URL, credentials, file type, target filename, reset-session flag, and firmware version matching

profile_upload

Upload file tasks attached to a profile — URL, credentials, file type, and instance targeting

profile_collector

Parameter names to retrieve (GetParameterValues) when the profile is applied — collects values from the device after provisioning

profile_filter

Links a profile to device filters that control which devices the profile is applied to

profile_condition

Conditional activation rules for a profile — code/value pairs that must be satisfied for the profile to apply

cpe_profile

Junction table linking a device to its assigned profiles — tracks assignment status, creation time, and the user who assigned it

cpe_profile_object

Tracks which profile object instances have been created on a specific device — records the actual instance number assigned by the device

2.2. Provision

2.2.1. Database Schema

schema-provision

2.2.2. Table Descriptions

Table Description

cpe_provision

Per-device parameter provisioning data — parameter name, desired value, and reprovision flag. Sent as SetParameterValues on next session

cpe_provision_attribute

Per-device parameter attribute provisioning — notification level and access list to set via SetParameterAttributes

cpe_provision_long_value

Overflow storage for provision values exceeding 1024 characters — linked by cpe_id to cpe_provision

cpe_provision_object

Per-device multi-instance object provisioning — defines objects to create via AddObject with instance count (copies) and parent hierarchy

cpe_provision_object_instance

Tracks which instances of provisioned objects have been created on the device

cpe_provision_object_parameter

Parameter values within a provisioned object instance — name/value pairs set after AddObject succeeds

cpe_delete_provision_object

Per-device objects pending deletion via DeleteObject — queued for the next device session

cpe_file

Per-device file download provisioning — URL, credentials, file type, reset-session flag, delivery protocol, and reprovision behavior

cpe_upload_file

Per-device file upload provisioning — URL, credentials, file type, and target instance

custom_rpc

Per-device custom RPC provisioning — stores a raw request/response XML message pair with the method name to invoke

file_type

Lookup table of file types (e.g. "Firmware Image", "Web Content") with their protocol scope

files_ftp

Available firmware/config files on the FTP server — file name, type, size, version, and model group scope. newest marks the latest version

3. Device Information

The Device Information module holds the core device inventory: device records, manufacturers, models, parameters, session logs, diagnostics, and software inventory.

3.1. Database Schema

device-info-db

3.2. Core Device Tables

Table Description

cpe

Primary device record — serial number, model reference, domain (location_id), online status, firmware version, protocol, active connection parameter, lifetime, and retry count

manufacturer

Device manufacturers — OUI (Organizationally Unique Identifier) and human-readable name

product_class

Device models — links manufacturer OUI to model name, model group, protocol, and gateway flag

product_class_group

Logical grouping of models by manufacturer + product class + protocol. Used to scope profiles, provisions, files, and monitoring

product_class_group_bcp_ext

Backup/config file extensions associated with a model group (e.g. .cfg, .xml)

product_class_group_parameter

Parameters automatically retrieved for all devices in a model group — used during initial tree discovery

isp

Domain / ISP definitions — name and up to 10 custom attributes for multi-tenant deployments

cust_device1

Customer device mapping — links serial to subscriber info (login name, telephone, location, tariffs) and up to 20 custom fields (cust1--cust20). GPS coordinates supported

3.3. Device Parameters and State

Table Description

cpe_parameter

Current device parameter values — one row per parameter per device. Stores value, writeable flag, notification level, and access list

cpe_parameter_extended

Overflow storage for parameter values exceeding 1024 characters

cpe_parameter_name

Global parameter name dictionary — maps integer IDs to full parameter path strings with type and encryption flag

cpe_changed_parameter

Parameter change history — records previous and current values for each parameter change, linked to the session log entry

cpe_custom_parameter

Denormalized custom parameter values per device — used for fast lookup of frequently accessed parameters mapped via config_custom_param

cpe_next_session_time

Scheduled next session time per device — used to enforce periodic inform intervals

cpe_method

Supported RPC methods per device — populated from GetRPCMethods response

cpe_method_name

Lookup table of TR-069 RPC method names

cpe_retrieve_method

Model groups that require explicit method retrieval during bootstrap

cpe_manageable_push

Parent-child device push mapping — for hub/sensor scenarios where a push to the parent triggers communication with the child device

3.4. Logging and Diagnostics

Table Description

cpe_log

Device session log — one entry per session recording event code, message type, and originator

cpe_log_event_name

Lookup table of Inform event codes (e.g. "0 BOOTSTRAP", "2 PERIODIC")

cpe_log_message_name

Lookup table of SOAP message names (e.g. "Inform", "SetParameterValues")

cpe_trace

Active SOAP trace sessions — enables full message capture for a device for a specified duration

cpe_trace_log

Captured SOAP messages for traced devices — full request/response XML content

cpe_diagnostic

Diagnostic sessions per device (e.g. IPPing, TraceRoute) — tracks creation, confirmation, and completion timestamps

cpe_set_diagnostic

Input parameters sent to the device for a diagnostic (SetParameterValues before the diagnostic)

cpe_get_diagnostic

Diagnostic result parameters retrieved from the device after completion

cpe_autonomous_file

Records of autonomous file transfers reported by devices — transfer URL, file type, status code, and timestamps

cpe_set_param_backup

Parameter value backups created before SetParameterValues — used for automatic rollback on failure (see ftacs_task.properties)

3.5. Software and Deployment Units

Table Description

cpe_software_parameter

Installed Deployment Units (DUs) per device — name, UUID, version, status, and model group

cpe_software_parameter_exec_unit

Installed Execution Units (EUs) per device — name, EUID, status, requested state, fault info, and disk usage

cpe_software_parameter_du_eu

Junction table mapping Deployment Units to their Execution Units on a device

4. Device Software Management

The Device Software Management module handles pending ChangeDUState operations — install, uninstall, and update requests queued for delivery to devices.

4.1. Database Schema

software-db

4.2. Table Descriptions

Table Description

cpe_op_install

Pending ChangeDUState Install operations per device — URL, credentials, and target Deployment Unit UUID for software installation

cpe_op_uninstall

Pending ChangeDUState Uninstall operations per device — UUID and version of the Deployment Unit to remove

cpe_op_update

Pending ChangeDUState Update operations per device — URL, credentials, UUID, and target version for software update

5. Events

The Events module defines event and parameter monitoring campaigns. You create a monitoring parent with start/end dates, attach concrete monitoring instances targeting specific model groups, and enroll devices individually or via filters. When a monitored event fires or a parameter condition is met, the platform triggers the configured action.

5.1. Database Schema

events-db

5.2. Table Descriptions

Table Description

event_monitoring_parent

Top-level event monitoring definition — a named monitoring campaign with start/end dates, state, and domain scope (location_id)

event_monitoring

Concrete event monitoring instance linked to a parent. Targets a model group, optionally uses a custom view for device filtering. apply_for_new auto-enrolls new devices; state tracks activation status

event_monitoring_cpe

Junction table enrolling individual devices into an event monitoring instance

cpe_event_monitor

Per-device event trigger rule — watches for a specific event code with quantity and duration thresholds. Fires when conditions are met within a transaction

cpe_parameter_monitor

Per-device parameter value trigger — monitors a named parameter against a condition (e.g. equals, greater-than). Fires when the parameter value satisfies the condition

parameter_monitor_condition

Lookup table of condition operators used by parameter monitors (e.g. "equals", "greater than", "changed")

profile_event_monitor

Event trigger rules attached to a device profile — same structure as cpe_event_monitor but applied when the profile is deployed

profile_parameter_monitor

Parameter value triggers attached to a device profile — applied when the profile is deployed to matching devices

mac_model

MAC address parameter mappings per device model — defines which parameter path contains the MAC address and whether it is under the active connection object

6. Hardcoded Events

Hardcoded events are system-defined event codes emitted by the ACS engine during device session processing. Each code signals a specific outcome (success, failure, rejection) for provisioning, file transfer, profile application, and other RPC operations. You can configure delivery per domain, choose the transport protocol (SOAP, HTTP, SNMP, SYSLOG), and attach JWT OAuth credentials for third-party receivers.

6.1. Event Code Reference

Event Code Description

1001 — provision failed

At least one provision task failed

1002 — provision succeeded

Provision task(s) completed successfully

1003 — download failed

Download file task failed

1004 — download succeeded

Download file task completed successfully

1005 — setvalue failed

Set Parameter Values task failed

1006 — setvalue succeeded

Set Parameter Values task completed successfully

1007 — config failed

CPE profile application failed

1008 — config succeeded

CPE profile applied successfully

1009 — upload failed

Upload file task failed

1010 — upload succeeded

Upload file task completed successfully

1011 — new device arrive

A new CPE was registered by ACS

1012 — add object failed

AddObject task failed

1013 — add object succeeded

AddObject task completed successfully

1014 — login failed

CPE tried to login with wrong credentials

1015 — download sent

Download request sent to the CPE

1016 — download rejected

Download task was rejected

1017 — upload sent

Upload request sent to the CPE

1018 — upload rejected

Upload task was rejected

1019 — factory reset sent

FactoryReset request sent to the CPE

1020 — factory reset failed

FactoryReset task failed

1021 — factory reset succeeded

FactoryReset task completed successfully

1022 — factory reset rejected

FactoryReset task was rejected

1023 — setvalue rejected

Set Parameter Values task(s) rejected

1024 — get parameter values failed

GetParameterValues task(s) failed

1025 — get parameter values rejected

GetParameterValues task(s) rejected

1026 — get parameter values succeeded

GetParameterValues task(s) completed successfully

1027 — get parameter names failed

GetParameterNames task(s) failed

1028 — get parameter names rejected

GetParameterNames task(s) rejected

1029 — get parameter names succeeded

GetParameterNames task(s) completed successfully

1030 — get parameter attributes failed

GetParameterAttributes task(s) failed

1031 — get parameter attributes rejected

GetParameterAttributes task(s) rejected

1032 — get parameter attributes succeeded

GetParameterAttributes task(s) completed successfully

1034 — set parameter attributes failed

SetParameterAttributes task(s) failed

1035 — set parameter attributes rejected

SetParameterAttributes task(s) rejected

1036 — set parameter attributes succeeded

SetParameterAttributes task(s) completed successfully

1037 — setvalue sent

Set Parameter Values task(s) sent

1038 — config rejected

CPE profile application rejected

1039 — config sent

CPE profile data sent

1040 — provision rejected

At least one provision task rejected

1041 — provision sent

Provision task(s) sent

1110 — SPV download sent

Download-related SPV task(s) sent to CPE

1111 — SPV download failed

Download-related SPV task(s) failed

1112 — SPV download rejected

Download-related SPV task(s) rejected

1113 — SPV download succeeded

Download-related SPV task(s) completed successfully

1114 — setvalue rollback

Set Parameter Values rolled back successfully

1115 — parameters updated in DB

A parameter was updated in the DB

2001 — profile sent

All requests completed during profile apply (profileId present)

2002 — profile rejected

At least one request rejected during profile apply (profileId present)

2003 — profile failed

At least one request failed during profile apply (profileId present)

6.2. SOAP Templates

6.2.1. Default Template (Placeholders)

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:fri="http://www.friendlytech.com/">
<soapenv:Header/>
<soapenv:Body>
<fri:deviceEventMonitorResult>
<fri:deviceEventMonitor>
<fri:deviceId>${deviceId}</fri:deviceId>
<fri:serialNumber>${serialNumber}</fri:serialNumber>
<fri:IPAddress>${ipAddress}</fri:IPAddress>
<fri:MACAddress>${macAddress}</fri:MACAddress>
<fri:transId>${transactionId}</fri:transId>
<fri:event>${event}</fri:event>
<fri:initialQuantity>${initialQuantity}</fri:initialQuantity>
<fri:currentQuantity>${currentQuantity}</fri:currentQuantity>
<fri:duration>${duration}</fri:duration>
<fri:date>${date}</fri:date>
<fri:validFrom>${validFrom}</fri:validFrom>
<fri:validTo>${validTo}</fri:validTo>
</fri:deviceEventMonitor>
</fri:deviceEventMonitorResult>
</soapenv:Body>
</soapenv:Envelope>

6.2.2. Windstream Template (Headers)

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://webservice.captiveportal.windstream.com">
<soapenv:Header>
<Authorization>${authorization}</Authorization>
<Account>${account}</Account>
</soapenv:Header>
<soapenv:Body>
<web:processSoapRequest>
<deviceId>${deviceId}</deviceId>
<serialNumber>${serialNumber}</serialNumber>
<IPAddress>${ipAddress}</IPAddress>
<MACAddress>${macAddress}</MACAddress>
<transId>${transactionId}</transId>
<event>${event}</event>
<initialQuantity>${initialQuantity}</initialQuantity>
<currentQuantity>${currentQuantity}</currentQuantity>
<duration>${duration}</duration>
<date>${date}</date>
<validFrom>${validFrom}</validFrom>
<validTo>${validTo}</validTo>
</web:processSoapRequest>
</soapenv:Body>
</soapenv:Envelope>

6.2.3. Supported Placeholders

Placeholder Description Example

${authorization}

Authorization token for API authentication

Bearer eyJhbGciOiJSU…​

${account}

Account name for request tracking

Friendly Technologies ACS

${deviceId}

Unique ID assigned to the device

687

${serialNumber}

Serial number of the device

346020ADAD

${ipAddress}

IP Address assigned to the device

192.168.4.121

${macAddress}

MAC Address of the device

EC:74:D7:36:69:9E

${transactionId}

Unique transaction ID

123456

${event}

Event code and description

1116 - cpe comes with bootstrap

${initialQuantity}

Initial quantity of the event-related metric

null

${currentQuantity}

Current count related to the event

null

${duration}

Duration of the event process

null

${date}

Timestamp

2025-01-16 08:54:27.54

${validFrom}

Start validity period

null

${validTo}

End validity period

null

6.3. MAC Address Mapping

MAC mapping is active only when hardcodedEventMacAddressMapping=1 (and the deprecated retrieveMacAddressesOnNewDeviceArrive is removed — event 1011 follows the same logic as 1116).

6.3.1. Flows

Inform flow
GetParameterValuesResponse flow
Retrieve MAC under active connection
Session end flow

6.3.2. REST API (MAC Model Mappings)

Base URL: /rest/mac-mappings

  • POST /getAll — returns list of MacModelDTO (requires IOT-AUTH-HEADER).

  • POST /getByModel — body: {"model":"ModelA"}.

  • PUT /replaceAll — body: list of MacModelDTO.

  • PUT /replaceForModel — body: single MacModelDTO.

  • DELETE /deleteAll.

  • DELETE /deleteForModel — body: {"model":"ModelA"}.

Example response (truncated):

{
  "model": "ModelA",
  "parameters": [
    {"parameterName": "Param1", "activeConnection": true},
    {"parameterName": "Param2", "activeConnection": false}
  ]
}

6.4. Database Schema

schema-hardcoded-events

6.4.1. Table Descriptions

Table Description

event_hardcoded

Master list of hardcoded event definitions — event ID, name, and description (e.g. "1001 — provision failed")

event_hardcoded_isp

Per-domain event enable/disable — links an event to a domain (isp_id) with a notification flag controlling whether the event triggers notifications for that domain

event_hardcoded_settings

Per-domain event delivery configuration — message protocol (SOAP/HTTP/SNMP/SYSLOG), timeout, retry attempts, pause between retries, primary and secondary URLs, and send-to mode

event_hardcoded_url

Maps individual events to receiver URLs per domain — controls which URL(s) receive notifications for each event

event_receiver_url

Receiver URL definitions — the target endpoint for event notifications, with a use_ftacs_ns flag for SOAP namespace control, scoped by domain

event_receiver_url_auth

OAuth2 authentication credentials for a receiver URL — auth type, client ID/secret, auth URL, and account name for JWT token acquisition

6.5. JWT OAuth Authentication for Events

This section defines JWT OAuth authentication for sending hardcoded events to third-party systems.

6.5.1. Functional Requirements

  • Authenticate to third-party systems using JWT OAuth.

  • Send event notifications using JWT OAuth.

  • Provide configuration UI for username/password (client id/secret) and auth URL.

  • Implement robust error handling and logging.

6.5.2. Web Service Changes

Methods updateReceiverUrls and createReceiverUrls accept authProps with optional fields: authType(NoAuth|OAUTH2), authUrl, clientId, clientSecret.

6.5.3. ACS Engine Changes

  • Persist WS-provided auth settings in DB and Hazelcast.

  • On send, obtain JWT using configured clientId/clientSecret and authUrl and attach via Authorization: Bearer <token>.

  • On authentication failure, log ERROR to monitors.log; on success, log token reception (INFO).

6.5.4. Logging

  • INFO: token received, event sent with auth details (non-sensitive).

  • ERROR: authentication or send failures.

6.6. Domain Changes (Per-Domain Events)

Hardcoded events are configurable per domain (ISP). If not configured, super-domain defaults apply.

6.6.1. Deprecated from acs_configuration.xml

  • enableHardcodedEvents — removed

  • hardcodedEventsProtocol — scheduled for removal

Parameters no longer used by Hardcoded Events (still used by Device Events): timeoutForSendingMonitorResult, attempsForSendingMonitorResult, rangeForSendingMonitorResult, sendToFEMS, urlForSendMonitorResult, urlForSendMonitorResultAdditional.

6.6.2. Database (Per-Domain)

  • New event_hardcoded_settings(id, isp_id, message_protocol, timeout, attempts, pause_time, url, url_with_ns, send_to) + index on (isp_id).

  • New event_hardcoded_isp(id, isp_id, event_hardcoded_id, notification) + unique (isp_id, event_hardcoded_id).

  • Modify event_receiver_url — add isp_id (indexed).

  • Modify event_hardcoded — drop column notification (migrated to event_hardcoded_isp).

  • Liquibase changeSets 6.4.12_35700_* provided (MySQL/Oracle variants).

6.6.3. ACS WS Changes (Per-Domain)

  • getHardcodedEventsGeneralSettingsByDomain(ispId) — returns protocol, sendToFems, urls, timeout/attempts/range, ispId.

  • saveHardcodedEventsGeneralSettings(settings) — upsert per-domain settings.

  • removeHardcodedEventsGeneralSettings(ispId) — delete, except super domain (ispId=0).

  • Existing createReceiverUrls/updateReceiverUrls now require ispId and the UI must use the new APIs (not acs_configuration.xml).

6.6.4. UI Flows

  • Management Portal → Settings → Alerts and Events → Events now uses WS calls above.

  • Add ispId in: changeHardcodedEvent, createReceiverUrls, updateReceiverUrls.

6.7. Ops Tips

  • Ensure receivers are idempotent — retries may produce duplicates.

  • Whitelist the event codes you consume to reduce noise.

  • Monitor the ratio of _failed/_rejected codes — spikes signal auth/policy issues.

7. QoE Monitoring

The QoE (Quality of Experience) Monitoring module runs parameter-sampling campaigns against enrolled devices. You define a monitoring parent with start/end dates, attach monitoring instances targeting model groups, and configure per-parameter sampling attributes (pmin, pmax, intervals). The module overrides periodic inform intervals for monitored devices while campaigns are active.

7.1. Database Schema

qoe-db

7.2. Table Descriptions

Table Description

qoe_monitoring_parent

Top-level QoE monitoring campaign — named definition with start/end dates, state, and domain scope

qoe_monitoring

Concrete QoE monitoring instance under a parent. Targets a model group with optional custom view filtering. monitoring_mode controls single-node vs cluster behavior

qoe_monitoring_cpe

Junction table enrolling individual devices into a QoE monitoring instance

qoe_monitoring_parameter

Parameters tracked by a QoE monitoring — each row links a parameter name to a monitoring instance. is_temporary marks parameters added dynamically during monitoring

qoe_monitoring_parameter_attribute

Per-parameter monitoring attributes (e.g. pmin, pmax, sampling intervals) for fine-grained QoE control

qoe_monitoring_periodic

Overrides the periodic inform interval for a monitoring — sets the device reporting frequency while QoE is active

qoe_monitoring_task

Links QoE monitoring instances to their generated pending tasks — tracks which task was created for which monitoring

qoe_cpe

Runtime state of QoE-monitored devices — stores serial, model group, MAC, periodic interval, next session time, and connection state

qoe_cpe_in_monitor

Tracks which device is currently participating in which monitoring instance and its activation state

qoe_cpe_parameter

Active monitored parameter data per device serial — lightweight junction of serial + parameter name ID used by the monitoring cache

qoe_cpe_parameter_name

QoE-specific parameter name lookup — stores parameter names used in QoE monitoring independently from the main cpe_parameter_name table

8. FCC

The FCC module manages Federal Communications Commission compliance testing — speed and latency tests executed via Update Groups. Test configuration is per-Update-Group, and results are stored individually with pass/fail status against speed tier thresholds.

8.1. Database Schema

fcc-db

8.2. Table Descriptions

Table Description

fcc_cpe

Tracks FCC test state per device — links a CPE to an Update Group action task, stores the test period and references download/upload speed result records

fcc_properties

Per-Update-Group FCC test configuration overrides — total/single duration, batch interval, retry counts for failed tests and WAN usage rechecks

ug_fcc

FCC task definition within an Update Group — stores speed tier thresholds (download/upload), hub ID, and test type (speed or latency)

ug_fcc_speed_result

Individual speed test result record — actual speed, total bytes, start/end timestamps, tier, status (pass/fail), and descriptive notes

ug_fcc_latency_result

Individual latency test result record — average/min/max latency, packets sent/received, status, tier, and URL tested

9. Security

The Security module manages device authentication, access control, serial registry, and ACS licensing.

9.1. Database Schema

security-db

9.2. Table Descriptions

Table Description

cpe_login

Device authentication credentials — login/password pairs used by CPEs to connect to the ACS, scoped by domain (location_id)

cpe_login_license

Per-login device count limitation. limitation sets the maximum number of devices allowed for this login; valid_to sets expiration

cpe_black_list

Blacklisted devices — devices matching manufacturer/model/serial combinations are blocked from connecting to the ACS

cpe_white_list

Whitelist rules for device access control. Rules match by manufacturer, model, IP range, and/or domain. only_created restricts to pre-registered devices only

cpe_white_list_serials

Individual device serials attached to a whitelist rule — devices whose serial appears here are allowed when whitelist is enforced

cpe_serial

Device serial registry — tracks known serials with their model group, protocol, domain, and deletion status. Used for serial-based device lookup and registration

ftacs_parameter

ACS-level system parameters — key/value configuration pairs (e.g. ACS URL) optionally scoped by protocol

license

ACS license data — stores the encrypted license blob with creation timestamp

10. Subscription API

The Subscription API module enables external systems to subscribe to parameter value-change notifications. Subscriptions scope by device model and domain, track individual device enrollment states, and deliver notifications to configured callback URLs (individually or batched).

10.1. Database Schema

subscription-db

10.2. Table Descriptions

Table Description

event_subs_group

Subscription scope by device model and domain — links a subscription token to one or more ProductClass models within an ISP

event_subs_param

Parameters watched by a subscription. monitored flag indicates whether value-change monitoring is active for the parameter

event_subs_serial

Individual device serials enrolled in a subscription. state tracks whether the device has been successfully configured for the subscription

event_subs_url

Callback URLs for delivering subscription notifications. use_batch controls whether events are sent individually or batched

11. System Metrics

The System Metrics module tracks ACS node health, Hazelcast cluster state, RPC task execution statistics, and device lifecycle audit logs.

11.1. Database Schema

metrics-db

11.2. Table Descriptions

Table Description

acs_info

ACS node identity and capabilities — node name, IP addresses, start date, RAM, max threads, max concurrent CPEs, DB session limit, and software version

acs_monitoring_data

Current (live) ACS performance snapshot per node — CPU, RAM, thread count, concurrent sessions, and counters for failed auths, license blocks, whitelist/blacklist blocks

acs_monitoring_data_his

Historical ACS performance data — same columns as acs_monitoring_data but with auto-increment ID for time-series storage

hazelcast_monitoring_data

Current Hazelcast cluster health per node — cluster size, uptime, RAM, CPU, load average, thread count, GC times, and pending partition migrations

hazelcast_monitoring_data_his

Historical Hazelcast cluster health data — time-series archive of hazelcast_monitoring_data snapshots

task_times

Current RPC task execution statistics per node — max/avg execution time and total count for each method name

task_times_his

Historical task execution statistics — time-series archive of task_times snapshots

cpe_deleted

Recently deleted device serials — used by auto-delete to prevent re-registration of devices removed by retention policy

cpe_deleted_log

Audit log of device deletions — records device identity (serial, model, manufacturer, ISP), last connection time, and deletion timestamp

cpes_blocked_by_license

Devices blocked from connecting due to license limitations — serial, model, manufacturer, and block timestamp

cpes_failed_auth

Devices that failed authentication — serial, model, manufacturer, and failure timestamp

12. Update Group

The Update Group module orchestrates automated mass-operations on Customer Premises Equipment (CPEs). It covers:

  1. Creation and update of groups through web services.

  2. Scheduling and reactivation logic handled by Quartz.

  3. Task generation and CPE response processing performed by the ACS core.

All modification operations on update_group database records must be executed only by ACS.

12.1. Provided Web Services

Service Description

createUpdateGroup

Creates a new UpdateGroup record and related metadata.

updateUpdateGroup

Modifies existing group parameters (e.g., schedule, device filters).

deleteUpdateGroup

Removes a group definition and its pending jobs.

12.2. Transaction Control

  • A unique transaction ID is generated for:

    • All CPEs and tasks created within one UpdateGroup execution.

    • Each group reactivation (Quartz firing).

  • Transaction IDs are persisted in ug_transaction.

Upper-level systems (UI/API) should query this table to trace job results.

12.3. Reactivation Expression

Scheduling expressions for group reactivation follow Quartz cron syntax: See Quartz CronTrigger documentation. Use the online validator at CronMaker during debugging.

12.4. CPE Online Check Flow

Executed only if sendOnlyForOnlineCPEs = 1.

  1. Set a temporary flag (in cache for clustered mode, in DB for standalone) to prevent session termination before task creation.

  2. Send Connection Request (CR) to the target CPE.

  3. If the CPE responds — create corresponding tasks.

  4. If not — remove the flag and skip that CPE.

This ensures tasks are generated only for devices currently reachable online.

12.5. Update Group Create Flow

Create Flow

12.5.1. Description

  1. Start Create UG — begins via WS createUpdateGroup.

  2. UpdateGroup — new record inserted into update_group tables.

  3. Insert Data to DB — persists metadata, schedules, filters.

  4. scheduled IS NULL? — if no cron provided, start immediately.

  5. Start UG — triggers the first execution cycle.

  6. Schedule UG Start — if scheduled not null, record job in Quartz DB.

  7. reactivateExpr IS NULL? — if defined, schedule future reactivations.

  8. End — process terminates or waits for Quartz event.

Data: update_group, ug_transaction, quartz_db.

12.6. Update Group Start Flow

Start Flow

12.6.1. Description

  1. Start UG Start — Quartz or manual trigger.

  2. Load update_group state; if inactive, skip.

  3. Set active=1 in DB and generate new transactionId.

  4. Retrieve corresponding ug_period rows.

  5. If no periods, Activate UG directly; otherwise loop per period.

  6. For each period, Schedule UG Activation (stored in Quartz DB).

  7. Commit and end.

Tables involved: update_group, ug_transaction, ug_period, quartz_db.

12.7. Update Group Activation Flow

Activation Flow

12.7.1. Description

  1. Start UG Activation — triggered by scheduled Quartz job.

  2. Fetch CPEs assigned to the UpdateGroup (ug_cpe).

  3. If list empty, end.

  4. For each CPE:

    • If SendOnlineCpe is TRUE, ensure device is online before tasking.

    • Check push policies (Push, PushAndWaitForTask).

    • Create initial ug_task entry.

    • Possibly reprovision device if Reprovision flag is true.

  5. Monitor task completion:

    • On success, update ug_cpe_completed.

    • On failure, mark CPE failed.

  6. When all CPEs are processed and PeriodAmount is reached:

    • Set update_group.active = 0.

    • If reactivateExpr is defined, reschedule next run.

  7. End or reschedule through Quartz DB.

12.8. Task Dependency Resolving Flow

Task Dependency Flow

12.8.1. Description

  1. Start Next Task Execution — triggered after previous task completion.

  2. Query ug_task for next step.

  3. If previous task completed:

    • Check if StopOnFailed flag is set.

    • If yes and task failed, set CPE state to FAILED.

  4. If no blocking errors:

    • Create new cpe_pending_task for the next step.

    • Continue loop until all tasks are processed.

  5. End when queue is empty or final step is reached.

Tables used: ug_task, cpe_pending_task, ug_cpe_completed.

12.9. Database Schema

update-group-db

12.10. Notes

  • Only ACS writes to update_group and dependent tables; external systems interact via WS APIs.

  • Quartz schedules handle both initial activation and future reactivations.

  • Transactions ensure idempotency and traceability across CPEs and tasks.

  • Use the cron expression validator during setup to prevent misfires.

13. IoT Configuration

The IoT Configuration module stores ACS configuration properties and security profiles per protocol (TR-069, MQTT, USP). Properties are grouped into named categories and support per-domain overrides. Security profiles bind device identifiers to authentication credentials and key material.

13.1. Database Schema

iot-config-db

13.2. Table Descriptions

Table Description

iot_configuration_group

Groups related ACS configuration properties under a named category. program_name is the unique machine-readable identifier

iot_configuration_property

Individual ACS configuration parameter — stores value, type, constraints (min_value/max_value/valid_values), description, and protocol scope. overridable and location_id support per-domain overrides

iot_security_configuration

Security profile definition for a protocol (TR-069, MQTT, USP). Binds an identifier (serial, model) to a security destination type within a domain

iot_sec_conf_details

Security credentials and key material for a security profile — supports PSK, RPK, and certificate-based modes with login/password, keys, and trust chains

14. Custom Parameters Mapping

The Custom Parameters Mapping module defines which device parameters appear as custom columns in the device list view. Each mapping links a display column name to a device parameter path, resolved per manufacturer and model.

14.1. Database Schema

custom-params-db

14.2. Table Descriptions

Table Description

config_custom_data

Defines custom columns displayed in the device list view. Each row maps a column_name to a human-readable view_name

config_custom_param

Maps a custom column to a device parameter path per manufacturer/model. active_conn indicates whether the parameter should be resolved under the device’s active connection object

15. Custom View Filtering

The Custom View Filtering module stores saved SQL filter queries used to narrow the device list view. Each query is scoped to a domain and can include typed bind parameters for safe, reusable filtering.

15.1. Database Schema

custom-view-db

15.2. Table Descriptions

Table Description

custom_view_query

Stores a saved SQL filter query for the device list view, scoped to a domain (location_id)

custom_view_query_parameter

Bind parameters for a custom view query — each row defines a named parameter (param_name) with its value and type used during query execution