Document Context

Note

To work efficiently with the Document Context, you want to use object instead of the JSON-like one. Please read through DocumentContext.md directly (select different version if needed).

Document context is an object that carries all information related to a FAIR Wizard project in order to produce a document. To investigate it, it is the best to use Questionnaire Report template with JSON format. The core fields are:

  • config = object with FAIR Wizard configuration related to documents, e.g., clientUrl for referring to the FAIR Wizard instance

  • document = object with the details about the document

    • createdAt = when the document was created (initial creation, not final generation of the document)

    • createdBy = user that created the document

    • documentTemplateId = ID of the document template used of the document

    • formatUuid = UUID of the format in the document template

    • name = name of the document (entered when creating, not file name)

    • uuid

  • extras = additional data added by document worker if requested

  • groups = groups with access to the project

  • knowledgeModel = object describing used KM for the project

    • annotations = list of key-value annotations of KM top-level entity

    • chapterUuids = list of UUIDs for chapters (ordered)

    • integrationUuids = list of UUIDs for integrations (ordered)

    • metricUuids = list of UUIDs for metrics (ordered)

    • phaseUuids = list of UUIDs for phases (ordered)

    • resourceCollectionUuids = list of UUIDs for resource collections (ordered)

    • tagUuids = list of UUIDs for tags (ordered)

    • entities = contains questions, answers, and other maps with UUID-entity pairs

    • uuid = UUID of the knowledge model

  • metamodelVersion = metamodel version of the document context (document template metamodel version)

  • organization = object describing organization that is using the FAIR Wizard

    • affiliations = list of suggested affiliation within the organization

    • description

    • name

    • organizationId

  • knowledgeModelPackage = object with metadata about the KM package such as version, name, or description

  • project = object representing the project

    • createdAt = when the project was created

    • createdBy = original author who created the project

    • description = optional description of the project

    • files = list of project files (each has uuid, fileName, fileSize, and contentType)

    • labels = path-list map of labels on questions (i.e. TODOs)

    • name = name of the project

    • phaseUuid = UUID of the current phase selected

    • replies = path-object map of replies to questions

    • updatedAt = when the project was last updated

    • uuid = UUID of the project

    • versionUuid = optional UUID of the current version of the project

    • versions = ordered list of project versions (objects with details)

  • report = object that contains report for the project that contains computed information about number of answered questions as well as metric values

  • users = users with access to the project (each entry contains perms list and user object)

This structure is provided to a Jinja template in Step: jinja and outputted from Step: json. We can use the JSON step to observe the actual content of the document context (structure as well as the values). Finally, we can also check Metamodel Schemas (the relevant JSON schema for document context).

Objectified Document Context

It is possible to easily turn the JSON-like / tree-structured document context into objects with additional helper relations, attributes, methods, and many more to ease up the template development:

{%- set dc = ctx|to_context_obj -%}

  • All data types are using Python, e.g., str is textual string, Optional[str] is a string or None, list[str] is a list of strings.

  • We use snake_case for naming of attributes and variables, PascalCase is used for class names.

  • datetime is the standard datetime module.

Diagram

We provide the structure visualized on a class diagram (right-click and open in to tab to enlarge):

document-context-diagram

Entities

Here is an interlinked description of each entity and its attributes and links. There are also aliases that are convenient shorthands to make template more concise.

DocumentContext

Aliases:

ContextConfig

  • app_title (str) - passed by backend from Settings

  • app_title_short (str) - passed by backend from Settings

  • client_url (str) - base URL of the FAIR Wizard instance (client app)

  • illustrations_color (str) - passed by backend from Settings

  • logo_url (str) - passed by backend from Settings

  • primary_color (str) - passed by backend from Settings

  • service_domain_name (str)

  • service_name (str)

  • service_name_short (str)

  • service_url (str)

Document

  • uuid (str)

  • name (str)

  • document_template_id (str)

  • format_uuid (str)

  • created_by (User)

  • created_at (datetime)

  • updated_at (datetime)

Organization

  • id (str)

  • name (str)

  • description (Optional[str])

  • affiliations (list[str])

KnowledgeModelPackage

  • id (str) - full ID of KM Package

  • organization_id (str)

  • km_id (str)

  • version (str)

  • versions (list[str])

  • name (str)

  • description (Optional[str])

  • created_at (datetime)

Project

  • uuid (str)

  • name (str)

  • description (Optional[str])

  • version (Optional[ProjectVersion])

  • versions (list[ProjectVersion])

  • phase (Optional[Phase])

  • project_tags (list[str])

  • replies (RepliesContainer)

  • files (dict[str, ``\ :ref:`odc-project-file`\ ``])

  • todos (list[str])

  • created_by (User)

  • created_at (datetime)

  • updated_at (datetime)

