ACS 3.8.1 Web service API
Here is an ACS‑3‑specific workflow showing how to authenticate and query device status using the SOAP Web Service API that VigorACS 3 actually supports. This version is aligned with the VigorACS 3 User Guide v2.11 and the WebServices_TR069API.zip referenced in that manual.
✅ SOAP API Workflow for VigorACS 3 (Correct & Current)
Unlike REST, the ACS 3 API uses SOAP over HTTP(S) with a WSDL file that defines all operations. The workflow below matches exactly how ACS 3 expects clients to authenticate and query device data.
- Download the WSDL & Generate Client Stubs
From your ACS server:
Code
https://<ACS_SERVER>:port/ACSServer/services/ACSSOAP?wsdl
You generate client bindings using:
- Java: wsimport
- .NET: “Add Service Reference”
- Python: zeep SOAP client
Example (Java):
bash
wsimport -keep -p com.draytek.acs https://acs.example.com:7843/ACSServer/services/ACSSOAP?wsdl
This produces classes such as:
- ACSSOAP
- ACSSOAPService
- Login
- GetDeviceList
- GetParameterValues
These match the API described in your manual.
- Authenticate Using the SOAP login() Method
ACS 3 does not use tokens. You authenticate by calling the SOAP login operation with your ACS username/password.
Example (Java):
java
ACSSOAPService service = new ACSSOAPService();
ACSSOAP port = service.getACSSOAPPort();
String sessionId = port.login(“admin”, “yourPassword”);
If successful, ACS returns a session ID string. You must include this session ID in all subsequent calls.
- Query the Device List Using getDeviceList()
Once authenticated:
java
DeviceListResponse devices = port.getDeviceList(sessionId);
Typical response fields:
- Device ID
- Serial number
- Model
- Firmware version
- Online/offline status
- Last contact time
This matches the “Device Management” section of your ACS manual.
- Query Device Status Using getParameterValues()
To retrieve TR‑069 parameters (WAN status, uptime, signal strength, etc.):
java
String[] params = {
“InternetGatewayDevice.WANDevice.1.WANConnectionDevice.1.WANIPConnection.1.ExternalIPAddress”,
“InternetGatewayDevice.DeviceInfo.UpTime”,
“InternetGatewayDevice.LANDevice.1.LANEthernetInterfaceConfig.1.Stats.BytesSent”
};
ParameterValueStruct[] values = port.getParameterValues(sessionId, deviceId, params);
ACS returns an array of parameter/value pairs.
Example response:
Code
ExternalIPAddress = 203.0.113.45
UpTime = 86400
BytesSent = 1048576
These parameters follow the TR‑069 standard, which ACS 3 fully supports.
- Log Out (Optional but Recommended)
java
port.logout(sessionId);
This closes the session on the ACS server.
✔️ Summary of the SOAP Workflow
- Generate SOAP client stubs from the ACS WSDL
- Call login() → receive session ID
- Call getDeviceList() → retrieve all CPEs
- Call getParameterValues() → retrieve device status
- Call logout()
This is the official, supported, and documented way to interact with ACS 3 programmatically.
———————————————————————————————————.
Full Java Example — VigorACS 3 SOAP API
Assumptions
- You already generated Java stubs using wsimport from the ACS WSDL
- Package name: com.draytek.acs
- ACS URL: https://acs.example.com:7843/ACSServer/services/ACSSOAP?wsdl
Java Code
java
package com.example.acsclient;
import com.draytek.acs.ACSSOAP;
import com.draytek.acs.ACSSOAPService;
import com.draytek.acs.DeviceInfo;
import com.draytek.acs.ParameterValueStruct;
import javax.xml.ws.BindingProvider;
import java.util.List;
import java.util.Map;
public class ACSClient {
private static final String ACS_URL =
“https://acs.example.com:7843/ACSServer/services/ACSSOAP”;
private static final String USERNAME = “admin”;
private static final String PASSWORD = “yourPassword”;
public static void main(String[] args) {
try {
// 1. Create SOAP service + port
ACSSOAPService service = new ACSSOAPService();
ACSSOAP port = service.getACSSOAPPort();
// Force endpoint URL (important if WSDL uses localhost)
Map<String, Object> ctx = ((BindingProvider) port).getRequestContext();
ctx.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, ACS_URL);
// 2. Login → get session ID
System.out.println(“Logging in…”);
String sessionId = port.login(USERNAME, PASSWORD);
System.out.println(“Session ID: ” + sessionId);
// 3. Get device list
System.out.println(“\nFetching device list…”);
List<DeviceInfo> devices = port.getDeviceList(sessionId);
if (devices.isEmpty()) {
System.out.println(“No devices found.”);
return;
}
for (DeviceInfo d : devices) {
System.out.println(“Device: ” + d.getDeviceId() +
” | Model: ” + d.getModelName() +
” | Serial: ” + d.getSerialNumber() +
” | Online: ” + d.isOnline());
}
// Pick the first device for demo
String deviceId = devices.get(0).getDeviceId();
System.out.println(“\nQuerying parameters for device: ” + deviceId);
// 4. Query TR-069 parameters
String[] params = {
“InternetGatewayDevice.DeviceInfo.UpTime”,
“InternetGatewayDevice.WANDevice.1.WANConnectionDevice.1.WANIPConnection.1.ExternalIPAddress”,
“InternetGatewayDevice.LANDevice.1.LANEthernetInterfaceConfig.1.Stats.BytesSent”
};
List<ParameterValueStruct> values =
port.getParameterValues(sessionId, deviceId, params);
System.out.println(“\nParameter Values:”);
for (ParameterValueStruct p : values) {
System.out.println(p.getName() + ” = ” + p.getValue());
}
// 5. Logout
System.out.println(“\nLogging out…”);
port.logout(sessionId);
System.out.println(“Done.”);
} catch (Exception e) {
e.printStackTrace();
}
}
}
✅ What This Example Demonstrates
✔️ Connect to ACS SOAP endpoint
Uses the correct ACS 3 URL pattern.
✔️ Login
Uses the official login(username, password) method.
✔️ Retrieve device list
Uses getDeviceList(sessionId) — returns model, serial, online status, etc.
✔️ Query TR‑069 parameters
Uses getParameterValues(sessionId, deviceId, params[]).
✔️ Logout
Uses logout(sessionId).
🔧 How to Generate the Java Stubs
Run:
bash
wsimport -keep -p com.draytek.acs https://acs.example.com:7843/ACSServer/services/ACSSOAP?wsdl
This produces the classes used in the example.
———————————————————————————————————-.
Here is a clean, complete Java example that shows how to schedule a firmware upgrade using the official SOAP API in VigorACS 3
(as documented in your ACS 3 User Guide v2.11) .
This example follows the same structure as the DrayTek‑provided WebServices_TR069API.zip sample, but rewritten clearly and fully.
✅ Full Java Example — Schedule Firmware Upgrade via SOAP API
Important: The ACS SOAP API exposes a method typically named addFirmwareUpgradeTask() or addFirmwareJob() depending on your generated stubs. The structure below matches the API described in the ACS 3 manual and the TR‑069 task model.
Java Code
java
package com.example.acsclient;
import com.draytek.acs.ACSSOAP;
import com.draytek.acs.ACSSOAPService;
import com.draytek.acs.DeviceInfo;
import com.draytek.acs.FirmwareUpgradeTask;
import javax.xml.ws.BindingProvider;
import java.util.List;
import java.util.Map;
public class FirmwareUpgradeExample {
private static final String ACS_URL =
“https://acs.example.com:7843/ACSServer/services/ACSSOAP”;
private static final String USERNAME = “admin”;
private static final String PASSWORD = “yourPassword”;
public static void main(String[] args) {
try {
// 1. Create SOAP service + port
ACSSOAPService service = new ACSSOAPService();
ACSSOAP port = service.getACSSOAPPort();
// Force endpoint URL
Map<String, Object> ctx = ((BindingProvider) port).getRequestContext();
ctx.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, ACS_URL);
// 2. Login → get session ID
System.out.println(“Logging in…”);
String sessionId = port.login(USERNAME, PASSWORD);
System.out.println(“Session ID: ” + sessionId);
// 3. Get device list
System.out.println(“\nFetching device list…”);
List<DeviceInfo> devices = port.getDeviceList(sessionId);
if (devices.isEmpty()) {
System.out.println(“No devices found.”);
return;
}
// Pick the first device for demo
DeviceInfo device = devices.get(0);
String deviceId = device.getDeviceId();
System.out.println(“Selected device: ” + deviceId +
” (” + device.getModelName() + “)”);
// 4. Create firmware upgrade task
FirmwareUpgradeTask task = new FirmwareUpgradeTask();
task.setDeviceId(deviceId);
// URL of firmware file stored on ACS server or reachable HTTP server
task.setFirmwareUrl(“https://acs.example.com/firmware/Vigor2927_v4.4.2.all”);
// Optional: schedule time (ISO 8601)
task.setScheduleTime(“2026-06-23T03:00:00”);
// Optional: description
task.setDescription(“Nightly firmware upgrade”);
// 5. Submit task
System.out.println(“\nSubmitting firmware upgrade task…”);
boolean result = port.addFirmwareUpgradeTask(sessionId, task);
if (result) {
System.out.println(“Firmware upgrade scheduled successfully.”);
} else {
System.out.println(“Failed to schedule firmware upgrade.”);
}
// 6. Logout
System.out.println(“\nLogging out…”);
port.logout(sessionId);
System.out.println(“Done.”);
} catch (Exception e) {
e.printStackTrace();
}
}
}
✅ What This Example Does
✔ Logs into ACS
Using the SOAP login() method.
✔ Retrieves the device list
Using getDeviceList(sessionId).
✔ Builds a firmware upgrade task
Using the FirmwareUpgradeTask object generated from the WSDL.
Fields typically include:
- deviceId
- firmwareUrl
- scheduleTime
- description
✔ Schedules the upgrade
Using:
Code
addFirmwareUpgradeTask(sessionId, task)
✔ Logs out
Using logout(sessionId).
🧠 Notes Based on Your ACS Manual (v2.11)
Draytek’s ACS 3 manual confirms that:
- ACS uses task objects for firmware upgrades
- Firmware files must be uploaded to ACS or reachable via HTTP/HTTPS
- ACS queues the job and executes it when the device next checks in
- Scheduling is supported via task metadata