blacklistDiscovery IDD

generic_mqtt & generic_mqtts

Overview

This page describes the generic_mqtt and generic_mqtts service interface of blacklistDiscovery which enables both Application and Core/Support systems to query the blacklist entries in force that apply to them, or check if a system is blacklisted. Note that a record is in force if it is ACTIVE and not expired. This service interface is implemented using protocol, encoding as stated in the following tables:

generic_mqtt

Profile type	type	Version
Transfer protocol	MQTT	3.1 and 3.1.1
Data encryption	N/A	-
Encoding	JSON	RFC 8259
Compression	N/A	-

generic_mqtts

Profile type	type	Version
Transfer protocol	MQTT	3.1 and 3.1.1
Data encryption	TLS	-
Encoding	JSON	RFC 8259
Compression	N/A	-

Hereby the Interface Design Description (IDD) is provided to the blacklistDiscovery - Service Description. For further details about how this service is meant to be used, please consult that document.

Interface Description

lookup

The requester can lookup for relevant entries that apply to them and are in force. The service operation request requires an MQTTRequestTemplate JSON encoded message in which the authentication is a proper identity info and the payload is empty. The requester name will be identified during authentication.

Topic: arrowhead/blacklist/lookup

{
  "traceId": "<trace-id>",
  "authentication":"<identity-info>",
  "responseTopic":"<response-topic>",
  "qosRequirement":"<0|1|2>"
}

The service operation responds with an MQTTResponseTemplate JSON encoded message in which the status code is 200 if called successfully. The response template payload is a BlacklistEntryListResponse.

{
  "status": 200,
  "traceId":"<trace-id>",
  "receiver":"<receiver-system-identifier>",
  "payload": {
    "entries": [
      {
        "systemName": "TemperatureProvider1",
        "createdBy": "Sysop",
        "createdAt": "2025-06-05T14:15:02Z",
        "updatedAt": "2025-06-05T14:15:02Z",
        "reason": "Needs further repair.",
        "active": true
      }
    ],
    "count": 1
  }
}

The error codes are 401 if the requester authentication was unsuccessful or 500 if an unexpected error happens. In these cases the response template payload is an ErrorResponse JSON.

{
  "status": 401,
  "traceId":"<trace-id>",
  "payload": {
    "errorMessage": "Invalid authentication info",
    "errorCode": 401,
    "exceptionType": "AUTH",
    "origin": "arrowhead/blacklist/lookup"
  }
}

check

The requester can check whether a system is on the blacklist. The service operation request requires an identity related header or certificate and the payload is a SystemName, which identifies the name of the system to check.

Topic: arrowhead/blacklist/check

{
  "traceId": "<trace-id>",
  "authentication":"<identity-info>",
  "responseTopic":"<response-topic>",
  "qosRequirement":"<0|1|2>"
  "payload": "AlertConsumer1"
}

The service operation responds with an MQTTResponseTemplate JSON encoded message in which the status code is 200 if called successfully. The response payload is a Boolean value which idicates if the system is blacklisted or not.

{
  "status": 200,
  "traceId":"<trace-id>",
  "receiver":"<receiver-system-identifier>",
  "payload": false
}

The error codes are 400 if the request is malformed, 401 if the requester authentication was unsuccessful, 403 if the requester has no permission and 500 if an unexpected error happens. In these cases the response template payload is an ErrorResponse JSON.

{
  "status": 400,
  "traceId": "<trace-id>",
  "receiver":"<receiver-system-identifier>",
  "payload": {
    "errorMessage": "The specified system name does not match the naming convention: AlertCon$umer1",
    "errorCode": 400,
    "exceptionType": "INVALID_PARAMETER",
    "origin": "arrowhead/blacklist/check"
  }
}