Skip to main content

POST – Create a subscription

Create a subscription for Redfish service to send event to subscriber.

Request URL​

POST https://<BMC_IPADDR>/redfish/v1/EventService/Subscriptions

Request body​

FieldTypeDescription

Destination

String

[Mandatory]This property shall contain a URI to the destination where the events will be sent.

HTTP/HTTPS URI if Protocol is Redfish;

RFC1157-defined URI if Protocol is SNMPv1;

RFC3411 and RFC3418 defined URI if Protocol is SNMPv3;

RFC5321-defined SMTP URI if Protocol is SMTP.

Context

String[Mandatory]A client-supplied string that is stored with the event destination subscription.

Protocol

StringThe support protocols are “Redfish”, “SMTP”, “SNMPv1” and “SNMPv3”.

RegistryPrefixes

Array

Item: string

Item count: maps to members under the resource /redfish/v1/Registries

 

RegistryPrefixes[N]

StringMaps to members under the resource /redfish/v1/Registries

Response body​

It responds the created subscription resource, refer the response body of Event subscription with GET method.

Status code​

HTTP Status CodeError Message ID
201Created
400BadRequest, PropertyValueNotInList
500InternalError

Example​

Create Redfish protocol subscription

The following example is POST body:

{
    "Protocol": "Redfish",
    "Context": "Test_Context",
    "Destination": "https://192.168.0.2:443",
    "RegistryPrefixes": [
        "EventRegistry"
    ]
}

The following example JSON response is returned:

{
   "SubscriptionType" : "RedfishEvent",
   "HttpHeaders" : [],
   "RegistryPrefixes" : [
      "EventRegistry"
   ],
   "EventFormatType" : "Event",
   "OriginResources@odata.count" : 0,
   "OriginResources" : [],
   "Id" : "3A048D0E",
   "Destination" : "https://192.168.0.2:443",
   "Context" : "Test_Context",
   "MessageIds" : [],
   "SubordinateResources" : null,
   "@odata.id" : "/redfish/v1/EventService/Subscriptions/3A048D0E",
   "@odata.etag" : "\"1575571584025\"",
   "@odata.type" : "#EventDestination.v1_5_0.EventDestination",
   "Protocol" : "Redfish",
   "Description" : "This resource represents the target of an event subscription, including the types of events subscribed and context to provide to the target in the Event payload.",
   "Name" : "Destination",
   "ResourceTypes" : []
}

Create SMTP protocol subscription

The following example is POST body:

{
    “Context”: “SMTP user”,
    "Destination": "mailto:userid@lenovo.com",
    "Protocol": "SMTP"
}

The following example JSON response is returned:

{
    "Protocol": "SMTP",
    "Description": "This resource represents an event destination for a Redfish implementation.",
    "EventFormatType": "Event",
    "Id": "REST-SMTP-1",
    "Status": {
        "State": "Enabled"
    },
    "Context": "SMTP user",
    "@odata.type": "#EventDestination.v1_11_0.EventDestination",
    "@odata.id": "/redfish/v1/EventService/Subscriptions/REST-SMTP-1",
    "@odata.etag": "\"363737e9a52729657ae\"",
    "Name": "REST-SMTP-1",
    "Destination": "mailto:userid@lenovo.com",
    "SubscriptionType": "RedfishEvent"
}

Create SNMPv1 trap subscription

The following example is POST body:

{
    "Destination": "snmp://10.10.10.10",
    "Protocol": "SNMPv1",
     "SNMP": {
        "TrapCommunity": "test"
    }
}

The following example JSON response is returned:

{
    "Protocol": "SNMPv1",
    "Id": "REST-SNMPv1-1",
    "SNMP": {
        "TrapCommunity": "test"
    },
    "@odata.type": "#EventDestination.v1_8_0.EventDestination",
    "@odata.id": "/redfish/v1/EventService/Subscriptions/REST-SNMPv1-1",
    "Destination": "snmp://10.10.10.10",
    "Description": "This resource represents an event destination for a Redfish implementation.",
    "Context": "",
    "Name": "REST-SNMPv1-1",
    "Status": {
        "State": "Disabled"
    },
    "@odata.etag": "\"38906ed3cd672966db8\"",
    "SubscriptionType": "SNMPTrap",
    "EventFormatType": "Event"
}

