Timeline events

Retrieving timeline event objects

A timeline event can be retrieved from a profile. Read out the timeline_events property of the BlueConic profile object to obtain all events from a profile. To prevent retrieving a lot of timeline events, see section Filtering timeline events.

Using timeline events objects

To add a new TimelineEvent to a profile the profile bulk handler can be used. You can only add values for event properties that are defined along with the definition of the event type. Other properties will be ignored.

>>> from blueconic import Client, TimelineEvent
>>> bc = Client()
>>>
>>> # Load an existing profile
>>> profile = bc.get_profile('29b138e2-9824-45c3-ace6-909ee308ceb1')
>>>
>>> # Create a new timeline event
>>> timeline_event = TimelineEvent("myEventTypeId", '2001-1-1T11:20:15Z', 'myId', 'mySource')
>>>
>>> # Set a value for the myProperty property for the new timeline object
>>> timeline_event.set_value('myProperty', 'myPropertyValue')
>>>
>>> # Multiple values can be set using the set_values method
>>> timeline_event.set_values('myMultiValueProperty', [1, 2, 3])
>>>
>>> # Add the timeline object to the profile by using the add_timeline_event() method on the profile
>>> profile.add_timeline_event(timeline_event)
>>>
>>> # Save the updated profile through the profile bulkhandler
>>> with bc.get_profile_bulkhandler(feedback=True) as bh:
>>>     bh.write(profile)

To update an existing TimelineEvent of a profile, the profile bulk handler can be used. You can only change the value for event properties that are defined along with the definition of the event type. Changes to event properties that are unknown, will be ignored.

>>> from blueconic import Client
>>> bc = Client()
>>>
>>> # Load an existing profile including the timeline events
>>> profile = bc.get_profile('myProfileId', include_timeline_events=True)
>>>
>>> # Get the first timeline event of our profile and set the myProperty property to a new value
>>> profile.timeline_events[0].set_value('myProperty', 'myPropertyValue')
>>>
>>> # Save the updated profile through the profile bulkhandler
>>> with bc.get_profile_bulkhandler(feedback=True) as bh:
>>>     bh.write(profile)

Nested properties can be set by providing a dict to the set_value method.

>>> timeline_event.set_value("myProperty", {"myNestedProperty": ["myNestedValue1", "myNestedValue2"]})
class TimelineEvent
__init__(event_type_id, date=None, event_id=None, source=None, properties=None)

This class represents a timeline event.

Parameters:

  • event_id (str) – The event ID

  • date (str or datetime) – The timestamp ISO string or a date object

  • event_type_id (str) – The event type ID

  • source (str) – Source

  • properties (dict) – Properties for this event

get_value(property_id)

Gets the first value of a property.

Parameters:

property_id (str) – The ID of the property to retrieve the value from

Raises:

KeyError – If the ID does not refer to an existing property

Returns:

The first value of the property

Return type:

str

get_values(property_id)

Gets all values of a property.

Parameters:

property_id (str) – The ID of the property to retrieve the values from

Raises:

KeyError – If the ID does not refer to an existing property

Returns:

All the values of the property

Return type:

[str]

set_value(property_id, property_value, set_if_empty=False)

Sets one value for this property. Removes all values that were already present.

Parameters:

  • property_id (str) – The ID of the property

  • property_value (int or str or bool or float or datetime.datetime) – The value to set. All values are cast to a string

  • set_if_empty (bool, optional) – When set to False, the existing value will always be replaced with the new value. Set this parameter to True to set the new value only when there was no value yet present in the property. Defaults to False.

Raises:

KeyError – If the ID does not refer to an existing property

set_values(property_id, property_values, set_if_empty=False)

Sets multiple values for this property. Remove all values that were already present.

Parameters:

  • property_id (str) – The ID of the property

  • property_values ([int or str or bool or float or datetime.datetime]) – A list of values. All values are cast to a string

  • set_if_empty (bool) – When set to False, the existing values will always be replaced with the new values. Set this parameter to True to set the new values only when there were no values yet present in the property. Defaults to False.

property date

Returns the date and time when the event took place.

property event_type_id

Returns the event type ID (e.g. PAGEVIEW, CLICK) of this timeline event.

property id

Returns the event ID of this timeline event.

property properties

Returns the properties of this object.

property property_ids

Returns the property IDs of this object.

property source

Returns the source of this timeline event.