Multiple Template Support

[dih-cdisc]

USDM would become more flexible if it could support multiple templates for a single study version. It might be that some documents are extracts of the protocol and not the full document

Child tickets:

Item	Ticket
Model	#405
CT	#406
API	#407
Rules	#408
IG	#411
Test Data	#410

[BSnoeijerCD]

@dih-cdisc @EMuhlbradt @czwickl @ASL-rmarshall : See annotated picture below for my suggested update. The following changes are suggested:

• Removed studyProtocol and/or Protocol from corresponding class names and attributes
• Removed direct relationship between DocumentVersion and NarrativeContent
• Add new class as container for structured items which can refer to a piece of predefined (reusable) content.
• Moved sectionNumber and sectionTitle to this new class
• Moved relationships previous, next and children to the new class
• Added boolean displayTitle to the new class to indicate whether the title/section number should be displayed in the new document.
• Added notes attribute to document and documentVersion class to enable extra sponsor specific coding details for users regarding the document in general or its specific version.
• Suggested adding type to Document class which then can indicate whether it is a protocol, an outline or else?
• Suggested relationship between new class and content to be 1 : 1 as I think for each piece of content in the document you would like 1 content piece otherwise you do not have information of ordering within this structured part.

[BSnoeijerCD]

@dih-cdisc , @EMuhlbradt , @czwickl, @ASL-rmarshall Changed overview of proposed changes based on our discussions during the scrum call today:

Language code CT to consider:

• FHIR: https://hl7.org/fhir/R5/valueset-languages.html
• ISO 639: https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes

[BSnoeijerCD]

Decisions during scrum:

• contentItems should be contentItem
• change Document and DocumentVersion to StudyDefinitionDocument and StudyDefinitionDocumentVersion
• move displayTitle to NarrativeContent class
• add displaySectionNumber

[ASL-rmarshall]