ProjectFile

  • uuid (str)

  • name (str)

  • size (int)

  • content_type (str)

  • reply (Optional[FileReply])

  • download_url (str)

ProjectVersion

  • uuid (str)

  • event_uuid (str)

  • name (str)

  • description (Optional[str])

  • created_by (SimpleAuthor)

  • created_at (datetime)

  • updated_at (datetime)

User

  • uuid (str)

  • first_name (str)

  • last_name (str)

  • email (str)

  • image_url (Optional[str])

  • affiliation (Optional[str])

  • created_at (datetime)

  • updated_at (datetime)

UserGroup

  • uuid (str)

  • name (str)

  • description (str)

  • private (bool)

  • members (list[UserMembership])

  • created_at (datetime)

  • updated_at (datetime)

UserMembership

  • uuid (str)

  • first_name (str)

  • last_name (str)

  • gravatar_hash (str)

  • image_url (Optional[str])

  • membership_type (str) - one of: member, owner

SimpleAuthor

  • uuid (str)

  • first_name (str)

  • last_name (str)

  • image_url (Optional[str])

  • gravatar_hash (Optional[str])

UserPermission

  • user (User)

  • permissions (list[str]) - contains: VIEW, COMMENT, EDIT, ADMIN

Helpers:

  • is_viewer (bool)

  • is_commenter (bool)

  • is_editor (bool)

  • is_owner (bool)

GroupPermission

  • group (UserGroup)

  • permissions (list[str]) - contains: VIEW, COMMENT, EDIT, ADMIN

Helpers:

  • is_viewer (bool)

  • is_commenter (bool)

  • is_editor (bool)

  • is_owner (bool)

Report

  • uuid (str)

  • total_report (ReportItem)

  • chapter_reports (list[ReportItem])

  • created_at (datetime)

  • updated_at (datetime)

ReportItem
ReportIndication

  • indication_type (str) - one of: PhasesAnsweredIndication, AnsweredIndication (use alias)

  • answered (int) - number of answered questions

  • unanswered (int) - number of unanswered questions

Aliases:

  • total (int) - answered + unanswered

  • percentage (float) - answered / total (handles zero division, number between 0.0 and 1.0)

  • is_for_phase (bool) - if it is a phase-related indication

  • is_overall (bool) - if it is an overall indication (not phase-related)

ReportMetric

  • measure (float) - number between 0.0 and 1.0

  • metric (Metric)

KnowledgeModel

Aliases:

Notes:

  • Equality of all KM entities is being done using the uuid comparison under the hood.

  • All KM entities that have annotations have also the a alias.

KnowledgeModelEntities

Container holding all types of Knowledge Model entities within UUID-key dictionaries:

Chapter

  • uuid (str)

  • title (str)

  • text (Optional[str]) - possibly Markdown text

  • questions (list[Question])

  • reports (list[ReportItem])

  • annotations (dict[str,str])

Question

Superclass with common attributes for all types of questions. You always get a more specific one and never just a Question.

  • uuid (str)

  • type (str)

  • title (str)

  • text (Optional[str])

  • required_phase (Optional[Phase])

  • is_required (bool) - if the question is required in the current phase

  • replies (dict[str,Reply]) - path-key dictionary of replies to the question

  • experts (list[Expert])

  • references (list[Reference])

  • tags (list[Tag])

  • parent (Union[Chapter,ListQuestion,Answer])

  • annotations (dict[str,str])

Aliases:

Notes:

  • Parent of a question can be of multiple kinds, you may use the of_type test to check what it is if needed.

ValueQuestion

Aliases:

  • is_string (bool)

  • is_text (bool)

  • is_number (bool)

  • is_date (bool)

ValueQuestionValidation

  • type (str)

  • full_type (str)

  • value (str | int | float | None) - based on the type

IntegrationQuestion
OptionsQuestion
MultiChoiceQuestion
ListQuestion
ItemSelectQuestion
FileQuestion

  • max_size (Optional[int]) - maximum file size (in bytes) allowed

  • file_types (Optional[str]) - comma-separated file type specifications

Answer

  • uuid (str)

  • label (str)

  • advice (Optional[str]) - possibly Markdown text

  • metric_measures (list[MetricMeasure])

  • followups (list[Question])

  • parent (OptionsQuestion)

  • annotations (dict[str,str])

MetricMeasure

