Include

Element Name	Include
Parent Elements	MetaDataVersion
Element XPath(s)	/ODM/Study/MetaDataVersion/Include
Element Textual Value	None
Attributes	StudyOID, MetaDataVerionOID, href
Child Elements	None
Usage/Business Rules	Other Information: When a metadata element such as an ItemDef is redefined in a MetaDataVersion that includes a previous MetaDataVersion, any metadata element of the same type and with the same OID in a preceding MetaDataVersion is completely replaced. This includes all attributes and child elements. It also means that all attributes and child elements not present in the new definition are effectively deleted from the previous version. Definitions (e.g., ItemDef) that have been defined in a previous included MetaDataVersion cannot be removed in later MetaDataVersions; only references to those Items can be removed. Referenced Items are removed by redefining the parent definition (e.g., ItemGroupDef) and omitting the undesired reference.

Attribute

Schema Datatype or Enumeration

Usage

Definition

Business Rules

StudyOID

oidref

Required

References the Study that provides a prior metadata version.

This attribute allows an Include element to reference a metadata version in another study. Thus, it is possible for many studies to share a set of common metadata definitions

MetaDataVersionOID

oidref

Required

References a prior MetaDataVersion within the Study referenced by the StudyOID attribute.

The MetaDataVersionOID must be unique within the StudyOID.

This version must be present earlier in the same ODM file or in a previous file in a series identified by the ODM/@PriorFileOID (Section 3.2, ODM).

href

URI

Optional

Reference to the location where the to be included Study-Metadata definition can be accessed.

The href attribute allows to provide the location (as a URL) of the ODM where the to-be-included elements can be retrieved, in the case that the combination of the referenced study and metadataversion is not present in the same file. The reference can be to a file (e.g., "file:///d:/MyStudies/MyStudy/PriorVersionODM.xml") or be an API call (e.g., "https://www.MyCompany.com/MyStudies?StudyOID=MyStudy&MetaDataVersionOID=MV.001").

The ODM sender is responsible for assuring that the URI is valid and accessible by the receiver.

A reference to a prior metadata version. This version must be present earlier in the same ODM file or in a previous file in the series. See the PriorFileOID attribute (Section 3.2, ODM).

When a metadata element such as an ItemDef is redefined in a MetaDataVersion that includes a previous MetaDataVersion, any metadata element of the same type and with the same OID in a preceding MetaDataVersion is completely replaced. This includes all attributes and child elements. It also means that all attributes and child elements not present in the new definition are effectively deleted from the previous version.

The href attribute allows to provide the location (as a URL) of the ODM where the to-be-included elements can be retrieved, in the case that the combination of the referenced study and metadataversion is not present in the same file. The reference can be to a file (e.g., "file:///d:/MyStudies/MyStudy/PriorVersionODM.xml") or be an API call (e.g., "https://www.MyCompany.com/MyStudies?StudyOID=MyStudy&MetaDataVersionOID=MV.001").

In the following example, question I.003 has been added to the ItemGroup IG.001 by adding an ItemRef element to the ItemGroupDef. The new version of the ItemGroupDef now contains only one of the Aliases, and the other Alias defined in MetaDataVersion MDV.001 has been removed. This same mechanism is used to remove ItemRefs from an ItemGroupDef, or to reorder them.

Example

Include Element

<Study OID="S.001">
  <MetaDataVersion OID="MDV.001" Name="First Metadata version"> 
    <ItemGroupDef OID="IG.001" Name="First ItemGroup" Type="Section"> 
      <ItemRef ItemOID="I.001" Mandatory="Yes" OrderNumber="1"/> 
      <ItemRef ItemOID="I.002" Mandatory="Yes" OrderNumber="2"/> 
      <Alias Context="Context1" Name="IG1"/> 
      <Alias Context="Context2" Name="FIRST"/> 
    </ItemGroupDef> 
  </MetaDataVersion> 
  
  <MetaDataVersion OID="MDV.002" Name="Second Metadata version"> 
    <Include StudyOID="S.001" MetaDataVersionOID="MDV.001"/>
    <ItemGroupDef OID="IG.001" Name="First ItemGroup (modified)" Type="Section"> 
      <ItemRef ItemOID="I.001" Mandatory="Yes" OrderNumber="1"/> 
      <ItemRef ItemOID="I.003" Mandatory="Yes" OrderNumber="2"/> 
      <ItemRef ItemOID="I.002" Mandatory="Yes" OrderNumber="3"/> 
      <Alias Context="Context1" Name="IG1"/> 
    </ItemGroupDef> 
  </MetaDataVersion> 
</Study>

Notes:

Definitions (e.g., ItemDef) that have been defined in a previous included MetaDataVersion cannot be removed in later MetaDataVersions; only references to those Items can be removed. Referenced Items are removed by redefining the parent definition (e.g., ItemGroupDef) and omitting the undesired reference.
The StudyOID attribute allows an Include element to reference a metadata version in another study. Thus, it is possible for many studies to share a set of common metadata definitions.

Page tree

Include