LinkedIn
Copied!

Table of Contents

Using data view endpoints

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}

Supported use cases:

  1. Use case: Retrieving data for a specific set of columns/fields with pagination, filtering, and sorting
  2. Use case: Retrieving aggregated data in a field and optionally grouping the aggregated data in a specific field
  3. Use case: Retrieving unique values from a filtered list
  4. Use case: Retrieving data from a non-queryable data view without query/paging

Use case: 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
Sample JSON for retrieving data with pagination
Sample JSON for retrieving data with pagination
  • Getting data without pagination:
Sample JSON for retrieving data without pagination
Sample JSON for retrieving 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
    Sample select element in a JSON query
    Sample select element
  • sortBy
    Sample sortBy element
    Sample sortBy element
    Sample sortBy element
    • Optional. If you do not specify it, 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 maxResultsToFetch
    paging with maxResultsToFetch
    paging with pageNumber
    paging with pageNumber
    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
    Sample filter element
    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
Sample response JSON
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: Retrieving aggregated data in a field and optionally grouping the aggregated data in a specific field

Request schema:

Sample request JSON
Sample request JSON
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
    Sample aggregations element
    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
Sample response JSON
Sample response JSON

Use case: Retrieving unique values from a filtered list

Request schema:

Sample request JSON
Sample request JSON
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: Retrieving data from a non-queryable data view without query/paging

Request schema:

Sample request JSON
Sample request JSON
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
Sample response JSON
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
Sample request JSON
Sample request JSON
  • distinctResultsOnly and filter are optional.

Response schema:

Sample response JSON
Sample response JSON
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 

  • Both queryable and non-queryable data views are supported.

Response schema:

Sample response JSON
Sample response JSON
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
Sample response JSON
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:

Element Type
request Page: Pega-API-DataExploration-Request
query Page: Embed-DataExploration-Query
select PageList: Embed-DataExploration-Item
field String
sortBy PageList: Embed-DataExploration-Item-Sort
type String
filter Page: Embed-DataExploration-Filter
filterConditions PageGroup: Embed-DataExploration-FilterCondition
lhs Page: Embed-DataExploration-Item-FilterLhs
comparator String
rhs Page: Embed-DataExploration-Item-FilterRhs
value String
values PageList: SingleValue-Text
logic String
aggregations PageGroup: Embed-DataExploration-Item-Aggregation
summaryFunction String
groupBy PageList: Embed-DataExploration-Item-Grouping
sortType String
distinctResultsOnly Boolean
returnTotalResultsCount Boolean
paging Page: Embed-DataExploration-Pagination
pageNumber Number
pageSize Number
maxResultsToFetch Number
dataviewParameters Page: any, paramName: paramValue
response Page: Pega-API-DataExploration-Response
fetchDateTime Date/Time
data PageList: any

The following diagram illustrates the data model (the fields marked yellow are inherited):

Data view APIS - data model
Data view APIS - data model
Data view APIS - data model
Suggest Edit
Did you find this content helpful?

Have a question? Get answers now.

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