Best Practices for Creating Usage Dashboards with our Analytics API

Overview

With our Analytics endpoint and our shared Mode Reports, customers want to be able to build out their own Guru usage views in their BI tool or replicate those Mode reports. In order to see different views of the usage data based on groups, collections, cards, etc. - customers will need to build out and store data from Guru in relational tables e.g. user to group(s) or card to collection. You can share the following information with customers who are looking to mimic our Mode reports or want to build their own custom reports in their BI or database tools.

Getting Started

If you plan on leveraging our Analytics API to build your own custom reports, you will also want to create and store relational tables that provide context to your usage data. For example, you can see that Gritty@getguru.com viewed a card, but how can you associate Gritty to his Group usage? Or how do you know which Collection the Card is in? This outline is a starting point to ensure you can get the relationships between users and events within your own reports. You may not need to create all these tables for your use case, but these are recommended for making a robust view of usage within your team.

API Access

If you have not already, please obtain a user API Token to get started. Please note that the Analytics API can only be accessed by Admins. If you are not an Admin, you will get a 401 error when trying to request the analytics endpoint. Once you have your API token, you will be able to pull events data from GEThttps://api.getguru.com/api/v1/teams/{TEAMID}/analytics. To get your Team ID, go to your Settings > Apps and Integrations > SSO/SCIM and copy your team ID from there.

Once you request the analytics endpoint, you will see responses for each event type with a similar response as below:

[  {    "type" : "card-viewed",    "user" : "gary.t.goat@getguru.com",    "eventDate" : "2016-01-20T03:10:11.351+0000",    "properties" : {      "cardId" : "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"    }  },  ...]

Group Mapping

The Analytics API Response will give you the user object, but you will need to create a mapping of that user to their designated Groups if you want to see user by Groups. You can use the Members endpoint to get a list of all user ids and each users' associated Groups. Each node will return the user id along with the Group objects each id is associated with:

"userAttributes":{...}"id":"gary.t.goat@getguru.com""user":{...} <-- User info"groups":[...] <-- Associated Groups this User id is in. 

By making a table of user id and associated groups, you can map the "user" object from the Analytics API endpoint to the Groups table you have now created.

collection mapping

The Analytics API Response will give you the cardID under the properties object. If you want to create a view of Card views, copies, favorites, etc by Collection, you will need to create a mapping of the Card ID to what Collection the Card belongs to. To get a list of all Cards metadata, you can make a request to GET https://api.getguru.com/api/v1/cards. This will return all cards under your account.

{     "content":"<h2 class="ghq-card-content__medium-heading" ...",     "id":"2895d5ab-8a10-4e45-bea7-5fc407181c47", !<-- Card ID      "lastModified":"2021-03-23T15:24:50.077+0000",     "owner":{},     "cardType":"CARD",     "teamId":"442b7bfa-db0f-4cb9-80a6-3083ad358369",     "dateCreated":"2021-02-16T21:42:53.383+0000",     "collection":{}, !<-- Collection ID and name objects within this bundle     "lastVerified":"2021-03-23T15:24:50.206+0000",     "lastVerifiedBy":{},     "lastModifiedBy":{},     "htmlContent":true,     "shareStatus":"TEAM",     "preferredPhrase":"Using The Company Wide Framework",     "verificationInterval":90,     "slug":"TRpnpbjc/Using-The-Company-Wide-Framework",     "guruSlateToolsVersion":"0.18.15",     "originalOwner":{},     "verificationState":"TRUSTED",     "verificationType":"RELATIVE",     "verificationReasons":[            ],     "nextVerificationDate":"2021-06-21T15:24:50.206+0000"}

By making a card table, you can quickly spin up different cuts of the analytics data for your usage analysis. You can track usage by Collection, Trust Score by Collection, usage on author's content (i.e. "originalOwner"), list of upcoming cards that will become unverified ("nextVerificationDate"). The possibilities are endless!

Once again, this is just a starting point into building out your own usage dashboards via our Analytics API. If you have more questions around how to set up your own usage dashboards, please reach out to support@getguru.com and we are happy to help!