Interface Definition

This document describes the interface between the frontend and the backend of the K-dPS project. The events are divided into three categories: events used to log in, events available on the patient route and event available on the trainer route. They are then further divided within their categories into events that can be sent from the frontend to the backend and events that can be sent from the backend to the frontend. Within these subcategories, the events are ordered alphabetically.

Color Legend

🟢 → event fully implemented
🟡 → event only implemented in frontend
🔵 → event only implemented in backend
🔴 → event not implemented

Login

via HTTP

🟢 Trainer Login

if a new username is entered, a new account is automatically generated and logged in
debug exercise credentials: username=test, password=password

Request

{
    "username":"X",
    "password":"X"
}

Response

success:

{
    "token":"X"
}

username or password is missing → status code 400
username exists, but password is wrong → status code 401

🟢 Patient Login

debug exercise credentials: exerciseid=abcdef, patientId=123456

Request

{
    "exerciseId":"abcdef",
    "patientId":"123456"
}

exerciseId: always six letters
patientId: always six digits

Response

success

{
  "token": "X"
}

exerciseId or patientId is missing → status code 400
either exerciseId or patientId is wrong → status code 401

Common

Websocket events that are available in Patient and Trainer connections

Frontend → Backend

🟢 test-passthrough

expects to receive test-passthrough event back

{
  "messageType": "test-passthrough"
}

Backend → Frontend

🟢 available-actions

send after authentication
at the moment only used in patient module but makes more sense as common because of consistency

{
  "messageType": "available-actions",
  "availableActions": [
    {
      "actionName": "X",
      "actionCategory": "treatment|examination|lab|other"
    }
  ]
}

🟢 available-materials

send after authentication

{
  "messageType": "available-materials",
  "availableMaterials": [
    {
      "materialName": "X",
      "materialType": "device|blood"
    }
  ]
}

🟢 available-patients

send after authentication

{
  "messageType": "available-patients",
  "availablePatients": [
    {
      "code": 1001,
      "personalDetails": "X",
      "injury": "X",
      "biometrics": "X",
      "triage": "-|G|Y|R|A|B|C|D|E",
      "mobility": "X",
      "preexistingIllnesses": "X",
      "permanentMedication": "X",
      "currentCaseHistory": "X",
      "pretreatment": "X"
    }
  ]
}

code: 1001-1041: IDs corresponding to the dynamic patient templates

🟢 exercise

send after authentication and on each exercise update

{
  "messageType": "exercise",
  "exercise": {
    "exerciseId": "X",
    "areas": [
      {
        "areaId": 0,
        "areaName": "X",
        "patients": [
          {
            "patientId": "X",
            "patientName": "X",
            "code": 1001,
            "triage": "-|X|1|2|3"
          }
        ],
        "personnel": [
          {
            "personnelId": 0,
            "personnelName": "X"
          }
        ],
        "material": [
          {
            "materialId": 0,
            "materialType": "X",
            "materialName": "X" 
          }
        ]
      }
    ]
  }
}

code: 1001-1041: analog to available-patients fetch

🟢 exercise-end

{
  "messageType": "exercise-end"
}

🟡 exercise-pause

{
  "messageType":"exercise-pause"
}

🟡 exercise-resume

{
  "messageType":"exercise-resume"
}

🟢 exercise-start

{
  "messageType": "exercise-start"
}

🟢 failure

{
  "messageType": "failure",
  "message": "X"
}

🟢 test-passthrough

{
  "messageType": "test-passthrough",
  "message": "received test event"
}

🟢 warning

{
  "messageType": "warning",
  "message": "X"
}

Patient

Websocket events that are available in Patient connections

Frontend → Backend

🟢 action-add

frontend won’t accept new actions by user until either an action-declination event or an action-confirmation event was sent in response to this event

{
  "messageType": "action-add",
  "actionName": "X"
}

🟢 action-cancel

{
  "messageType":"action-cancel",
  "actionId":213
}

🟢 action-check

start sending action-check events for the specific action

{
  "messageType":"action-check",
  "actionName":"X"
}

🟢 action-check-stop

start sending action-check events for the specific action

{
  "messageType":"action-check-stop"
}

🔵 example

used for internal backend tests

{
  "messageType":"example",
  "exerciseId":"abcdef", 
  "patientId":"123456"
}

🟢 material-assign