Note that if the “State” in the response is “Disabled”, you would need to enable the SNMPv1 trap in /redfish/v1/Managers/1/NetworkProtocol /Oem/Lenovo/SNMP.

Create SNMPv3 trap subscription

The following example is POST body:

{
    "Destination": "snmp://test@10.10.10.10",
    "Protocol": "SNMPv3"
}

The following example JSON response is returned:

{
    "Protocol": "SNMPv3",
    "Id": "REST-SNMPv3-2",
    "SubscriptionType": "SNMPTrap",
    "@odata.type": "#EventDestination.v1_8_0.EventDestination",
    "@odata.id": "/redfish/v1/EventService/Subscriptions/REST-SNMPv3-2",
    "Destination": "snmp://test@10.10.10.10",
    "Description": "This resource represents an event destination for a Redfish implementation.",
    "Context": "",
    "Name": "test",
    "Status": {
        "State": "Disabled"
    },
    "SNMP": {
        "TrapCommunity": null
    },
    "@odata.etag": "\"3b17f6a279c82667a00\"",
    "EventFormatType": "Event"
}

Note
If the “State” in the response is “Disabled”, you would need to enable the SNMPv1 trap in /redfish/v1/Managers/1/NetworkProtocol /Oem/Lenovo/SNMP.

Create SNMPv2c trap subscription

The following example is POST body:

{
    "Destination": "snmp://10.10.10.10",
    "Protocol": "SNMPv2c",
    "SNMP": {
        "TrapCommunity": "test"
    }
}

The following example JSON response is returned:

{
    "Description": "This resource represents an event destination for a Redfish implementation.",
    "Id": "REST-SNMPv2c-2",
    "Name": "REST-SNMPv2c-2",
    "@odata.type": "#EventDestination.v1_12_0.EventDestination",
    "@odata.id": "/redfish/v1/EventService/Subscriptions/REST-SNMPv2c-2",
    "@odata.context": "/redfish/v1/$metadata#EventDestination.EventDestination",
    "Protocol": "SNMPv2c",
    "@odata.etag": "\"3e29269e00cd2a26e2e\"",
    "Context": "",
    "Destination": "snmp://10.10.10.10",
    "EventFormatType": "Event",
    "SubscriptionType": "SNMPTrap",
    "SNMP": {
        "TrapCommunity": "test"
    },
    "Status": {
        "State": "Enabled"
    },
    "@Message.ExtendedInfo": [
        {
            "Resolution": "If failed, retry before meeting the requirement of the security mode.",
            "Message": "The value \"snmp://10.10.10.10\" for the property Destination is not recommanded by current security mode Standard.",
            "@odata.type": "#Message.v1_1_2.Message",
            "MessageArgs": [
                "\"snmp://10.10.10.10\"",
                "Destination",
                "Standard"
            ],
            "MessageId": "LenovoExtendedWarning.1.0.NotRecommandedOperation",
            "MessageSeverity": "Warning"
        }
    ]
}

Note
For SNMPv3, the format shall be consistent with RFC4088: “snmp://<user>@<host>”. If format is incorrect, the error PropertyValueConflict is returned.

Create SNMPv3 trap subscription

The following example is POST body:

{
    "Destination": "snmp://test@10.10.10.10",
    "Protocol": "SNMPv3"
}

The following example JSON response is returned:

{
    "Protocol": "SNMPv3",
    "Id": "REST-SNMPv3-2",
    "SubscriptionType": "SNMPTrap",
    "@odata.type": "#EventDestination.v1_8_0.EventDestination",
    "@odata.id": "/redfish/v1/EventService/Subscriptions/REST-SNMPv3-2",
    "Destination": "snmp://test@10.10.10.10",
    "Description": "This resource represents an event destination for a Redfish implementation.",
    "Context": "",
    "Name": "test",
    "Status": {
        "State": "Disabled"
    },
    "SNMP": {
        "TrapCommunity": null
    },
    "@odata.etag": "\"3b17f6a279c82667a00\"",
    "EventFormatType": "Event"
}

Note
If the “State” in the response is “Disabled”, you would need to enable the SNMPv3 trap in /redfish/v1/Managers/1/NetworkProtocol /Oem/Lenovo/SNMP.