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 instancedocument
= object with the details about the documentcreatedAt
= when the document was created (initial creation, not final generation of the document)createdBy
= user that created the documentdocumentTemplateId
= ID of the document template used of the documentformatUuid
= UUID of the format in the document templatename
= name of the document (entered when creating, not file name)uuid
extras
= additional data added by document worker if requestedgroups
= groups with access to the projectknowledgeModel
= object describing used KM for the questionnaireannotations
= list of key-value annotations of KM top-level entitychapterUuids
= 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
= containsquestions
,answers
, and other maps with UUID-entity pairsuuid
= UUID of the knowledge model
metamodelVersion
= metamodel version of the document context (document template metamodel version)organization
= object describing organization that runs the DSW instanceaffiliations
= list of suggested affiliation within the organizationdescription
name
organizationId
package
= object with metadata about the KM package such asversion
,name
, ordescription
questionnaire
= object representing the questionnairecreatedAt
= when the questionnaire/project was createdcreatedBy
= original author who created the questionnaire/projectdescription
= optional description of the questionnaire/projectlabels
= path-list map of labels on questions (i.e. TODOs)name
= name of the questionnaire/projectphaseUuid
= UUID of the current phase selectedreplies
= path-object map of replies to questionsupdatedAt
= when the questionnaire/project was last updateduuid
= UUID of the questionnaire/projectversionUuid
= optional UUID of the current version of the questionnaireversions
= 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 valuesusers
= users with access to the project (each entry containsperms
list anduser
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 orNone
,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):
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#
config
(ContextConfig)current_phase
(Optional[
Phase]
)document
(Document)groups
(list[
GroupPermission]
)km
(KnowledgeModel)metamodel_version
(int
)organization
(Organization)package
(Package)questionnaire
(Questionnaire)report
(Report)users
(list[
UserPermission]
)
Aliases:
e
(KnowledgeModelEntities) - same askm.entities
doc
(Document) - same asdocument
org
(Organization) - same asorganization
pkg
(Package) - same aspackage
qtn
(Questionnaire) - same asquestionnaire
replies
(RepliesContainer) - same asquestionnaire.replies
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 Packageorganization_id
(str
)km_id
(str
)version
(str
)versions
(list[str]
)name
(str
)description
(Optional[str]
)created_at
(datetime
)
Questionnaire#
uuid
(str
)name
(str
)description
(Optional[str]
)version
(Optional[
QuestionnaireVersion]
)versions
(list[
QuestionnaireVersion]
)phase
(Optional[
Phase]
)project_tags
(list[str]
)replies
(RepliesContainer)todos
(list[str]
)created_by
(User)created_at
(datetime
)updated_at
(datetime
)
QuestionnaireFile#
uuid
(str
)name
(str
)size
(int
)content_type
(str
)reply
(Optional[
FileReply]
)download_url
(str
)
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
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#
indications
(list[
ReportIndication]
)metrics
(list[
ReportMetric]
)chapter
(Optional[
Chapter]
) - set if it is a chapter report
ReportIndication#
indication_type
(str
) - one of:PhasesAnsweredIndication
,AnsweredIndication
(use alias)answered
(int
) - number of answered questionsunanswered
(int
) - number of unanswered questions
Aliases:
total
(int
) -answered
+unanswered
percentage
(float
) -answered
/total
(handles zero division, number between0.0
and1.0
)is_for_phase
(bool
) - if it is a phase-related indicationis_overall
(bool
) - if it is an overall indication (not phase-related)
ReportMetric#
measure
(float
) - number between0.0
and1.0
metric
(Metric)
KnowledgeModel#
uuid
(str
)annotations
(dict[str,str]
)entities
(KnowledgeModelEntities)chapters
(list[
Chapter]
)integrations
(list[
Integration]
)metrics
(list[
Metric]
)phases
(list[
Phase]
)resource_collections
(list[
ResourceCollection]
)tags
(list[
Tag]
)
Aliases:
e
(KnowledgeModelEntities) - same asentities
a
(dict[str,str]
) - same asannotations
Notes:
Equality of all KM entities is being done using the
uuid
comparison under the hood.All KM entities that have
annotations
have also thea
alias.
KnowledgeModelEntities#
Container holding all types of Knowledge Model entities within UUID-key dictionaries:
answers
(dict[str,
Answer]
)chapter
(dict[str,
Chapter]
)choices
(dict[str,
Choice]
)experts
(dict[str,
Expert]
)integrations
(dict[str,
Integration]
)metrics
(dict[str,
Metric]
)phases
(dict[str,
Phase]
)questions
(dict[str,
Question]
)references
(dict[str,
Reference]
)resource_collections (``dict[str,
ResourceCollection]
)tags
(dict[str,
Tag]
)
Chapter#
uuid
(str
)title
(str
)text
(Optional[str]
) - possibly Markdown textquestions
(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 phasereplies
(dict[str,
Reply]
) - path-key dictionary of replies to the questionexperts
(list[
Expert]
)references
(list[
Reference]
)tags
(list[
Tag]
)parent
(Union[
Chapter,
ListQuestion,
Answer]
)annotations
(dict[str,str]
)
Aliases:
url_references
(list[
URLReference]
)resource_page_references
(list[
ResourcePageReference]
)
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#
integration
(Integration)props
(dict[str,str]
)
OptionsQuestion#
answers
(list[
Answer]
)
MultiChoiceQuestion#
choices
(list[
Choice]
)
ListQuestion#
followups
(list[
Question]
)
ItemSelectQuestion#
list_question
(Optional[
ListQuestion]
)
FileQuestion#
max_size
(Optional[int]
) - maximum file size (in bytes) allowedfile_types
(Optional[str]
) - comma-separated file type specifications
Answer#
uuid
(str
)label
(str
)advice
(Optional[str]
) - possibly Markdown textmetric_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 between0.0
and1.0
(inclusive)weight
(float
) - value between0.0
and1.0
(inclusive)metric
(Metric)
Choice#
uuid
(str
)label
(str
)parent
(MultiChoiceQuestion)annotations
(dict[str,str]
)
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#
resource_page
(Optional[
ResourcePage]
)
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 textannotations
(dict[str,str]
)
Phase#
uuid
(str
)title
(str
)description
(Optional[str]
) - possibly Markdown textorder
(int
) - order of the phase within the KMannotations
(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 textcolor
(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 bracketslen(X)
(int
) - number of replies in the containerget(path: str) -> Optional[
Reply]
iterate_by_prefix(path_prefix: str) -> Iterable[
Reply]
- O(n) iteration with filteriterate_by_suffix(path_suffix: str) -> Iterable[
Reply]
- O(n) iteration with filtervalues() -> 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 ofQuestion
based on a type ofReply
AnswerReply#
answer
(Answer) - selected answer as the option
Aliases:
value
(str
) - UUID of the answer (answer.uuid
)
Notes:
question
is always OptionsQuestion
MultiChoiceReply#
choices
(list[
Choice]
) - selected answer as the option
Aliases:
value
(list[str]
) - list of UUIDs of the choices
Notes:
question
is always OptionsQuestionYou 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 numberas_datetime
(Optional[datetime]
) - tries to cast the value to a timestamp
Notes:
question
is always ValueQuestion
FileReply#
file_uuid
(str
)file
(Optional[
QuestionnaireFile]
) -None
if file has been deleted
Aliases:
value
(str
) - same asfile_uuid
Notes:
question
is always FileQuestion
ItemListReply#
items
(list[str]
) - list of items UUIDs (used in reply paths)
Aliases:
value
(list[str]
) - same asitems
Notes:
question
is always ListQuestionYou can iterate directly over reply object (
for item in reply
)
ItemSelectReply#
item_uuid
(str
)item_title
(str
)
Aliases:
value
(str
) - same asitem_uuid
Notes:
question
is always ItemSelectQuestion
IntegrationReply#
value
(str
)item_id
(Optional[str]
) - ID of item if selected using Integration
Aliases:
id
(Optional[str]
) - same asitem_id
is_plain
(bool
) - entered by user ignoring the integrationis_integration
(bool
) - selected by user using the integrationurl
(Optional[str]
) - item URL based Integration if selected from it