Retrieving record data

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

Data endpoint

In order to get data for a record, you need to start building the URL for the Knowledge Model and record you 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 you want to query. You can get it through the schema endpoints.
  • <record_id> id for the record. You can get this through the schema endpoints.

Specifying the fields that you want to consume

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

Call fields to one of the following:

  • Attributes
  • Augmented Attributes
  • Flags

In order to specify which fields you want to get data for, you need to pass a fields query parameter and specify the list of field ids that you previously got from the record schema endpoint separated by commas. For example, if you want to get the data for three fields called ID, ACTIVITIES and EVENTTIME, then you 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 you will see in following sections, you can sort the returned information. This parameter will show you which sort criteria is being used.
  • content: Contains the data for the record that is being requested
    • header: If you 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, you got two rows of data. The first one corresponds with the activity "Put in the oven" that has an id equal to 1 and happened on 2015-05-01. According to the headers you should be able to filter and sort by any of the headers (id, activities or eventtime).

Sorting the data

For this example, you can see that the activities are not correctly ordered. You would like to have "Roll out the dough" first and then "Put in the oven" second. To achieve this, you can 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 this example you wanted to sort by id, so you 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 you have hundreds or thousands of rows being returned by your query. How can you filter the entries that you are interested in?

There are two 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, you could have a filter with an id "rolloutthe_dough" that filters all the entries that have an activity with the name "Roll out the dough".

If you wanted to use this filter in your query, you can simply pass it in the query parameter filters. In your example, you 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 by separating the ids by a comma.

Specifying a filter expression in the request

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

  • field: is the id of the field that you 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 your example, you 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 this 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.