This article is intended to provide a general guideline for setting up REST API views for prognosis alerts. It explains how REST API can be used to PULL prognosis alerts (tickets) and consume in any 3rd party ticketing system integration, e.g feeding into ServiceNow or OpsRamp. 

 

1.  Prognosis Alerts as REST API Datasets

 

This guide allows prognosis admins to configure and access prognosis alerts to be available in prognosis REST API, it includes: 

  • PROBSUM – Open Problems
  • PROBSUMC – Closed Problems

2.  High Level Design

image.png

3.  Persistent Views Setup

To setup REST API objects, it is advisable to setup the views as persistent. This helps with data immediately available for REST API instead of waiting for response from pql server and prognosis. To setup persistent views for open and closed problems, copy the below content into <prognosis>\WebUI\IIS\Dashboards\User\persistviewsUI_user.xml before the </views> tag.

 

<!-- Persistent Views for Open and Closed Problems -->
    <view name="Custom_User_PROBSUM_View">
      <query>
         SELECT
            META.NODE,
            *,
            META.NODE AS MonitoringNode
         FROM PROBSUM
       OPTION HISTORICAL ODD 5000
       WHERE OpenTime > Now() - 7 DAYS AND 
         (((RuleName NOT MATCHES 'PROGNOSIS*' OR RuleName IS NULL) AND ObjectType = 'Threshold') OR (AnalystName = 'WindowsAnalyst' OR ObjectType != 'Analyst')) AND 
         (RuleName NOT CONTAINS 'CapacityPlanning' OR RuleName IS NULL) AND 
         (RuleName NOT MATCHES REGEX '^Hidden' OR RuleName IS NULL) 
         NODE ALL
         EVERY 60 SECONDS
         TIMEOUT PERSISTENT LOCAL
      </query>
    </view>
    <view name="Custom_User_PROBSUMC_View">
      <query>
         SELECT
            META.NODE,
            *,
            META.NODE AS MonitoringNode
         FROM PROBSUMC
       OPTION HISTORICAL ODD 5000
       WHERE CloseTime > Now() - 7 DAYS AND 
         (((RuleName NOT MATCHES 'PROGNOSIS*' OR RuleName IS NULL) AND ObjectType = 'Threshold') OR (AnalystName = 'WindowsAnalyst' OR ObjectType != 'Analyst')) AND 
         (RuleName NOT CONTAINS 'CapacityPlanning' OR RuleName IS NULL) AND 
         (RuleName NOT MATCHES REGEX '^Hidden' OR RuleName IS NULL)
         NODE ALL
         EVERY 60 SECONDS
         TIMEOUT PERSISTENT LOCAL
      </query>
    </view>

 

 

Please note that any filtering we need to apply to reduce noisy alerts and/or prognosis internal alerts should be handled at this level, so that we only keep the alerts in memory that we are interested in. Besides alerts filtering, we keep upto 5000 alerts that are 7 or less days old.

4.  REST API Datasets Setup

After the persistent views are setup, we can now create the datasets fro REST API. To do so, copy the below contents in <Prognosis>\WebUI\IIS\Administration\Config\RestApiDataSets.xml  </dataSetCollection>  tag.

 

   <!—DataSets for Open and Closed Problems -->
      <dataSet>
    <id>OpenProblems</id>
    <query>Select * FROM Custom_User_PROBSUM_View WHERE OpenTime > DateAdd(Minute, -@checkinterval, Now())</query>
  </dataSet>
  <dataSet>
    <id>ClosedProblems</id>
    <query>Select * FROM Custom_User_PROBSUMC_View WHERE CloseTime > DateAdd(Minute, -@checkinterval, Now())</query>
  </dataSet>  

 

Please note that while most of filtering is applied on the views level, the rest query requires ‘checkinterval’ parameter to determine what result set to return. Based on initial poll, this can be a larger (a day or so) interval, and thereafter it can be same as the frequency of the poll, e.g 1 minute.

To get the views created, IrPrognosisSite needs to be restart within IIS Manager.image.png

 

Once that is done, the views should be available in WebUI. To test them out login to prognosis WebUI and access following URLs:

 

