Understanding TR-369 GetInstances and GetInstances Response Messages

Within the TR-369 USP (User Services Platform) specification, efficient data retrieval and mapping of Multi-Instance Objects are essential for effective communication between Controllers and Agents.

The GetInstances Message serves as a powerful tool for Controllers to request the Agent to provide a quick map of the existing instances of an object, including any Multi-Instance Sub-Objects.

In this post, we will delve into the purpose and functionality of GetInstances Messages and their corresponding GetInstancesResp Messages.

Let's see the GetInstances message proto-buff definition from the official usp proto-buffer file:

message GetInstances {
  repeated string obj_paths = 1;
  bool first_level_only = 2;
}

GetInstances Messages: The GetInstances Message allows Controllers to request the Agent to provide information about the instances of a specific object, including Multi-Instance Sub-Objects. It serves as a means to quickly map the Multi-Instance Objects (such as tables) represented by the Agent and their unique key parameters.

{
  "header": {
    "msg_id": "2023-05-06T23:54:43.492Z",
    "msg_type": "GET_INSTANCES"
  },
  "body": {
    "request": {
      "get_instances": {
        "obj_paths": [
          "Device.LocalAgent.Controller.1.MTP.1."
        ],
        "first_level_only": false
      }
    }
  }
}

By specifying the object path of an object in the GetInstances Message, Controllers can retrieve all instances of that object currently present in the Agent's Instantiated Data Model. The GetInstances Message also supports a flag called "first_level_only," which determines whether the response should include all sub-objects or only the data for the specified object. This flexibility allows Controllers to retrieve the desired level of detail.

Let's see the GetInstancesResp message proto-buff definition from the official usp proto-buffer file:

message GetInstancesResp {
  repeated RequestedPathResult req_path_results = 1;

  message RequestedPathResult {
    string requested_path = 1;
    fixed32 err_code = 2;
    string err_msg = 3;
    repeated CurrInstance curr_insts = 4;
  }


  message CurrInstance {
    string instantiated_obj_path = 1;
    map<string, string> unique_keys = 2;
  }
}

GetInstancesResp Message: Upon receiving a GetInstances Message, the Agent responds with a GetInstancesResp Message. This response message contains the Object Instance Paths and unique key parameters of the matched instances. It allows Controllers to understand the structure and unique keys of the Multi-Instance Objects within the Agent's data model.

{
  "header": {
    "msg_id": "2023-05-06T23:54:43.492Z",
    "msg_type": "GET_INSTANCES_RESP"
  },
  "body": {
    "response": {
      "get_instances_resp": {
        "req_path_results": [
          {
            "requested_path": "Device.LocalAgent.Controller.1.MTP.1.",
            "curr_insts": [
              {
                "instantiated_obj_path": "Device.LocalAgent.Controller.1.MTP.1.",
                "unique_keys": [
                  {
                    "key": "Alias",
                    "value": "cpe-1"
                  },
                  {
                    "key": "Protocol",
                    "value": "MQTT"
                  }
                ]
              }
            ]
          }
        ]
      }
    }
  }
}

Handling Errors: In case of any errors during the GetInstances operation, the GetInstancesResp Message includes an "err_code" field, indicating the type of error encountered. A value of 0 signifies a successful read operation, while other values correspond to specific error codes. Additionally, the "err_msg" field provides additional information about the cause of the error.

{
  "header": {
    "msg_id": "2023-05-06T23:54:12.844Z",
    "msg_type": "GET_INSTANCES_RESP"
  },
  "body": {
    "response": {
      "get_instances_resp": {
        "req_path_results": [
          {
            "requested_path": "Device.LocalAgent.Controller.1.MTP",
            "err_code": 7008,
            "err_msg": "PATH_RESOLVER_ResolveDevicePath: Path must end in '.'"
          }
        ]
      }
    }
  }
}

Instance Mapping with CurrInstance: The GetInstancesResp Message contains a "curr_insts" field, which holds a message of type CurrInstance for each instance of the matched objects. The CurrInstance message includes the Object Instance Path and a map of key/value pairs representing the unique key parameters of the object. This mapping provides Controllers with a comprehensive overview of the Multi-Instance Objects and their associated key parameters.

Permissions and Read Access: Controllers must ensure they have the necessary Read permission for the object or parameters specified in the GetInstances request. If the Controller lacks the required permissions, the corresponding objects or parameters will not be returned in the GetInstancesResp message.

Conclusion: USP GetInstances Messages play a crucial role in mapping Multi-Instance Objects and retrieving instance information from Agents within the USP ecosystem. By utilizing the GetInstances Message, Controllers can efficiently navigate and manipulate data within the Agent's Instantiated Data Model. The corresponding GetInstancesResp Message provides comprehensive mapping, including Object Instance Paths and unique key parameters. Understanding the functionality and structure of these messages empowers developers and implementers to harness the full potential of USP for effective data management.