Start Analyzing Aternity's Data with an Overview of all REST APIs in OData

You can send REST API queries to directly extract and analyze Aternity's data without accessing 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. Then save and reopen as needed, selecting 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.

Access data using the OData interface by sending a URL and receiving data in XML or JSON formats

To find the URL to access your REST API, contact your Administrator of Aternity on-premise. During the setup of the Aternity REST API Server, you define its external_url (learn more). For example, http://odata-aternity.company.com:80/aternity.odata/API_NAME

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

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.

See View All Reported Activities with REST API.

APPLICATIONS_RAW

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

See Analyze the Raw List of Application Performance Reports with REST API.

APPLICATIONS_HOURLY or APPLICATIONS_DAILY

Use APPLICATIONS_HOURLY or APPLICATIONS_DAILY to view the performance 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.

See Analyze Application Performance Hourly or Daily with REST API.

APPLICATION_RESOURCES_HOURLY

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.

See Analyze Resource Usage of a Managed Application (PRC) with REST API.

APPLICATION_EVENTS

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.

See View Application Events with REST API.

BUSINESS_ACTIVITIES_RAW

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, or any other query you want to check.

See Analyze the Raw List of Activities with REST API.

BUSINESS_ACTIVITIES_HOURLY

(replaces API_USER_ACTIVITY_HOURLY)

BUSINESS_ACTIVITIES_HOURLY returns an hourly aggregation of the list of activities (from o'clock to o'clock), along with the application, user and device details.

See Analyze Activities Per Hour with REST API.

BUSINESS_ACTIVITIES_DAILY

BUSINESS_ACTIVITIES_DAILY returns a daily aggregation of activities, along with the application, user and device details.

See Analyze Activities Per Day with REST API.

DASHBOARD_VIEWS_AUDIT

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.

See Analyze Activities Per Day with REST API.

DEVICE_INVENTORY

Use DEVICE_INVENTORY to view all monitored devices which have the Aternity Agent 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.

See Analyze Device Inventory with REST API.

REPORTING_AGENTS_COUNT

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.

See Analyze Device (Agent) Status with REST API.

NOT_REPORTING_ACTIVITIES

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.

See View All Activities Not Reported to Aternity with REST API.

USER_AUDIT

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

See Audit Aternity Access with REST API.

WINDOWS_MACHINE_BOOTS

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

See Analyze the Boot Times of Devices with REST API.

API_NOC_APPLICATION_CURR_SCORE

API_NOC_APPLICATION_CURR_SCORE is for companies with their own NOC systems and want to display Aternity's data there. It 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.

See View Current NOC Scores with REST API.

Before you begin

Ensure you have the following:

  • To send a REST API query in Excel, PowerBI or a browser, enter an Aternity username which has the OData Role privilege, and its password. For SSO users, generate your own Aternity REST API password by selecting User icon > REST API Password. For LDAP users, enter the domain name, then a backslash ('\'), then your network username and password. For example domain_name\jsmith

  • If you have Microsoft Excel 2010 or 2013, download and install the Microsoft Power Query add-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:

    Enter a URL like http://odata-aternity.company.com:80/aternity.odata/BUSINESS_ACTIVITIES_HOURLY?$top=5.

    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. Enter http://odata-aternity.company.com:80/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:

    Enter a URL like http://odata-aternity.company.com:80/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 .../aternity.odata/API_NAME?$filter=(USERNAME eq 'jsmith@company.com'), or several parameter-value pairs each separated by an ampersand (&), like .../aternity.odata/API_NAME?$format=xml&$top=5.
    Parameter Description
    $filter=

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

    Combine several parameters using 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) and le (less than or equal to). You can also use the text operator contains, though it significantly slows the API performance.

    Aternity also supports the not operator, which negates the query expression that follows it. For example, .../aternity.odata/API_NAME?$filter=(CLIENT_DEVICE_TYPE eq 'Laptop' or CLIENT_DEVICE_TYPE eq 'Tablet') and not(LOCATION_CITY eq 'Miami' or LOCATION_CITY eq 'Los Angeles') will return data for laptops and tablets for all locations except Miami and Los Angeles. For details on these OData parameters that are supported by Aternity, see Microsoft's OData documentation.

    Use the relative_time() filter to easily limit the timeframe of your query. For example, .../aternity.odata/API_NAME?$filter=relative_time(yesterday). Possible values are:

    • last_6_hours: Shows data starting from exactly six hours ago, displaying it summarized (aggregated) according to the view you selected.

    • last_24_hours: Shows data starting exactly this time yesterday, displaying it summarized (aggregated) according to the view you selected.

    • today: Displays data starting from 00:00AM today in the time zone of the Aternity Management Server.

    • yesterday: Displays data starting from 00:00AM yesterday according to the time zone of the Aternity Management Server.

    • last_48_hours: Displays data starting exactly this time two days ago, displaying it summarized (aggregated) according to the view you selected.

    • last_7_days: Displays data starting from 00:00AM seven days ago in the time zone of the Aternity Management Server.

    • this_week: Displays data for this week, beginning from 00:00 AM on Sunday morning according to the time zone of the Aternity Management Server, until the current time.

    • last_week: Displays data from 00:00AM on Sunday morning to 23:59 on the most recent Saturday night according to the time zone of the Aternity Management Server. Use this view to compare consistent weekly results.

    • last_14_days: Displays data from exactly this time 14 days ago, displaying it summarized (aggregated) according to the view you selected.

    • last_30_days: Displays data from exactly this time 30 days ago, displaying it summarized (aggregated) according to the view you selected.

    $format=

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

    .../aternity.odata/API_NAME?$format=xml

    $orderby

    Use $orderby to order the returned data according to the value you choose. For example, to order results device inventory results based on location, use .../aternity.odata/DEVICE_INVENTORY?$orderby=LOCATION

    $select=

    Use $select to return only the data of specific columns (attributes). To return several columns, list them separated by a comma (no space).

    For example, to return only the application and department, use:

    .../aternity.odata/API_NAME?$select=APPLICATION,DEPARTMENT&...

    $top=

    Use $top (lower case only, not TOP) 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 in any way), use:

    .../aternity.odata/API_NAME?$top=5

  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 an Aternity username which has the OData Role privilege, and its password. For SSO users, generate your own Aternity REST API password by selecting User icon > REST API Password. For LDAP users, enter the domain name, then a backslash ('\'), then your network username and password. For example domain_name\jsmith

  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.

    If your query returns too many entries, the system automatically returns the first page (usually 1000 entries), with a link to the next page. In Excel or Power BI, select the displayed link to see the next page. Programmers can reference the rel="next" link returned near the top of each page: <a:link rel="next" href="next_url"/>. To display the number of entries (<m:count>), add $count=true.