Using the Publish-Subscribe REST approach to receive events

The REST API is used to create a stream event subscription. The API will create the new event based on the criteria provided. Event-stream identifier is supported with query only.

Creating a stream event subscription

The REST API uses the POST method to create a stream event subscription. You must provide authentication credentials by using the login API before accessing the data. For information about the authentication process, see Authentication-for-the-Infrastructure-Management-REST-API.

URL to create a stream event subscription

The generic format of the URL to create a stream event subscription is as follows:

http|https://<serverHost>:<port>/bppmws/api/stream/subscribe?dataType=event

Example

http://bppmwsserver:80/bppmws/api/stream/subscribe?dataType=event

Input parameters in the JSON format to create a stream event subscription

You can provide the following parameters to create a stream event subscriptions in the JSON format along with the URL.

When you provide input parameters for any REST API request, you must specify the content-type parameter in the header of the REST API request as follows:

content-type application/json

Input parameters in the JSON format to create a stream event subscription

Attributes

Description

dataType

Type of data to be streamed. The supported type is event.

subscriptionName

Unique name for the subscription.

destination

The details of requested destination.
type: REST
url: URL to be used for REST destination.
username: User name to be used for REST
password: Base64 encoded password to be used for REST.

criteria

A criteria defines the following fields:

  • resourceType: The resource type specified for a criteria. The supported values are cell and event.
  • condition: The string representing the criteria. The <"slotname EQUALS \"value\""> syntax is used as a condition for cell. For example, <"name EQUALS \"pncell_vm-1304\"">.The "condition": "severity EQUALS \"CRITICAL\"" syntax is used as a condition for an event.
    The cell condition should be declared before an event condition.
    The following conditional syntaxes are supported:
    • OR
    • NOT
    • AND
    • EQUALS
    • EQUALSIGNORECASE

For information on the list of operators that can be used with this parameter, see Operator List.

See API Sample.

Limitation

You can only subscribe to the default Infrastructure Management cell. Subscribing to the remote cells or additional Infrastructure Management cells is not supported.

criterias

One or more criteria used to select data. Specifying at least a single criteria is mandatory.


Note

The following operators are applicable only to the criteria input parameter where the field resourceType equals event.

The first and second operands correspond to the following:

  • first operand: The input message string specified before the operator type
  • second operand: The comparison string value specified after the operator type

Operator list for Create a Stream Event Subscription API

Operator Type

Description

Example

ENDS_WITH

It returns true if the first operand ends with values specified in second operand, else it returns false. Both the operands are expected as string values.

{
   "subscriptionName": "CustSubs17Mayendswith",
   "criterias": [
       {
           "resourceType": "cell",
           "condition": "name EQUALS \"pncell_clm-pun-t30eo1\"",
           "criterias": [
               {
                   "resourceType": "event",
                   "condition": "severity EQUALS \"MAJOR\" AND msg ENDS_WITH \"perf\""
               }
                   
            ]
       }
    ],
   "destination": {
       "type": "REST",
       "url": "http://clm-pun-t30eo1:8080/TestStreamingClient/notify",
       "username": "admin",
   "password": "YWRtaW4="
   }
}

Sample: If msg ENDS_WITH perf then:

msg="sdhhperf" returns true

msg="dhjdhfj" returns false

ENDS_WITH_IGNORE_CASE

It is similar to ENDS_WITH operator type, however it ignores the case. It returns true if the first operand ends with values specified in the second operand irrespective of the case, else it returns false.

{
   "subscriptionName": "CustSubs17Mayendswithigcase",
   "criterias": [
       {
           "resourceType": "cell",
           "condition": "name EQUALS \"pncell_clm-pun-t30eo1\"",
           "criterias": [
               {
                   "resourceType": "event",
                   "condition": "severity EQUALS \"MAJOR\" AND msg ENDS_WITH_IGNORE_CASE \"Paris\""
               }
                   
            ]
       }
    ],
   "destination": {
       "type": "REST",
       "url": "http://clm-pun-t30eo1:8080/TestStreamingClient/notify",
       "username": "admin",
   "password": "YWRtaW4="
   }
}

Sample: If msg ENDS_WITH_IGNORE_CASE Paris then:

msg="HoustonPARIS" returns true

