Managing ephemeral external data in QueueMetrics

You can push and query short-lived key-value data from external systems (e.g. sensor readings, integration state, live metrics) via HTTP/HTTPS web services. Each attribute has an expiry time; expired values are still returned but flagged, so the client can decide how to display them.

Attributes are identified by a composite key of attribute name, queue and agent. The same attribute can hold independent values for different queues and agents, or be left unscoped (global) by omitting queue and agent.

There are two services:

  • insertEphemeralData.do — pushes (inserts or updates) a batch of attributes with a shared validity period

  • readEphemeralData.do — queries attributes by optional filters

Both are located relative to the base QM URL; so if QM’s main URL is at https://my.queuemetrics-live/somecustomer, the insert service will appear at https://my.queuemetrics-live/somecustomer/insertEphemeralData.do.

The endpoints accept both GET and POST requests. The payload is expressed as a JSON structure in the single parameter named data. When using GET, the data parameter must be URL-encoded.

Authentication and keys

The user must have the key ROBOT and one or both of the following keys:

  • EPHEMERAL_WRITE — required to insert or update data

  • EPHEMERAL_READ — required to read data back

In general, writers do not need read access, as the typical use case is a one-way push from an external system.

Response format

If all goes well, the response will be a JSON object with HTTP status 200:

{
  "response": "ok"
}

or, for read operations:

{
  "response": "ok",
  "attributes": [ ... ]
}

An error is indicated by an HTTP status code other than 200.

Data model

Insert request

An insert request contains a shared validity (in seconds) and a list of attributes to push. If an attribute with the same composite key already exists, its value and expiry are overwritten.

Field Required Description

validity

Yes

Time-to-live in seconds. Each attribute will expire this many seconds after insertion (e.g. 300 = 5 minutes).

attributes

Yes

Array of attributes to push (see below).

Read request

A read request contains optional filter lists. An empty or missing list means "don’t filter on that dimension" — i.e. return all values.

Field Required Description

attributes

No

List of attribute keys to match. If omitted or empty, all attribute keys are returned.

queues

No

List of queue IDs to match. If omitted or empty, all queues are returned (including unscoped).

agents

No

List of agent IDs to match. If omitted or empty, all agents are returned (including unscoped).

An empty payload {} returns all attributes currently stored.

Attribute object

The same structure is used for both input (insert) and output (read).

Field Required Description

attr

Yes

The attribute key, e.g. SENSOR_TEMP or SYSTEM_STATUS. The . (dot) character is not accepted in attribute keys and will cause the insert to be rejected — use _ or another separator instead.

queue

No

The queue this value is scoped to. Defaults to "" (unscoped / global) if omitted.

agent

No

The agent this value is scoped to. Defaults to "" (unscoped / global) if omitted.

value

Yes

The attribute value as a string, e.g. "23.5" or "online". Maximum 50 characters.

expired

—

Output only. true if the attribute has passed its expiry time, false otherwise. Not present in input.
Attribute keys must not contain the . (dot) character. An insert request containing a dotted key (e.g. SENSOR.TEMP) is rejected with a non-200 error; use an underscore or another separator (e.g. SENSOR_TEMP) instead. This restriction applies uniformly whether the data is pushed via this web service or via the internal admin UI.

The composite key for uniqueness is (attr, queue, agent). Pushing a value for an existing composite key overwrites the previous value and resets the expiry — like updating a temperature reading.

The value field is always a string. The wallboard will cast it to the appropriate data type for display — for example, an integer to show the number of waiting calls. If the value cannot be cast to the expected type (e.g. an unexpected string where a number is expected), the wallboard treats it the same as an expired value, usually displaying it grayed out.

A minimal attribute on input looks like:

{
  "attr": "SYSTEM_STATUS",
  "value": "online"
}

This implies queue="" and agent="" (unscoped).

Typical workflows

Push periodic measurements

An external system pushes sensor data every minute with a 5-minute validity. If a reading is not refreshed within 5 minutes, it will appear as expired.

curl -v --user robot:robotpwd \
  http://localhost:8080/qm/insertEphemeralData.do \
  -G --data-urlencode 'data={
    "validity": 300,
    "attributes": [
      {
        "attr": "SENSOR_TEMP",
        "queue": "Q1",
        "value": "23.5"
      },
      {
        "attr": "SENSOR_HUMIDITY",
        "queue": "Q1",
        "value": "65"
      }
    ]
  }'

Push agent-scoped status

An integration pushes per-agent status that expires after 10 minutes:

curl -v --user robot:robotpwd \
  http://localhost:8080/qm/insertEphemeralData.do \
  -G --data-urlencode 'data={
    "validity": 600,
    "attributes": [
      {
        "attr": "CRM_STATUS",
        "agent": "agent101",
        "value": "in-call"
      },
      {
        "attr": "CRM_STATUS",
        "agent": "agent102",
        "value": "available"
      }
    ]
  }'

Read all unscoped attributes

To retrieve all global (unscoped) attributes, filter on empty queue and agent:

curl -v --user robot:robotpwd \
  http://localhost:8080/qm/readEphemeralData.do \
  -G --data-urlencode 'data={
    "queues": [""],
    "agents": [""]
  }'

Read everything

An empty payload returns all stored attributes, regardless of scope:

curl -v --user robot:robotpwd \
  http://localhost:8080/qm/readEphemeralData.do \
  -G --data-urlencode 'data={}'

Service reference

Insert

Pushes a batch of attributes. Each attribute is inserted or updated (upserted) based on its composite key (attr, queue, agent).

Keys required: EPHEMERAL_WRITE and ROBOT

Input:

curl -v --user robot:robotpwd \
  http://localhost:8080/qm/insertEphemeralData.do \
  -G --data-urlencode 'data={
    "validity": 300,
    "attributes": [
      {
        "attr": "SENSOR_TEMP",
        "queue": "Q1",
        "agent": "",
        "value": "23.5"
      },
      {
        "attr": "SENSOR_HUMIDITY",
        "queue": "Q1",
        "value": "65"
      },
      {
        "attr": "SYSTEM_STATUS",
        "value": "online"
      }
    ]
  }'

Output:

{
  "response": "ok"
}

An error is indicated by an HTTP status code other than 200.

If an attribute with the same (attr, queue, agent) already exists, its value and expiry are silently overwritten.

Read

Retrieves attributes matching optional filters, ordered by attribute key, queue and agent.

Keys required: EPHEMERAL_READ and ROBOT

Input (with filters):

curl -v --user robot:robotpwd \
  http://localhost:8080/qm/readEphemeralData.do \
  -G --data-urlencode 'data={
    "attributes": ["SENSOR_TEMP", "SENSOR_HUMIDITY"],
    "queues": ["Q1"]
  }'

Input (no filters):

curl -v --user robot:robotpwd \
  http://localhost:8080/qm/readEphemeralData.do \
  -G --data-urlencode 'data={}'

Output:

{
  "response": "ok",
  "attributes": [
    {
      "attr": "SENSOR_HUMIDITY",
      "queue": "Q1",
      "agent": "",
      "value": "65",
      "expired": false
    },
    {
      "attr": "SENSOR_TEMP",
      "queue": "Q1",
      "agent": "",
      "value": "23.5",
      "expired": true
    }
  ]
}

Results are ordered alphabetically by attribute key, then queue, then agent. Expired attributes are included in the results with expired set to true. If no attributes match the filters, an empty array is returned.