Timeline API Documentation¶
This document contains API documentation for the timeline
app. Included
are functionalities and classes intended to be used by other applications.
Backend API¶
The TimelineAPI
class contains the Timeline backend API. It should be
initialized using the Projectroles.plugins.get_backend_api()
function.
-
class
timeline.api.
TimelineAPI
[source]¶ Timeline backend API to be used by Django apps.
-
static
add_event
(project, app_name, user, event_name, description, classified=False, extra_data=None, status_type=None, status_desc=None, status_extra_data=None)[source]¶ Create and save a timeline event.
- Parameters
project – Project object
app_name – ID string of app from which event was invoked (NOTE: should correspond to member “name” in app plugin!)
user – User invoking the event
event_name – Event ID string (must match schema)
description – Description of status change (may include {object label} references)
classified – Whether event is classified (boolean, optional)
extra_data – Additional event data (dict, optional)
status_type – Initial status type (string, optional)
status_desc – Initial status description (string, optional)
status_extra_data – Extra data for initial status (dict, optional)
- Returns
ProjectEvent object
- Raise
ValueError if app_name or status_type is invalid
-
static
get_event_description
(event, request=None)[source]¶ Return the description of a timeline event as HTML.
- Parameters
event – ProjectEvent object
request – Request object (optional)
- Returns
String (contains HTML)
-
static
get_object_link
(project_uuid, obj)[source]¶ Return an inline HTML icon link for a timeline event object history.
- Parameters
project_uuid – UUID of the related project
obj – Django database object
- Returns
String (contains HTML)
-
static
Models¶
-
class
timeline.models.
ProjectEvent
(*args, **kwargs)[source]¶ Class representing a Project event
-
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶
-
add_object
(obj, label, name, extra_data=None)[source]¶ Add object reference to an event.
- Parameters
obj – Django object to which we want to refer
label – Label for the object in the event description (string)
name – Name or title of the object (string)
extra_data – Additional data related to object (dict, optional)
- Returns
ProjectEventObjectRef object
-
app
¶ App from which the event was triggered
-
classified
¶ Event is classified (only viewable by user levels specified in rules)
-
description
¶ Description of status change (may include {object_name} references)
-
event_name
¶ Event ID string
-
extra_data
¶ Additional event data as JSON
-
project
¶ Project in which the event belongs
-
set_status
(status_type, status_desc=None, extra_data=None)[source]¶ Set event status.
- Parameters
status_type – Status type string (see EVENT_STATUS_TYPES)
status_desc – Description string (optional)
extra_data – Extra data for the status (dict, optional)
- Returns
ProjectEventStatus object
- Raise
TypeError if status_type is invalid
-
sodar_uuid
¶ UUID for the event
-
user
¶ User who initiated the event
-
exception
-
class
timeline.models.
ProjectEventManager
[source]¶ Manager for custom table-level ProjectEvent queries
-
get_object_events
(project, object_model, object_uuid, order_by='-pk')[source]¶ Return events which are linked to an object reference.
- Parameters
project – Project object
object_model – Object model (string)
object_uuid – sodar_uuid of the original object
order_by – Ordering (default = pk descending)
- Returns
QuerySet
-
-
class
timeline.models.
ProjectEventObjectRef
(*args, **kwargs)[source]¶ Class representing a reference to an object (existing or removed) related to a Timeline event status
-
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶
-
event
¶ Event to which the object belongs
-
extra_data
¶ Additional data related to the object as JSON
-
label
¶ Label for the object related to the event
-
name
¶ Name or title of the object
-
object_model
¶ Object model as string
-
object_uuid
¶ Object SODAR UUID
-
exception
-
class
timeline.models.
ProjectEventStatus
(*args, **kwargs)[source]¶ Class representing a Timeline event status
-
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶
-
description
¶ Description of status change (optional)
-
event
¶ Event to which the status change belongs
-
extra_data
¶ Additional status data as JSON
-
status_type
¶ Type of the status change
-
timestamp
¶ DateTime of the status change
-
exception