Reading Data
Introduction
Reading data through the API is a relatively straightforward process once you have gone through the process of retrieving metadata and getting the section name or Id you wish to work with. There are two different methods for accessing data, one for lists of records and another for an individual record.
Lists
To get a list of data for a section, you will be calling the data API. You will need to know the page name and section name or Id that you wish to retrieve data for. You will then be able to build a URL similar to the following;
https://ofd-api.blueprintcpq.net/data/list/quote/61233d68-3fe5-e511-80cd-00155d2d8e03
The first part (https://ofd-api.blueprintcpq.net/data/list/) is always the same. The next parameter is the page name and the final parameter is the section (this can be either the Id or name of the section). Once you call this as a GET request you will receive back a set of data similar to the following;
{
"TotalRecords": 84,
"PageNumber": 1,
"PageSize": 20,
"SortBy": "OurReference",
"SortDirection": "desc",
"IdField": "9c983d68-3fe5-e511-80cd-00155d2d8e03",
"Data": [
{
"Id": "8503d6d4-94ae-4416-b3b6-291e20d9d96e",
"Data": [
{
"Field": "9c983d68-3fe5-e511-80cd-00155d2d8e03",
"FieldName": "Guid",
"Value": "8503d6d4-94ae-4416-b3b6-291e20d9d96e",
"HumanReadableValue": null
},
{
"Field": "a0983d68-3fe5-e511-80cd-00155d2d8e03",
"FieldName": "OurReference",
"Value": "Q002262",
"HumanReadableValue": null
},
{
"Field": "a2983d68-3fe5-e511-80cd-00155d2d8e03",
"FieldName": "CustomerGuid",
"Value": "247d2c2f-c02a-45d1-8147-c5eeb4ce8a42",
"HumanReadableValue": "Test Inc."
},
...
]
},
{
"Id": "cf9bc95c-0041-409f-ab42-0c38af2250d6",
"Data": [
{
"Field": "9c983d68-3fe5-e511-80cd-00155d2d8e03",
"FieldName": "Guid",
"Value": "cf9bc95c-0041-409f-ab42-0c38af2250d6",
"HumanReadableValue": null
},
{
"Field": "a0983d68-3fe5-e511-80cd-00155d2d8e03",
"FieldName": "OurReference",
"Value": "Q002261",
"HumanReadableValue": null
},
{
"Field": "a2983d68-3fe5-e511-80cd-00155d2d8e03",
"FieldName": "CustomerGuid",
"Value": null,
"HumanReadableValue": null
},
...
]
},
{
"Id": "68419b0e-895b-4b56-a061-e376ed21ffee",
"Data": [
{
"Field": "9c983d68-3fe5-e511-80cd-00155d2d8e03",
"FieldName": "Guid",
"Value": "68419b0e-895b-4b56-a061-e376ed21ffee",
"HumanReadableValue": null
},
{
"Field": "a0983d68-3fe5-e511-80cd-00155d2d8e03",
"FieldName": "OurReference",
"Value": "Q002260",
"HumanReadableValue": null
},
{
"Field": "a2983d68-3fe5-e511-80cd-00155d2d8e03",
"FieldName": "CustomerGuid",
"Value": null,
"HumanReadableValue": null
},
...
]
},
...
]
}
As can be seen at the start of the JSON, there is some metadata sent back with the response that defines the field that the records are sorted by, as well as the direction, page size and page number. It is possible to define the page and page size in the request.
If you wish to define the page number in your request, you must add an additional parameter to the end of your URL like follows;
https://ofd-api.blueprintcpq.net/data/list/quote/61233d68-3fe5-e511-80cd-00155d2d8e03/2
The same then applies if you wish to change the size of the page;
https://ofd-api.blueprintcpq.net/data/list/quote/61233d68-3fe5-e511-80cd-00155d2d8e03/2/50
The main bulk of the above example response will be the rows for the list. There is a top level Data property that will contain an array of objects consisting of an Id (the records Id in XaitCPQ) and the field and value properties.
You may also wish to filter the data returned by certain values. This can be performed by applying a filter to the URL. Filters are split into three properties;
- Filters
- Operators
- Values
It is possible to add multiple filters using the following format;
https://ofd-api.blueprintcpq.net/data/list/quote/61233d68-3fe5-e511-80cd-00155d2d8e03?filters[0]=Field&operators[0]=1&values[1]=Value&filters[1]=Field&operators[1]=1&values[1]=Value
It is worth noting that there are a lot of options and combinations available here and it is worth checking the API Reference to see all of them.
Record
As well as lists, you may only want to retrieve data for a single record in XaitCPQ. This is also a relatively straightforward process and very similar to the list method. Again you will need to know the section name or Id but you will also need to know the record Id you wish to get data for. Then you should be able to build a URL similar to the following;
https://ofd-api.blueprintcpq.net/data/quote/61233d68-3fe5-e511-80cd-00155d2d8e03/8503d6d4-94ae-4416-b3b6-291e20d9d96e
This request will return a set of data similar to the following;
{
"Section": "69993d68-3fe5-e511-80cd-00155d2d8e03",
"Data": [
{
"Field": "9c983d68-3fe5-e511-80cd-00155d2d8e03",
"FieldName": "Guid",
"Value": "8503d6d4-94ae-4416-b3b6-291e20d9d96e",
"HumanReadableValue": null
},
{
"Field": "a0983d68-3fe5-e511-80cd-00155d2d8e03",
"FieldName": "OurReference",
"Value": "Q002262",
"HumanReadableValue": null
},
{
"Field": "a2983d68-3fe5-e511-80cd-00155d2d8e03",
"FieldName": "CustomerGuid",
"Value": "247d2c2f-c02a-45d1-8147-c5eeb4ce8a42",
"HumanReadableValue": "Test Inc."
},
...
]
}
As you can see, this is an identical structure to that provided by the list method. It is possible the fields could be different due to the way sections are configured.
If you do not know the section you wish to get data for or you wish to access a page record directly, you can perform a GET request without the section name or section identifier in the URL like follows;
https://ofd-api.blueprintcpq.net/data/quote/8503d6d4-94ae-4416-b3b6-291e20d9d96e
This request can be used in conjunction with the section defaults metadata calls which are documented in the metadata documentation to read, write and update records directly from the page.
Lists related to a record
Finally, as you may have seen throughout XaitCPQ there are often lists of records that are related to the main record (e.g. a Quote has lists of Configurable Items, BOM Items etc.). It is possible to access these related records by specifying the base record as a query string parameter in the URL. The baserecord parameter takes the identifier of the master record. So, in terms of loading the Configurable Items for a Quote, you will produce a URL similar to the following;
https://ofd-api.blueprintcpq.net/data/list/quote/067faf2e-1c0e-4c27-abdb-54e53123bd29?baseRecord=8503d6d4-94ae-4416-b3b6-291e20d9d96e