{
  "messageType":"material-assign",
  "materialId":1
}

🟡 material-move

{
  "messageType":"material-move",
  "materialId":0,
  "areaId":0
}

🟢 material-release

{
  "messageType":"material-release",
  "materialId":1
}

🟢 patient-move

{
  "messageType":"patient-move",
  "areaId":0
}

🟢 personnel-assign

{
  "messageType":"personnel-assign",
  "personnelId":1
}

🟡 personnel-move

{
  "messageType":"personnel-move",
  "personnelId":0,
  "areaId":0
}

🟢 personnel-release

{
  "messageType":"personnel-release",
  "personnelId":1
}

🟢 triage

the current triage color of this patient

{
  "messageType": "triage",
  "triage": "-|X|1|2|3"
}

Backend → Frontend

🟢 action-check

check action requirements
will only be sent if action-check was sent by frontend before

{
  "messageType": "action-check",
  "actionCheck": {
    "actionName": "X",
    "applicationDuration": 4,
    "effectDuration": 3,
    "personnel": [
      {
        "name": "X",
        "available": 1,
        "assigned": 1,
        "needed": 1
      }
    ],
    "material": [
      {
        "name": "X",
        "available": 1,
        "assigned": 1,
        "needed": 1
      }
    ],
    "lab_devices": [
      {
        "name": "X",
        "available": 1,
        "needed": 1
      }
    ],
    "requiredActions": {
      "singleActions": ["A1"],
      "actionGroups": [
        {
          "groupName": "Tubusse",
          "actions": [
            "A2",
            "A3"
          ]
        }
      ]
    },
    "prohibitiveActions":["A1"]
  }
}

actionName: important if the user already opened another action applicationDuration: in seconds effectDuration: in seconds requiredActions: only the ones still missing prohibitiveActions: only the ones actually blocking it

🟢 action-confirmation

frontend won’t accept new actions by user until this event or an action-declination event was sent for the last action added via action-add

{
  "messageType": "action-confirmation",
  "actionName": "X",
  "actionId": 123
}

🟢 action-declination

frontend won’t accept new actions by user until this event or an action-confirmation event was sent for the last action added via action-add

{
  "messageType": "action-declination",
  "actionName": "X",
  "actionDeclinationReason": "X"
}

🟢 action-list

send every time the action list of the patient is changed (no timeUntilCompletion updates)

{
  "messageType":"action-list",
  "actions":[{
    "actionId":123,
    "orderId":123,
    "actionName":"X",
    "actionStatus":"IP|FI|PL|OH|IE|EX",
    "timeUntilCompletion":123,
    "actionResult":"X"
  }]
}

timeUntilCompletion: in seconds, null if completed actionResult: null if not completed or no result

🔴 delete

{
  "messageType":"delete"
}

🟢 ressource-assignments

can consist out of one or multiple areas

{
  "messageType": "ressource-assignments",
  "ressourceAssignments": [
    {
      "areaId": 0,
      "personnel": [
        {
          "personnelId": 1,
          "patientId": 1
        }
      ],
      "material": [
        {
          "materialId": 1,
          "patientId": 1
        }
      ]
    }
  ]
}

patientId: null if unassigned

🔵 response

used for internal backend tests

{
  "messageType":"response",
  "content":"X"
}

🟢 state

dynamic patient information - send on ever phase change

{
  "messageType": "state",
  "state": {
    "airway": "X",
    "breathing": "X",
    "circulation": "X",
    "consciousness": "X",
    "pupils": "X",
    "psyche": "X",
    "skin": "X"
  }
}

🔴 patient-active

{
  "messageType":"patient-active"
}

🟢 patient-back

send if lab-side action is finished

{
  "messageType":"patient-back"
}

🔴 patient-inactive

{
  "messageType":"patient-inactive",
  "inactiveInfo":"X",
  "timeUntilBack":123
}

timeUntilBack: in seconds

🟢 patient-relocating

send if a lab-side action is started

{
  "messageType":"patient-relocating",
  "relocatingInfo":"X",
  "timeUntilBack":123
}

timeUntilBack: in seconds

🟡 visible-injuries

{
  "messageType":"visible-injuries",
  "injuries":[{
    "injuryId":0,
    "injuryType":"blood|fracture",
    "position":"X"
  }]
}

position: there is a list of possible positions in the frontend

Trainer

Websocket events that are available in Patient connections