msg="HoustonParis" returns true

msg="ParisHouston" returns false

STARTS_WITH

It returns true if the first operand starts with values specified in the second operand, else it returns false. Both the operands are expected as string values.

{
   "subscriptionName": "CustSubs17May3",
   "criterias": [
       {
           "resourceType": "cell",
           "condition": "name EQUALS \"pncell_clm-pun-t30eo1\"",
           "criterias": [
               {
                   "resourceType": "event",
                   "condition": "severity EQUALS \"MAJOR\" AND msg STARTS_WITH \"perf\""
               }
                   
            ]
       }
    ],
   "destination": {
       "type": "REST",
       "url": "http://clm-pun-t30eo1:8080/TestStreamingClient/notify",
       "username": "admin",
   "password": "YWRtaW4="
   }
}

Sample: If msg STARTS_WITH perf then:

msg="perfsdhh" returns true

msg="dhjdhfj" returns false

STARTS_WITH_IGNORE_CASE

It is similar to STARTS_WITH operator type, however it ignores the case. It returns true if the first operand starts with values specified in the second operand irrespective of the case, else it returns false.

{
   "subscriptionName": "CustSubs17Maystartswithigcase",
   "criterias": [
       {
           "resourceType": "cell",
           "condition": "name EQUALS \"pncell_clm-pun-t30eo1\"",
           "criterias": [
               {
                   "resourceType": "event",
                   "condition": "severity EQUALS \"MAJOR\" AND msg STARTS_WITH_IGNORE_CASE \"Denver\""
               }
                   
            ]
       }
    ],
   "destination": {
       "type": "REST",
       "url": "http://clm-pun-t30eo1:8080/TestStreamingClient/notify",
       "username": "admin",
   "password": "YWRtaW4="
   }
}

Sample: If msg STARTS_WITH_IGNORE_CASE Denver then:

msg="DENVERhouston" returns true

msg="Denverhouston" returns true

msg="Houstondenver" returns false

CONTAINS

It returns true if the second operand value is present in the first operand, else it returns false. Both the operands are expected as string values.

{
   "subscriptionName": "CustSubs17May1",
   "criterias": [
       {
           "resourceType": "cell",
           "condition": "name EQUALS \"pncell_clm-pun-t30eo1\"",
           "criterias": [
               {
                   "resourceType": "event",
                   "condition": "severity EQUALS \"MAJOR\" AND msg CONTAINS \"perform\""
               }
                   
            ]
       }
    ],
   "destination": {
       "type": "REST",
       "url": "http://clm-pun-t30eo1:8080/TestStreamingClient/notify",
       "username": "admin",
   "password": "YWRtaW4="
   }
} 

Sample: If msg CONTAINS perform then:

msg="performsteps" returns true

msg="stepstoperform" returns true

msg="message" returns false

CONTAINS_IGNORECASE

It returns true if the second operand value is present in the first operand irrespective of the case, else it returns false. Both the operands are expected as string values.

{
   "subscriptionName": "CustSubs19Maycontainsigcase",
   "criterias": [
       {
           "resourceType": "cell",
           "condition": "name EQUALS \"pncell_clm-pun-t30eo1\"",
           "criterias": [
               {
                   "resourceType": "event",
                   "condition": "severity EQUALS \"MAJOR\" AND msg CONTAINS_IGNORECASE \"HousTon\""
               }
                   
            ]
       }
    ],
   "destination": {
       "type": "REST",
       "url": "http://clm-pun-t30eo1:8080/TestStreamingClient/notify",
       "username": "admin",
   "password": "YWRtaW4="
   }
}

Sample: If msg CONTAINS_IGNORECASE HousTon then:

msg="Check houston message" returns true

msg="HOUston" returns true

msg="test" returns false

NOT_EQUALS

It returns true if the first operand is not equal to value of the second operand, else it returns false. The values for the first and the second operand cannot be blank.

{
   "subscriptionName": "CustSubs19Maynotequals",
   "criterias": [
       {
           "resourceType": "cell",
           "condition": "name EQUALS \"pncell_clm-pun-t30eo1\"",
           "criterias": [
               {
                   "resourceType": "event",
                   "condition": "severity EQUALS \"INFO\" AND msg NOT_EQUALS \"firewall\""
               }
                   
            ]
       }
    ],
   "destination": {
       "type": "REST",
       "url": "http://clm-pun-t30eo1:8080/TestStreamingClient/notify",
       "username": "admin",
   "password": "YWRtaW4="
   }
}

