Projectroles API Documentation

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

Plugins

SODAR plugin point definitions and helper functions for plugin retrieval are detailed in this section.

Plugin point definitions and plugin API for apps based on projectroles

class projectroles.plugins.BackendPluginPoint

Projectroles plugin point for registering backend apps

get_api()

Return API entry point object.

get_statistics()

Return backend statistics as a dict. Should take the form of {id: {label, value, url (optional), description (optional)}}.

Returns

Dict

class projectroles.plugins.ProjectAppPluginPoint

Projectroles plugin point for registering project specific apps

get_extra_data_link(_extra_data, _name)

Return a link for the given timeline label that stars with "extra:".

get_object(model, uuid)

Return object based on the model class and the object’s SODAR UUID.

Parameters

• model – Object model class

• uuid – sodar_uuid of the referred object

Returns

Model object or None if not found

Raise

NameError if model is not found

get_object_link(model_str, uuid)

Return the URL for referring to a object used by the app, along with a label to be shown to the user for linking.

Parameters

• model_str – Object class (string)

• uuid – sodar_uuid of the referred object

Returns

Dict or None if not found

get_project_list_value(column_id, project)

Return a value for the optional additional project list column specific to a project.

Parameters

• column_id – ID of the column (string)

• project – Project object

Returns

String (may contain HTML) or None

get_statistics()

Return app statistics as a dict. Should take the form of {id: {label, value, url (optional), description (optional)}}.

Returns

Dict

get_taskflow_sync_data()

Return data for synchronizing taskflow operations.

Returns

List of dicts or None.

search(search_term, user, search_type=None, keywords=None)

Return app items based on a search term, user, optional type and optional keywords.

Parameters

• search_term – String

• user – User object for user initiating the search

• search_type – String

• keywords – List (optional)

Returns

Dict

update_cache(name=None, project=None, user=None)

Update cached data for this app, limitable to item ID and/or project.

Parameters

• name – Item name to limit update to (string, optional)

• project – Project object to limit update to (optional)

• user – User object to denote user triggering the update (optional)

urls = []

App URLs (will be included in settings by djangoplugins)

class projectroles.plugins.RemoteSiteAppPlugin

Site plugin for remote site and project management

app_permission = 'userprofile.update_remote'

Required permission for displaying the app

description = 'Management of remote SODAR sites and remote project access'

Description string

entry_point_url_id = 'projectroles:remote_sites'

Entry point URL ID

icon = 'cloud'

FontAwesome icon ID string

name = 'remotesites'

Name (slug-safe, used in URLs)

title = 'Remote Site Access'

Title (used in templates)

urls = []

App URLs (will be included in settings by djangoplugins)

class projectroles.plugins.SiteAppPluginPoint

Projectroles plugin point for registering site-wide apps

get_messages(user=None)

Return a list of messages to be shown to users.

Parameters

user – User object (optional)

Returns

List of dicts or and empty list if no messages

projectroles.plugins.change_plugin_status(name, status, plugin_type='app')

Change the status of a selected plugin in the database.

Parameters

• name – Plugin name (string)

• status – Status (int, see djangoplugins)

• plugin_type – Type of plugin (“app”, “backend” or “site”)

Raise

ValueError if plugin_type is invalid or plugin with name not found

projectroles.plugins.get_active_plugins(plugin_type='project_app')

Return active plugins of a specific type.

Parameters

plugin_type – “project_app”, “site_app” or “backend” (string)

Returns

List or None

Raise

ValueError if plugin_type is not recognized

projectroles.plugins.get_app_plugin(plugin_name)

Return active app plugin.

Parameters

plugin_name – Plugin name (string)

Returns

ProjectAppPlugin object or None if not found

projectroles.plugins.get_backend_api(plugin_name, force=False)

Return backend API object.

Parameters

• plugin_name – Plugin name (string)

• force – Return plugin regardless of status in ENABLED_BACKEND_PLUGINS

Returns

Plugin object or None if not found

Models

Projectroles models are used by other apps for project access and metadata management as well as linking objects to projects.

class projectroles.models.AppSetting(*args, **kwargs)

Project and users settings value.

The settings are defined in the “app_settings” member in a SODAR project app’s plugin. The scope of each setting can be either “USER” or “PROJECT”, defined for each setting in app_settings. Project AND user-specific settings or settings which don’t belong to either are are currently not supported.

exception DoesNotExist

