Overview for Analyzing with Aternity REST API (OData)

You can send REST API queries to directly extract and analyze Aternity's data without Aternity's dashboards. You can combine the data with other data sources if needed, or transform it as required, then view it in Microsoft Excel, Power BI, or your own data application.

For example, you can automatically load the data into Microsoft Excel or Power BI by entering the URL in the format of OData version 4 (Aternity supports only some of OData's parameters). Then select Refresh to update with the latest data. Alternatively, a programmer can send an OData URL request directly from the source code to retrieve the data, and then process it in the application as required.

Tip

You can always see the latest version of this page by going to https://help.aternity.com/restapi.

Access data by sending a URL to a browser, Excel or PowerBI

To view an Aternity REST API, enter the base URL from User icon > REST API Access, followed by the name of the API: <base_url>/API_NAME into a browser, Excel or PowerBI (learn more). :

The list of all APIs is as follows:

REST API Name Description
CONNECTION_TEST

Use CONNECTION_TEST to check your connection to the REST API service. This API (only) does not require a username or password.

ALL_ACTIVITIES (Learn more)

Use ALL_ACTIVITIES to view all activities reported to Aternity over the past seven days. Use this API to get an overview of which activities are taking place, their frequency, and how many users are performing the activity.

Learn more.

APPLICATIONS_RAW (Learn more)

Use the APPLICATIONS_RAW API to retrieve the raw list of performance reports to Aternity, showing the performance and usage of each discovered application at five minute intervals running on each monitored device.

Learn more.

APPLICATIONS_HOURLY or APPLICATIONS_DAILY (Learn more)

Use APPLICATIONS_HOURLY or APPLICATIONS_DAILY to view the performance of each discovered application running on a device, where the measurements are aggregated per hour or per day, along with the user, location and device details.

Learn more.

APPLICATIONS_DAILY_ANONYMIZED (Learn more)

Use APPLICATIONS_DAILY_ANONYMIZED to view the daily average performance of each discovered application WITHOUT any PII (personally identifiable information), hence queries can have a much longer retention. It returns daily summaries of each application's performance, along with location and device attributes.

Learn more

APPLICATION_RESOURCES_HOURLY (Learn more)

Use APPLICATION_RESOURCES_HOURLY to view the resource usage (PRC) of the process of each managed application aggregated hourly, along with application, user, location and device details.

Learn more.

APPLICATION_EVENTS (Learn more)

Use APPLICATION_EVENTS to return application events which report errors or check how often someone used a feature in your application, like accessing the online help. You create an application event in the Aternity Activity Designer and upload it to Aternity as a custom activity.

Learn more.

BUSINESS_ACTIVITIES_RAW (Learn more)

BUSINESS_ACTIVITIES_RAW returns the list of activities as reported to Aternity one by one, showing the detailed user experience of all activities performed. For example, you can check one, several, or all devices, or any whose hostname contains the text mktg, for one user or any combination of users.

Learn more.

BUSINESS_ACTIVITIES_HOURLY (Learn more)

BUSINESS_ACTIVITIES_HOURLY returns the list of activities which each user performed in a one-hour time slot (from o'clock to o'clock), along with the activity's average performance (response time) the application name, user details and device details.

(Replaces API_USER_ACTIVITY_HOURLY)

Learn more.

BUSINESS_ACTIVITIES_DAILY (Learn more)

BUSINESS_ACTIVITIES_DAILY returns the list of activities which each user performed each day, along with the activity's average performance (response time) the application name, user details and device details.

Learn more.

BUSINESS_ACTIVITIES_DAILY_ANONYMIZED (Learn more)

Use BUSINESS_ACTIVITIES_DAILY_ANONYMIZED to return the list of activities performed each day WITHOUT any PII (personally identifiable information), hence your queries can go back further in history. It returns daily aggregations of each activity's response time the application name and device attributes.

Learn more.

DASHBOARD_VIEWS_AUDIT (Learn more)

DASHBOARD_VIEWS_AUDIT returns a list of Aternity dashboards that users accessed over the past seven days, and the username and time of each access, so that you can audit or monitor the users who view different parts of Aternity.

Learn more.

DEVICE_HEALTH_DAILY_ANONYMIZED (Learn more)

Use DEVICE_HEALTH_DAILY_ANONYMIZED to return the list of health events that occurred each day, without PII (personally identifiable information).

Learn more.

DEVICE_HEALTH_RAW (Learn more)

Use DEVICE_HEALTH_RAW (beta) to view the list of all device health events reported to Aternity up to the last seven days, updated every hour.

Learn more.

DEVICE_INVENTORY (Learn more)

Use DEVICE_INVENTORY to view all monitored devices which have the Agent for End User Devices locally deployed, and which reported data to Aternity over the past seven days, so you can keep an updated inventory of devices and their attributes.

Learn more.

HOST_RESOURCES_HOURLY (Learn more)

Use HOST_RESOURCES_HOURLY to view data regarding CPU and memory usage by devices (HRC, not the usage by one application).

Learn more.

HOST_RESOURCES_DAILY (Learn more)

Use HOST_RESOURCES_DAILY to view daily average CPU and memory usage (HRC of all applications running on your monitored devices (NOT the resources of a single app).

Learn more.

HOST_RESOURCES_DAILY_ANONYMIZED (Learn more)

Use HOST_RESOURCES_DAILY_ANONYMIZED to view data regarding CPU and memory usage by devices (HRC, not the usage by one application), without PII (personally identifiable information).

Learn more.

INCIDENTS (Learn more)

Use INCIDENTS to view the live list of incidents which Aternity automatically opened for widespread slow performance of an activity.

Learn more.

INSTALLED_SOFTWARE (Learn more)

Use INSTALLED_SOFTWARE to check the software present on each Windows physical monitored device, along with its version and deployment date. It includes all software deployed on the device but does NOT include Universal Windows Platform (UWP) applications (learn more)..

Learn more.

INSTALLED_SOFTWARE_CHANGE_LOG(Learn more)

Use INSTALLED_SOFTWARE_CHANGE_LOG to check and analyze the installed software related changes on each Windows physical monitored device, along with its version and deployment date. It includes all software deployed on the device but does NOT include Universal Windows Platform (UWP) applications (learn more).

Learn more.

LICENSE_EVENTS (Learn more)

Use LICENSE_EVENTS to view a device's most recent request to Aternity for a monitoring license, and if rejected, it displays the reason.

Learn more.

MOBILE_APPLICATIONS_INVENTORY (Learn more)

Use MOBILE_APPLICATIONS_INVENTORY to track the versions of all monitored mobile apps on devices which reported during the past seven days.

Learn more.

NOT_REPORTING_ACTIVITIES (Learn more)

Use NOT_REPORTING_ACTIVITIES to view all activities which did NOT report to Aternity over the past seven days, because no one performed this action, or perhaps because of a problem with the activity's core definition, causing it to miss capturing an event in your application.

Learn more.

REPORTING_AGENTS_COUNT (Learn more)

REPORTING_AGENTS_COUNT returns a summary of the number of reporting devices in each location over the past seven days, to quickly determine whether all devices are continually reporting data.

Learn more.

SERVICE_DESK_ALERTS_RAW (learn more)

SERVICE_DESK_ALERTS_RAW returns all the service desk alerts which occurred in your organization. A service desk alert (SDA) indicates that the same health event occurred several times on the same device within a certain time. Aternity sends SDAs to draw attention to devices which suffer repeated application errors, system crashes or hardware issues. Use this API to analyze for patterns on similar types of alerts, and to check for correlations with device attributes, subnet or location.

Learn more.

USER_AUDIT (Learn more)

USER_AUDIT returns a list of users and the times that they successfully signed in, so that you can audit or monitor the people accessing Aternity.

Learn more.

WIFI_STATISTICS_HOURLY (Learn more)

WIFI_STATISTICS_HOURLY tracks the customer experience of WiFi in your enterprise by returning an hourly summary of the WiFi details like its speed, signal strength, and access points for each monitored device.

Learn more.

WINDOWS_MACHINE_BOOTS (Learn more)

WINDOWS_MACHINE_BOOTS returns the boot times of all monitored Windows devices: the total boot time, the machine boot, and the user logon time.

Learn more.

API_NOC_APPLICATION_CURR_SCORE (Learn more)

API_NOC_APPLICATION_CURR_SCORE is for companies who want to display Aternity data in their NOC systems. The API returns activity scores and volumes of each application in each location, in each department within that location. The volumes and scores are for the past five minutes, the past hour and the past 24 hours.

Learn more.

SKYPE_CALLS_RAW (Learn more)

SKYPE_CALLS_RAW returns the raw list of Skype for Business calls. Use this API for analysis of Skype for Business performance, including in-depth understanding of factors affecting call quality and the frequency of dropped calls.

Learn more.

Tip

Wherever possible, use $select and $filter to narrow your query, to avoid receiving an error like Returned data is too large. Learn more.

Before you begin

Ensure you have the following:

  • To send a REST API query in Excel, PowerBI or a browser, enter the URL of the REST API, your Aternity username (must have the OData REST API role) and its password. You can find this by selecting User icon > REST API Access. SSO users must generate (once) and use a special password, as Aternity's REST API does not authenticate with your enterprise's identity provider.

  • If you have a legacy Microsoft Excel 2010 or 2013, download and add the Microsoft Power Query plug-in (only available for Windows only, not Mac). It adds a Power Query tab in Excel 2010 or 2013, which understands the latest OData standard.

    If you have Excel 2016, there is no need for an extra plugin, as this functionality is built-in.

Procedure

  1. Step 1 (Optional) As a simple test to preview the raw data in XML or JSON format, enter the request URL in a browser.

    Use any of the available APIs. For example, to view the first five entries of the list of activities in a one-hour slot, enter <base_url/$metadata

    For example, enter https://my-demo-odata.aternity.com/aternity.odata/$metadata

    Previewing the raw REST API response in a browser
    Tip

    If you cannot connect, try the CONNECTION_TEST API, which does not require you to sign in. Depending on your region, try this for my-odata, us2-odata, or eu-odata. For example, enter http://my-demo-odata.aternity.com/aternity.odata/CONNECTION_TEST

    Some browsers default to XML format, others to JSON. You can force the format by adding $format=XML in the URL.

  2. Step 2 Select From OData Feed in Excel.

    In Excel 2010 or 2013, select Power Query > From Other Sources > From OData Feed.

    Use Power Query plugin to access REST API

    In Excel 2016, select Data > New Query > From Other Sources > From OData Feed.

    Access REST API in Excel 2016

    Alternatively, if you use Microsoft Power BI, select Get Data > OData Feed.

  3. Step 3 Enter the URL of the OData API which you want to retrieve.

    Use any of the available APIs. For example, to retrieve a list of activities performed in one hour slots:

    In the US, enter: https://my-odata.aternity.com/aternity.odata/BUSINESS_ACTIVITIES_HOURLY or https://us2-odata.aternity.com/aternity.odata/BUSINESS_ACTIVITIES_HOURLY. In EMEA, the same request would be: https://eu-odata.aternity.com/aternity.odata/BUSINESS_ACTIVITIES_HOURLY.

    Enter the URL of the OData interface you want to retrieve
  4. Step 4 You can add parameters to the URL to filter the returned data, by adding a question mark (?) followed by a parameter and value, such as .../API_NAME?$filter=(USERNAME eq 'jsmith@company.com'), or several parameter-value pairs each separated by an ampersand (&), like .../API_NAME?$format=xml&$top=5.

    For example, to plot the hourly UXI for just one application on one device called hostname in the past 24 hours, select to view the UXI and its associated timestamp, and add a filter to return only that application name, that device name and the past 24 hours.

    <base_url>/APPLICATIONS_HOURLY?$select=timeframe,UXI&filter=(SERVING_DEVICE_NAME eq 'hostname') and relative_time(last_24_hours) and APPLICATION eq 'Microsoft Word'

    Tip

    Wherever possible, use $select and $filter to narrow your query, to avoid receiving an error like Returned data is too large. Learn more.

    Parameter Description
    $select=

    Use $select to return only specific columns (attributes), to make queries more efficient: ...API_NAME?$select=COL1,COL2,COL3

    $filter=

    Use $filter to insert conditions that narrow down the data, to return only entries where those conditions are true..

    To limit the timeframe of a query, add $filter=relative_time() like, .../API_NAME?$filter=relative_time(last_x_hours) or (last_x_days). Learn more.

    Create conditions with operators: and, or, eq (equals) gt (greater than), ge (greater than or equal), lt (less than), le (less than or equal), ge (greater than or equal to), ne (not equal to), le (less than or equal to), not and contains. Use operators with parentheses to group conditions logically: .../API_NAME?$filter=(COLUMN1 eq 'value1' or COL2 neq 'val2') and (COL3 gt number) and not (COL4 eq 'val4' or contains(COL5,'val5'))

    $format=

    Use $format to force the returned data to be either in XML or JSON format. This is only useful for testing the raw data in a web browser. For example: .../API_NAME?$format=xml

    $orderby=

    Use $orderby to sort the returned data according to the value you choose. For example, .../API_NAME?$orderby=LOCATION

    $top=

    Use $top (lower case only) when you are initially testing the response of the API by returning the first few entries.

    For example, to return the first five entries (not sorted), use: ...API_NAME?$top=5

    $search is NOT supported.

    Do not use $search in Aternity's REST APIs.

  5. Step 5 If you need to enter credentials, select Basic in the sidebar.
    Enter credentials to access OData APIs
    Field Description
    Username / Password

    Enter your Aternity username and password.

    To send a REST API query in Excel, PowerBI or a browser, enter the URL of the REST API, your Aternity username (must have the OData REST API role) and its password. You can find this by selecting User icon > REST API Access. SSO users must generate (once) and use a special password, as Aternity's REST API does not authenticate with your enterprise's identity provider.

  6. Step 6 Select Connect to display a preview of the data to be loaded.
    Tip

    If you see an error message that the API is not defined, that the property does not existor that it is unable to resolve the type name ‘<API_name>’ to an EdmType, select New Query > Query Options > Clear Cache.

    Tweak the query, or load it as is directly into Excel

    To change the API parameters or merge it with other queries, select Edit.

  7. Step 7 Select Load to insert the data into the spreadsheet.
    View data retrieved from the OData interface
    Tip

    To refresh the data in Excel from the same URL, select Design > Refresh.

    The columns of data depend on the API request you sent. For more information on the details returned by each API, see its own article.