Websocket Messages

Overview of how to use Websockets in conjunction with Qordoba

Websocket messages types

There are 3 different types of messages that can be sent/received by our Websocket:

  • request / response
  • subscription (send -- to "subscribe" to certain workspaces/personas/milestones and receive push notifications when content is updated)
  • push notification (receive -- you will receive push notifications for workspaces/personas/milestones you are subscribed to)

Request / Response

These messages are used to download segments, similar to normal AJAX request. They are also used to send back "heartbeat" to keep connection open

Heartbeat messages

Qordoba sends heartbeat messages frequently to the all connected clients to check if the connection is still needed. If the client doesn't respond to the message, Qordoba will drop the connection.

From Qordoba:

Key
Value

identifier

heartbeat

message_id

563509csdfsffscadf56jkixtq8semi

message_type

""

Response needed from your client:

Key
Value

identifier

heartbeat

message_id

563509csdfsffscadf56jkixtq8semi

Segment Download Messages

You can send this message to Qordoba to download segments at a specific workflow step from a specific language. You can also provide page id's if you'd like to limit the response to certain files.

Please note that workflow step will be ignored if you download the source language, as source content does not have workflow steps.

Request to send to Qordoba:

Key
Value
Description

identifier

/projects/:project_id/languages/:language_id/milestones/:milestone_id/editable

params

{
"project_id": "135",
"language_id": "234",
"milestone_id": "194"
}

  • project_id: number, mandatory.
  • language_id: number, mandatory.
  • milestone_id: optional; when {language_id} is source language, mandatory when {language_id} is localized language.

message_id

4kzx09c7qyscadf56jkixtq8semi

random uuid, will be in the response message

message_type

request

Response you will get from Qordoba for "target" and "source" languages:

Key
Value
Description

identifier

/projects/:project_id/languages/:language_id/milestones/:milestone_id/editable

params

{
"project_id": "135",
"language_id": "234",
"milestone_id": "194"
}

  • project_id: number, mandatory.
  • language_id: number, mandatory.
  • milestone_id: optional; when {language_id} is source language, mandatory when {language_id} is localized language.

message_id

4kzx09c7qyscadf56jkixtq8semi

uuid, coming from request message

message_type

response

content

{
"segments": [
{
"page_id": 375,
"project_id": 135,
"segment_id": 18734,
"translation_id": -1,
"segment": "OK",
"translation": "OK",
"reference": "btnOK",
"plurals": null,
"archive_segment": "",
"order": null,
"string_key": "btnOK",
"last_saved": 1533735964000
},
{
"page_id": 375,
"project_id": 135,
"segment_id": 18735,
"translation_id": -1,
"segment": "Submit",
"translation": "Submit",
"reference": "btnSubmit",
"plurals": [
{
"source": "Submit",
"rule": "one"
},
{
"source": "Submit",
"rule": "other"
}
],
"archive_segment": "",
"order": null,
"string_key": "btnSubmit",
"last_saved": 1533735964000
}
],
"result": "success"
}

for "target" languages

content

{
"segments": [
{
"page_id": 375,
"project_id": 135,
"segment_id": 18735,
"segment": "Submit",
"reference": "btnSubmit",
"plurals": [
{
"source": "Submit",
"rule": "one"
},
{
"source": "Submit",
"rule": "other"
}
],
"comments": 0,
"archive_segment": "",
"translation_id": 38335,
"translation": "Enviar",
"plural_rule": "other",
"saved": false,
"locked": false,
"order": null,
"string_key": "btnSubmit",
"smart_suggest": {
"match": 100,
"text": "Enviar"
},
"last_saved": 1533735965000,
"flags": {
"do_not_modify": false,
"flag": true
}
},
{
"page_id": 375,
"project_id": 135,
"segment_id": 18736,
"segment": "Next",
"reference": "btnNext",
"plurals": null,
"comments": 0,
"archive_segment": "",
"translation_id": 38336,
"translation": "Siguiente",
"plural_rule": null,
"saved": false,
"locked": false,
"order": null,
"string_key": "btnNext",
"smart_suggest": {
"match": 100,
"text": "Siguiente"
},
"last_saved": 1533735965000,
"flags": {
"do_not_modify": false,
"flag": false
}
}
],
"result": "success"
}

