Unified Error Code Reporting in PP API for SPV Failures SDD

This document outlines the proposed enhancements to the ACS and PP API response mechanism to propagate parameter-specific fault codes, including device-originated codes like 9820, during SPV (SetParameterValues) operations.

1. Overview

This document outlines the proposed enhancements to the ACS (Auto Configuration Server) and PP API response mechanism in order to propagate parameter-specific fault codes, including device-originated codes like 9820, during SPV (SetParameterValues) operations.

2. Background

During SPV requests sent via the PP API, inconsistencies have been observed in the way faults are reported across the system:

The Wi-Fi 6 device responds with error code 9820 when the same password is reused.
The ACS currently maps this to a generic error code 2460 in the PP API response.
In the UI device activity log, the code 9003 is shown.

These discrepancies hinder traceability and troubleshooting.

3. Customer Concern

Airtel has requested that the original error code 9820, as received from the device, be propagated to the PP API response for the following reasons:

Consistent error visibility across UI, logs, and API.
Better issue traceability and root cause analysis.
Improved integration and support processes.

4. Technical Description

According to the TR-069 specification, the response to SetParameterValues can contain both a general fault code and detailed per-parameter fault codes. Example:

<soap-env:Fault>
  <faultcode>Client</faultcode>
  <faultstring>CWMP fault</faultstring>
  <detail>
    <cwmp:Fault>
      <FaultCode>9003</FaultCode>
      <FaultString></FaultString>
      <SetParameterValuesFault>
        <ParameterName>...FirmwareVersion</ParameterName>
        <FaultCode>9007</FaultCode>
        <FaultString>Read-only parameter</FaultString>
      </SetParameterValuesFault>
      <SetParameterValuesFault>
        <ParameterName>...Username</ParameterName>
        <FaultCode>9008</FaultCode>
        <FaultString>Invalid parameter value</FaultString>
      </SetParameterValuesFault>
    </cwmp:Fault>
  </detail>
</soap-env:Fault>

However, the ACS currently processes and stores only the top-level fault code (9003) and discards detailed information such as the specific fault per parameter (9007, 9008, or vendor-specific like 9820).

5. ACS Implementation Details

When a Fault response with SetParameterValuesFault entries is received, the ACS will:
- Parse and persist each parameter-specific fault.
- Store these in the error_log table using the current task_id.
- This means multiple entries per task_id may be created.
- Error message is taken directly from each SetParameterValuesFault element.
- A new column name_id (default NULL) is added to the error_log table to store the name of the parameter associated with the specific error.
If the response does not contain any SetParameterValuesFault elements, ACS continues operating in the legacy mode:
- Only the general fault code is saved as a single entry in error_log.

6. Provision Portal API Implementation:

6.1. DB change:

A new table ftacs.status_fault with 'id', 'status_id', 'fault_code', 'error_text_id', 'name_id' must be added
In case of erroneous exit from the PP flow due to SPV task failure, specific fault codes per parameters along with parameter names and fault messages must be stored into the ftacs.status_fault table using the current bid.
The values of the fault codes must be retrieved from the error_log table.
The error text IDs must be retrieved from the error_log table.

6.2. Logging change

In case of erroneous exit from the PP flow due to SPV task failure relevant specific fault codes per parameters must be added into log entry along with PP exit code
Status entry example:

Host: qa61, Date: 06.01.2025, Time: 10:43:06, Value: FT010SN00087QS2222463002077 2460 : At least one task was failed or rejected:

Parameter name: "Device.ManagementServer.ConnectionRequestURZZZ", Fault code: "9005", Fault string: "Invalid parameter name"

Parameter name: "Device.ManagementServer.ConnectionRequestURL", Fault code: "7010", Fault string: "Attempt to update non-writable parameter"

Affected status codes:
- 1390
- 1520
- 1890
- 2380
- 2460
- 4240
- 5121

6.3. "GetStatus" method output changes:

A new tag <Fault/> must be added to the GetStatus Provision Portal API method response
The new tag must remain self-closing in case of successful end of provisioning.
The new tag must contain a list of parameter names that have failed SPV task along with relevant fault codes and fault strings in case of erroneous exit from the PP flow due to SPV task failure, according to the example presented below
Response example:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
    <GetStatusResponse>
      <GetStatusResult>
        <Status>
          <Id>24</Id>
          <BId>f984e9fa-be9d-457a-9a31-2cdca97073ac</BId>
          <Sn>FT001SN00002SERIALBUK</Sn>
          <Mac/>
          <OperationCode>248</OperationCode>
          <Fault/>
          <Created>2025-08-05T15:55:54</Created>
        </Status>
        <Status>
          <Id>23</Id>
          <BId>f984e9fa-be9d-457a-9a31-2cdca97073ac</BId>
          <Sn>FT001SN00001SERIALBUK</Sn>
          <Mac/>
          <OperationCode>2460</OperationCode>
          <Fault>
            <Parameters>
              <Parameter>
                <Name>Device.ManagementServer.ConnectionRequestURZZZ</Name>
                <FaultCode>9005</FaultCode>
                <FaultString>Invalid parameter name</FaultString>
              </Parameter>
              <Parameter>
                <Name>Device.ManagementServer.ConnectionRequestURL</Name>
                <FaultCode>7010</FaultCode>
                <FaultString>Attempt to update non-writable parameter</FaultString>
              </Parameter>
            </Parameters>
          </Fault>
          <Created>2025-08-05T15:55:54</Created>
        </Status>
      </GetStatusResult>
    </GetStatusResponse>
  </soap:Body>
</soap:Envelope>

6.4. "ProvisioningForDevice" method output changes:

A new tag <Fault/> must be added to the ProvisioningForDevice Provision Portal API method response
The new tag must remain self-closing in case of successful end of provisioning.
The new tag must contain a list of parameter names that have failed SPV task along with relevant fault codes and fault strings in case of erroneous exit from the PP flow due to SPV task failure, according to the example presented below
Response example:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
    <ProvisioningForDeviceResponse>
      <ProvisioningForDeviceResult>
        <Result>200</Result>
        <Message>At least one task was failed or rejected</Message>
        <Bid>33ef836c-431d-4963-b76d-b31f8aec4049</Bid>
        <Status>2460</Status>
        <Fault>
          <Parameters>
            <Parameter>
              <Name>Device.ManagementServer.ConnectionRequestURZZZ</Name>
              <FaultCode>9005</FaultCode>
              <FaultString>Invalid parameter name</FaultString>
            </Parameter>
            <Parameter>
              <Name>Device.ManagementServer.ConnectionRequestURL</Name>
              <FaultCode>7010</FaultCode>
              <FaultString>Attempt to update non-writable parameter</FaultString>
            </Parameter>
          </Parameters>
        </Fault>
      </ProvisioningForDeviceResult>
    </ProvisioningForDeviceResponse>
  </soap:Body>
</soap:Envelope>

7. Impact Analysis

Data model changes:
- Addition of name_id column in error_log table.
- Additional table ftacs.status_fault with 'id', 'status_id', 'fault_code', 'error_text_id', 'name_id'.
API schema and client integrations will require updates.
Minor performance impact anticipated due to additional fault parsing and persistence.