Managing Object Removal with TR-369 USP Delete Messages

Efficient object removal is a cornerstone of effective device management, ensuring systems remain well-organized and functional. In the TR-369 User Services Platform (USP) specification, Delete Messages provide a standardized mechanism to request and confirm the removal of device objects.

In this post, we delve into the structure and usage of USP Delete Messages and their corresponding Delete Response Messages, shedding light on how they facilitate clean and efficient object removal in device management workflows.

USP Delete Messages: Requesting Object Removal

Delete Messages in USP allow control systems to initiate the deletion of specific objects within a device. These messages are used to streamline the removal of unnecessary or outdated objects, ensuring the system remains optimized.

Structure of a Delete Message

A Delete Message consists of two main components:

1. Header
   • msg_id: A unique identifier for tracking the request.
   • msg_type: Set to "DELETE" to denote the nature of the message.
2. Body
   • allow_partial: Indicates whether partial deletion is acceptable if errors occur during the process.
   • obj_paths: An array specifying the paths of objects to be removed. These paths provide context for identifying the target objects.

Proto-Buffer Definition for Delete Messages

message Delete {
  bool allow_partial = 1;
  repeated string obj_paths = 2;
}

Example: Delete Message

{
  "header": {
    "msg_id": "2023-05-12T19:37:45.909Z",
    "msg_type": "DELETE"
  },
  "body": {
    "request": {
      "delete": {
        "allow_partial": true,
        "obj_paths": [
          "evice.LocalAgent.Controller.5."
        ]
      }
    }
  }
}

In this example, the request targets the deletion of the object located at Device.LocalAgent.Controller.5., allowing partial success if errors occur.

USP Delete Response Messages: Confirming Object Removal

Upon receiving a Delete Message, the device validates the request, performs the deletion, and generates a Delete Response Message. This response communicates the outcome of the operation, including details about successful deletions or any encountered errors.

Structure of a Delete Response Message

A Delete Response Message provides detailed feedback and consists of the following:

1. Deleted Object Results
   • requested_path: Specifies the object path from the initial request.
   • Operation Status: Indicates success or failure of the deletion operation, with additional details if applicable.
2. Success (oper_success)
   • affected_paths: Lists the paths of successfully deleted objects.
   • unaffected_path_errs (optional): Details paths that could not be deleted and associated errors.
3. Failure (oper_failure)
   • err_code and err_msg: Provide error specifics.

Proto-Buffer Definition for Delete Response Messages

message DeleteResp {
  repeated DeletedObjectResult deleted_obj_results = 1;

  message DeletedObjectResult {
    string requested_path = 1;
    OperationStatus oper_status = 2;

    message OperationStatus {
      oneof oper_status {
        OperationFailure oper_failure = 1;
        OperationSuccess oper_success = 2;
      }

      message OperationFailure {
        fixed32 err_code = 1;
        string err_msg = 2;
      }

      message OperationSuccess {
        repeated string affected_paths = 1;
        repeated UnaffectedPathError unaffected_path_errs = 2;
      }
    }
  }

  message UnaffectedPathError {
    string unaffected_path = 1;
    fixed32 err_code = 2;
    string err_msg = 3;
  }
}

Example: Successful Delete Response

{
  "header": {
    "msg_id": "2023-05-12T18:26:58.579Z",
    "msg_type": "DELETE_RESP"
  },
  "body": {
    "response": {
      "delete_resp": {
        "deleted_obj_results": [
          {
            "requested_path": "Device.LocalAgent.Controller.5.",
            "oper_status": {
              "oper_success": {
                "affected_paths": [
                  "Device.LocalAgent.Controller.5."
                ]
              }
            }
          }
        ]
      }
    }
  }
}

This response confirms the successful deletion of the object at the specified path.

Example: Non-Existent Object Response

If the requested object does not exist, the response may appear as follows:

{
  "header": {
    "msg_id": "2023-05-10T22:46:59.166Z",
    "msg_type": "DELETE_RESP"
  },
  "body": {
    "response": {
      "delete_resp": {
        "deleted_obj_results": [
          {
            "requested_path": "Device.LocalAgent.Controller.5.",
            "oper_status": {
              "oper_success": {}
            }
          }
        ]
      }
    }
  }
}

The absence of affected paths indicates that the object was already missing.

Key Benefits of USP Delete Messages

1. Efficient Resource Management
   • Enables the removal of obsolete or redundant objects, optimizing system performance.
2. Structured Error Handling
   • Provides detailed feedback on errors, enabling administrators to diagnose and resolve issues effectively.
3. Scalability
   • Supports batch deletions with partial success for flexible and scalable device management.

Conclusion

USP Delete Messages and Delete Response Messages are vital tools for managing device objects in a TR-369-compliant system. By providing a clear framework for initiating and confirming deletions, they ensure systems remain organized, functional, and optimized.

Understanding these messages is critical for engineers and administrators aiming to build or maintain efficient and scalable device management systems.

For more insights and technical documentation, visit TR369.org.

References:

1. TR-369 USP Specification, Broadband Forum, https://www.broadband-forum.org/tr-369
2. USP Record Definitions, GitHub Repository, https://github.com/BroadbandForum/usp