Subscribe to the Beacon real-time notification stream

GET /beacon/v1/notifications

Operation id: subscribeNotifications

Description

Opens a long-lived Server-Sent Events connection that streams heartbeat, RSP, and WALK named events for the authenticated user's unit/domain. The response contains notification events filtered by the user's domain and unit context.

Authentication: domainId, userId, unitId, langCode, and upstream domainNo are resolved from the validated session (unitId ← session unit, domainNo ← String.valueOf(session.domainId)), matching the Angular SSE client. Query parameters are not accepted for unit/domain scope.


Named Events

EventDescription
heartbeatLiveness ping. No meaningful data payload; only resets the client's watchdog timer.
RSPMyWork/feed domain event. data is a JSON object matching SseMessage.
WALKSWA walk/form domain event. data is a JSON object matching SseMessage.

function Values

SSE EventfunctionDomain Area
RSPFEEDFeed/task list update
RSPRRCMESSAGEComments/message thread update
RSPBROADCASTMESSAGEBroadcast message update
WALKWALKSCHEDULEINFOWalk schedule/conduct update
WALKMODELSTATELISTINGWalk model-state update
WALKMODELSTATELISTING_FORM_TEMPLATEForm template model-state update
WALKMODELSTATELISTING_FORM_INSTANCEForm instance model-state update
WALKFORMMODELForm instance update
WALKFORMMODEL_TEMPLATEForm template update

Error Scenarios

ScenarioHTTPError CodeMessage
Missing X-reflexis-csrf-token-X header400E112X-reflexis-csrf-token-X header is mandatory
Invalid or expired token401E204Invalid or expired token
Session has no unit id400E900unitId is mandatory
Upstream Beacon forbids unit/domain403E902Requested unitId/domainNo does not match the authenticated session
Upstream Beacon service rejects the forwarded token401E204Invalid or expired token
Upstream Beacon service unavailable or handshake failed500E903Beacon notification service is unavailable

Error Codes Reference

CodeDescription
E112X-reflexis-csrf-token-X header is mandatory
E204Invalid or expired token
E900Session unit id is missing (unitId is mandatory)
E902Upstream rejected unit/domain context
E903Beacon notification service is unavailable

Tags: BeaconNotifications

Parameters

Header parameters

NameTypeRequiredDescription
AcceptstringYesMust be text/event-stream.

Security

  • AuthTokenHeader (apiKey)
    • Session authentication token validated server-side against the user session store.

Responses

200 — Success — a text/event-stream connection kept open indefinitely. Named events:

heartbeat (no payload), RSP/WALK (data is a JSON object matching SseMessage).

Content type: text/event-stream

400 — E112 header missing / E900 session unitId mandatory

Content type: application/json

401 — Invalid or expired X-reflexis-csrf-token-X token (HTTP 401)

Content type: application/json

403 — Requested unitId/domainNo does not match the authenticated session (HTTP 403)

Content type: application/json

500 — Unexpected server-side error

Content type: application/json

Response models

200 — Success — a text/event-stream connection kept open indefinitely. Named events:

heartbeat (no payload), RSP/WALK (data is a JSON object matching SseMessage).

Content type: text/event-stream

Schema

JSON payload carried in the data: field of RSP/WALK named SSE events. The client only reacts to function's presence; additional properties may be present and are not required to be consumed.

PropertyTypeRequiredDescription
functionstringYesDiscriminator identifying which domain change occurred.
{
  "type": "object",
  "description": "JSON payload carried in the `data:` field of `RSP`/`WALK` named SSE events. The client\nonly reacts to `function`'s presence; additional properties may be present and are not\nrequired to be consumed.\n",
  "required": [
    "function"
  ],
  "properties": {
    "function": {
      "type": "string",
      "description": "Discriminator identifying which domain change occurred.",
      "enum": [
        "FEED",
        "RRCMESSAGE",
        "BROADCASTMESSAGE",
        "WALKSCHEDULEINFO",
        "MODELSTATELISTING",
        "MODELSTATELISTING_FORM_TEMPLATE",
        "MODELSTATELISTING_FORM_INSTANCE",
        "FORMMODEL",
        "FORMMODEL_TEMPLATE"
      ]
    }
  }
}

