Table of Contents

Subscribing to Pega Predictive Diagnostic Cloud notifications by using a REST API

Pega Predictive Diagnostic Cloud™ (PDC) identifies important events that occur in your Pega Platform™ applications. The best way to be informed about these events is to configure email and SMS notifications to be sent to the appropriate recipients when these events occur. If recipients are unable to receive the standard PDC messages, for example, because of their network settings, you can configure PDC to store event-based notifications, and then configure an external application to request these notifications by using the GET method through a REST API.

Before accessing notifications that PDC stores, you must enable the Notification API in PDC, subscribe to notifications with the Notification API method, and then configure the external application with the credentials that PDC provides.

Enabling the Notification API

  1. Log in to PDC as a manager.
  2. In the header, click the Properties icon, and then select Integrations > APIs.
  3. In the Available APIs section, turn on the Status switch.
    The Notification API method appears in the Manage notifications window. For more information, see Managing notifications in Pega Predictive Diagnostic Cloud. After you create a new notification with the Notification API method, PDC stores the notifications so that you can use the API to retrieve them.

Configuring an external application

The Notification API supports OAuth 2.0 authentication. To configure an external application to retrieve the notifications that PDC has stored, obtain an access token by using the authentication credentials that PDC provides.

This example uses Postman v7.23.0 as the REST client.
  1. In the header of PDC, click the Properties icon, and then select Integrations > APIs.
  2. On the Configured APIs list, click Notification API.
    All of the credentials that are required to configure the external application are displayed at the top of the Notification API Details window.
  3. Use the Copy to clipboard icons to copy the following credentials:
    • Endpoint URL
    • Access token endpoint
    • Authorization endpoint
    • Token revocation endpoint
    • Client ID
    • Client secret
    • Username
    • Password
    Accessing authentication credentials for API integration
    "Accessing authentication credentials for API integration"
    Accessing authentication credentials for API integration
  4. Open Postman.
  5. In the header of Postman, click New and then in the Create New tab, click Request.
  6. In the Save request dialog, enter a name for the request, for example, Notification API, and then select a collection or folder to save the request in, for example, APIs.
  7. Click Save to Notification API.
  8. In the list of methods, select GET and then, in the Enter request URL field, enter the endpoint URL that you obtained in step 3, for example,
    https://pdc-central.pegacloud.io/prweb/PRRestService/5xLsHgqamz8B3N84WHSChhM8itHxUzfv*/PDCNotificationAPI/v1/PDCNotifications/{cluster_name}
    In the request URL, replace {cluster_name} with the name of your system, for example, uPlusTelco-prod.
    The following figure presents an example GET request URL:
    Entering a GET request in Postman
    "Entering a GET request in Postman"
    Entering a GET request in Postman
  9. In the Authorization tab, in the TYPE list, select OAuth 2.0.
  10. Click Get New Access Token, and then complete the following fields:
    • Token Name – Enter the name that you want to use for your token, for example, NewToken.
    • Grant Type – Select Password Credentials.
    • Access Token URL – Enter the access token endpoint URL that you obtained in step 3, for example, https://pdc-central.pegacloud.io/prweb/PRRestService/5xLsHgqamz8B3N84WHSChhM8itHxUzfv*/oauth2/v1/token
    • Username – Enter the username that you obtained in step 3, for example, PDCServiceAPI.
    • Password – Enter the password that you obtained in step 3, for example, rules.
    • Client ID – Enter the client ID that you obtained in step 3, for example, 47632981754497104158.
    • Client Secret – Enter the client secret that you obtained in step 3, for example, A313962FCF95A3A9D313C6D73D7A54BB.
    • Client Authentication – Select Send as Basic Auth header.
    The following figure presents example token configuration:
    Getting a new access token in Postman
    "The Get New Access dialog in Postman with an example configuration"
    Getting a new access token in Postman
  11. Click Request Token.
    The details about your new token are displayed.
  12. Click Use Token.
    Applying an access token in Postman
    "The Manage Access Tokens dialog in Postman with the newly added token"
    Applying an access token in Postman
  13. Click Send.
    The following figure presents an example response to a request:
    An example response to a GET request
    "An response to a GET request in Postman"
    An example response to a GET request

    For more examples of responses linked to specific notifications, see Examples of the API response structure.

For more information about configuring the integration in an external application, see the online documentation for the application that you use.

Parameters for API calls

You can pass the following input parameters with calls to the Notification API:

Parameter Description

ClusterName

(mandatory)

The name of the cluster or system.

Status

(optional)

This variable has two options:

  • 0 – Provide only notifications that have not been fetched before.
  • 1 – Provide all notifications from the given time range, regardless of whether they have been fetched before.

The default value is 0.

StartTime

(optional)

The earliest time from which you want to receive notifications, in the following format: 20191022T082559.733 GMT.

If you do not pass this value, you receive all notifications until the EndTime.

EndTime

(optional)

The latest time from which you want to receive notifications, in the following format: 20191022T082559.733 GMT.

If you do not pass this value, the current time is used.

Examples of the API request structure

The following URLs are examples of properly formatted API calls for the following actions:

  • Get all notifications for a system named Pega123:
    https://10.225.93.51:8443/prweb/PRRestService/beEBp4uRVTogorRwSwWqbO83nTrERiPE2-uo6mPqVLM(*/PDCNotificationAPI/v1/PDCNotifications/ Pega123
  • Get all notifications for a system named Pega123 within the specified time range:
    https://10.225.93.51:8443/prweb/PRRestService/beEBp4uRVTogorRwSwWqbO83nTrERiPE2-uo6mPqVLM(*/PDCNotificationAPI/v1/PDCNotifications/ Pega123?StartTime=20200319T082559.733 GMT&EndTime=20200320T082559.733 GMT&Status=1

