Data Packaging Guidelines

This section outlines the guidelines for packaging and formatting messages for the Xentara WebSocket interface. The messages must adhere to the following guidelines:

• All messages transmitted through the Xentara WebSocket interface must be encapsulated within an array. This means every message, whether it contains a single request or multiple ones, must be enclosed in this array format. The response message from the server will adhere to the same format.
• Inside this outer array, it is possible to include multiple requests in a single message. This allows for the efficient packaging of several operations within one transmission.
• Responses to multiple requests will be packaged on a one-to-one basis. This means that for each request in a message, there will be a corresponding response. For example, if a message contains three requests, the resulting message will contain three corresponding responses.
• Each individual request must be enclosed within its own nested array. This ensures that each request is properly isolated within the message structure. The response message from the server will adhere to the same format.
• Only packets of the same type will be packaged together. This means that events and responses will not be mixed within the same packet. Each packet will contain either only events or only responses, but not both.

The following example demonstrates how to include multiple request packets in a single message and the corresponding responses:

Below is a request comprised of a lookup, a get stage, and a metadata command.

[                                                                # Outer Array
  [                                                              # Request Packet 1
    0,                                                           # Request Packet
    65,                                                          # Message Id
    3,                                                           # Lookup OpCode
    {                                                            # Lookup Object
      0: "Group 1.Data Point 1"                                  # Primary Key of the Xentara Element
    }                                                            
  ],                                                             
  [                                                              # Request Packet 2          
    0,                                                           # Request Packet
    66,                                                          # Message Id
    8                                                            # Get Stage OpCode
  ],                                                             
  [
    0,                                                           # Request Packet 3
    67,                                                          # Message Id
    2,                                                           # Metadata OpCode
    {                                                            # Metadata Object
        0: 37(h'E3EE10714D884BA18E5D0F1E4CE25EE8'),              # Xentara Element UUID
        1: [0,83]                                                # Array of Metadata identifiers
    }
  ]
]

The response to the aforementioned multiple request packet will adhere to the previously outlined guidelines and is presented below for reference. This format similarly applies to events, where multiple events are also combined in the same manner.

[                                            # Outer Array
  [                                          # Response Packet 1
    1,                                       # Packet Type - Success Response
    65,                                      # Message Id
    37(h'E3EE10714D884BA18E5D0F1E4CE25EE8')  # Xentara Element UUID
  ],
  [                                          # Response Packet 2
    1,                                       # Packet Type - Ok Response
    66,                                      # Message Id
    2                                        # Operational Stage Xentara
  ],
  [                                          # Response Packet 3
    2,                                       # Packet Type - Error Response
    67,                                      # Message Id
    {                                        
      0: -32602,                             # Error Code
      1: "unknown metadata identifier"       # Error Message
    }
  ]
]