Sample: If msg NOT_EQUALS firewall then:

msg="fireWall" returns true

msg="firewall" returns false

NOT_EQUALS_IGNORE_CASE

It returns true if the first operand is not equal to value of the second operand irrespective of the case, else it returns false. The values for the first and the second operand cannot be blank.

{
   "subscriptionName": "CustSubs19Maynotequalsigcase",
   "criterias": [
       {
           "resourceType": "cell",
           "condition": "name EQUALS \"pncell_clm-pun-t30eo1\"",
           "criterias": [
               {
                   "resourceType": "event",
                   "condition": "severity EQUALS \"MINOR\" AND msg NOT_EQUALS_IGNORE_CASE \"HelsinKI\""
               }
                   
            ]
       }
    ],
   "destination": {
       "type": "REST",
       "url": "http://clm-pun-t30eo1:8080/TestStreamingClient/notify",
       "username": "admin",
   "password": "YWRtaW4="
   }
}

Sample: If msg NOT_EQUALS_IGNORE_CASE HelsinKI then:

msg="test" returns true

msg="Helsinki" returns false

msg="HelsinKI" returns false

EQUALS

It returns true if the first operand is equal to value of the second operand, else it returns false.

{
   "subscriptionName": "CustSubs19Mayequals",
   "criterias": [
       {
           "resourceType": "cell",
           "condition": "name EQUALS \"pncell_clm-pun-t30eo1\"",
           "criterias": [
               {
                   "resourceType": "event",
                   "condition": "severity EQUALS \"MAJOR\" AND msg EQUALS \"York\""
               }
                   
            ]
       }
    ],
   "destination": {
       "type": "REST",
       "url": "http://clm-pun-t30eo1:8080/TestStreamingClient/notify",
       "username": "admin",
   "password": "YWRtaW4="
   }
}

Sample: If msg EQUALS York then:

msg="York" returns true

msg="YORK" returns false

EQUALS_IGNORE_CASE

It returns true if the first operand is equal to value of the second operand irrespective of the case, else it returns false.

{
   "subscriptionName": "CustSubs19Mayequalsigcase",
   "criterias": [
       {
           "resourceType": "cell",
           "condition": "name EQUALS \"pncell_clm-pun-t30eo1\"",
           "criterias": [
               {
                   "resourceType": "event",
                   "condition": "severity EQUALS \"MAJOR\" AND msg EQUALS_IGNORE_CASE \"YorkSHire\""
               }
                   
            ]
       }
    ],
   "destination": {
       "type": "REST",
       "url": "http://clm-pun-t30eo1:8080/TestStreamingClient/notify",
       "username": "admin",
   "password": "YWRtaW4="
   }
}

Sample: If msg EQUALS_IGNORE_CASE YorkSHire then:

msg="yorkshire" returns true

msg="This is yorkshire" returns false

LIST_CONTAINS

It is used for LIST_OF data type in a cell. It returns true if the first operand(which is a list) has a value which is exactly equal to second operand, else it returns false.

{
   "subscriptionName": "CustSubs21Maylistcontains",
   "criterias": [
       {
           "resourceType": "cell",
           "condition": "name EQUALS \"pncell_clm-pun-t30eo1\"",
           "criterias": [
               {
                   "resourceType": "event",
                   "condition": "severity EQUALS \"MAJOR\" AND ii_strlist LIST_CONTAINS \"ben\""
               }
                   
            ]
       }
    ],
   "destination": {
       "type": "REST",
       "url": "http://clm-pun-t30eo1:8080/TestStreamingClient/notify",
       "username": "admin",
   "password": "YWRtaW4="
   }
}

Sample: If ii_strlist LIST_CONTAINS ben then:

ii_strlist=["abc","ben"] returns true

ii_strlist=["abc","tubenha"] returns false

ii_strlist=["abc","boa"] returns false

SMALLER_THAN

It returns true if the first operand is smaller than the value of the second operand, else it returns false. It is applicable to integer and string data types. 

