Skip to content
This repository was archived by the owner on Aug 2, 2022. It is now read-only.

DocumentContext.md

Latest commit

 

History

History
432 lines (300 loc) · 12.6 KB

DocumentContext.md

File metadata and controls

432 lines (300 loc) · 12.6 KB
Raw

Document Context

This document describes the structure of document context provided by the Document Worker to the Jinja templates. Currently, the root object of DocumentContext must be created like this:

{%- set x = 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.datetime.
  • You can investigate the context module; however, constructs that are not documented here may change in any version without an explicit notice.

Diagram

We provide the structure visualized on a class diagram: SVG.

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

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

Document

  • uuid (str)
  • created_at (datetime)
  • updated_at (datetime)

Organization

  • id (str)
  • name (str)
  • description (Optional[str])
  • affiliations (list[str])

Package

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

Questionnaire

QuestionnaireVersion

  • 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)
  • role (str) - one of: admin, dataSteward, researcher
  • image_url (Optional[str])
  • affiliation (Optional[str])
  • permissions (list[str])
  • sources (list[str])
  • created_at (datetime)
  • updated_at (datetime)

SimpleAuthor

  • uuid (str)
  • first_name (str)
  • last_name (str)
  • image_url (Optional[str])
  • gravatar_hash (Optional[str])

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:

💡 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:

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

ValueQuestion
  • value_type (str) - type of value, use alias

Aliases:

  • is_string (bool)
  • is_text (bool)
  • is_number (bool)
  • is_date (bool)
IntegrationQuestion
OptionsQuestion
MultiChoiceQuestion
ListQuestion

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])
URLReference
  • label (str)
  • url (str)
ResourcePageReference
  • short_uuid (str)
  • url (str) - URL composed using client_url from ContextConfig

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)
  • id (str)
  • name (str)
  • item_url (str)
  • logo (str)
  • props (dict[str,str])
  • rq_method (str)
  • rq_url (str)
  • rq_headers (dict[str,str])
  • rq_body (str)
  • rs_list_field (str)
  • rs_item_id (str)
  • rs_item_template (str)
  • annotations (dict[str,str])

Operations:

  • item(item_id: str) -> str - URL of an item identified by string ID

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)

💡 question is always OptionsQuestion

MultiChoiceReply

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

Aliases:

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

💡 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

💡 question is always ValueQuestion

ItemListReply

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

Aliases:

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

💡 question is always ListQuestion

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

IntegrationReply

  • value (str)
  • item_id (item_id) - ID of item if selected using Integration

Aliases:

  • id (str) - same as item_id
  • is_plain (bool) - entered by user ignoring the integration
  • is_integration (bool) - selected by user using the integration
  • url (Optional[str]) - item URL based Integration if selected from it

Examples

TBD

Important Notes

  • The variable ctx is still the JSON-like document context provided from DSW described by the JSON Schema; from v3.6.0 that will be changed and ctx will be an object of DocumentContext. For compatibility, the plain context will be also supplied with other name.
  • For deprecation warnings, search for DEPRECATED in this document.
  • If you think that something useful is missing in the context or its documentation, please let us know.

This document has been last revised for DSW Document Worker v3.4.0.