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 DSW questionnaire 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 DSW configuration related to documents, e.g., clientUrl for referring to the DSW instance

  • createdAt = timestamp when the document was created

  • createdBy = object describing author of the document

  • knowledgeModel = object describing used KM for the questionnaire

    • chapterUuids = list of UUIDs for chapters

    • integrationUuids = list of UUIDs for integrations

    • tagUuids = list of UUIDs for tags

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

    • name = name of the knowledge model

    • uuid = UUID of the knowledge model

  • level = current desirability level selected for the questionnaire

  • levels = list of desirability levels possible

  • metrics = list of available metrics

  • organization = object describing organization that runs the DSW instance

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

  • questionnaireName = name of the questionnaire

  • questionnaireReplies = map of replies with path-reply pairs, each reply has type and value

  • questionnaireUuid = UUID of the questionnaire

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

  • updatedAt = timestamp when the document was last updated

  • uuid = UUID of the document

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#

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

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#

  • 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 (Optional[str])

  • logo (Optional[str])

  • props (dict[str,str])

  • rq_method (str)

  • rq_url (str)

  • rq_headers (dict[str,str])

  • rq_body (str)

  • rs_list_field (Optional[str])

  • rs_item_id (Optional[str])

  • rs_item_template (str)

  • annotations (dict[str,str])

Operations:

  • item(item_id: str) -> Optional[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)

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

Notes:

ItemListReply#

  • items (list[str]) - list of item 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)

IntegrationReply#

  • value (str)

  • item_id (Optional[str]) - ID of item if selected using Integration

Aliases:

  • id (Optional[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