{
   "subscriptionName": "CustSubs21Maysmallerthan",
   "criterias": [
       {
           "resourceType": "cell",
           "condition": "name EQUALS \"pncell_clm-pun-t30eo1\"",
           "criterias": [
               {
                   "resourceType": "event",
                   "condition": "severity EQUALS \"WARNING\" AND msg SMALLER_THAN \"def\""
               }
                   
            ]
       }
    ],
   "destination": {
       "type": "REST",
       "url": "http://clm-pun-t30eo1:8080/TestStreamingClient/notify",
       "username": "admin",
   "password": "YWRtaW4="
   }
}

Sample: If msg SMALLER_THAN def then:

msg="aaa" returns true

msg="ghi" returns false

SMALLER_OR_EQUALS

It returns true if the first operand is smaller than or equal to the value of the second operand, else it returns false. It is applicable to integer and string data types. 

{
   "subscriptionName": "CustSubs21Maysmallerequals",
   "criterias": [
       {
           "resourceType": "cell",
           "condition": "name EQUALS \"pncell_clm-pun-t30eo1\"",
           "criterias": [
               {
                   "resourceType": "event",
                   "condition": "severity EQUALS \"WARNING\" AND msg SMALLER_OR_EQUALS \"pqr\""
               }
                   
            ]
       }
    ],
   "destination": {
       "type": "REST",
       "url": "http://clm-pun-t30eo1:8080/TestStreamingClient/notify",
       "username": "admin",
   "password": "YWRtaW4="
   }
}

Sample: If msg SMALLER_OR_EQUALS pqr then:

msg="pqr" returns true

msg="abc" returns true

msg="rst" returns false

GREATER_THAN

It returns true if the first operand is greater than the value of the second operand, else it returns false. It is applicable to integer and string data types. 

{
   "subscriptionName": "CustSubs21Maygreaterthan",
   "criterias": [
       {
           "resourceType": "cell",
           "condition": "name EQUALS \"pncell_clm-pun-t30eo1\"",
           "criterias": [
               {
                   "resourceType": "event",
                   "condition": "CLASS EQUALS \"IITEST_EV\" AND severity EQUALS \"WARNING\" AND ii_num GREATER_THAN \"10\""
               }
                   
            ]
       }
    ],
   "destination": {
       "type": "REST",
       "url": "http://clm-pun-t30eo1:8080/TestStreamingClient/notify",
       "username": "admin",
   "password": "YWRtaW4="
   }
}

Sample: If ii_num GREATER_THAN 10 then:

ii_num=11 returns true

ii_num=8 returns false

GREATER_OR_EQUALS

It returns true if the first operand is greater than or equal to the value of the second operand, else it returns false. It is applicable to integer and string data types. 

{
   "subscriptionName": "CustSubs21Maygreaterthanequals",
   "criterias": [
       {
           "resourceType": "cell",
           "condition": "name EQUALS \"pncell_clm-pun-t30eo1\"",
           "criterias": [
               {
                   "resourceType": "event",
                   "condition": "severity EQUALS \"WARNING\" AND msg GREATER_OR_EQUALS \"abc\""
               }
                   
            ]
       }
    ],
   "destination": {
       "type": "REST",
       "url": "http://clm-pun-t30eo1:8080/TestStreamingClient/notify",
       "username": "admin",
   "password": "YWRtaW4="
   }
}

Sample: If msg GREATER_OR_EQUALS abc then:

msg="aqw" returns true

msg="abc" returns true

msg="aaa" returns false


Sample input parameters in the JSON format are as follows:

{
   "subscriptionName": "Prod_Critical_events",
   "criterias": [
        {
           "resourceType": "cell",
           "condition": "name EQUALS \"pncell_vm-1304\"",
           "criterias": [
                {
                   "resourceType": "event",
                   "condition": "severity EQUALS \"CRITICAL\""
                }
            ]
        }
    ],
   "destination": {
       "type": "REST",
       "url": "http://{HOSTNAME}:8080/TestStreamingClient/notify",
       "username": "admin",
   "password": "YWRtaW4="
    }
}

Sample event data posted to the destination URL specified in the create stream event subscription request