exception MultipleObjectsReturned

app_plugin

App to which the setting belongs

get_value()

Return value of the setting in the format specified in ‘type’

name

Name of the setting

project

Project to which the setting belongs

save(*args, **kwargs)

Version of save() to convert ‘value’ data according to ‘type’

sodar_uuid

AppSetting SODAR UUID

type

Type of the setting

user

Project to which the setting belongs

user_modifiable

Setting visibility in forms

value

Value of the setting

value_json

Optional JSON value for the setting

class projectroles.models.AppSettingManager

Manager for custom table-level AppSetting queries

get_setting_value(app_name, setting_name, project=None, user=None)

Return value of setting_name for app_name in project or for user.

Note that project and/or user must be set.

Parameters

• app_name – App plugin name (string)

• setting_name – Name of setting (string)

• project – Project object or pk

• user – User object or pk

Returns

Value (string)

Raise

AppSetting.DoesNotExist if setting is not found

class projectroles.models.Project(*args, **kwargs)

A SODAR project. Can have one parent category in case of nested projects. The project must be of a specific type, of which “CATEGORY” and “PROJECT” are currently implemented. “CATEGORY” projects are used as containers for other projects

exception DoesNotExist

exception MultipleObjectsReturned

description

Short project description

get_children()

Return child objects for the Project sorted by title

get_delegates()

Return RoleAssignments for delegates

get_depth()

Return depth of project in the project tree structure (root=0)

get_full_title()

Return full title of project (just an alias for __str__())

get_members()

Return RoleAssignments for members of project excluding owner and delegates

get_owner()

Return RoleAssignment for owner or None if not set

get_parents()

Return an array of parent projects in inheritance order

get_source_site()

Return source site or None if this is a locally defined project

has_role(user, include_children=False)

Return whether user has roles in Project. If include_children is True, return True if user has roles in ANY child project

is_remote()

Return True if current project has been retrieved from a remote SODAR site

is_revoked()

Return True if remote access has been revoked for the project

parent

Parent category if nested, otherwise null

readme

Project README (optional, supports markdown)

save(*args, **kwargs)

Version of save() to include custom validation for Project

sodar_uuid

Project SODAR UUID

submit_status

Status of project creation

title

Project title

type

Type of project (“CATEGORY”, “PROJECT”)

class projectroles.models.ProjectInvite(*args, **kwargs)

Invite which is sent to a non-logged in user, determining their role in the project.

exception DoesNotExist

exception MultipleObjectsReturned

active

Status of the invite (False if claimed or revoked)

date_created

DateTime of invite creation

date_expire

Expiration of invite as DateTime

email

Email address of the person to be invited

issuer

User who issued the invite

message

Message to be included in the invite email (optional)

project

Project to which the person is invited

role

Role assigned to the person

secret

Secret token provided to user with the invite

sodar_uuid

ProjectInvite SODAR UUID

class projectroles.models.ProjectManager

Manager for custom table-level Project queries

find(search_term, keywords=None, project_type=None)

Return projects with a partial match in full title or, including titles of parent Project objects, or the description of the current object. Restrict to project type if project_type is set. :param search_term: Search term (string) :param keywords: Optional search keywords as key/value pairs (dict) :param project_type: Project type or None :return: List of Project objects

class projectroles.models.ProjectUserTag(*args, **kwargs)

Tag assigned by a user to a project

exception DoesNotExist

exception MultipleObjectsReturned

name

Name of tag to be assigned

project

Project to which the tag is assigned

sodar_uuid

ProjectUserTag SODAR UUID

user

User for whom the tag is assigned

class projectroles.models.RemoteProject(*args, **kwargs)

Remote project relation

exception DoesNotExist

exception MultipleObjectsReturned

date_access

DateTime of last access from/to remote site

get_project()

Get the related Project object

level

Project access level

project

Related project object (if created locally)

project_uuid

Related project UUID

site

Related remote SODAR site

sodar_uuid

RemoteProject relation UUID (local)

class projectroles.models.RemoteSite(*args, **kwargs)

Remote SODAR site

exception DoesNotExist

exception MultipleObjectsReturned

description

Site description

get_access_date()

Return date of latest project access by remote site

get_url()

Return sanitized site URL

mode

Site mode

name

Site name

save(*args, **kwargs)

Version of save() to include custom validation

secret

Secret token used to connect to the master site

sodar_uuid

