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
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.
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.
- POST request to https://<prognosis-web-server>/Prognosis/LoginApi
With body containing:
UserName=<username>&Password=<password>
- 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.
