Timeline API Documentation¶
This document contains API documentation for the timeline
app. Included
are functionalities and classes intended to be used by other applications.
NOTE: When viewing this document in GitLab critical content will by default be missing. Please click “display source” if you want to read this in GitLab.
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