Create Sub-Session Command

Table of Contents

• Command
• Parameters
  • Authentication Information
    • OAuth 2.0 Authorization
    • Certificate-Based Authentication
    • Username/Password Authentication
  • Desired Session Id
• Response
• Errors
• Examples
  • Request
  • Response

Command

OpCode	Name	Description
12	create_sub_session	Create a light-weight sub-session.

Parameters

The parameter object outlined in request packet for this command includes:

ID	Name	Optional	Description
0	authentication_information	no	An object containing authentication information (see below).
1	desired_session_id	yes	A UUID specifying the desired UUID of the Session (see below).

Authentication Information

The authentication_information contains the necessary details to create a session, and it is encapsulated in an alternatives tags.

Here are the specific tag assignments and the structure for each type of authentication:

OAuth 2.0 Authorization

• Tag: 121 (alternatives 0)
• Format: An object containing the encoded token as a text string.
• Example:

  121({0: "add your OAuth 2.0 token here"})

Certificate-Based Authentication

• Tag: 122 (alternatives 1)
• Format: An object containing the DER certificate with key 0 as byte string.
• Example:

  122({0: 'add your DER certificate here'})

  Note

  Proof of possession of the certificate’s private key should already be done by the client. The Xentara WebSocket server does not verify the proof of possession.

Username/Password Authentication

• Tag: 123 (alternatives 2)
• Format:An object containing the username with key 0 and password with key 1, both as text strings.
• Example:

  123({0: "add username here", 1: "add password here"})

Desired Session Id

The desired_session_id contains the UUID formatted as specified in format for UUID. If the desired_session_id is not supplied, the Xentara WebSocket interface will generate a new session ID and return the new UUID in the response. If the provided desired_session_id already exists, the existing session will be replaced, meaning the old session with the same session id will be removed and a new session with updated information will be created. Also, the desired session UUID cannot be null.

Response

The response item outlined in response packet for this command includes:

Name	Type	Description
Session Id	UUID	A UUID specifying the UUID of the Session in format of UUIDs.

If an error occurs, the response will include an error packet with detailed error information.

Errors

Below is the list of the potential errors that may be encountered with this command. Further details regarding errors in the Xentara WebSocket interface can be accessed here.

Sr. No.	Error Code	Error Description
1	-32700	Parse Error
2	-32603	Internal Error
3	-32602	Invalid Parameter
4	-32600	Invalid Request
5	-32000	Missing Client Hello Request
6	-32102	Access Denied

Examples

Request

Below is an example for the request to browse the Xentara model tree for the element with the UUID "e3ee1071-4d88-4ba1-8e5d-0f1e4ce25ee8". The request should retrieve information up to the second layer of depth and include categories "Element Group" and "Data Point". The message id 65 is an arbitrary number assigned for this particular request.

[
  0,                                            # Request Packet
  65,                                           # Message Id
  12,                                           # Create Session OpCode
  {                                             # Create Session Object
    0: 123({0: "add username here", 
            1: "add password here"}),           # Username/Password Authentication
    1: 37('E3EE10714D884BA18E5D0F1E4CE25EE8')   # Desired Session Id
  }
]

[
  0,                                            # Request Packet
  65,                                           # Message Id
  12,                                           # Create Session OpCode
  {                                             # Create Session Object
    0: 121({0: "add OAuth 2.0 token here"}),    # OAuth2.0 Authentication
    1: 37('E3EE10714D884BA18E5D0F1E4CE25EE8')   # Desired Session Id
  }
]

Response

Below is an example of the successful response to the aforementioned request. It indicates a package type of 1, signifying a successful response. The provided Message ID is intended for matching with the corresponding request. The response includes the session id.

[
  1,                                        # Packet Type - Success Response
  65,                                       # Message Id
  37('E3EE10714D884BA18E5D0F1E4CE25EE8')    # Session Id
]