Additional information regarding languages - the following is from the Data Formats section of the ODM v2.0 specification (it's also present in earlier versions):

A languageTag represents a natural language or a country-specific variant of a natural language. The allowed values are specified in IETF RFC 3066: Tags for the Identification of Languages. Note that a languageTag cannot be null.

Example: "fr-CA" denotes the French language, Canadian variant. See Section 3.2.1.1, TranslatedText, for a discussion of how languageTags are used.

[ASL-rmarshall]

@BSnoeijerCD

Decisions during scrum:

• ...
• move displayTitle to NarrativeContent class
• add displaySectionNumber

I think there should be naming consistency (in terms of including or excluding "Section" in attribute names) for these pairs of attributes:

• Either sectionTitle / displayTitle and sectionNumber / displayNumber
• Or sectionTitle / displaySectionTitle and sectionNumber / displaySectionNumber

I have a slight preference for the second option.

[ASL-rmarshall]

@dih-cdisc @BSnoeijerCD Also worth documenting the initial thoughts for the API:

• StudyVersion should have a narrativeContentItems collection
• NarrativeContent will reference a contentItem by identifier, so will need contentItemId instead of contentItem.

[BSnoeijerCD]

@dih-cdisc @BSnoeijerCD Also worth documenting the initial thoughts for the API:

• StudyVersion should have a narrativeContentItems collection
• NarrativeContent will reference a contentItem by identifier, so will need contentItemId instead of contentItem.

The id part will be added in the API as described in the IG: https://wiki.cdisc.org/display/USDMIGv4/USDM+API See #407

[BSnoeijerCD]

@dih-cdisc @EMuhlbradt @czwickl @ASL-rmarshall I made all the changes and aligned with the suggestion of Richard regarding displaySectionTitle At the last moment I also saw that since relationship to documentVersion is now plural it should be documentVersions I will upload the UML when branch 4.4 is available.

[ASL-rmarshall]

@dih-cdisc @BSnoeijerCD Also worth documenting the initial thoughts for the API:

• StudyVersion should have a narrativeContentItems collection
• NarrativeContent will reference a contentItem by identifier, so will need contentItemId instead of contentItem.

I was just thinking about rules related to this and it struck me that putting the narrativeContentItems collection in StudyVersion feels a bit weird. NarrativeContent is defined within StudyDefinitionDocumentVersion, which is defined within StudyDefinitionDocument, which is defined within Study - so you'd be "building" a study definition document version using narrative content items that are not defined within the definitional hierarchy of the document version itself. Would you ever want to create a StudyDefinitionDocumentVersion that is not referenced by a StudyVersion? If so, where would the narrative content items come from?

I wonder if having the narrativeContentItems collection in Study might be better...

[ASL-rmarshall]

@BSnoeijerCD I think the cardinality for NarrativeContentItem.text needs to be changed from 0..1 to 1 - if you create an instance of NarrativeContentItem, you must populate text (if you don't need text you just wouldn't reference a NarrativeContentItem).

[dih-cdisc]

Additional information regarding languages - the following is from the Data Formats section of the ODM v2.0 specification (it's also present in earlier versions):

A languageTag represents a natural language or a country-specific variant of a natural language. The allowed values are specified in IETF RFC 3066: Tags for the Identification of Languages. Note that a languageTag cannot be null.

Example: "fr-CA" denotes the French language, Canadian variant. See Section 3.2.1.1, TranslatedText, for a discussion of how languageTags are used.

It seems to reference ISO 639 so that should probably be our reference for the Code class

[dih-cdisc]

@BSnoeijerCD

Decisions during scrum:

• ...
• move displayTitle to NarrativeContent class
• add displaySectionNumber

I think there should be naming consistency (in terms of including or excluding "Section" in attribute names) for these pairs of attributes:

• Either sectionTitle / displayTitle and sectionNumber / displayNumber
• Or sectionTitle / displaySectionTitle and sectionNumber / displaySectionNumber

I have a slight preference for the second option.

Prefer the second option as well

[BSnoeijerCD]

@BSnoeijerCD I think the cardinality for NarrativeContentItem.text needs to be changed from 0..1 to 1 - if you create an instance of NarrativeContentItem, you must populate text (if you don't need text you just wouldn't reference a NarrativeContentItem).

Good point. I changed the text cardinality to 1 and uploaded UML to the 3-4 branch

[BSnoeijerCD]

@dih-cdisc sectionNumber and sectionTitle are required now. Can we make it optional (e.g. cardinality 0..1) to be more flexible in setting up the content? As discussed yesterday we can have pieces of text without title and/or number.

[BSnoeijerCD]

@dih-cdisc @ASL-marshall We changed the ref from studyVersion to StudyDefinitionDocumentVersion to 0..* Should we do that as well from StudyDesign to StudyDefinitionDocumentVersion? It is now stil 0..1 Or do we think that 1 design is only represented by 1 document?

[ASL-rmarshall]

@dih-cdisc @ASL-marshall We changed the ref from studyVersion to StudyDefinitionDocumentVersion to 0..* Should we do that as well from StudyDesign to StudyDefinitionDocumentVersion? It is now stil 0..1 Or do we think that 1 design is only represented by 1 document?

Yes, I think this probably needs to be changed to allow multiple document versions to be referenced for each StudyDesign. A single study design might be based on a study definition that is documented using multiple templates and/or languages. Unless you want to mark one particular type(/template/language) of study definition document as the "primary" documentation of the study definition, I think you have to allow references to any relevant document version.

This also raises a couple of questions about rules:

• Is a study design only allowed to reference a study definition document version that is also referenced by its (the study design's) parent study version?
• Is there any restriction on the type of study definition document whose versions can be referenced by either a study version or a study design?

[dih-cdisc]

@dih-cdisc @BSnoeijerCD Also worth documenting the initial thoughts for the API:

• StudyVersion should have a narrativeContentItems collection
• NarrativeContent will reference a contentItem by identifier, so will need contentItemId instead of contentItem.

I was just thinking about rules related to this and it struck me that putting the narrativeContentItems collection in StudyVersion feels a bit weird. NarrativeContent is defined within StudyDefinitionDocumentVersion, which is defined within StudyDefinitionDocument, which is defined within Study - so you'd be "building" a study definition document version using narrative content items that are not defined within the definitional hierarchy of the document version itself. Would you ever want to create a StudyDefinitionDocumentVersion that is not referenced by a StudyVersion? If so, where would the narrative content items come from?

I wonder if having the narrativeContentItems collection in Study might be better...

This bit ... "Would you ever want to create a StudyDefinitionDocumentVersion that is not referenced by a StudyVersion? " I do not think you would. I think StudyVersion is the right level for the overall collection of NarrativeContentItems. It is the "collection of all the text needed for all of my documents for my version".

That said, in an implementation, there is no restriction on the implementation having two StudyVersions point to (link to) the same NarrativeContentItem (i.e the content does not change across versions). So we need a relationship in the UML from StudyVersion -> NarrativeContentItem (0..*) that acts as the main container. I think it is nicer tohave in the model rather than just in the API.

[dih-cdisc]

@dih-cdisc sectionNumber and sectionTitle are required now. Can we make it optional (e.g. cardinality 0..1) to be more flexible in setting up the content? As discussed yesterday we can have pieces of text without title and/or number.

Make them optional [0..1]

[BSnoeijerCD]

@dih-cdisc @BSnoeijerCD Also worth documenting the initial thoughts for the API:

• StudyVersion should have a narrativeContentItems collection
• NarrativeContent will reference a contentItem by identifier, so will need contentItemId instead of contentItem.

I was just thinking about rules related to this and it struck me that putting the narrativeContentItems collection in StudyVersion feels a bit weird. NarrativeContent is defined within StudyDefinitionDocumentVersion, which is defined within StudyDefinitionDocument, which is defined within Study - so you'd be "building" a study definition document version using narrative content items that are not defined within the definitional hierarchy of the document version itself. Would you ever want to create a StudyDefinitionDocumentVersion that is not referenced by a StudyVersion? If so, where would the narrative content items come from? I wonder if having the narrativeContentItems collection in Study might be better...

This bit ... "Would you ever want to create a StudyDefinitionDocumentVersion that is not referenced by a StudyVersion? " I do not think you would. I think StudyVersion is the right level for the overall collection of NarrativeContentItems. It is the "collection of all the text needed for all of my documents for my version".

That said, in an implementation, there is no restriction on the implementation having two StudyVersions point to (link to) the same NarrativeContentItem (i.e the content does not change across versions). So we need a relationship in the UML from StudyVersion -> NarrativeContentItem (0..*) that acts as the main container. I think it is nicer tohave in the model rather than just in the API.

Agree with Dave. If you would nest it in Study and assume the same content can be referred to from different versions then you would need version control for the narrative content class as well, given we have ordering and so included which will become more and more complex.

[BSnoeijerCD]

@dih-cdisc sectionNumber and sectionTitle are required now. Can we make it optional (e.g. cardinality 0..1) to be more flexible in setting up the content? As discussed yesterday we can have pieces of text without title and/or number.

Make them optional [0..1]

Done and uploaded to github 3.4 branch

[BSnoeijerCD]

Changed template to templateName in UML. See ticket #406