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

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:


ParameterInput
content-typeapplication/json
acceptapplication/json
authorizationauthToken <Auth Token issued by Remedy Single Sign-On or Atrium Single Sign-On>

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

AttributesDescription
dataType

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

subscriptionNameUnique 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-28-rdp1304\"">.
    The "condition": "severity EQUALS \"CRITICAL\"" syntax is used as a condition for an event.
    The cell condition should be declared before an event condition. See the sample mentioned below.
criteriasOne or more criteria used to select data. Specifying at least a single criteria is mandatory.

Sample input parameters in the JSON format are as follows:

Example 1
{
    "subscriptionName": "Prod_Critical_events",
    "criterias": [
        {
            "resourceType": "cell",
            "condition": "name EQUALS \"pncell_vm-w28-rds1304\"",
            "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-w28-rds1304\"",
			"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-w28-rds1304\"",
			"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-w28-rds1304\"",
			"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-w28-rds1304\"",
			"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="
	}
}

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

The following table provides information about the URL.

EntryDescription

http|https

Type of protocol to send the request. BMC Infrastructure Management web services support both HTTP and HTTPS protocols.

serverHost

Host name of the BMC 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.

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:


ParameterInput
content-typeapplication/json
acceptapplication/json
authorizationauthToken <Auth Token issued by Remedy Single Sign-On or Atrium Single Sign-On>

Response information of the Subscriptions REST API (POST method)

The response to the 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"
}

List Subscription REST API (GET method)

List 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

The following table provides information about the URL.

EntryDescription

http|https

Type of protocol to send the request. BMC Infrastructure Management web services support both HTTP and HTTPS protocols.

serverHost

Host name of the BMC 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.

subscriptionIDThe subscription identification returned by the stream/subscribe API.
You must specify the following parameters in the header of the web service request:


ParameterInput
content-typeapplication/json
acceptapplication/json
authorizationauthToken <Auth Token issued by Remedy Single Sign-On or Atrium Single Sign-On>

Response information of the Subscription REST API (GET method)

The response to the List 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-w28-rds1304\"",
          "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"
}
Was this page helpful? Yes No Submitting... Thank you

10 Comments

  1. What all operators are allowed in the condition?  The example only shows EQUALS.

     

    If you want NOT EQUALS, is it that, or is it NOT_EQUALS, etc?  If you want greater than, is it just GREATER THAN?  We need to have documentation of all supported condition operators.

     

    Charles

     

  2.  

  3.  

  4.  

  5.  

  6.  

    1.  

  7. As Charles said, we need more information on condition.

    I need for example "subclass_of" which fails as is.

    Guillaume

    1. Thanks Guillaume,

      I have started a discussion thread with the SMEs and will keep you updated.


      Hari

  8. Hello,

    I opened a case for using this API for a remote cell and the response I got is that the Publish-Subscribe REST Web Service is only capable of working with TSIM/BPPM pncell and not with any remote Cells but I don't see it mentioned anywhere in the documentation.

    .Also, if the cell name isn't really a condition that can be changed, why require it in the json at all. The cell name will always be the TSIM cell if the remote cells aren't permitted. Including the option in there makes it confusing.

    Thanks,

    Karan


© Copyright 2019 BMC Software, Inc.
Legal notices