Sample event data
{   "type":"EVENT",
  "data":{
     "mc_tool_address":"192.168.1.1",
     "mc_origin_sev":"",
     "mc_propagations":"[]",
     "itsm_manufacturer":"",
     "mc_parameter_threshold":"",
     "mc_modhist":"['pncell_clm-pun-t30eo1']",
     "itsm_location":"",
     "mc_origin_key":"",
     "mc_object_owner":"",
     "mc_tool_time":"1592978411",
     "mc_smc_impact":"NOT_ELECTED",
     "mc_cause":"0",
     "mc_bad_slot_names":"[]",
     "mc_host_address":"192.168.1.1",
     "date_reception":"1592978411",
     "mc_using_organization_id":"",
     "mc_tool_id":"",
     "event_handle":"217151",
     "mc_event_model_version":"1.1.00",
     "mc_associations":"[]",
     "mc_abstraction":"[]",
     "status":"OPEN",
     "mc_relationships":"0/0",
     "mc_smc_type":"",
     "mc_object_uri":"",
     "mc_timeout":"0",
     "mc_location":"Unknown",
     "mc_origin_class":"",
     "mc_client_address":"192.168.1.1",
     "mc_long_msg":"",
     "mc_tool_key":"",
     "mc_tool_rule":"",
     "pn_device_name":"",
     "mc_tool_sev":"",
     "mc_smc_causes":"[]",
     "itsm_model_version":"",
     "mc_smc_effects":"[]",
     "mc_tool_uri":"",
     "mc_collectors":"['1.1', '3.1.1', '4.1', '5.1']",
     "mc_history":"['pncell_clm-pun-t30eo1:217151']",
     "pn_detail_diag_count":"0",
     "mc_abstracted":"[]",
     "mc_origin":"",
     "mc_date_modification":"1592978411",
     "mc_event_subcategory":"OTHER",
     "mc_using_organization":"",
     "mc_host_class":"",
     "mc_object_class":"",
     "mc_bad_slot_values":"[]",
     "itsm_incident_id":"",
     "date":"20200624113011.000000+330",
     "mc_original_priority":"PRIORITY_5",
     "msg":"test message2 24 june ",
     "mc_service":"",
     "itsm_type":"",
     "mc_tool_class":"",
     "mc_smc_id":"",
     "repeat_count":"0",
     "CLASS":"EVENT",
     "mc_parameter_value":"",
     "mc_owner":"",
     "mc_parameter":"",
     "mc_parameter_unit":"",
     "mc_priority":"PRIORITY_5",
     "mc_account":"",
     "itsm_category":"",
     "mc_notes":"[]",
     "mc_object":"",
     "mc_host_id":"0",
     "adapter_host":"",
     "mc_incident_report_time":"1592978411",
     "mc_effects":"[]",
     "mc_operations":"[]",
     "mc_smc_priority":"0",
     "mc_original_severity":"CRITICAL",
     "itsm_item":"",
     "mc_local_reception_time":"1592978411",
     "mc_event_relations":"[]",
     "mc_tool":"",
     "itsm_product_name":"",
     "duration":"0",
     "pn_detail_diag":"0",
     "administrator":"",
     "mc_host":"clm-pun-t30eo1",
     "mc_smc_alias":"",
     "mc_event_category":"",
     "itsm_company":"",
     "mc_ueid":"mc.pncell_clm-pun-t30eo1.1ef2ebeb.0",
     "mc_arrival_time":"1592978411",
     "itsm_operational_category3":"",
     "itsm_operational_category2":"",
     "itsm_operational_category1":"",
     "severity":"CRITICAL",
     "mc_notification_history":"[]",
     "itsm_incident_status":"",
     "mc_tool_suggestion":"",
     "mc_action_count":"0",
     "mc_incident_time":"0",
     "mc_relation_source":"",
     "mc_acl":"[]"

  },
  "action":"create",
  "subscriptionId":"47e6d129-0797-4b4f-aeb6-4e0128ac17fa"
}

JSON response to the create API

A sample JSON response is as follows:

{
   "response": [
       {"subscriptionId": "e6a9bb54-da25-102b-9a03-2db401e887ec"}
    ],
   "statusCode": "200",
   "statusMsg": "OK",
   "responseTimeStamp": "2012-06-20T08:36:24"
}

Deleting a stream event subscription