400 — E112 header missing / E900 session unitId mandatory

Content type: application/json

Schema

PropertyTypeRequiredDescription
statusstringYesAlways "ER" for error responses
errorCodestringYesApplication-level error code (e.g. E204, E112, E902)
responsestringYesHuman-readable error message
{
  "type": "object",
  "example": {
    "status": "ER",
    "errorCode": "E204",
    "response": "Invalid or expired token"
  },
  "required": [
    "status",
    "errorCode",
    "response"
  ],
  "properties": {
    "status": {
      "type": "string",
      "description": "Always \"ER\" for error responses",
      "enum": [
        "ER"
      ]
    },
    "errorCode": {
      "type": "string",
      "description": "Application-level error code (e.g. E204, E112, E902)"
    },
    "response": {
      "type": "string",
      "description": "Human-readable error message"
    }
  }
}

Example:

{
  "status": "ER",
  "errorCode": "E900",
  "response": "unitId is mandatory"
}

401 — Invalid or expired X-reflexis-csrf-token-X token (HTTP 401)

Content type: application/json

Schema

PropertyTypeRequiredDescription
statusstringYesAlways "ER" for error responses
errorCodestringYesApplication-level error code (e.g. E204, E112, E902)
responsestringYesHuman-readable error message
{
  "type": "object",
  "example": {
    "status": "ER",
    "errorCode": "E204",
    "response": "Invalid or expired token"
  },
  "required": [
    "status",
    "errorCode",
    "response"
  ],
  "properties": {
    "status": {
      "type": "string",
      "description": "Always \"ER\" for error responses",
      "enum": [
        "ER"
      ]
    },
    "errorCode": {
      "type": "string",
      "description": "Application-level error code (e.g. E204, E112, E902)"
    },
    "response": {
      "type": "string",
      "description": "Human-readable error message"
    }
  }
}

Example:

{
  "status": "ER",
  "errorCode": "E204",
  "response": "Invalid or expired token"
}

403 — Requested unitId/domainNo does not match the authenticated session (HTTP 403)

Content type: application/json

Schema

PropertyTypeRequiredDescription
statusstringYesAlways "ER" for error responses
errorCodestringYesApplication-level error code (e.g. E204, E112, E902)
responsestringYesHuman-readable error message
{
  "type": "object",
  "example": {
    "status": "ER",
    "errorCode": "E204",
    "response": "Invalid or expired token"
  },
  "required": [
    "status",
    "errorCode",
    "response"
  ],
  "properties": {
    "status": {
      "type": "string",
      "description": "Always \"ER\" for error responses",
      "enum": [
        "ER"
      ]
    },
    "errorCode": {
      "type": "string",
      "description": "Application-level error code (e.g. E204, E112, E902)"
    },
    "response": {
      "type": "string",
      "description": "Human-readable error message"
    }
  }
}

Example:

{
  "status": "ER",
  "errorCode": "E902",
  "response": "Requested unitId/domainNo does not match the authenticated session"
}

500 — Unexpected server-side error

Content type: application/json

Schema

PropertyTypeRequiredDescription
statusstringYesAlways "ER" for error responses
errorCodestringYesApplication-level error code (e.g. E204, E112, E902)
responsestringYesHuman-readable error message
{
  "type": "object",
  "example": {
    "status": "ER",
    "errorCode": "E204",
    "response": "Invalid or expired token"
  },
  "required": [
    "status",
    "errorCode",
    "response"
  ],
  "properties": {
    "status": {
      "type": "string",
      "description": "Always \"ER\" for error responses",
      "enum": [
        "ER"
      ]
    },
    "errorCode": {
      "type": "string",
      "description": "Application-level error code (e.g. E204, E112, E902)"
    },
    "response": {
      "type": "string",
      "description": "Human-readable error message"
    }
  }
}

Example:

{
  "status": "ER",
  "errorCode": "E903",
  "response": "Beacon notification service is unavailable"
}