RTC

Jexia's Real Time Communication provide you opportunity to get notifications when your DataSet, FileSet or User Management data will be changed. With this you can update you app and provide real time functionality for your clients.

Jexia's realtime functionality uses the WebSocket protocol. In JavaScript for example you will need to create a Websocket object. The Websocket constructor has one required parameter which is the URL:

wss://<project-id>.app.jexia.com/rtc?access_token=<access token>

For further information about Websocket consult the Websocket documentation.

All other (common) languages have similar WebSocket client implementations available.

Sending data to the server

After establishing the connection to the WebSocket API, the client can send messages to perform actions, like subscribing to particular events and receive messages, like notifications about changes.

All data send to the RTC server uses the JSON format and have the same structure:

  • type - type of message
    • command - send command to RTC
      • command
      • event
      • notification
  • data - JSON data depending on type

Commands

Each command has the command field in the data object to specify the command and optionally an arguments object to specify the arguments of the command.

The client (API / UMS) needs to have the proper permissions for the command to be accepted and executed. You can configure permissions via Policy area in Jexia dashboard. 

Commands have following data fields:

  • command - command to send (see available commands below)
  • arguments - JSON object with  commands arguments (actual fields depend on the command)

Subscribe

The following example shows a subscribe command that subscribes to the created, updated and deleted events of mydataset.

{
  "type": "command",
  "data": {
    "command": "subscribe",
    "arguments": {
      "action": [ "created", "updated", "deleted" ],
      "resource": {
        "type": "ds",
        "name": "mydataset"
      }
    }
  }
}

to subscribe for User Management module you need to change type to ums and ignore name option: 

{
  "type": "command",
  "data": {
    "command":   "subscribe",
    "arguments": {
      "action":    [ "signedin","signedup","passwordchanged","deleted" ],
      "resource":  {
        "type":      "ums"
      }
    }
  }
}

Unsubscribe

Send the following command to unsubscribe to the specified event(s).

The response indicates if subscribing succeeded or not, typical error responses are 1000 (Unknown resource type), 1001 (Unknown resource name), and 1002 (Unknown action).

{
  "type": "command",
  "data": {
    "command":   "unsubscribe",
    "arguments": {
      "action":    [ "DELETE","UPDATE" ],
      "resource":  {
        "type":      "ds",
        "name":      "todo"
      }
    }
  }
}

Receiving responses

When messages are received, they will also have the same structure always:

  • type - type of message
    • command  - command was processed 
    • event - data in the project got changed
  • data - JSON object containing the information
{
  "type": "command response",
  "data": {
    "request": "<request fields>",
    "response": "<response fields>",
    "error":   {
      "code":    "<error code>",
      "info":    "<human-readable information>"
    }
  }
}
  • <request fields> - object containing a copy of the request message
  • <request fields> - object containing the command response data (if available)
  • error - when the command failed, this object contains the error information
    • <error code> - Easy to use code for application to determine what went wrong 
    • <human-readable information> - Textual (English) information about the error

Events

The event type has the following data fields:

  • action
  • resource
    • type - resource type that is changed, currently it can be
      • ds - dataset
      • fs - fileset
  • modifier - holds information who/what made the change
    • id - unique id of the entity that caused the event
  • data - record data/information. At the moment it only will has one field (change be changed later):
    • id - record that got changed

In this example the event is received when a new record is created in Dataset.

{
  "type": "event",
  "data": {
    "action": "created",
    "resource": {
      "name": "mydataset",
      "type": "ds"
    },
    "modifier": {
      "id": "cb3a519e-c173-4aee-a8e2-11b93cadc033"
    },
    "timestamp": "2019-02-12T13:34:29Z",
    "data": [{
      "id": "1603087e-44a5-4d19-bff0-6b5713845c15"
    }]
  }
}