This documentation supports the 21.3 version of BMC Helix Innovation Studio.

To view an earlier version, select the version from the Product version menu.

Retrieving record instances using REST API

The RecordInstanceDataPageQuery REST API is used to retrieve record instances from any record definition based on certain filtering conditions or query predicates.

Use the following syntax for RecordInstanceDataPageQuery:

<<URL>>/api/rx/application/datapage/?dataPageType=com.bmc.arsys.rx.application.record.datapage.RecordInstanceDataPageQuery
&pageSize=<<any valid number as pageSize>>
&startIndex=<<any valid number as startIndex>>
&recorddefinition=<<fully qualified name of the recorddefinition>>
&propertySelection=<<comma separated fieldIds>>
&sortBy=<<comma separated fieldIds>>
&<<fieldID>>=<<fieldvalue>>

Which includes the following parameters:

ParameterDescription
dataPageType
  • Specifies the fully qualified class name of the RecordInstanceDataPageQuery.
  • This is a mandatory query parameter. 

Note: Do not change the value of this parameter.

pageSize
  • Specifies how many records should be fetched in this page.
  • This is a mandatory query parameter.
startIndex
  • Specifies the first record's index of the "page".  
  • This is a mandatory query parameter.

For example:

  • If startIndex=0 and pageSize=50, the dataPageQuery will return the first 50 records from the dataset.  
  • If startIndex=50 and pageSize=50, then the dataPageQuery will return the records 50 - 100 from the dataset.
  • If startIndex=500 and pageSize=50, then the dataPageQuery will return the records 500 - 550 from the dataset.
  • If pageSize=-1, then all records are returned. Be careful when using this option because it may return a very large number of records.
recorddefinition
  • Specifies the name of the record definition.
  • This is a mandatory query parameter.

propertySelection

  • Specifies the list of comma separated properties which should appear in the response object, that is, the DataPage.data.
  • The propertySelection parameter accepts numeric fieldIds.

  • This is an optional query parameter.

For example,

  • &propertySelection=1,2,4,7
    Here, we used only the fieldIds in the propertySelection.
sortBy
  • Specifies the list of comma separated properties by which data should get sorted.
  • The sortBy parameter accepts numeric fieldIds.
  • To indicate descending sort, prefix the value with hyphen (-).
  • This is an optional query parameter.

For example:

  • To sort the data in an ascending order, specify the setting as sortBy = 1,2.
    This means that the data is sorted in the ascending order of property ID 1 then by 2.
  • To sort the data in a descending order, specify the setting as sortBy=-3,-7.
    This means that the data is sorted in the descending order of property Id 3 then by status.
  • To sort the data in an ascending and descending order, specify the setting as sortBy=1,-3,7.
    This means that the data is sorted in the ascending order of property Id 1 then by descending order of property Id 3 and
     then by ascending order of property status.

fieldId

  • Specifies the filtering condition of the query, using field IDs of the record definition.
  • You can specify multiple name-value pairs and the relational qualification between these name-value pairs is always set as AND.
  • This is an optional query parameter.

For example:

  • &7=new
    This means that retrieve only those records whose 'status' field's value is new.
  • &7=new&name=Jack
    This means that retrieve only those records whose 'status' field's value is new and 'name' field's value is Jack.
queryExpression
  • Specifies complex queries that should be supported by RecordInstanceDataPageQuery.
  • You can specify attribute Id in place of attribute name.
  • You can specify the existing way of adding qualifications.
  • Ensure that you follow the URL encoding rules while specifying queryExpression.

For example:

  • To specify complex query supported by RecordInstanceDataPageQuery.
    &queryExpression=('Description' LIKE "%A%" AND 'TaskID' > 29 )&startIndex=0&pageSize=-1
  • To specify atrribute Id for Description and TaskID attribute name.
    &queryExpression=('536870913' LIKE "%A%" AND '536870915' > 29 )&startIndex=0&pageSize=-1
  • To specify the URL encoding rules.
    &queryExpression=('Character Field1' = %27Character Field1%27%3D%22some description%22), where %27 represents ', %3D represents =.

Example 1

To fetch the tasks where the 'status' of the task is new, use the following REST API call:

<<URL>>/api/rx/application/datapage/?dataPageType=com.bmc.arsys.rx.application.record.datapage.RecordInstanceDataPageQuery
&pageSize=500&startIndex=0&recorddefinition=com.example.taskmanager-lib:Task&7=new

In this example, the instances will be fetched from com.example.taskmanager-lib:Task RecordDefinition and 7 is one of the FieldDefinitinition's ID on this RecordDefinition.

Example 2

To fetch the tasks where the 'status' of the task is new and data is to be fetched for fieldIds 1, 8, 7, 379 and the tasks should be sorted on fieldId 1, use the following REST API call:

<<URL>>/api/rx/application/datapage/?dataPageType=com.bmc.arsys.rx.application.record.datapage.RecordInstanceDataPageQuery&
pageSize=500&startIndex=0&recorddefinition=com.example.taskmanager-lib:Task&7=new&propertySelection=1,8,7,379&sortBy=1

In this example, the instances will be fetched from com.example.taskmanager-lib:Task RecordDefinition and 7 is one of the FieldDefinition's ID on this RecordDefinition. 1, 8, 7, 379 are Ids of the FieldDefinitions on this RecordDefinition.

Example 3

To fetch the tasks where the 'Description' of the task is Printing, use the following REST API call:

<<URL>>/api/rx/application/datapage/?dataPageType=com.bmc.arsys.rx.application.record.datapage.RecordInstanceDataPageQuery
&pageSize=500&startIndex=0&recorddefinition=com.example.taskmanager-lib:Task&queryExpression=(%27Description%27%3D%22Printing%22)

In this example, the instances will be fetched from com.example.taskmanager-lib:Task RecordDefinition. 

Related topics

Was this page helpful? Yes No Submitting... Thank you

Comments