Case Websockets

Getting started

To get started with consuming data from our websocket endpoint you need:

• A websocket client. That could be a browser or a commandline utility like websocat

• An Argus session or API Key

Once you have something like the above you can connect to the websocket. Here is a basic example:

websocat wss://api.mnemonic.no/cases/v2/case/updates -H "Argus-API-Key:my/api/key"

Usage and client requirements

Note

It is a conscious design choice that the websocket output does not contain any text data fields, only metadata.

This means that you will need to use a combination of the websocket and REST API to retrieve a complete representation of a case. A client should use the websocket endpoint to detect changes, and then fetch the actual data using the REST API.

To fetch the representation of the exact change, use the transaction ID and fetch the corresponding history transaction using the History API

Connection shutdown

The websocket connection may be disrupted, some common causes are:

• Network instability

• Rolling restart of servers

A client must handle connection shutdown gracefully. A client can use the cursor functionality to resume consuming data from its last consumed object. To achieve this a client should:

• Record the last successfully received cursor for every received message. A cursor is valid for 24 hours. The client will receive at least one update per hour (type=keepAlive) with an updated cursor.

• If connection is lost, then client should reconnect with the cursor as a query parameter. This will request the endpoint to resume from the cursor position, e.g websocat wss://api.mnemonic.no/cases/v2/case/updates?cursor=$cursor -H "Argus-API-Key:my/api/key"

• If the websocket endpoint refuses the provided cursor (e.g. the cursor is expired), the client should have a backup strategy:

  • Connecting to the live websocket (without cursor) to receive all further updates from now on

  • Fetching all previous states from a REST endpoint

Websocket data format

Objects emitted on the socket have the following format:

CaseUpdateWSMessage

Key	Type	Possible values	Description
cursor	String		The current cursor position
operation	String	See Operations in the History API	The case operation that triggered this message
timestamp	Number		Timestamp when the operation was executed, in milliseconds since epoch
transactionID	String		A reference to the transaction in the Case History API of the referenced case. See the case history documentation for more information about the data available in the history API, and how to use it.
viewID	String		To know if the websocket update comes from the changes invoked by the client itself, the message contains a viewID field which will be populated by clients that include the HTTP header Argus-Case-ViewID: someviewid. Each client should set a unique, random value for viewID upon start, and use/reuse this value for all requests to the case service. By comparing all websocket updates with this value, the client can determine if the update represents a change invoked by the client itself.
currentUserID	Number		Id of the user owning the websocket session
type	String	transaction, cursorInvalid, cursorExpired, invalidCase, invalidArguments, keepAlive	The type of websocket message. Type: “transaction” is the only message type that actually contains metadata for cases with case updates
case	Object		See CaseActivityWSModel below
events	Array		Array of changes in this transaction. See CaseChangeEventWSModel below

CaseActivityWSModel

Key	Type	Possible values	Description
id	Number		The id of the case. Can be used to query the REST API for more information
type	String	securityIncident, operationalIncident, informational	The type of case. Please note that case type can change
status	String	pendingCustomer, pendingSoc, pendingVendor, workingSoc, workingCustomer, pendingClose, closed	The case status
priority	String	low, medium, high, critical	The current priority of the case

CaseChangeEventWSModel

Key	Type	Possible values	Description
field	String	customerID, service, category, type, status, fieldAdded, fieldRemoved, priority, subject, description, setProperties, removeProperties, customerReference, accessMode, reporterID, assignedUserID, assignedTechID, setFlag, unsetFlag, addComment, addTag, addWatcher, addLink, updateWatcher, deleteWatcher, sentNotification, resetWorkflow, updateWorkflow, deleteWorkflow, enableVerbose, disableVerbose, customerDueTimestamp, techDueTimestamp, associatedEvent, enquiry	Identifying what has changed on the case.
object	Object		A simple object representation of the changed value, or null if not represented. Where returned, this is a minimal object intended for identifying the real object. Most fields on the object will not be included. See AbstractCaseChangeEventValueWSModel below.

AbstractCaseChangeEventValueWSModel

Key	Type	Possible values	Description
objectType	String	assignedUser, associatedEvent, enquiry, priority, status	The type of this object
subjectID	Number	Only for assignedUser and assignedTech	The id of the user
type	String	Only for associatedEvent. Valid values are RAW and AGGR.	The type of the associated event
timestamp	Number	Only for associatedEvent	The timestamp of the associated event
customerID	Number	Only for associatedEvent	The customerID of the associated event
eventID	String	Only for associatedEvent	The eventID of the associated event
id	String	Only for enquiry	The id of the linked enquiry
priority	String	Only for priority	The priority value set
status	String	Only for status	The status value set

Example:

{
  "cursor": "eyJwb2ludGVycyI6eyJDYXNlLlVwZGF0ZSI6eyIwIjp7Im9mZnNldCI6MTcxNywidGltZXN0YW1wIjoxNjQ2MDg0MTY0OTcyfX19fQ==",
  "operation": "updateCase",
  "timestamp": 1646084164133,
  "transactionID": "d30e8658-211d-4fb4-8f93-476b9463d74e",
  "viewID": "dcf9449a-81be-4b9a-8e95-b548eaac8cfa",
  "currentUserID": 1234,
  "type": "transaction",
  "case": {
    "id": 20797705,
    "type": "securityIncident",
    "status": "pendingSoc",
    "priority": "critical"
  },
  "events": [
    {
      "field": "status",
      "object": {
        "objectType": "priority",
        "priority": "medium"
      }
    }
  ]
}

Important

It is important to note that new fields, new object-types and new values for string enums can be introduced at any time. The client needs to be resilient against additive changes and accept unknown values. The following example code illustrates how a client can be specific about which operations a developer has accounted for:

switch (message.operation) {
  case "createCase":
    handleCreateCase();
    break;
  case "updateCase":
  case "deleteCase":
    // All other known operations
    break;
  default:
    // Log this so it can be detected and handled.
    Logger.getLogger.warn(
      `Unknown case operation identified. Operation: ${message.operation}`
    );
}

Available websocket endpoints

Case Update Websocket

The Case Update Websocket receives all updates whenever any case is created or updated, which the user has access to.

All entries in the “Activity” tab in cases will be emitted on this socket.

Endpoint

wss://api.mnemonic.no/cases/v2/case/updates

Parameters

Parameter	Comments
cursor	Resume websocket connection at the last known cursor position

Message types

• Messages with type transaction contain some change to the case. See Websocket data format above for the message format.

• If connecting to the endpoint with an invalid cursor, the endpoint will respond with type cursorInvalid and immediately close.

• If connecting to the endpoint with a cursor which has expired in the system message log, the endpoint will respond with type cursorExpired and immediately close.

Case Activity Websocket

The Case Activity Websocket receives updates whenever a single case is updated. Every registered transaction on the case will be emitted on this socket.

Endpoint

wss://api.mnemonic.no/cases/v2/case/{caseID}/activity

Parameters

Parameter	Comments
cursor	Resume websocket connection at the last known cursor position

Message types

• Messages with type transaction contain some change to the case. See Websocket data format above for the message format.

• If connecting to the endpoint with an invalid/inaccessible caseID, the endpoint will respond with a 403, 404 or 412 error. and immediately close.

• If connecting to the endpoint with an invalid cursor, the endpoint will respond with type cursorInvalid and immediately close.

• If connecting to the endpoint with a cursor which has expired in the system message log, the endpoint will respond with type cursorExpired and immediately close.

• The system will generate a message of type keepAlive every hour, to ensure that the client receives a valid cursor. Cursors are valid for 24 hours.