Read Event History

  • Reads event

  • Required security permission - READ (On the event object and custom data store if referenced).

  • HTTP methods supported: GET, POST.

  • Transform, Filter and Sort Output.

Description

This endpoint exposes the geteventhistory function available in the syslib library used to retrieve stored events.

Parameters

Name Type Optional Description

start_time

string

no

The start time (UTC) of the interval to retrieve data for.

end_time

string

no

The end time (UTC) of the interval to retrieve data for.

identifier

string or integer

no

The path or ID of the event object to be queried for historical information. When using the POST method, an array of identifiers can be provided.

data_store

string

yes

Specifies a data store for the query operation. If not specified, this defaults to the System Event Data Store for Master Cores. For Local Cores, this option is required. The value should be an objspec (path or ID), identifying the System object or a Custom Event Store object.

filter

string

yes

To retrieve the event data, a MongoDB "find" call is made. Refer to the MongoDB documentation for details on how to compose filter query expressions. The JSON query expression must be Base64 encoded for use in the url.

sort

string

yes

A MongoDB document as a JSON (dictionary), which specifies sorting for the returned documents. The syntax is identical to the MongoDB sort expression syntax. The JSON sort expression must be Base64 encoded for use in the url.

project

string

yes

A JSON document defining the MongoDB project expression, which specifies the fields to include or exclude from the result set. The JSON project expression must be Base64 encoded for use in the url.

limit

integer

yes

Caps the count of returned events to the number specified. If the limit is not provided, all matching events are retrieved.

skip

integer

yes

Skips over the first "n" matched events.

transformation

string

yes

String indicating the format of the returned data. Options are:

  • none: Data is returned un-altered

  • readable : Append a long name to the document keys. for example, the document root key "c_" becomes "c_Common" in the output.

  • readable_lc : Same as readable except that all the appended names are strictly in lower case.

  • kv : Flattens the output to show only the event "system" properties as a set of "key", "value" pairs.

  • kv_lc : Same as the kv options, with all the keys in lower case.

This field can’t be used when "projection" is also specified.

insights

boolean

yes

Indicates application insights should be included in the response, by default false.

Example

Get the last two events generated by a specific source .

This example shows how to use the readeventhistory API-call to retrieve the last two events raised from any source object with a path starting with /System/Core/Examples

To do so, we will need to provide the following parameters:

  • Mandatory parameters:

    • identifier: In this scenario, the /System/Core/Examples/Demo Data/Events/ScriptEvent1 event object is used.

    • Start and end times: Select an time span of one hour using ISO UTC strings such as "2021-12-08T17:00:00Z" and "2021-12-08T18:00:00Z"

  • Optional parameters:

    • filter: The filter expression will ensure that only the required subset of events are considered.

      {
    "e_.o_.h_.x_.i" : {
        "$regex" : "^/System/Core/Examples",
        "$options" : ""
    }
}

    • sort: Sort the events in descending time order so the most recent ones are at the top.

      {
    "e_.s_.t": -1
}

    • limit: Restrict the query to return only 2 elements.

    • project: To keep the output concise, we’ll remove the _id field from the output, and explicitly ask for the timestamp, message and source tags

      {
    "_id": 0,
    "e_.o_.h_.x_.i": 1,
    "e_.s_.t": 1,
    "e_.c_.m": 1
}

HTTP POST

Let’s consider the POST method first, since it is the easiest to configure:

Request URL

  • /api/v2/readeventhistory

Request body
{
    "items": [
    {
        "p": "/System/Core/Examples/Demo Data/Events/ScriptEvent1"
    }
    ],
    "start_time" : "2021-12-08T17:00:00Z",
    "end_time" : "2021-12-08T18:00:00Z",
    "filter" : {
        "e_.o_.h_.x_.i" : {
            "$regex" : "^/System/Core/Examples",
            "$options" : ""
        }
    },
    "project" : {
        "_id": 0,
        "e_.o_.h_.x_.i": 1,
        "e_.s_.t": 1,
        "e_.c_.m": 1
    },
    "sort" : {
        "e_.s_.t": -1
    }
}
Response body
{
  "items": [
        {
            "events": [
                {
                    "e_": {
                        "s_": {
                            "t": {
                                "$date": "2021-12-10T15:21:17.308+0100"
                            }
                        },
                        "c_": {
                            "m": "script event generator 130.497192382813"
                        },
                        "o_": {
                            "h_": {
                                "x_": {
                                    "i": "/System/Core/Examples/Demo Data/Events/ScriptEventGenerator1"
                                }
                            }
                        }
                    }
                }
            ]
        },
        {
            "e_": {
                "s_": {
                    "t": {
                        "$date": "2021-12-10T15:22:17.312+0100"
                    }
                },
                "c_": {
                    "m": "script event generator 129.135864257813"
                },
                "o_": {
                    "h_": {
                        "x_": {
                            "i": "/System/Core/Examples/Demo Data/Events/ScriptEventGenerator1"
                        }
                    }
                }
            }
        }
    ]
}

HTTP GET

To make the same call using an HTTP GET, all the query parameters need to be provided in the url and the JSON ones have to be Base64 encoded. This results in the in the following URL

Request URL

  • api/v2/readeventhistory?
    start_time=2021-12-08T17%3A00%3A00Z&
    end_time=2021-12-08T17%3A01%3A00Z&
    identifier=%2FSystem%2FCore%2FExamples%2FDemo%20Data%2FEvents%2FScriptEvent1&
    filter=eyAKICAgICJlXy5vXy5oXy54Xy5pIiA6IHsgCiAgICAgICAgIiRyZWdleCIgOiAiXi9TeXN0ZW0vQ29yZS9FeGFtcGxlcyIsCiAgICAgICAgIiRvcHRpb25zIiA6ICIiICAKICAgIH0gCn0g&
    sort=eyAKICAgICJlXy5zXy50IjogLTEKfQ%3D%3D&
    project=eyAKICAgICJfaWQiOiAwLAogICAgImVfLm9fLmhfLnhfLmkiOiAxLCAKICAgICJlXy5zXy50IjogMSwgCiAgICAiZV8uY18ubSI6IDEgCn0%3D&limit=1&transformation=%22readable%22