Timeline Django API Documentation

This document contains Django API documentation for the timeline app. Included are functionalities and classes intended to be used by other applications.

Backend API

The backend API can be retrieved as follows.

from projectroles.plugins import get_backend_api
app_alerts = get_backend_api('timeline_backend')

Make sure to also enable timeline_backend in the ENABLED_BACKEND_PLUGINS Django setting.

class timeline.api.TimelineAPI

Timeline backend API to be used by Django apps.

classmethod add_event(project, app_name, user, event_name, description, classified=False, extra_data=None, status_type=None, status_desc=None, status_extra_data=None, plugin_name=None)

Create and save a timeline event.

Parameters:

• project – Project object or None

• app_name – Name of app from which event was invoked (must correspond to “name” attribute of app plugin)

• user – User invoking the event or None

• 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)

• plugin_name – Name of plugin to which the event is related (optional, plugin with the name of the app is assumed if unset)

Returns:

ProjectEvent object

Raise:

ValueError if app_name or status_type is invalid

classmethod get_event_description(event, plugin_lookup=None, request=None)

Return the description of a timeline event as HTML.

Parameters:

• event – ProjectEvent object

• plugin_lookup – App plugin lookup dict (optional)

• request – Request object (optional)

Returns:

String (contains HTML)

classmethod get_models()

Return project event model classes for custom/advanced queries.

Returns:

ProjectEvent, ProjectEventObjectRef

classmethod get_object_link(obj, project=None)

Return an inline HTML icon link for a timeline event object history.

Parameters:

• obj – Django database object

• project – Related Project object or None

Returns:

String (contains HTML)

classmethod get_object_url(obj, project=None)

Return the URL for a timeline event object history.

Parameters:

• obj – Django database object

• project – Related Project object or None

Returns:

String

classmethod get_project_events(project, classified=False)

Return timeline events for a project.

Parameters:

• project – Project object

• classified – Include classified (boolean)

Returns:

QuerySet

Models

Models for the timeline app

class timeline.models.ProjectEvent(*args, **kwargs)

Class representing a Project event. Can also be a site-wide event not linked to a specific project.

exception DoesNotExist

exception MultipleObjectsReturned

add_object(obj, label, name, extra_data=None)

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

get_status()

Return the current event status

get_status_changes(reverse=False)

Return all status changes for the event

get_timestamp()

Return the timestamp of current status

plugin

Plugin to which the event is related (optional)

project

Project to which the event belongs

set_status(status_type, status_desc=None, extra_data=None)

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 (optional)

class timeline.models.ProjectEventManager(*args, **kwargs)

Manager for custom table-level ProjectEvent queries

find(search_terms, keywords=None)

Return events matching the query.

Parameters:

• search_terms – Search terms (list of strings)

• keywords – Optional search keywords as key/value pairs (dict)

Returns:

QuerySet of ProjectEvent objects

get_object_events(project, object_model, object_uuid, order_by='-pk')

Return events which are linked to an object reference.

Parameters:

• project – Project object or None

• 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)

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

class timeline.models.ProjectEventStatus(*args, **kwargs)

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

get_project()

Return the project for the event

sodar_uuid

UUID for the status

status_type

Type of the status change

timestamp

DateTime of the status change