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

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)

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)

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)

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 get_object_url(project_uuid, obj)

Return the URL for a timeline event object history.

Parameters

• project_uuid – UUID of the related project

• obj – Django database object

Returns

String

static get_project_events(project, classified=False)

Return timeline events for a project.

Parameters

• project – Project object

• classified – Include classified (boolean)

Returns

QuerySet

Models

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

Class representing a Project event

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_current_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

project

Project in 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

class timeline.models.ProjectEventManager

Manager for custom table-level ProjectEvent queries

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

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)

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

status_type

Type of the status change

timestamp

DateTime of the status change