Cases 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 tool support OData through inbuilt adapters or connectors and use the extracted Cases data for reporting purpose.

Extract Cases Data

Before You Begin

You must have the OData Extract-Cases permission to extract the Cases data.
You must obtain the authorization bearer token for a tenant.
For more information about obtaining the authorization bearer token for a tenant, refer to Obtain the Authorization Token for your 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 Cases based on the Asset Permissions

The extracted Cases 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 Cases, to list only the assets to which you have access.

Filter Cases based on Limited Visibility Permissions

The extracted Cases 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 Cases, with respect to your Limited Visibility permission in the Predix Essentials dashboard. You will not be able to access all the Cases 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 Cases across tenants. This support allows you to consolidate the total Cases 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/Cases.svc/$metadata.

Examples of OData Operations

Operations	Example
To extract 1000 Cases from the top of the list	https://apm-odata-alerts-cases`<domain prefix>`.int-app.aws-usw02-pr.predix.io/Cases.svc/Cases?$top=1000
To extract the Cases 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/Cases.svc/Cases?$filter=UpdatedDate gt 2017-09-01T00:00:00.000Z and UpdatedDate lt 2017-10-01T00:00:00.000Z
To extract the Cases based on the Case Name or Case ID	https://apm-odata-alerts-cases`<domain prefix>`.int-app.aws-usw02-pr.predix.io/Cases.svc/Cases?$select=CaseId,Id,Name
To extract the Category and Likelihood details for a Case	https://apm-odata-alerts-cases`<domain prefix>`.int-app.aws-usw02-pr.predix.io/Cases.svc/Cases?$expand=FieldValue

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 Cases aggregated by the name of the sites.

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

{
    "@odata.context": "https://apm-odata-alerts-cases-svc-rc.int-app.aws-usw02-pr.predix.io/Cases.svc/$metadata#Cases(Asset(SiteName),CaseCount)",
    "value": [
        {
            "@odata.id": null,
            "CaseCount": 2,
            "Asset": {
                "@odata.id": null,
                "SiteName": "Alexanderson Energy"
            }
        },
        …
        …
        {
            "@odata.id": null,
            "CaseCount": 11063,
            "Asset": {
                "@odata.id": null,
                "SiteName": "AZ - APS - Prescott - SITE"
            }
        }
    ]
}

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}}/Cases.svc/Cases?$apply=groupby((Severity),aggregate(Id with countdistinct as CaseCount))

{
    "@odata.context": "$metadata#Cases(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}}/Cases.svc/Cases?$apply=groupby((Severity,TenantId),aggregate(Id with countdistinct as CaseCount))

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

Numeric Aggregations Support

The OData microservice supports the 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}}/Cases.svc/Cases?$apply=aggregate(Severity with average as AvgSeverity)

{
    "@odata.context": "$metadata#Cases(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}}/Cases.svc/Cases?$apply=aggregate(Severity with average as AvgSeverity)

{
    "@odata.context": "$metadata#Cases(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 Cases created for each asset that is associated with an enterprise.

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

{
    "@odata.context": "https://apm-odata-latest.run.aws-usw02-pr.ice.predix.io/Cases.svc/$metadata#Cases(Asset(AssetName),CNT_CASEID)",
    "value": [
        {
            "@odata.id": null,
            "CNT_CASEID": 4,
            "Asset": {
                "@odata.id": null,
                "AssetName": "PV System #2 SEGMENT"
            }
        },
        {
            "@odata.id": null,
            "CNT_CASEID": 2,
            "Asset": {
                "@odata.id": null,
                "AssetName": "Schindler APM Asset"
            }
        },
        {
            "@odata.id": null,
            "CNT_CASEID": 37,
            "Asset": {
                "@odata.id": null,
                "AssetName": "TS Asset Type1"
            }
        },
        {
            "@odata.id": null,
            "CNT_CASEID": 3781,
            "Asset": {
                "@odata.id": null,
                "AssetName": "TS Asset V2 Type1"
            }
        }
    ]
}

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}}/Cases.svc/Cases?$apply=aggregate(AssetId with countdistinct as Assets)

{
    "@odata.context": "$metadata#Cases(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}}/Cases.svc/Cases?$apply=aggregate(AssetId with countdistinct as Assets)

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