The REST API uses the DELETE method to unsubscribe a stream event subscription. You must provide authentication credentials by using the login API before accessing the data. For information about the authentication process, see Authentication-for-the-Infrastructure-Management-REST-API.

URL to delete a stream event subscription

The generic format of the URL to delete a stream event subscription is as follows:

http|https://<serverHost>:<port>/bppmws/api/stream/<subscriptionID>/unsubscribe

Example

http://bppmwsserver:80/bppmws/api/stream/<subscriptionID>/unsubscribe

JSON response

A sample JSON response is as follows:

{
   "response": [
       {"subscriptionId": ["e6a9bb54-da25-102b-9a03-2db401e887ec"]}

    ],
   "statusCode": "200",
       "statusMsg": "OK",
       "responseTimeStamp": "2013-06-20T08:36:24"
}

List all Subscriptions REST API (POST method)

List all Subscriptions REST API (POST method) is used to list all the stream event subscriptions specified in the URL.

You must provide authentication credentials by using the login API before accessing the data. For information about authentication, see Authentication-for-the-Infrastructure-Management-REST-API.

URL to access the Subscriptions REST API (POST method)

The generic format of the URL is as follows:

http|https://<serverHost>:<port>/bppmws/api/stream/list

Example

http://bppmwsserver:80/bppmws/api/stream/list

Input parameters in the JSON format to list all stream event Subscriptions

You must provide a blank {} JSON body as POST body. In addition, you must specify the content-type parameter in the header of the REST API request as follows:

content-type application/json

Entry

Description

http|https

Type of protocol to send the request. Infrastructure Management REST APIs support both HTTP and HTTPS protocols.

serverHost

Host name of the Infrastructure Management Server

port

Port number through which communication is established. The default port number is 80 if you use the HTTP protocol and 443 if you use the HTTPS protocol.

Response information of the List Subscriptions REST API (POST method)

The response to the List Subscriptions REST API (POST method) depends on the query parameters that you pass.

A sample JSON response is as follows:

{
   "response": [
       {"subscriptionId": ["e6a9bb54-da25-102b-9a03-2db401e887ec"]},
               {"subscriptionId": ["f6a9bb54-da25-102b-9a03-2db401e887ec"]},
               {"subscriptionId": ["g6a9bb54-da25-102b-9a03-2db401e887ec"]}
    ],
   "statusCode": "200",
       "statusMsg": "OK",
       "responseTimeStamp": "2013-06-20T08:36:24"
}

Get Subscription REST API (GET method)

Get Subscription REST API (GET method) is used to get details about the stream event subscription specified in the URL. It uses the subscriptionID to get the details.

You must provide authentication credentials by using the login API before accessing the data. For information about authentication, see Authentication-for-the-Infrastructure-Management-REST-API.

URL to access the Subscription REST API (GET method)

The generic format of the URL is as follows:

http|https://<serverHost>:<port>/bppmws/api/stream/<subscriptionID>/list

Example

http://bppmwsserver:80/bppmws/api/stream/<{{code language="none"}}
subscriptionID
{{/code}}>/list

Entry

Description

http|https

Type of protocol to send the request. Infrastructure Management REST APIs support both HTTP and HTTPS protocols.

serverHost

Host name of the Infrastructure Management Server

port

Port number through which communication is established. The default port number is 80 if you use the HTTP protocol and 443 if you use the HTTPS protocol.

subscriptionID

The subscription identification returned by the stream/subscribe API.

Response information of the Subscription REST API (GET method)

The response to the Get Subscription REST API (GET method) depends on the query parameters that you pass.

A sample JSON response is as follows:

{
 "response": [
    {
     "subscriptionName": "Prod_Critical_events",
     "criterias": [
        {
         "resourceType": "cell",
         "condition": "name EQUALS \"pncell_vm-1304\"",
         "criterias": [
            {
             "resourceType": "event",
             "condition": "severity EQUALS \"CRITICAL\""
            }
          ]
        }
      ],
     "destination": {
       "type": "REST",
       "url": "http://{HOSTNAME}:8080/TestStreamingClient/notify",
       "username": "admin",
   "password": "YWRtaW4="
      }
    }
  ],
 "statusCode": "200",
 "statusMsg": "OK",
 "responseTimeStamp": "2013-06-20T08:36:24"
}

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*