The following figure presents passing input parameters in a request URL:

Passing input parameters in a GET query by using the Query Params feature in Postman
"Passing three example input parameters in a GET query by using the Query Params feature in Postman"
Passing input parameters in a GET query by using the Query Params feature in Postman

Response codes

The Notification API sends the following response messages:

Code Description
200 OK. Successfully executed.
200 There is no result in the given time range.
400 Cluster Name should not be blank.
400 Cluster Name does not exist.
400 fetchedstatus value should be 0 or 1.
400 The start time is not in valid date time format like 20191002T082557.733 GMT.
400 The end time is not in valid date time format like 20191002T082557.733 GMT.
400 End time should be greater than start time.
401 Wrong credentials.
403 There are more than 100000 notifications, reduce the time duration to fetch the data.
429 API is already processing a request. Please retry after sometime.
500 Internal Server Error
Examples of the API response structure

The following examples are JSON responses for the following notifications:

  • Agent status issues

{
"Application":"PDC:01.01.01"
,"ClusterName":"PDC2Prod"
,"CorrelationID":"PDC2Prod:OPS0015:Agent status issue:cd7e3c8e6b7dcd5c506c625ee7f3ec23917"
,"GeneratedDateTime":"2020-01-25T06:34:00.178Z"
,"InitialAction":"NA"
,"KPIThreshold":"1000"
,"KPIValue":"20"
,"LineInfo":"Stale snapshot for agent status. Last status received on 20200125T042011.754 GMT"
,"MsgID":"OPS0015"
,"Node":"PDC util-i-000d400f8e7bb295c"
,"NotificationCategory":"EventBased"
,"NotificationName":"Agent status issues"
,"OperatorInfo":"none"
,"PDCURL":"https://pdc-monitoring.pegacloud.io/prweb/cdEBp4uPKTogorRwSwWqbBvUKUKdn26OaUHj-faXmif%5B*/!STANDARD"
,"pxObjClass":"PegaAES-Data-ServiceAPIInfo"
,"pzInsKey":"PEGAAES-DATA-SERVICEAPIINFO PDC2PROD:OPS0015:AGENT STATUS ISSUE:CD7E3C8E6B7DCD5C506C625EE7F3EC23917!20200125T063400.178 GMT!PDC2PROD"
}

  • New exception

{
"Application":"NA"
,"ClusterName":"PDC2Prod"
,"CorrelationID":"PDC2Prod:EXCEPTION:cdc22a26e37deb4494885863595b3de"
,"ExceptionClass":"com.pega.pegarules.pub.runtime.IndeterminateConditionalException"
,"ExceptionMessage":"PRRuntimeException"
,"GeneratedDateTime":"2020-02-18T17:55:34.454Z"
,"MsgID":"EXCP0001"
,"Node":"web-i-0c4481e056459c539"
,"NotificationCategory":"ExceptionBased"
,"NotificationName":"New exception"
,"OccurrenceTime":"2020-02-18T17:55:34.454Z"
,"OperatorInfo":"NA"
,"PDCURL":"https://pdc-monitoring.pegacloud.io/prweb/cdEBp4uPKTogorRwSwWBkQvUKUKdn26OaUHj-faXmif%5B*/!STANDARD"
,"pxObjClass":"PegaAES-Data-ServiceAPIInfo"
,"pzInsKey":"PEGAAES-DATA-SERVICEAPIINFO PDC2PROD:EXCEPTION:CDC22A26E37DEB4494885863595B3DE!20200218T175534.454 GMT!PDC2PROD"
,"ThreadName":"NA"
}

  • Pulse down

{
"ClusterName":"PDC2Prod"
,"CurrentStatus":"critical"
,"GeneratedDateTime":"2020-02-26T04:17:14.445Z"
,"Indicator":"lastPulse"
,"LineInfo":"Time elapsed since last system pulse exceeded byundefined<b>5 min</b>"
,"Node":"stream-i-03279ec0421cc606f"
,"NotificationCategory":"PulseDown"
,"NotificationName":"Pulse down"
,"OccurrenceTime":"2020-02-26T04:17:14.445Z"
,"PDCURL":"https://pdc-monitoring.pegacloud.io/prweb/cdEBp4uKTwogorRwSwWqbBvUKthdn16OaUHj-faMtif%5B*/!STANDARD"
,"PreviousStatus":"normal"
,"pxObjClass":"PegaAES-Data-ServiceAPIInfo"
,"Threshold":"Difference between snapshot and the pulse"
}

  • Health status change

{
"ClusterName":"PDC2Prod"
,"CurrentStatus":"urgent"
,"EndTime":"2020-03-11T05:04:41.380Z"
,"GeneratedDateTime":"2020-03-11T05:04:40.179Z"
,"Indicator":"urgentEvents"
,"LineInfo":"The current status of \"urgentEvents\" exceeded the urgent threshold limit byundefined<b>1 count</b>"
,"Node":"web-i-0846680a04de2a823"
,"NotificationCategory":"HealthStatusChange"
,"NotificationName":"Health status change"
,"OccurrenceTime":"2020-03-11T05:04:40.179Z"
,"PreviousStatus":"normal"
,"pxObjClass":"PegaAES-Data-ServiceAPIInfo"
,"StartTime":"2020-03-11T04:34:41.380Z"
,"Threshold":"Current :1 >Excepted: 0undefined<b>1 count</b>"
}

What to do next

After you configure the Notification API, you can subscribe to the notifications that you want to retrieve with this method. For more information, see Managing notifications in Pega Predictive Diagnostic Cloud.

Suggest Edit

75% found this useful

Have a question? Get answers now.

Visit the Collaboration Center to ask questions, engage in discussions, share ideas, and help others.