Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

Data view endpoints

Updated on August 5, 2022

DX API lets you manage data views in your custom application. For example, you can use API endpoints to explore metadata and retrieve specific fields, filtered values, and more.

You can use the following endpoints even if your application is based on DX API v1. In such cases, make sure that the authentication setting on the application service package is set appropriately (for more information, see Creating authorization for DX API tests).

Retrieving a list type data view

Endpoint:POST /data_views/{data_view_ID}

The endpoint supports the following use cases:

Use case 1: Retrieving data for a specific set of columns/fields with pagination, filtering, and sorting
Request schema:
Getting data with pagination:
Sample JSON for retrieving data with pagination
Getting data without pagination:
Sample JSON for retrieving data without pagination
  • maxResultsToFetch refers to maximum results to fetch when the data is not paginated. The default and maximum value is 5000.
  • A request that includes both maxResultsToFetch and pageNumber/pageSize generates a validation error.
  • query is optional. If you do not specify it, the parameter is executed as a regular data view.
  • dataViewParameters is optional if the data view doesn't have mandatory parameters.
Query elements:
  • select:
    Sample select element
  • sortBy:
    Sample sortBy element
    • Optional. If you do not specify the element, the query retrieves default data.
    • The default values are sortType: ASC and sortOrder: order of fields.
    • Sorting works for individual fields and aggregated values that are specified in aggregations.
    • If you do not specify a value for aggregations, the fields that you specify in sortBy are added to select and the query fetches the data for those fields.
    • If you specify a value for aggregations, only that value and the fields in select are used for sorting.
  • paging:
    Paging with maxResultsToFetch
    Paging with pageNumber
    • Optional. If you do not specify it, the query applies the value of maxResultsToFetch.
    • If pageSize is greater than 5000, the system runs a validation check.
    • The default values are pageNumber: 1 and pageSize: 100.
    • You can specify either maxResultsToFetch or pageNumber/pageSize.
  • filter:
    Sample filter element
    • In lhs, you can specify any relevant scalar field.
    • In rhs, you can specify the following elements:
      • field – property reference
      • value – string literal
      • values – list of values
    • The following operations are supported:
      • boolean: IS_TRUE, IS_FALSE, IS_NULL, IS_NOT_NULL, EQ, NEQ.
      • string: EQ, NEQ, IN, NOT_IN, IS_NULL, IS_NOT_NULL, STARTS_WITH, NOT_STARTS_WITH, ENDS_WITH, NOT_ENDS_WITH, CONTAINS, NOT_CONTAINS.
      • number, date: EQ, NEQ, IN, NOT_IN, GT, GTE, LT, LTE, ISNULL, ISNOTNULL.
    • All comparators are case-sensitive.
    • To apply filtering that is not case-sensitive to text-based fields, set ignoreCase to true.
    • Date and time fields should follow the RFC-3339 standard.
    • Specifying rhs as any of the following comparators is incorrect and the call ignores it:
      • IS_TRUE
      • IS_FALSE
      • IS_NULL
      • IS_NOT_NULL
    • The IN and NOT_IN comparators identify a list of values (they apply to values).
    • logic supports the AND and OR comparators. The default value is AND.

      The expression supports parentheses, for example: (F1 AND F2) OR (F3 AND F4).

Response schema:
Sample response JSON
  • The response returns the values of pageNumber and pageSize if they are included in paging.
  • For queryable data views without pagination or non-queryable data views, the response includes resultCount and hasMoreResults (only for data views sourced by report definitions, if more results exist).
  • The response ignores fields specified in the report definition that sources the data view.
  • The filters specified in the query are applied in addition to the existing filters in the report definition.
Use case 2: Retrieving aggregated data in a field and optionally grouping the aggregated data in a specific field
Request schema:
Sample request JSON
  • maxResultsToFetch is optional. The default and maximum value is 5000.
  • dataViewParameters is optional if the data view doesn't have mandatory parameters.
  • select, sortBy, and filter are optional.
  • If you specify only aggregations but not select, the call returns all aggregated data without grouping.
Query elements:
aggregations:
Sample aggregations element
  • The following operations are supported: COUNT, MAX, MIN, DISTINCT_COUNT. For number data types, also: SUM, AVG.
  • summaryFunction names are case-sensitive in the query.
  • AverageAge is a unique name for the aggregation which the response returns with the aggregated value.
  • To aggregate data, you specify the list of fields and a function for the summary.
  • Filtering is not supported on aggregation fields.
Response schema:
Sample response JSON
Use case 3: Retrieving unique values from a filtered list
Request schema:
Sample request JSON
Query element:
distinctResultsOnly:
  • Set to “true” to return distinct set of results only.
  • Cannot be specified with aggregation.
  • You can specify either maxResultsToFetch or pageNumber/pageSize.
Use case 4: Retrieving data from a non-queryable data view without query/paging.
Request schema:
Sample request JSON
  • Only list-type data views are supported.
  • The request retrieves the data from a specific data view.
  • The request includes only data view parameters.
  • Data queries and pagination are not supported.
Response schema:
Sample response JSON
hasMoreResults returns a value only if the data view is sourced by a report definition.

Retrieving the count of total results for a specified criteria

Endpoint:POST /data_views/{data_view_ID}/count

Request schema:
Sample request JSON
distinctResultsOnly and filter are optional.
Response schema:
Sample response JSON
  • The maximum value for resultCount is 5000 for queryable data views.
  • hasMoreResults returns value only if the data view is sourced by a report definition.

Retrieving data view metadata which includes data view parameters and list of queryable fields

Endpoint:GET /data_views/{data_view_ID}/metadata

The endpoint supports both queryable and non-queryable data views.

Response schema:
Sample response JSON
  • source returns additional metadata that is related to the data source. For example, local-type picklist fields, prompt lists, source data views, field values, and user reference fields.
  • The response returns a HATEOAS link for data view/field value picklists and user reference fields. The link references the /data_views/{data_view_ID} endpoint.

Retrieving a list of data objects

Endpoint:GET /data_objects

The available values for the type query parameter are case and data.

Response schema:
Sample response JSON
  • Without the query parameter, the response returns all data objects. If you specify the parameter, the response returns only data objects that are related to data types or case types. However, for case types, the response returns dataObjectID as empty.
  • The response returns a HATEOAS link for the default data view metadata.

Data model

The following table categorizes query elements in the Pega-API-DataExploration class:

ElementType
requestPage: Pega-API-DataExploration-Request
queryPage: Embed-DataExploration-Query
selectPageList: Embed-DataExploration-Item
fieldString
sortByPageList: Embed-DataExploration-Item-Sort
typeString
filterPage: Embed-DataExploration-Filter
filterConditionsPageGroup: Embed-DataExploration-FilterCondition
lhsPage: Embed-DataExploration-Item-FilterLhs
comparatorString
rhsPage: Embed-DataExploration-Item-FilterRhs
valueString
valuesPageList: SingleValue-Text
logicString
aggregationsPageGroup: Embed-DataExploration-Item-Aggregation
summaryFunctionString
groupByPageList: Embed-DataExploration-Item-Grouping
sortTypeString
distinctResultsOnlyBoolean
returnTotalResultsCountBoolean
pagingPage: Embed-DataExploration-Pagination
pageNumberNumber
pageSizeNumber
maxResultsToFetchNumber
dataviewParametersPage: any, paramName: paramValue
responsePage: Pega-API-DataExploration-Response
fetchDateTimeDate/Time
dataPageList: any

The following diagram illustrates the data model (the highlighted elements are inherited):

Data view APIs - data model

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us