Asset 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 Assets data for reporting purpose.

Extract Assets Data

Before You Begin

You must have the GEDA-OData feature permission to extract the Assets 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 Asset based on the Asset Permissions

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

Cross-tenant Support

The OData microservice supports cross-tenant queries. Users who have permissions in more than one tenant can query for Assets across tenants. This support allows you to consolidate the total Asset 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-asset-odata-svc-<domain prefix>.app-api.aws-usw02-pr.predix.io/v1/$metadata.

Examples of OData Operations

Operations	Example
To extract 1000 Assets from the top of the list	https://apm-asset-odata-svc-`<domain prefix>`.app-api.aws-usw02-pr.predix.io/v1/EntityInstances?$top=100
To extract the Assets which were created or updated in the month of September 2017	https://apm-asset-odata-svc-`<domain prefix>`.app-api.aws-usw02-pr.predix.io/v1/EntityInstances?$filter=LastModifiedDate gt 2017-09-01T00:00:00.000Z and LastModifiedDate lt 2017-10-01T00:00:00.000Z
To extract the Assets based on the Asset Name or Asset ID	https://apm-asset-odata-svc-`<domain prefix>`.app-api.aws-usw02-pr.predix.io/v1/EntityInstances?$select=AssetName,Id
To extract the GeoLocation details for Assets	https://apm-asset-odata-svc-`<domain prefix>`.app-api.aws-usw02-pr.predix.io/v1/EntityInstances?$select=Latitude,Longitude,Altitude

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 Assets aggregated by the Asset make.

{
    "@odata.context": "https://apm-asset-odata-svc-rc.int-app.aws-usw02-pr.predix.io/v1/$metadata#EntityInstances(AssetMake,TenantId,Count)",
    "value": [
        {
            "@odata.id": null,
            "AssetMake": "GE",
            "TenantId": "a49d0312-cc4b-47c6-817d-4fdabcf56544",
            "Count": 20
        },
        {
            "@odata.id": null,
            "AssetMake": "GE",
            "TenantId": "8d663b3d-faf9-43d8-9aa1-62ac70f7a3eb",
            "Count": 35393
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Alert and Cases Asset",
            "TenantId": "8d663b3d-faf9-43d8-9aa1-62ac70f7a3eb",
            "Count": 4
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Analysis 01",
            "TenantId": "8d663b3d-faf9-43d8-9aa1-62ac70f7a3eb",
            "Count": 3
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Analysis 02",
            "TenantId": "8d663b3d-faf9-43d8-9aa1-62ac70f7a3eb",
            "Count": 2
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Analysis Asset",
            "TenantId": "8d663b3d-faf9-43d8-9aa1-62ac70f7a3eb",
            "Count": 25
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Analysis ok",
            "TenantId": "8d663b3d-faf9-43d8-9aa1-62ac70f7a3eb",
            "Count": 1
        },
        {
            "@odata.id": null,
            "AssetMake": "GE AVID Wind Turbine",
            "TenantId": "8d663b3d-faf9-43d8-9aa1-62ac70f7a3eb",
            "Count": 3
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Make for avid Chart Asset",
            "TenantId": "8d663b3d-faf9-43d8-9aa1-62ac70f7a3eb",
            "Count": 1
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Make for Chart Asset",
            "TenantId": "8d663b3d-faf9-43d8-9aa1-62ac70f7a3eb",
            "Count": 5
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Red Wind Turbine",
            "TenantId": "8d663b3d-faf9-43d8-9aa1-62ac70f7a3eb",
            "Count": 2
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Wind Turbine A1111111",
            "TenantId": "8d663b3d-faf9-43d8-9aa1-62ac70f7a3eb",
            "Count": 3
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Wind Turbine A11111111",
            "TenantId": "8d663b3d-faf9-43d8-9aa1-62ac70f7a3eb",
            "Count": 1
        }
    ]
}

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:

{
    "@odata.context": "https://apm-asset-odata-svc-rc.int-app.aws-usw02-pr.predix.io/v1/$metadata#EntityInstances(AssetMake,Count)",
    "value": [
        {
            "@odata.id": null,
            "AssetMake": "GE",
            "Count": 20
        },
        {
            "@odata.id": null,
            "AssetMake": "GE",
            "Count": 35393
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Alert and Cases Asset",
            "Count": 4
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Analysis 01",
            "Count": 3
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Analysis 02",
            "Count": 2
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Analysis Asset",
            "Count": 25
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Analysis ok",
            "Count": 1
        },
        {
            "@odata.id": null,
            "AssetMake": "GE AVID Wind Turbine",
            "Count": 3
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Make for avid Chart Asset",
            "Count": 1
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Make for Chart Asset",
            "Count": 5
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Red Wind Turbine",
            "Count": 2
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Wind Turbine A1111111",
            "Count": 3
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Wind Turbine A11111111",
            "Count": 1
        }
    ]
}

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