RemoteSite relation UUID (local)

url

Site URL

user_display

RemoteSite’s link visibilty for users

class projectroles.models.Role(*args, **kwargs)

Role definition, used to assign roles to projects in RoleAssignment

exception DoesNotExist

exception MultipleObjectsReturned

description

Role description

name

Name of role

class projectroles.models.RoleAssignment(*args, **kwargs)

Assignment of an user to a role in a project. One role per user is allowed for each project. Roles of project owner and project delegate assignements might be limited (to PROJECTROLES_DELEGATE_LIMIT) per project.

exception DoesNotExist

exception MultipleObjectsReturned

project

Project in which role is assigned

role

Role to be assigned

save(*args, **kwargs)

Version of save() to include custom validation for RoleAssignment

sodar_uuid

RoleAssignment SODAR UUID

user

User for whom role is assigned

class projectroles.models.RoleAssignmentManager

Manager for custom table-level RoleAssignment queries

get_assignment(user, project)

Return assignment of user to project, or None if not found

class projectroles.models.SODARUser(*args, **kwargs)

SODAR compatible abstract user model

get_full_name()

Return full name or username if not set

sodar_uuid

User SODAR UUID

projectroles.models.assign_user_group(sender, user, **kwargs)

Signal for user group assignment

projectroles.models.handle_ldap_login(sender, user, **kwargs)

Signal for LDAP login handling

App Settings

Projectroles provides an API for getting or setting project and user specific settings.

class projectroles.app_settings.AppSettingAPI

classmethod get_all_defaults(scope, post_safe=False)

Get all default settings for a scope.

Parameters

• scope – Setting scope (PROJECT, USER or PROJECT_USER)

• post_safe – Whether POST safe values should be returned (bool)

Returns

Dict

classmethod get_all_settings(project=None, user=None, post_safe=False)

Return all setting values. If the value is not found, return the default.

Parameters

• project – Project object (can be None)

• user – User object (can be None)

• post_safe – Whether POST safe values should be returned (bool)

Returns

Dict

Raise

ValueError if neither project nor user are set

classmethod get_app_setting(app_name, setting_name, project=None, user=None, post_safe=False)

Return app setting value for a project or an user. If not set, return default.

Parameters

• app_name – App name (string, must correspond to “name” in app plugin)

• setting_name – Setting name (string)

• project – Project object (can be None)

• user – User object (can be None)

• post_safe – Whether a POST safe value should be returned (bool)

Returns

String or None

Raise

KeyError if nothing is found with setting_name

classmethod get_default_setting(app_name, setting_name, post_safe=False)

Get default setting value from an app plugin.

Parameters

• app_name – App name (string, must correspond to “name” in app plugin)

• setting_name – Setting name (string)

• post_safe – Whether a POST safe value should be returned (bool)

Returns

Setting value (string, integer or boolean)

Raise

KeyError if nothing is found with setting_name

classmethod get_setting_def(name, plugin=None, app_name=None)

Return definition for a single app setting, either based on an app name or the plugin object.

Parameters

• name – Setting name

• plugin – Plugin object extending ProjectAppPluginPoint

• app_name – Name of the app plugin (string)

Returns

Dict

Raise

ValueError if neither app_name or plugin are set or if setting is not found in plugin

classmethod get_setting_defs(scope, plugin=False, app_name=False, user_modifiable=False)

Return app setting definitions of a specific scope from a plugin.

Parameters

• scope – PROJECT, USER or PROJECT_USER

• plugin – project app plugin object extending ProjectAppPluginPoint

• app_name – Name of the app plugin (string)

• user_modifiable – Only return modifiable settings if True (boolean)

Returns

Dict

Raise

ValueError if scope is invalid or if if neither app_name or plugin are set

classmethod set_app_setting(app_name, setting_name, value, project=None, user=None, validate=True)

Set value of an existing project or user settings. Creates the object if not found.

Parameters

• app_name – App name (string, must correspond to “name” in app plugin)

• setting_name – Setting name (string)

• value – Value to be set

• project – Project object (can be None)

• user – User object (can be None)

• validate – Validate value (bool, default=True)

Returns

True if changed, False if not changed

Raise

ValueError if validating and value is not accepted for setting type

Raise

ValueError if neither project nor user are set

Raise

KeyError if setting name is not found in plugin specification

classmethod validate_setting(setting_type, setting_value)

Validate setting value according to its type.