for "source" languages

Subscriptions

You can "Subscribe" to one of three things in Qordoba:

1) A workspace/persona combination within a project for a target language. This will generate push notifications whenever segment targets are modified in a project (save, push, complete, un-complete, push back a step, etc.)
2) The source language for a project. This will generate push notifications whenever the target content is modified (add file, delete file, add segment, edit source, etc.).
3) Releases for a given project. This will generate a push notification every time a release goes out with the URL to download the zip file of the release's contents.

Subscribe to Target OR Source

You would send the following to Qordoba:

Key
Value
Description

identifier

/projects/:project_id/languages/:language_id/segments_live_updates

params

{"project_id": 1, "language_id": 2}

If language_id is source language, you will subscribe to source. Else, you will subscribe to target.

message_id

sdfsd509csdfsffscadrrrjkixtq8semi

message_type

subscribe

And get the following response, confirming your subscription:

Key
Value

identifier

/projects/:project_id/languages/:language_id/segments_live_updates

params

{"project_id": 1, "language_id": 2}

message_id

sdfsd509csdfsffscadrrrjkixtq8semi

message_type

subscribe

content

{"result": "success"}

Subscribe to Releases

You would send the following to Qordoba:

Key
Value

identifier

/projects/:project_id/releases

params

{"project_id": "1"}

message_id

yu509csdfsffscadrrrjkixtq8styu

message_type

subscribe

And get the following response to confirm your subscription:

identifier

/projects/:project_id/releases

params

{"project_id": "1"}

message_id

yu509csdfsffscadrrrjkixtq8styu

message_type

response

content

{"result": "success"}

Push Notifications

Changes to Source / Target

For changes to source or target, you will receive the following notification:

Key
Value
Description

identifier

/projects/:project_id/languages/:language_id/segments_live_updates

params

{
"project_id": "2677",
"language_id": "234",
"type": "save_target",
"last_updated": 1533738123230
}

type might take one of these options based on the segment action

[push_target, save_target, add_file, delete_file, complete_target, send_back_target,uncomplete_target, do_not_modify, add_segment, edit_source, delete_segment, flagged]

message_id

4kzx09c7qyscadf56jkixtq8semi

message_type

push_notification

content

{
"flags": {do_not_modify: false, flag: false},
"do_not_modify": false,
"flag": false,
"locked": false,
"milestone_id": 5601,
"page_id": 423075,
"saved": true
"segment_id": 3565331
"segment_key": "msgTopNetworkError"
"source": "Without internet is the largest pain."
"translation": "Sin internet es el mayor dolor."
"translation_id":4608371
"updated_user_id":6
}

for target languages

content

{
"flags": {do_not_modify: false, flag: false},
"do_not_modify": false,
"flag": false,
"locked": false,
"milestone_id": 5601,
"page_id": 423075,
"saved": false
"segment_id": 3565331
"segment_key": "msgTopNetworkError"
"source": "Without internet is the largest pain."
"translation": "Without internet is the largest pain."
"translation_id": -1
"updated_user_id":6
}

for source language

  • "translation" will match "source"

*"translation_id" will always be -1

Releases

When a release from a workspace in Qordoba you've subscribed to goes live, you will get the following push notification with a download link for the files contained in the release:

Key
Value

identifier

/projects/:project_id/releases

params

{"project_id": "41"}

message_id

4kzx09c7qyscadf56jkixtq8semi

message_type

push_notification

content

{"link": "http://google.com/file_path.zip", "type" : "release", "last_updated": }

Full code sample

To see an example of creating a websocket and utilizing the various functions above, see repo here:
https://github.com/Qordobacode/sample-ws-logic