Frontend → Backend

🟢 area-add

{
  "messageType":"area-add"
}

🟢 area-delete

{
  "messageType":"area-delete",
  "areaId":0
}

🟢 area-rename

{
  "messageType":"area-rename",
  "areaId":0,
  "areaName":"X"
}

🔵 example

used for internal backend tests

{
  "messageType":"example",
  "exerciseId":"abcdef"
}

🟢 exercise-create

{
  "messageType":"exercise-create"
}

🟢 exercise-end

{
  "messageType":"exercise-end"
}

🟡 exercise-pause

{
  "messageType":"exercise-pause"
}

🟡 exercise-resume

{
  "messageType":"exercise-resume"
}

🟢 exercise-start

{
  "messageType":"exercise-start"
}

🟢 material-add

{
  "messageType": "material-add",
  "areaId": 0,
  "materialName": "X"
}

🟢 material-delete

{
  "messageType": "material-delete",
  "materialId": 0
}

🟢 patient-add

{
  "messageType":"patient-add",
  "areaId":0,
  "patientName":"X",
  "code":1001
}

code: 1001-1041: analog to available-patients fetch

🟢 patient-delete

{
  "messageType":"patient-delete",
  "patientId":"X"
}

🟢 patient-rename

{
  "messageType":"patient-rename",
  "patientId":0,
  "patientName":"X"
}

🟢 patient-update

{
  "messageType": "patient-update",
  "patientId": "X",
  "code": 1001
}

code: 1001-1041: analog to available-patients fetch

🟢 personnel-add

{
  "messageType":"personnel-add",
  "areaId":0,
  "personnelName":"X"
}

🟢 personnel-delete

{
  "messageType":"personnel-delete",
  "personnelId":0
}

🟢 personnel-rename

{
  "messageType": "personnel-rename",
  "personnelId": 0,
  "personnelName": "X"
}

🟡 set-speed

{
  "messageType": "set-speed",
  "speed": 1
}

speed: from 0.2 to 4 in 0.1 steps

Backend → Frontend

🟢 log-update

on first login during running exercise send all log entries

{
    "messageType":"log-update",
    "logEntries":[{
        "logId":0,
        "logMessage":"X",
        "logTime":0,
        "areaId":0,
        "patientId":"X",
        "personnelIds":[0],
        "materialNames": ["X"]
    }]
}

logTime: number of milliseconds since January 1, 1970, 00:00:00 UTC.

🔵 response

used for internal backend tests

{
  "messageType":"response",
  "content":"X"
}

🟡 set-speed

{
  "messageType": "set-speed",
  "speed": 1
}

speed: from 0.2 to 4 in 0.1 steps

Files

interface-definition.md

Latest commit

History

interface-definition.md

File metadata and controls

Interface Definition

Color Legend

Login

🟢 Trainer Login

Request

Response

🟢 Patient Login

Request

Response

Common

Frontend → Backend

🟢 test-passthrough

Backend → Frontend

🟢 available-actions

🟢 available-materials

🟢 available-patients

🟢 exercise

🟢 exercise-end

🟡 exercise-pause

🟡 exercise-resume

🟢 exercise-start

🟢 failure

🟢 test-passthrough

🟢 warning

Patient

Frontend → Backend

🟢 action-add

🟢 action-cancel

🟢 action-check

🟢 action-check-stop

🔵 example

🟢 material-assign

🟡 material-move

🟢 material-release

🟢 patient-move

🟢 personnel-assign

🟡 personnel-move

🟢 personnel-release

🟢 triage

Backend → Frontend

🟢 action-check

🟢 action-confirmation

🟢 action-declination

🟢 action-list

🔴 delete

🟢 ressource-assignments

🔵 response

🟢 state

🔴 patient-active

🟢 patient-back

🔴 patient-inactive

🟢 patient-relocating

🟡 visible-injuries

Trainer

Frontend → Backend

🟢 area-add

🟢 area-delete

🟢 area-rename

🔵 example

🟢 exercise-create

🟢 exercise-end

🟡 exercise-pause

🟡 exercise-resume

🟢 exercise-start

🟢 material-add

🟢 material-delete

🟢 patient-add

🟢 patient-delete

🟢 patient-rename

🟢 patient-update

🟢 personnel-add

🟢 personnel-delete

🟢 personnel-rename

🟡 set-speed