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

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

    • 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 runs the DSW instance

    • affiliations = list of suggested affiliation within the organization

    • description

    • name

    • organizationId

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

  • questionnaire = object representing the questionnaire

    • createdAt = when the questionnaire/project was created

    • createdBy = original author who created the questionnaire/project

    • description = optional description of the questionnaire/project

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

    • name = name of the questionnaire/project

    • phaseUuid = UUID of the current phase selected

    • replies = path-object map of replies to questions

    • updatedAt = when the questionnaire/project was last updated

    • uuid = UUID of the questionnaire/project

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

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

  • report = object that contains report for the questionnaire 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#

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

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

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)

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#

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

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

  • 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