Alerts Data Extraction

Overview

OData is a REST standard for creating data centric APIs and is used to share the data through HTTP in a secured manner. BI tools support OData through inbuilt adapters or connectors and use the extracted Alerts data for reporting purpose.

Extract Alerts Data

Before You Begin

You must have the OData Extract-Alerts permission to extract the Alerts data.
You must obtain the authorization bearer token for a tenant.
Note: You must use the User ID and password instead of the Client ID and password.

Access the OData service to extract data in any supported BI tool using their inbuilt adapters.

Filter Alerts based on the Asset Permissions

The extracted Alerts returned by the OData service is filtered based on the asset permissions of the logged in user. This filtering capability allows you to filter the Alerts, to list only the assets to which you have access.

Filter Alerts based on Limited Visibility Permissions

The extracted Alerts returned by the OData service is filtered based on the asset permissions of the logged in user. This filtering capability allows you to filter and view Alerts, with respect to your Limited Visibility permission in the Predix Essentials dashboard. You will not be able to access all the Alerts for a particular asset, without the Limited Visibility permission.

Cross-tenant Support

The OData microservice supports cross-tenant queries. Users who have permissions in more than one tenant can query for Alerts across tenants. This support allows you to consolidate the total Alerts count and the query results returned by the OData service.

Note: Ordering data is not supported in a cross-tenant query. As a result, any order by clause in a query will be applied per tenant and the tenant results are concatenated.

OData Metadata

To get all the metadata including entities, properties, and relationships, use the link:

https://apm-odata-alerts-cases<domain prefix>.int-app.aws-usw02-pr.predix.io/Alerts.svc/$metadata.

Examples of OData Operations

Operations	Example
To extract 1000 Alerts from the top of the list	https://apm-odata-alerts-cases`<domain prefix>`.int-app.aws-usw02-pr.predix.io/Alerts.svc/Alerts?$top=1000
To extract the Alerts which were created or updated in the month of September 2017	https://apm-odata-alerts-cases`<domain prefix>`.int-app.aws-usw02-pr.predix.io/Alerts.svc/Alerts?$filter=UpdatedDate gt 2017-09-01T00:00:00.000Z and UpdatedDate lt 2017-10-01T00:00:00.000Z
To extract the Alerts based on the Alert Name or Alert ID	https://apm-odata-alerts-cases`<domain prefix>`.int-app.aws-usw02-pr.predix.io/Alerts.svc/Alerts?$select=AlertId,Id,Name
To expose the density details for an Alert	https://apm-odata-alerts-cases`<domain prefix>`.intapp.aws-usw02-pr.predix.io/Alerts.svc/Densities?$top=1 https://apm-odata-alerts-cases`<domain prefix>`.intapp.aws-usw02-pr.predix.io/Alerts.svc/Alerts?$top=1&$expand=Density

Data Aggregation

Supported Functions

Grouping and Aggregation

The OData microservice supports the grouping and aggregation functionality (e.g. sum, avg, min, and max) on the properties of the associated entities.

The following query example provides the number of Alerts aggregated by the name of the sites.

GET {{host}}/Alerts.svc/Alerts?$apply=groupby((Asset/SiteName),aggregate(Id with countdistinct as AlertCount))

{
    "@odata.context": "https://apm-odata-alerts-cases-svc-rc.int-app.aws-usw02-pr.predix.io/Alerts.svc/$metadata#Alerts(Asset(SiteName),AlertCount)",
    "value": [
        {
            "@odata.id": null,
            "AlertCount": 4,
            "Asset": {
                "@odata.id": null,
                "SiteName": "AK-Site"
            }
        },
        {
            "@odata.id": null,
            "AlertCount": 21,
            "Asset": {
                "@odata.id": null,
                "SiteName": "AllFault_VSG_Testa_Q2"
            }
        },
        {
            "@odata.id": null,
            "AlertCount": 39,
            "Asset": {
                "@odata.id": null,
                "SiteName": "ASCIITESTCategory139_Level2"
            }
        }
]
}

Note:

If you have permissions on multiple tenants, the response will contain one entry per tenant, and could result in repeated entries for the grouped property:

GET {{host}}/Alerts.svc/Alerts?$apply=groupby((Severity),aggregate(Id with countdistinct as AlertCount))

{
    "@odata.context": "$metadata#Alerts(Severity,Result)",
    "value": [
        {
            "@odata.id": null,
            "Severity": 1,
            "Result": 308683
        },
        {
            "@odata.id": null,
            "Severity": 2,
            "Result": 38792
        },
        {
            "@odata.id": null,
            "Severity": 3,
            "Result": 163438
        },
        {
            "@odata.id": null,
            "Severity": 1,
            "Result": 11879
        },
        {
            "@odata.id": null,
            "Severity": 2,
            "Result": 409
        }
    ]
}

To display the Tenant Id of the record, you must include the TenantId property in the groupby function:

GET {{host}}/Alerts.svc/Alerts?$apply=groupby((Severity,TenantId),aggregate(Id with countdistinct as AlertCount))

{
    "@odata.context": "{{host}}/Alerts.svc/$metadata#Alerts(Severity,TenantId,AlertCount)",
    "value": [
        {
            "@odata.id": null,
            "Severity": 1,
            "TenantId": "a49d0312-cc4b-47c6-817d-4fdabcf56544",
            "AlertCount": 308683
        },
        {
            "@odata.id": null,
            "Severity": 2,
            "TenantId": "a49d0312-cc4b-47c6-817d-4fdabcf56544",
            "AlertCount": 38792
        },
        {
            "@odata.id": null,
            "Severity": 3,
            "TenantId": "a49d0312-cc4b-47c6-817d-4fdabcf56544",
            "AlertCount": 163438
        },
        {
            "@odata.id": null,
            "Severity": 1,
            "TenantId": "8d663b3d-faf9-43d8-9aa1-62ac70f7a3eb",
            "AlertCount": 11879
        },
        {
            "@odata.id": null,
            "Severity": 2,
            "TenantId": "8d663b3d-faf9-43d8-9aa1-62ac70f7a3eb",
            "AlertCount": 409
        }
    ]
}

Numeric Aggregations Support

The OData microservice supports the numeric aggregation methods using ?$apply=aggregate(<PropertyName> with <method> as <alias>)

The following aggregation methods are supported:

sum - Provides the total of all the values for the specified property.
average - Provides the average value of all the values for the specified property.
min - Provided the smallest value of all the values for the specified property.
max - Provides the largest of all the values for the specified property.

{{host}}/Alerts.svc/Alerts?$apply=aggregate(Severity with average as AvgSeverity)

{
    "@odata.context": "$metadata#Alerts(AvgSeverity)",
    "value": [
        {
            "@odata.id": null,
            "AvgSeverity": 1.7697726851152447
        }
    ]
}

Note: If you have permissions on multiple tenants, the response will contain one entry per tenant.{{host}}/Alerts.svc/Alerts?$apply=aggregate(Severity with average as AvgSeverity)

{
    "@odata.context": "$metadata#Alerts(AvgSeverity)",
    "value": [
        {
            "@odata.id": null,
            "AvgSeverity": 1.7697726851152447
        },
        {
            "@odata.id": null,
            "AvgSeverity": 1.1111111111111112
        }
    ]
}

Basic Aggregations with User Permission Filters

You must apply the same user permission on aggregated data that is applied to the standard OData queries.

User permissions are the sets in Predix Essentials which restrict the view that users can have to a specific Asset Hierarchy. The standard OData queries filter data using these permissions.

Filter Aggregations

You can filter aggregations based on the filter parameters specified in an aggregate query. You can add a filter syntax to the aggregate query to limit the values used in an aggregation.

The following query example provides the number of Alerts created for each asset that is associated with an enterprise.

{{host}}/Alerts.svc/Alerts?$apply=filter(Asset/EnterpriseName eq 'E2E EDISON ENTERPRISE')/groupby((AssetName),aggregate(AlertId with countdistinct as CNT_ALERTID))

{
    "@odata.context": "https://odata-latest.run.aws-usw02-pr.ice.predix.io/Alerts.svc/$metadata#Alerts(AssetName,CNT_ALERTID)",
    "value": [
        {
            "@odata.id": null,
            "AssetName": "APS Small Gen Segment #1",
            "CNT_ALERTID": 8
        },
        {
            "@odata.id": null,
            "AssetName": "Array #1 ASSET TYPE 2",
            "CNT_ALERTID": 20514
        },
        {
            "@odata.id": null,
            "AssetName": "TS Asset Type1",
            "CNT_ALERTID": 174
        },
        {
            "@odata.id": null,
            "AssetName": "TS Asset V2 Type1",
            "CNT_ALERTID": 2262
        }
    ]
}

COUNT (DISTINCT) Support

The Count Distinct operation allows you to obtain a distinct count on any property of an entity. The count aggregation function can be used on the primary key. The OData microservice supports the COUNT DISTINCT function in the queries, using ?$apply=aggregate(<PropertyName> with countdistinct as <alias>)

GET {{host}}/Alerts.svc/Alerts?$apply=aggregate(AssetId with countdistinct as Assets)

{
    "@odata.context": "$metadata#Alerts(Assets)",
    "value": [
        {
            "@odata.id": null,
            "Assets": 25
        }
    ]
}

Note: If you have permissions on multiple tenants, the response will contain one entry per tenant. GET {{host}}/Alerts.svc/Alerts?$apply=aggregate(AssetId with countdistinct as Assets)

{
    "@odata.context": "$metadata#Alerts(Assets)",
    "value": [
        {
            "@odata.id": null,
            "Assets": 25
        },
        {
            "@odata.id": null,
            "Assets": 15
        }
    ]
}