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 web service 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 Web-services-authentication.

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 web service request, you must specify the following parameters in the header of the web service request as follows:


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

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:

Example 1
{
   "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="
    }
}
Example 2
{
"subscriptionName": "mc_hosts_events",
"criterias": [
{
"resourceType": "cell",
"condition": "name EQUALS \"pncell_vm-1304\"",
"criterias": [
{
"resourceType": "event",kA
"condition": "mc_host CONTAINS \"clm-pun\""
}
]
}
],
"destination": {
"type": "REST",
"url": "http://<Thrid-Party-Subscribing-Client-FQDN>:8080/TestStreamingClient/notify",
"username": "admin",
"password": "YWRtaW4="
}
}
Example 3
{
"subscriptionName": "Not_Critical_events",
"criterias": [
{
"resourceType": "cell",
"condition": "name EQUALS \"pncell_vm-1304\"",
"criterias": [
{
"resourceType": "event",
"condition": "severity NOT_EQUALS \"CRITICAL\""
}
]
}
],
"destination": {
"type": "REST",
"url": "http:// <Thrid-Party-Subscribing-Client-FQDN>:8080/TestStreamingClient/notify",
"username": "admin",
"password": "YWRtaW4="
}
}
Example 4
{
"subscriptionName": "duration_events",
"criterias": [
{
"resourceType": "cell",
"condition": "name EQUALS \"pncell_vm-1304\"",
"criterias":[
{
"resourceType": "event",
"condition": "duration GREATER_OR_EQUALS \"10\""
}
]
}
],
"destination": {
"type": "REST",
"url": "http:// <Thrid-Party-Subscribing-Client-FQDN>:8080/TestStreamingClient/notify",
"username": "admin",
"password": "YWRtaW4="
}
}
Example 5
{
"subscriptionName": "Prod_Critical_events_list_filter",
"criterias": [
{
"resourceType": "cell",
"condition": "name EQUALS \"pncell_vm-1304\"",
"criterias": [
{
"resourceType": "event",
"condition": "severity LIST_CONTAINS \"MINOR\""
}
]
}
],
"destination": {
"type": "REST",
"url": "http:// <Thrid-Party-Subscribing-Client-FQDN>: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 web service 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 Web-services-authentication.

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 Web-services-authentication.

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

The following table provides information about the URL.

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 following parameters in the header of the web service request:


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 Web-services-authentication.

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

The following table provides information about the URL.

You must specify the following parameters in the header of the web service request:


Response information of the Get 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*