Feeds API¶
Use the Feeds API to retrieve raw data about app usage, users, and access within your organization; the data is returned in JSON format. Feeds are similar to the reports available in the Admin Portal, but can be consumed by automated tasks.
Each feed returns a fixed amount of data in blocks, so to retrieve the entire data set for a particular feed you may need to send multiple requests. The size of each block may be different for different feeds. To limit the data returned, you can filter on the value of one or more columns. You can also specify a start and end date to return data within a certain date range only.
The following feeds are available:
- App Usage Activity - Lists usage information tracked for all apps with the App Usage policy applied. The report includes the name, ID, and version of the app, date and time of use, and details about the user and device. Note: The App Usage report is automatically filtered to display data from the previous week, and includes data from the past 6 months. You can use the Feeds API to view data older than 6 months.
- Download Activity - Lists an entry for every time a user/device downloaded any version of a native app. For example, if a user downloads the same app 5 times, 5 entries would appear in the list for that user. Note: The report lists downloads of the App Catalog, but the initial download of an App Catalog is not counted until a user has logged into the App Catalog on the device; subsequent downloads of App Catalog updates are counted without requiring the user to log in.
- Download Activity (Latest Version) - Reports each time the current version of each app is downloaded. The data in this feed may change over time. For example, if a user initially downloads an app, then later downloads a new version of the same app, the feed would only display an event for the new (most recent) version of the app for that user. Additionally, if you then upload another new version of the app, and a different user downloads this new version, the feed would only display an event for the new user downloading the most recent version (the previous event for the other user would disappear).
- Login Activity - Lists attempts to log in to any app managed by Apperian, including the App Catalog. Use this report to identify login failures or difficulties.
- Signing Activity - Lists information about apps that were signed using the Admin Portal, including the name, version, and platform of the application, the user who signed it, the date and time it was signed, and the name of the certificate with which it was signed.
- Password Change Activity - Lists the date and time of any changes to an Apperian administrator’s password. This report logs all administrator password changes, including changes made when an administrator is prompted to reset an expired password, and changes initiated by the administrator on the My Account page in the Admin Portal or through the Forget Password? link in the App Catalog.
- Direct Install Activity - Lists information about apps that were downloaded via a direct install URL rather than through the App Catalog.
Resources¶
-
GET/v1/feeds/¶ Return a List of Available Data Feeds
Requires administrator privileges. Authenticate as an Apperian administrator.
Returns a list of all feed names and detailed information about each feed, including columns and any additional parameters that can be included in the feed.
URLs
Environment URL North America https://na01ws.apperian.com/v1/feeds Europe https://eu01ws.apperian.eu/v1/feeds URL Parameters
None
Header Parameter
- X-TOKEN
- (Required) API token or User token (POST /users/authenticate). For more information, see Authentication.
Data Parameters
None
Example
Request
The following request returns a list of all available feeds and associated information.
curl -X GET https://na01ws.apperian.com/v1/feeds --header "X-TOKEN: kEqMb_-2RlG6KmGaK-CZ_w"
Response
{ "app_usage_activity": { "description": "Provides tracked usage information for apps with the App Usage policy applied.", "fields": [ { "description": "App Name", "type": "string", "name": "app_name" }, { "description": "App ID", "type": "string", "name": "app_id" }, { "description": "Version", "type": "string", "name": "version" }, { "description": "Email", "type": "string", "name": "email" }, { "description": "First Name", "type": "string", "name": "first_name" }, { "description": "Last Name", "type": "string", "name": "last_name" }, { "description": "User ID", "type": "string", "name": "user_id" }, { "description": "Date", "type": "date", "name": "date" }, { "description": "Device ID", "type": "string", "name": "device_id" }, { "description": "Device name", "type": "string", "name": "device_name" } ], "path": "/v1/feeds/app_usage_activity", "filter_params": [ { "name": "start_date" "required": false, "type": "date", "description": "Start Date" } ] }, ... }
-
GET/v1/feeds/(feed_name)/field_info¶ Return Feed Information
Requires administrator privileges. Authenticate as an Apperian administrator.
Returns information about the columns and additional parameters that can be included in the feed (but no actual data). Depending on the particular feed, additional parameters may be included; see filter_params in the response to determine which parameters can be used (they are also documented below).
URLs
Environment URL North America https://na01ws.apperian.com/v1/feeds/<feed_name>/field_info Europe https://eu01ws.apperian.eu/v1/feeds/<feed_name>/field_info URL Parameters
- feed_name
(Required) Name of the data feed. Enter the name exactly as it appears in this list:
app_usage_activitydownload_activitydownload_activity_latest_versionslogin_activitysigning_activitypassword_change_activitydirect_install_activity
Header Parameter
- X-TOKEN
- (Required) API token or User token (POST /users/authenticate). For more information, see Authentication.
Data Parameters
None
Example
Request
The following request returns detailed information about the app_usage_activity feed, which includes a list of data columns and additional filter parameters.
curl -X GET "https://na01ws.apperian.com/v1/feeds/app_usage_activity/field_info \ --header "X-TOKEN: eTg8ktZXRqKIBJTHunwP6A"
Response
{ "app_usage_activity": { "fields": { "first_name": { "type": "string", "description": "First Name" }, "last_name": { "type": "string", "description": "Last Name" }, "user_id": { "type": "string", "description": "User ID" }, "app_name": { "type": "string", "description": "App Name" }, "app_id": { "type": "string", "description": "App ID" }, "device_name": { "type": "string", "description": "Device name" }, "version": { "type": "string", "description": "Version" }, "date": { "type": "date", "description": "Date" }, "email": { "type": "string", "description": "Email" }, "device_id": { "type": "string", "description": "Device ID" } }, "path": "/v1/feeds/app_usage_activity", "filter_params": [ { "name": "start_date", "required": false, "type": "date", "description": "Start Date" } ], "description": "App launch events, for apps wrapped with the App Usage policy" } }
-
GET/v1/feeds/(feed_name)/¶ Return Feed Data
Requires administrator privileges. Authenticate as an Apperian administrator.
Returns the raw data contained in a specified feed.
Each feed returns a fixed amount of data in blocks, so to retrieve the entire data set for a particular feed you may need to send multiple requests. Every response includes a
block_tokenwhich you can use in subsequent requests to continue retrieving data at the exact point where the previous response ended.URLs
Environment URL North America https://na01ws.apperian.com/v1/feeds/<feed_name> Europe https://eu01ws.apperian.eu/v1/feeds/<feed_name> URL Parameters
- feed_name
(Required) Name of the data feed. Enter the name exactly as it appears in this list:
app_usage_activitydownload_activitydownload_activity_latest_versionslogin_activitysigning_activitypassword_change_activitydirect_install_activity
Note
When including more than one of the following parameters in a request, precede the first parameter with
?and subsequent parameters with&.- block_token
- (Optional) Include this parameter to retrieve data beginning at the exact point where the previous response ended. The token value can be found in the response under next_block_token.
- <additional filter parameters>
(Optional) Some additional parameters may be included. The specific additional parameters appear under filter_params when you return /feeds/<feed_name>/field_info, and they are also documented below.
The start_date parameter is present in every feed. It is a date in ISO 8601 format (e.g. YYYY-MM-DD) which filters out any row of data before that date.
Note
If column values include any special characters, they need to be URL encoded. For example, change
jsmith@example.comtojsmith%40example.com. For an ASCII encoding reference, see HTML URL Encoding Reference.
Header Parameter
- X-TOKEN
- (Required) API token or User token (POST /users/authenticate). For more information, see Authentication.
Data Parameters
None
Example for Retrieving Feed Data
Request
The following request returns the first block of raw data for the app_usage_activity feed starting on the date: 2017-11-29. Note the
next_block_tokenvalue at the end of the request - you will include this in your next response to ensure the block of data starts exactly where this one ended.curl -X GET https://na01ws.apperian.com/v1/feeds/app_usage_activity?start_date=2017-11-29 \ --header "X-TOKEN: kEqMb_-2RlG6KmGaK-CZ_w"Response
{ "end_of_data": true, "rows": [ { "first_name": "James", "last_name": "Black", "user_id": "james_black", "app_name": "My app", "app_id": "org.my.app", "device_name": "nexus", "version": "0.3", "date": "2017-11-29T09:20:25.774804+00:00", "email": null, "device_id": "00:00:00:00:00:00" }, { "first_name": "James", "last_name": "Black", "user_id": "james_black", "app_name": "My app", "app_id": "org.my.app", "device_name": "nexus", "version": "0.3", "date": "2017-11-30T10:30:16.225237+00:00", "email": null, "device_id": "00:00:00:00:00:00" } ], "feed_name": "app_usage_activity", "rows_returned": 2, "next_block_token": "AUxqNUMvN1RPZDRWWXFKUG5NZUY2dEE9PQ==" }
Example for Continued Data Retrieval
Request
The following request returns the first block of raw data for app_usage_activity from the date 2017-11-29, continuing from the exact point where the previous request ended. Note here that the
block_tokenURL parameter includes the value returned bynext_block_tokenfrom the end of the previous example. Repeat this request until you have retrieved all data from the feed.curl -X GET "https://na01ws.apperian.com/v1/feeds/app_usage_activity?start_date=2017-11-29&block_token=AUxqNUMvN1RPZDRWWXFKUG5NZUY2dEE9PQ --header "X-TOKEN: kEqMb_-2RlG6KmGaK-CZ_w"
Response
{ "end_of_data": true, "rows": [ { "first_name": "James", "last_name": "Black", "user_id": "james_black", "app_name": "My app", "app_id": "org.my.app", "device_name": "nexus", "version": "0.3", "date": "2017-11-29T09:20:35.774804+00:00", "email": null, "device_id": "00:00:00:00:00:00" }, { "first_name": "James", "last_name": "Black", "user_id": "james_black", "app_name": "My app", "app_id": "org.my.app", "device_name": "nexus", "version": "0.3", "date": "2017-11-30T10:40:18.156145+00:00", "email": null, "device_id": "00:00:00:00:00:00" } ], "feed_name": "app_usage_activity", "rows_returned": 2, "next_block_token": "AU5tck1XbS9WMVNEdXJBM05BZUdwdmc9PQ==" }