RTC

Jexia's Real Time Communication provides you the opportunity to get notifications when your datasets, filesets or user management data will be changed. With this, you can update your app and provide real time functionality for your clients.

Jexia's real time 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>

To get token you need to make auth call before.

Sending data to the server

After establishing the connection to the JEXIA RTC, the client can send messages to perform actions, like subscribing to particular events.

All request which is being sent to the RTC server uses the JSON format and have the same structure:

  • type -  command to RTC
  • data - JSON data depending on the type

Requests

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

Commands have the following data fields:

  • command - command to send (subscribe, unsubscribe)
  • 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 the type to the UMS and ignore name option: 

{
  "type": "command",
  "data": {
    "command":   "subscribe",
    "arguments": {
      "action":    [ "signedin","signedup","passwordchanged", "created", "updated", "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).

Below you can find the example of how to unsubscribe from deleted, updated events for to do dataset. 

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

Receiving responses

After running request to Jexia, you will get the respond with the same structure:

  • type - the type of message
    • command  - command was processed 
  • 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> - an object containing a copy of the request message
  • <request fields> - an 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 the application to determine what went wrong 
    • <human-readable information> - Textual (English) information about the error

Events

After you did subscriptions (like updated action for todo dataset) your app started to get events as soon as data will be changed in the resource. For example, somebody changes task status in the dataset. 

The event type has the following data fields:

  • action
  • resource
    • type - resource type that is changed, currently it can be
      • ds - dataset
      • fs - fileset
      • for resource User Management you do not need type fields.
  • 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 have 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"
    }]
  }
}

Notification messages

Jexia will send you a notification when something is happening, which is not related to your subscriptions. For example, when the token is about to expire. 

Notification has similar data structure to events or commands:

{
  "type": "notification",
  "data": {
    "code": "<notification code>",
    "info": "<human readable information>",
    "data": "<additional data>"
  }
}

Example: 
{
  "type": "notification",
  "data": {
    "code": 1,
    "info": "Soon token will expire"
  }
}

You can choose to ignore this message (and send the token itself periodically) or use this message as a reminder.

Notification codes

Code Description Details
1 Token about to expire The token is about to expire, it is a good time to send a replacement token.

Error codes

Code Description Details
1 Internal Error Something went wrong in Sharky which is not due to wrong user input.
2 Unauthorized The client JWT is not allowed to execute the command.
3 Invalid token The provided token is not valid
4 Formatting error The received message could not be decoded.
5 Unknown type The provided type was not recognized/supported.
6 Unknown command The provided command was not recognized.
1000 Unknown resource type The provided resource type was not recognized.
1001 Unknown resource name The provided resource name does not exist for the given type.
1002 Unknown action One of the provided action(s) is not recognized/supported.

Refreshing JWT

The JWT has an expiration time, so to keep the WebSocket connection alive, a new JWT token needs to be provided before the old one is expired.

The WebSocket server will notify the client that it is time to replace the token with a new one, or the client can send new tokens manually.

Replace JWT

Use the following command to replace the current token with a new one (e.g. when the current token is about to expire).

Note that <new JWT> is the (access) token, not the refresh token! Most typical error responds is 3 (invalid token)

{ 
       "type": "command", 
       "data": { 
                  "command": "jwt replace", 
                  "arguments": { "token": "<new JWT>" } 
        }
 }

Policy setup

If you interesting to get events from User Management System you need to add Subject and Resourcse - AllUsers, into your policy setup.