Indication of how an answer affects a certain metric.

  • measure (float) - value between 0.0 and 1.0 (inclusive)

  • weight (float) - value between 0.0 and 1.0 (inclusive)

  • metric (Metric)

Choice
Expert

  • uuid (str)

  • name (str)

  • email (str)

  • annotations (dict[str,str])

Reference

As for the Question class, Reference is also a superclass and you will always get an object of its subclass.

  • uuid (str)

  • type (str)

  • annotations (dict[str,str])

CrossReference

  • target_uuid (str)

  • description (str)

ResourcePageReference
URLReference

  • label (str)

  • url (str)

ResourceCollection

  • uuid (str)

  • title (str)

  • pages (list[ResourcePage])

  • annotations (dict[str,str])

ResourcePage

  • uuid (str)

  • title (str)

  • content (str)

  • collection (ResourceCollection)

  • annotations (dict[str,str])

Metric

  • uuid (str)

  • title (str)

  • abbreviation (str)

  • description (Optional[str]) - possibly Markdown text

  • annotations (dict[str,str])

Phase

  • uuid (str)

  • title (str)

  • description (Optional[str]) - possibly Markdown text

  • order (int) - order of the phase within the KM

  • annotations (dict[str,str])

Integration

  • uuid (str)

  • name (str)

  • type (str)

  • variables (dict[str,str])

  • annotations (dict[str,str])

ApiIntegration

  • allow_custom_reply (bool)

  • request_method (str)

  • request_url (str)

  • request_headers (dict[str,str])

  • request_body (str)

  • request_allow_empty_search (bool)

  • response_list_field (str)

  • response_item_template (str)

  • response_item_template_for_selection (str)

PluginIntegration

  • plugin_uuid (str)

  • integration_id (str)

  • settings (object) - plugin-specific settings object

Tag

  • uuid (str)

  • name (str)

  • description (Optional[str]) - possibly Markdown text

  • color (str)

  • annotations (dict[str,str])

RepliesContainer

Wrapper around a path-key dictionary of replies.

  • replies (dict[str,Reply])

Operations:

  • X[path: str] (Optional[Reply]) - you can get a reply using square brackets

  • len(X) (int) - number of replies in the container

  • get(path: str) -> Optional[Reply]

  • iterate_by_prefix(path_prefix: str) -> Iterable[Reply] - O(n) iteration with filter

  • iterate_by_suffix(path_suffix: str) -> Iterable[Reply] - O(n) iteration with filter

  • values() -> Iterable[Reply]

  • keys() -> Iterable[str]

  • items() -> ItemsView[str,Reply]

Reply

Superclass with common attributes for all types of replies. You always get a more specific one and never just a Reply.

  • path (str)

  • fragments (list[str]) - UUIDs of the path (starting with chapter)

  • type (str)

  • created_at (datetime)

  • created_by (SimpleAuthor)

  • question (Question) - you can assume more specific type of Question based on a type of Reply

AnswerReply

  • answer (Answer) - selected answer as the option

Aliases:

  • value (str) - UUID of the answer (answer.uuid)

Notes:

MultiChoiceReply

  • choices (list[Choice]) - selected answer as the option

Aliases:

  • value (list[str]) - list of UUIDs of the choices

Notes:

  • question is always OptionsQuestion

  • You can iterate directly over reply object(for choice in reply)

StringReply

  • value (str)

Aliases:

  • as_number (Optional[float]) - tries to cast the value to a number

  • as_datetime (Optional[datetime]) - tries to cast the value to a timestamp

  • markdown_html (str) - renders the value as Markdown and returns HTML

  • markdown_plain (str) - renders the value as Markdown and returns plain text (without formatting)

Notes:

FileReply

  • file_uuid (str)

  • file (Optional[ProjectFile]) - None if file has been deleted

Aliases:

  • value (str) - same as file_uuid

Notes:

ItemListReply

  • items (list[str]) - list of items UUIDs (used in reply paths)

Aliases:

  • value (list[str]) - same as items

Notes:

  • question is always ListQuestion

  • You can iterate directly over reply object (for item in reply)

ItemSelectReply

  • item_uuid (str)

  • item_title (str)

Aliases:

  • value (str) - same as item_uuid

Notes:

IntegrationReply

  • type (str) - one of: PlainType, IntegrationType

  • value (str) - rendered value from integration (or plain reply)

  • raw (Optional[Any]) - returned raw value stored from API or plugin (e.g., JSON object)

Aliases:

  • is_plain (bool) - entered by user ignoring the integration

  • is_integration (bool) - selected by user using the integration