Parameters

• setting_type – Setting type

• setting_value – Setting value

Raise

ValueError if setting_type or setting_value is invalid

Common Template Tags

These tags can be included in templates with {% load 'projectroles_common_tags' %}.

Template tags provided by projectroles for use in other apps

projectroles.templatetags.projectroles_common_tags.check_backend(name)

Return True if backend app is available, else False

projectroles.templatetags.projectroles_common_tags.core_version()

Return the SODAR Core version

projectroles.templatetags.projectroles_common_tags.force_wrap(s, length)

Force wrapping of string

projectroles.templatetags.projectroles_common_tags.get_app_setting(app_name, setting_name, project=None, user=None)

Get a project/user specific app setting from AppSettingAPI

projectroles.templatetags.projectroles_common_tags.get_backend_include(backend_name, include_type='js')

Returns import string for backend app Javascript or CSS. Returns empty string if not found.

projectroles.templatetags.projectroles_common_tags.get_class(obj, lower=False)

Return object class as string

projectroles.templatetags.projectroles_common_tags.get_display_name(key, title=False, count=1, plural=False)

Return display name from SODAR_CONSTANTS

projectroles.templatetags.projectroles_common_tags.get_django_setting(name, js=False)

Return value of Django setting by name or None if it is not found. Return a Javascript-safe value if js=True.

projectroles.templatetags.projectroles_common_tags.get_full_url(request, url)

Get full URL based on a local URL

projectroles.templatetags.projectroles_common_tags.get_history_dropdown(project, obj)

Return link to object timeline events within project

projectroles.templatetags.projectroles_common_tags.get_info_link(content, html=False)

Return info popover link icon

projectroles.templatetags.projectroles_common_tags.get_project_by_uuid(sodar_uuid)

Return Project by sodar_uuid

projectroles.templatetags.projectroles_common_tags.get_project_link(project, full_title=False, request=None)

Return link to project with a simple or full title

projectroles.templatetags.projectroles_common_tags.get_project_title_html(project)

Return HTML version of the full project title including parents

projectroles.templatetags.projectroles_common_tags.get_remote_icon(project, request)

Get remote project icon HTML

projectroles.templatetags.projectroles_common_tags.get_user_by_username(username)

Return User by username

projectroles.templatetags.projectroles_common_tags.get_user_html(user)

Return standard HTML representation for a User object

projectroles.templatetags.projectroles_common_tags.get_visible_projects(projects, can_view_hidden_projects=False)

Return all projects that are either visible by user display or by view hidden permission

projectroles.templatetags.projectroles_common_tags.highlight_search_term(item, term)

Return string with search term highlighted

projectroles.templatetags.projectroles_common_tags.render_markdown(raw_markdown)

Markdown field rendering helper

projectroles.templatetags.projectroles_common_tags.site_version()

Return the site version

projectroles.templatetags.projectroles_common_tags.static_file_exists(path)

Return True/False based on whether a static file exists

projectroles.templatetags.projectroles_common_tags.template_exists(path)

Return True/False based on whether a template exists

Utilities

General utility functions are stored in utils.py.

projectroles.utils.build_invite_url(invite, request)

Return invite URL for a project invitation.

Parameters

• invite – ProjectInvite object

• request – HTTP request

Returns

URL (string)

projectroles.utils.build_secret(length=32)

Return secret string for e.g. public URLs.

Parameters

length – Length of string if specified, default value from settings

Returns

Randomized secret (string)

projectroles.utils.get_app_names()

Return list of names for locally installed non-django apps

projectroles.utils.get_display_name(key, title=False, count=1, plural=False)

Return display name from SODAR_CONSTANTS.

Parameters

• key – Key in SODAR_CONSTANTS[‘DISPLAY_NAMES’] to return (string)

• title – Return name in title case if true (boolean, optional)

• count – Item count for returning plural form, overrides plural=False if not 1 (int, optional)

• plural – Return plural form if True, overrides count != 1 if True (boolean, optional)

Returns

String

projectroles.utils.get_expiry_date()

Return expiry date based on current date + INVITE_EXPIRY_DAYS

Returns

DateTime object

projectroles.utils.get_user_display_name(user, inc_user=False)

Return full name of user for displaying.

Parameters

• user – User object

• inc_user – Include user name if true (boolean)

Returns

String

projectroles.utils.set_user_group(user)

Set user group based on user name.