Retrieving record data

Once we understand how the schema endpoints work, we are ready to start getting data for the records.

Data endpoint

In order to get data for a record we need to start building the URL for the Knowledge Model and record we want to consume. This URL should follow this pattern: https://<team>.<cluster>.celonis.cloud/intelligence/api/knowledge-models/<km_id>/records/<record_id>/data where:

  • <team> is the name for your team in the EMS
  • <cluster> the cluster assigned for you (i.e. us-2, eu-3, etc.)
  • <km_id> the id for the Knowledge Model we want to query. We can get it through the schema endpoints.
  • <record_id> id for the record. We can get this through the schema endpoints.

Specifying the fields that we want to consume

The above URL won't do much on its own. We need to specify the list of fields that we want to consume.

We call fields to one of the following:

  • Attributes
  • Augmented Attributes
  • Flags

In order to specify which fields we want to get data for, we need to pass a fields query parameter and specify the list of field ids that we previously got from the record schema endpoint separated by commas. For example, if we want to get the data for 3 fields called ID, ACTIVITIES and EVENTTIME, then we need to specify the query parameter in the following way: fields: ID, ACTIVITIES, EVENTTIME. Keep in mind that the ids are case sensitive. In Postman, this should look like this:

Fields parameter

If the information is correct, you should get a response like this:

Copy
Copied
{
  "page": 0,
  "pageSize": 50,
  "total": 2,
  "sort": [],
  "content": {
    "headers": [
      {
        "id": "ID",
        "name": "Id",
        "type": "integer",
        "format": ",.0f",
        "aggregation": false,
        "filterable": true,
        "sortable": true
      },
      {
        "id": "EVENTTIME",
        "name": "Eventtime",
        "type": "date",
        "format": "%Y-%m-%d",
        "aggregation": false,
        "filterable": true,
        "sortable": true
      },
      {
        "id": "ACTIVITIES",
        "name": "Activities",
        "type": "string",
        "aggregation": false,
        "filterable": true,
        "sortable": true
      }
    ],
    "data": [
      {
        "EVENTTIME": "2015-05-01",
        "ACTIVITIES": "Put in the oven",
        "ID": 1
      },
      {
        "EVENTTIME": "2015-05-01",
        "ACTIVITIES": "Roll out the dough",
        "ID": 0
      }
    ]
  }
}

Let's analyze the response:

  • page: As you have probably noticed for other endpoints, most of the information that the Intelligence API returns is paginated. You can navigate through the different pages, changing the value of this parameter.
  • pageSize: Lets you specify the size of the page with the results. The default value is 50.
  • total: Tells you total number of entries that are being returned by your query to the data endpoint.
  • sort: As we will see in following sections, we can sort the returned information. This parameter will show you which is the sort criteria being used.
  • content: Contains the data that for the record that is being requested
    • header: If we consider the data returned as a table, then the list of fields that you are passing will be the headers. This attribute will also tell you the format that this field has and other information like for example if it's filterable or sortable.
    • data: Contains the actual data that corresponds to each of the header/fields that were specified.

So, for the example above, we got 2 rows of data. The first one corresponds with the activity "Put in the oven" that has an id equals to 1 and it happened on 2015-05-01. According to the headers we should be able to filter and sort by any of the headers (id, activities or eventtime).

Sorting the data

For our example, you can see that the activities are not correctly ordered. We would like to have "Roll out the dough" first and then "Put in the oven" second. In order to achieve this, we could sort the data by the ID.

For the data endpoint, you can specify a sort query parameter with the fields that you would like to use for sorting. These fields need to be separated by a comma. You can also specify if you want that field to be sorted ascending or descending. If you want the field to be sorted ascending you need to prepend a + character to the name of the field, whereas if you want the field to be sorted descending you will need to prepend a - character. For example: sort: +id, -Activities will sort the data first by id ascending and then it will sort it by the activity names in a descending way.

In our example we simply wanted to sort by id, so we can just specify the following query parameter sort: id. Notice that the + character is optional, as it is the default criteria if no criteria is specified.

Filtering the data

Now, let's imagine we have hundreds or thousands of rows being returned by our query. How can we filter the entries that we are interested in?

There are basically 2 ways:

  • Using one or more Knowledge Model filter/s.
  • Specifying a filter expression in the request.

Using one or more Knowledge Model filter/s

Your Knowledge Model may already contain some filters. These filters can be retrieved by the filters schema endpoint. For example, we could have a filter with an id "rolloutthe_dough" that filters all the entries that have an activity with name "Roll out the dough".

If we wanted to use this filter in our query, we can simply pass it in the query parameter filters. In our example, we can filter only the "Roll out the dough" entries with the query parameter filters: roll_out_the_dough. Similar to the fields or sort, you can specify more than one filter, simply separating the ids by a comma.

Specifying a filter expression in the request

If we wanted to filter the entries that contain an activity called "Roll out the dough", we could also specify a filter expression in our request. The filter expressions follow the pattern field operator value, where:

  • field: is the id of the field that we want to filter.
  • operator: is one of the following operators eq(=), gt(>), lt(<), ne(!=), ge(>=), le(<=), is(IS) and in(IN) .
  • value: is a constant like 'Roll out the dough'.

So, in our example, we could achieve the same result as using a Knowledge Model filter by specifying the following query parameter: filterExpr: ACTIVITIES eq 'Roll out the dough'.

It is also possible to combine filters with logical operators, parenthesis and some OData predictors

  • and, or, not
  • startswith, endswith, contains

These predictors have the following structure

  • predictor is an OData predicator's name
  • field is a filterable attribute, augmented attribute or flag of a record. This value is case-sensitive and should be equal to the attribute id.
  • value is a constant, such as a Salesforce Opportunity ID or a text.

In our example, another way to achieve the same result is by using a predictor specifying the following query parameter: filterExpr: startswith(ACTIVITIES,'Roll out the dough'). You can specify multiple filter expressions, simply separating them by a comma or combining them with logical operators.

Hopefully, with this information, you should now be able to get, sort and filter all the record data that you need. If you got this far, we would like to hear from you. Have you found any limitation or something tha you would like us to improve? If so, please fill our feedback form that will help us to improve our API.