{{host}}/v1/EntityInstances?$apply=groupby((AssetMake,TenantId),aggregate($count as Count))/filter(contains(AssetMake,'GE'))

{
    "@odata.context": "https://apm-asset-odata-svc-rc.int-app.aws-usw02-pr.predix.io/v1/$metadata#EntityInstances(AssetMake,TenantId,Count)",
    "value": [
        {
            "@odata.id": null,
            "AssetMake": "GE",
            "TenantId": "a49d0312-cc4b-47c6-817d-4fdabcf56544",
            "Count": 20
        },
        {
            "@odata.id": null,
            "AssetMake": "GE",
            "TenantId": "8d663b3d-faf9-43d8-9aa1-62ac70f7a3eb",
            "Count": 35393
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Alert and Cases Asset",
            "TenantId": "8d663b3d-faf9-43d8-9aa1-62ac70f7a3eb",
            "Count": 4
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Analysis 01",
            "TenantId": "8d663b3d-faf9-43d8-9aa1-62ac70f7a3eb",
            "Count": 3
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Analysis 02",
            "TenantId": "8d663b3d-faf9-43d8-9aa1-62ac70f7a3eb",
            "Count": 2
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Analysis Asset",
            "TenantId": "8d663b3d-faf9-43d8-9aa1-62ac70f7a3eb",
            "Count": 25
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Analysis ok",
            "TenantId": "8d663b3d-faf9-43d8-9aa1-62ac70f7a3eb",
            "Count": 1
        },
        {
            "@odata.id": null,
            "AssetMake": "GE AVID Wind Turbine",
            "TenantId": "8d663b3d-faf9-43d8-9aa1-62ac70f7a3eb",
            "Count": 3
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Make for avid Chart Asset",
            "TenantId": "8d663b3d-faf9-43d8-9aa1-62ac70f7a3eb",
            "Count": 1
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Make for Chart Asset",
            "TenantId": "8d663b3d-faf9-43d8-9aa1-62ac70f7a3eb",
            "Count": 5
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Red Wind Turbine",
            "TenantId": "8d663b3d-faf9-43d8-9aa1-62ac70f7a3eb",
            "Count": 2
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Wind Turbine A1111111",
            "TenantId": "8d663b3d-faf9-43d8-9aa1-62ac70f7a3eb",
            "Count": 3
        },
        {
            "@odata.id": null,
            "AssetMake": "GE Wind Turbine A11111111",
            "TenantId": "8d663b3d-faf9-43d8-9aa1-62ac70f7a3eb",
            "Count": 1
        }
    ]
}

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 APM 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 Assets having the same Asset Make.

{{host}}/v1/EntityInstances?$apply=filter(AssetMake eq 'GE')/groupby((AssetState),aggregate($count as Count))

{
    "@odata.context": "https://apm-asset-odata-svc-rc.int-app.aws-usw02-pr.predix.io/v1/$metadata#EntityInstances(AssetState,Count)",
    "value": [
        {
            "@odata.id": null,
            "AssetState": "Design",
            "Count": 3
        },
        {
            "@odata.id": null,
            "AssetState": "Procure",
            "Count": 1
        },
        {
            "@odata.id": null,
            "AssetState": "Build",
            "Count": 1
        },
        {
            "@odata.id": null,
            "AssetState": "Commission",
            "Count": 4
        },
        {
            "@odata.id": null,
            "AssetState": "Operate",
            "Count": 35248
        },
        {
            "@odata.id": null,
            "AssetState": "CustomState",
            "Count": 136
        }
    ]
}

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>)

{{host}}/v1/EntityInstances?$apply=aggregate(EntityTypeId with countdistinct as EntityTypes)

{
    "@odata.context": "https://apm-asset-odata-svc-rc.int-app.aws-usw02-pr.predix.io/v1/$metadata#EntityInstances(EntityTypes)",
    "value": [
        {
            "@odata.id": null,
            "EntityTypes": 35538
        }
    ]
}

Note: If you have permissions on multiple tenants, the response will contain one entry per tenant.

{{host}}/v1/EntityInstances?$apply=aggregate(EntityTypeId with countdistinct as EntityTypes)

{
    "@odata.context": "https://apm-asset-odata-svc-rc.int-app.aws-usw02-pr.predix.io/v1/$metadata#EntityInstances(EntityTypes)",
    "value": [
        {
            "@odata.id": null,
            "EntityTypes": 4
        },
        {
            "@odata.id": null,
            "EntityTypes": 35538
        }
    ]
}