Custom Pivot API

The custom pivots API allows you to take existing list and pivot reports and represent them as JSON. This enables developers to pull related data from multiple types of records in a single API query.

There are two types of reports that you can pull via this API: list or pivot. See the documentation below for a full explanation of their formats.

The :report_id parameter is the ID of a saved view in Aha!. To find the ID of an existing report, choose the report from the Views -> Saved views dropdown in Aha!. Then take the large number of the end of the URL that looks like: /bookmarks/custom_pivots/6434552458299516367. In this case the :report_id is 6434552458299516367.

List view

GET/api/v1/bookmarks/custom_pivots/:report_id

The list view responds with a JSON object with three attributes: pagination, columns, and rows.

The columns attribute is an array of objects that give detailed information about the columns of the list. The objects include the name of the table, the field, and a human readable title attribute.

The rows attribute is an of array of arrays. Each object within the inner array contains the value of that for a specific column. Each object contains attributes for various representations of the data. The fields are:

  • id: The unique id of the object
  • plain_value: A string representation of the object
  • html_value: An HTML representation of the object. This is the same HTML that is used in Aha! to represent the value in our reports.
  • rich_value: If the object is a reference to another object (such as a tag), the, this will be the object representation. For instance, a tag would be representated as:
    {
      id: "6013053275679792248",
      name: "API"
    }

The third attribute is pagination. This works like everywhere else in the Aha! API and is documented here.

Parameters
NameDescription
report_id The ID of the saved view in Aha! to return data for.
view The type of API response you want. This should either be list or pivot. It defaults to list
Example Request

Pivot view

GET/api/v1/bookmarks/custom_pivots/:report_id

The pivot view is similar to the list view, but is more referential. There are six attributes in the JSON response: top_level_columns, columns, top_level_rows, rows, cells, field_definitions.

The columns attribute is an object where the keys are the unique id of column within the report. Rows and field_definitions have the same referential treamtment. The attributes are the id in order to ease lookup.

Since pivot reports are referential in nature and can be nested, there are top_level_rows and top_level_columns. This allows you to easily iterate throught the nested structure. Each column and row object contain a reference to their parent object (parent_ref). They also contain a set of references to their direct children (child_refs). They also, along with cells, contain a reference to their field definition (via field_definitions_refs).

The field definitions object is an object that acts as a map to look up the definitions of the fields used within the report. Similarly to the list view, these contain table, field, and title attributes.

The cells attribute is a set of nested arrays. The lowest level array is a list of the fields for a specific value. Each element in this set has a row_ref, column_ref, and field_definition_ref which can be used to lookup which column and row this value is representing. Just like the list view, there are multiple formats of the value:

  • id: The unique id of the object
  • plain_value: A string representation of the object
  • html_value: An HTML representation of the object. This is the same HTML that is used in Aha! to represent the value in our reports.
  • rich_value: If the object is a reference to another object (such as a tag), the, this will be the object representation.

There is no pagination with pivot report.

Parameters
NameDescription
report_id The ID of the saved view in Aha! to return data for.
view The type of API response you want. This should either be list or pivot. It defaults to list
Example Request
© 2020 Aha! Labs Inc.All rights reserved