AggregationCatalog

Quick Links

Accounts Accounting Entries Products Customers Sales quotes Sales invoices Suppliers Purchase invoices

Description

The aggregationCatalog operation exposes a ready-to-use list of aggregation capabilities available in Sage Active.

It is designed to simplify the way aggregations are discovered and executed by providing a predefined catalog of possible aggregations, their grouping options, filters, and available value columns.

This approach allows clients to obtain meaningful aggregated results without needing to understand or configure the underlying business queries.

For more advanced or highly specific aggregation scenarios, it is still possible to use the historical aggregation mechanism described in aggregations.

This operation does not return business data.
It returns metadata describing how aggregations can be performed across multiple domains such as:

This catalog is used to dynamically discover:

Most importantly, this catalog is the single source of truth for building valid calls to the aggregationExecute operation.

Each value returned in the catalog must be reused as-is when calling aggregationExecute.
Any value not explicitly returned by this catalog must be considered invalid.

These are not technical codes but the exact expected input values.

Functionality
Input Parameters
Response

The service returns the catalog entries in the definitions field.
Each definition describes how an aggregation can be executed.

The following aggregation contexts are currently available through the catalog:

This list may evolve over time as new aggregation capabilities are added.

This operation returns static business metadata that can be filtered using contextContains.
There is no pagination and no edges/nodes pattern.

Key Value
Authorization Bearer Current access Token How to find?
x-api-key Primary or secondary subscription key of your app How to find?
GraphQL Query
query {
  aggregationCatalog(contextContains: "Accounting Entry") {
    definitions {
      entityKey
      context
      aggregationTypes
      periodTypes
      filters
      groupBy { name title1 title2 }
      valueColumns
      distinctCounts
      searchScopes
    }
  }
}
Example Response
{
  "data": {
    "aggregationCatalog": {
      "definitions": [
        {
          "entityKey": "queryAggregateAccountingEntryLines",
          "context": "Accounting Entry Lines by Account",
          "aggregationTypes": ["SUM", "AVG", "MIN", "MAX", "DISTINCTCOUNT", "COUNT"],
          "periodTypes": ["Day", "Week", "Month", "Quarter", "Year"],
          "filters": ["All accounts", "Charges & Revenues", "Charges", "Revenues", "Suppliers & Customers"],
          "groupBy": [
            { "name": "None", "title1": null, "title2": null },
            { "name": "Account Code", "title1": "Account Code", "title2": "Account Name" },
            { "name": "First 2 Digits", "title1": "First 2 Digits", "title2": "" },
            { "name": "First 3 Digits", "title1": "First 3 Digits", "title2": "" }
          ],
          "valueColumns": ["Debit", "Credit"],
          "distinctCounts": ["Accounting Entries", "Accounting Exercises", "Journal Types"],
          "searchScopes": ["CustomerId", "ProductId"]
        },
        {
          "entityKey": "queryAggregateAccountingEntryLinesByJournal",
          "context": "Accounting Entry Lines by Journal",
          "aggregationTypes": ["SUM", "AVG", "MIN", "MAX", "DISTINCTCOUNT", "COUNT"],
          "periodTypes": ["Day", "Week", "Month", "Quarter", "Year"],
          "filters": ["All Journals","Charges & Revenues","Charges, Revenues, Financial"],
          "groupBy": [
            {"name": "Journal Code","title1": "Journal Code","title2": "Journal Name"},
            {"name": "Journal Type","title1": "Type","title2": ""}
          ],
          "valueColumns": ["Debit", "Credit"],
          "distinctCounts": ["Accounting Entries","Accounts Used","Accounting Exercises"],
          "searchScopes": ["CustomerId", "ProductId"]
        }
      ]
    }
  }
}

aggregationCatalog Input parameters

Fields Type Description
contextContains String Filters aggregation definitions by matching the value against context
Info

  • contextContains
    Optional free-text filter used to restrict the aggregation catalog results based on the aggregation context.
    When provided, only aggregation definitions whose context contains the given value are returned.

    • narrow down the catalog to a functional domain (for example: Accounting, Sales)
    • simplify discovery when many aggregation definitions are available

    This filter applies only to the catalog metadata.
    It does not affect aggregation execution or business data.

aggregationCatalog Response

Fields Type Description
definitions[] AggregationDefinition List of available aggregation catalog definitions

Definition fields

Fields Type Description
entityKey String Technical identifier of the aggregation
context String Human readable description
aggregationTypes[] [String] Aggregation operations to reuse as-is
periodTypes[] [String] Supported period values to reuse as-is
filters[] [String] Predefined filters to reuse as-is
groupBy[] [GroupByItem] Available grouping definitions
valueColumns[] [String] Columns that can be aggregated to reuse as-is
distinctCounts[] [String] Distinct count metrics to reuse as-is
searchScopes[] [String] Allowed scopes for ID-based search execution

GroupBy Response

Fields Type Description
name String Value to reuse as-is in aggregationExecute
title1 String First display label
title2 String Second display label
Info

  • definitions
    The catalog response contains a list of aggregation definitions.
    Each definition describes exactly which input values are allowed when executing an aggregation using aggregationExecute.

    Each definition includes:

    • entityKey
      Technical identifier of the aggregation to reuse as-is as entityKey in aggregationExecute

    • context
      Human-readable description of the aggregation purpose.

    • aggregationTypes[]
      List of allowed aggregation operations to reuse as-is as aggregationType in aggregationExecute
      (for example: SUM, AVG, MIN, MAX, COUNT, DISTINCTCOUNT).

    • periodTypes[]
      Supported time grouping values to reuse as-is as periodType in aggregationExecute
      (for example: Day, Week, Month, Quarter, Year, None).

    • filters[]
      Predefined business filters that can be reused as-is as filterName in aggregationExecute

    • groupBy[]
      Available business grouping definitions to reuse as-is as groupByName in aggregationExecute
      The special value “None” represents a grand total without business grouping.

    • valueColumns[]
      Value columns that can be aggregated and reused as-is as valueColumn1 or valueColumn2 in aggregationExecute.

    • distinctCounts[]
      Metrics that can be used when aggregationType is DISTINCTCOUNT as-is as distinctCountName in aggregationExecute

    • searchScopes[]
      Optional list of supported entity scopes for ID-based restriction.
      When present, these values indicate that the aggregation can be restricted using the search (and optional searchScope) parameter in aggregationExecute.