https://<prognosis-web-server>/Prognosis/rest/v1/data/OpenProblems?checkinterval=1

https://<prognosis-web-server>/Prognosis/rest/v1/data/ClosedProblems?checkinterval=1

 

5.  Authenticating programmatically against Prognosis

In order to access the REST API objects, user needs to be authenticated against prognosis. Once authenticated, the visibility of data is subject to Role Based Security (RBS). Here is how you can authenticate with username/password.

  1. POST request to https://<prognosis-web-server>/Prognosis/LoginApi

With body containing:

UserName=<username>&Password=<password>

  1. Authentication token is then stored in the cookie jar session and subsequent rest/v1/data queries should be able to poll rest objects.

Below is a sample javascript code to authenticate and access ‘OpenProblems’:

 

const request = require('request').defaults({jar:true});

var server = 'localhost',
   username = 'username',
   password = 'Password',
   dataset = 'OpenProblems';

console.log ('Logging into prognosis WebUI ...');
request.post({
   url: 'https://' + server + '/Prognosis/LoginApi',
   headers: {'content-type' : 'application/x-www-form-urlencoded'},
   method: 'POST',
   rejectUnauthorized: false,
   body: 'UserName=' + username + '&Password=' + password,
}, 
function(err, res, body) {
   console.log ('Logged in to prognosis WebUI');
   console.log ('Requesting REST Data for ' + dataset + ' ...');
   request({
      url: 'https://' + server + '/Prognosis/rest/v1/data/' + dataset,
      method: 'GET',
      rejectUnauthorized: false,
   }, function (err, res, data) {
      console.log ('Got REST Data for ' + dataset);
      console.log ('Done.');
   });
});

  

6.  Troubleshooting Dataset does not exist: <dataset name>

  • Dataset name is case sensitive, make sure you are using same case as in the <id> tag of rest xml file.
  • Verify that dataset exists in the xml file.
  • Verify that you have restarted IIS > IrPrognosisSite after modifying the xml file.
  • Verify that there is no syntax error in the query specified in the <query> tag of the dataset in xml.
  • Run the query speicified in xml manually using ..\irpqlcli "<query>" -r in command prompt at <server>\configuration directory.

Custom_User_PROBSUM_View or Custom_User_PROBSUMC_View views not found

  • Verify that views exists in the persistentviews_user.xml file.
  • Run the query speicified in xml manually using below in command prompt at <server>\configuration directory.

..\irpqlcli "SELECT * FROM Custom_User_PROBSUM_View" -r

  • STOP/DROP view

..\irpqlcli "STOP Custom_User_PROBSUM_View" -r

..\irpqlcli "DROP Custom_User_PROBSUM_View" -r

 

  • After STOP/DROP, just touch the xml file (by adding a space and removing e.g) and save for prognosis to create the views again.
  • Verify there is no syntax error in the query.
  • Try to manually run the query using pqlcli to make sure there is no syntax error.

Some data is missing?

  • Run the query manually to verify data is consistent between pqlcli and rest api.
  • Verify missing data is not because of RBS. If user accessing the rest objects doesn’t have access to particular customer’s data, it would be missing from the result set. Update the user to allow permission for those customers in WebUI > Admin.
1 Comment
05 Base Camper

Hello Shoaib_Dilawar, thank you so much for this post - very useful

1.  What is the "SECURITY" setup to use and limit who has access to invoke REST API call to prognosis webUI.

2. How to monitor who is making REST API call to Prognosis and how much traffic/interval etc..

 

We are starting to get more requests to export prognosis bulk data  to external other systems e.g. splunk however as you suggested the preference is using ODBC data collection to SQL instead of using REST API.  We also prefer to keep data local and utilize WebUI + an extractor to pull the data into prognosis instead of exporting the data out. anyway, REST API are very common/popular and we have advanced clients already starting to experiment and impacting WebUI console but we have no way to findout who and how to control this access. 

 

In some other cases there is good use of REST API for small data, e.g. sending alerts to ServiceNow but need to be done with best practice using above guide and perhaps a seperate WebUI than using the common console for general monitoring use...

 

thank you so much..John A.