Using the SHARE API to Grab the Latest CDISC Terminology Packages

Keeping your repository up to date with the latest CDISC Controlled Terminology (CT) packages represents a challenge to many organizations. The SHARE API make it easier to retrieve the CT packages and initiate the process of updating your repository. In this post I'll walk through the process of finding and retrieving the CT from SHARE using the API. We'll use the default media type of XML. When requesting a full CT package the XML media-type uses the NCI EVS extended versionof ODM that includes the additional metadata needed to represent the CT content.

The following figure provides an overview of the steps taken to retrieve the latest CT packages using the SHARE API.
The first step is to determine what CT Packages are available for loading. This can be done by using the Get Standard Terminology List API. The SHARE API is RESTful so this entails requesting the /terminology-packages resource. The default Lifecycle-Status parameter retrieves Approved Final content. Since the NCI EVS team curates the CDISC CT, CDISC loads this content into SHARE as Approved Final. I'm running this in a test environment and will retrieve older, draft content. The following is an example of a URL that uses the /terminology-packages resource to request the list of CT packages.

https://example.share.com/SHARE/terminology-packages?user-id=ct_user&encoding=identity

The following shows an XML snippet for one of the CT packages retrieved, CDASH 2013-12-20. Each package is returned as an ItemGroupDef inside the ODM MetaDataVersion element. 

1:        <ItemGroupDef Name="CDASH Terminology 2013-12-20 ([CDISC Terminologies] MDES 1)" OID="1.0_13909862886802094447920" Purpose="Data Collection" Repeating="No" mdr:DatePublished="2017-01-27" mdr:Status="Draft">  
2:          <Description>  
3:            <TranslatedText xml:lang="en">CDISC Terminology Package</TranslatedText>  
4:          </Description>  
5:          <Alias Context="Terminologies API" Name="/terminology-packages/{asset-id}/terminologies"/>  
6:          <Alias Context="Standard Metadata API" Name="/standards/{asset-id}/metadata"/>  
7:        </ItemGroupDef>

Your software will need to compare the list of ItemGroupDefs returned from SHARE to the list of CT packages available in your repository and select those that you want to retrieve. We'll simply request the CDASH package listed above. Notice the Alias elements on line 5 and 6. These elements represent how the package can be retrieved. The Alias element on line 5 has a Context="Terminologies API" with a Name attribute that holds the resource needed to return the list of the code lists in the package. Subsequently, these code lists can be used to retrieve the associated terms. For this example, we'll use the Alias on line 6 with Context="Standards Metadata API" and the resource /standards/{asset-id}/metadata to retrieve the full CT package.

The ItemGroupDef OID (identifier) on line 1 in the XML above is used to replace the {asset-id} to create the resource to request the full CDASH 2012-12-20 CT package. The resource now reads /standards/ 1.0_13909862886802094447920/metadata and an example URL using this resource looks like the following.

https://example.share.com/SHARE/standards/1.0_13909862886802094447920/metadata
?user-id=ct_user&lifecycle-status=draft&encoding=identity

Your code can now retrieve the full CT package in ODM XML from SHARE. Here's a snippet of the ODM XML that's returned by the SHARE API that shows one code list.

1:  <ODM xmlns="http://www.cdisc.org/ns/odm/v1.3" xmlns:nciodm="http://ncicb.nci.nih.gov/xml/odm/EVS/CDISC" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" CreationDateTime="2017-02-22T21:20:48" FileOID="Semantics.Manager.SHARE.11.5.ODM_1.3.2.CDASHTerminology2013-12-20.[CDISC_Terminologies]_MDES_1" FileType="Snapshot" ODMVersion="1.3.2" Originator="CDISC" SourceSystem="SHARE" SourceSystemVersion="7.1.3.97" xsi:schemaLocation="http://ncicb.nci.nih.gov/xml/odm/EVS/CDISC controlledterminology1-0-0.xsd">  
2:    <Study OID="STUDY.CDASHTerminology2013-12-20.[CDISC_Terminologies]_MDES_1">  
3:      <GlobalVariables>  
4:        <StudyName>Study - CDASH Terminology 2013-12-20</StudyName>  
5:        <StudyDescription>Export of CDASH Terminology 2013-12-20 with version [CDISC Terminologies] MDES 1</StudyDescription>  
6:        <ProtocolName>STUDY.CDASHTerminology2013-12-20.[CDISC_Terminologies]_MDES_1</ProtocolName>  
7:      </GlobalVariables>  
8:      <MetaDataVersion Name="CDASH Terminology 2013-12-20 MDV" OID="MDV.CDASHTerminology2013-12-20.[CDISC_Terminologies]_MDES_1.2017-02-22_21:20:48">  
9:        <CodeList DataType="text" Name="Vital Signs Position of Subject" OID="CL.VSPOS.VD_1" nciodm:CodeListExtensible="Yes" nciodm:ExtCodeID="C78431">  
10:          <Description>  
11:            <TranslatedText xml:lang="en">A terminology subset of the CDISC SDTM Position codelist created for CDASH Vital Signs Position of Subject codelist. (NCI)</TranslatedText>  
12:          </Description>  
13:          <EnumeratedItem CodedValue="SITTING" nciodm:ExtCodeID="C62122">  
14:            <nciodm:CDISCSynonym>Sitting</nciodm:CDISCSynonym>  
15:            <nciodm:CDISCDefinition>The state or act of one who sits; the posture of one who occupies a seat. (NCI)</nciodm:CDISCDefinition>  
16:            <nciodm:PreferredTerm>Sitting</nciodm:PreferredTerm>  
17:          </EnumeratedItem>  
18:          <EnumeratedItem CodedValue="SUPINE" nciodm:ExtCodeID="C62167">  
19:            <nciodm:CDISCSynonym>Supine</nciodm:CDISCSynonym>  
20:            <nciodm:CDISCDefinition>A posterior recumbent body position whereby the person lies on its back and faces upward. (NCI)</nciodm:CDISCDefinition>  
21:            <nciodm:PreferredTerm>Supine Position</nciodm:PreferredTerm>  
22:          </EnumeratedItem>  
23:          <EnumeratedItem CodedValue="STANDING" nciodm:ExtCodeID="C62166">  
24:            <nciodm:CDISCSynonym>Standing</nciodm:CDISCSynonym>  
25:            <nciodm:CDISCDefinition>The act of assuming or maintaining an erect upright position. (NCI)</nciodm:CDISCDefinition>  
26:            <nciodm:PreferredTerm>Standing</nciodm:PreferredTerm>  
27:          </EnumeratedItem>  
28:          <nciodm:CDISCSubmissionValue>VSPOS</nciodm:CDISCSubmissionValue>  
29:          <nciodm:CDISCSynonym>Vital Signs Position of Subject</nciodm:CDISCSynonym>  
30:          <nciodm:PreferredTerm>CDISC CDASH Vital Signs Position of Subject Terminology</nciodm:PreferredTerm>  
31:        </CodeList>


That's how you retrieve CT packages from SHARE using the API. The CT is published quarterly so new content arrives regularly.

You can find more information on working with the SHARE API on the SHARE for Technical Implementers page on the CDISC web site.

Comments

Post a Comment

Popular posts from this blog

Value Level Metadata, Vertically Structured Datasets, and Normalizaton

Image
As part of the work to implement Value Level Metadata in SHARE, as well as to author a Define-XML Implementation Guide article, this will be the first of a series of posts on the topic of Value Level Metadata. These posts target a more technical audience, however the Define-XML IG article will include less technical jargon. Future posts will cover additional Value Level Metadata topics and examples. Value Level Metadata (VLM) is metadata that constrains a variable definition based on the value of another variable(s). VLM was originally specified in Define-XML v1.0 as a mechanism for providing the additional metadata needed for software to more accurately interpret these constrained variables.  For example, VSORRES is a variable with structural metadata of  DataType=”Text” and Length=”200”. However, when VSTESTCD=”DIABP” that definition is constrained by VLM to use DataType=”integer” and Length="3". In this case, the value of DIABP in VSTESTCD has triggered the application o
Read more

ODMv2: Renovating the ODM Standard

  ODM, CDISC's Operational Data Model , version 1.x will be 17 years old in October, making it a mature standard. ODM has come of age , and it's time for ODM to take on a bit more responsibility around here. Toward this end, a new XML Technologies development team has recently started work on ODMv2, a substantially updated version of ODM that breaks backwards compatibility with version 1.3.x to add a number of significant new features. This post highlights some areas of new development for ODMv2. As ODMv2 is still in the early stages of development, the scope of the project and specific features are subject to change. Among the more important new ODMv2 features will be a RESTful API that specifies standard methods of data and metadata exchange. The RESTful architecture uses specific URLs and the HTTP protocol to leverage pervasive, scalable web technologies to simplify data interchange. Lack of a common API for data exchange in clinical research has limited the available
Read more

What’s the difference between iSHARE and eSHARE?

Image
CDISC SHARE is a metadata repository (MDR) that supports the development, governance, publishing, and consumption of the CDISC standards in human and machine-readable formats. For more information about SHARE see the   CDISC Website . eSHARE and iSHARE are parts of the overall SHARE system. They represent two separate ways to access SHARE content, as shown in the diagram below. Interactive SHARE, or iSHARE , is the tool used by the CDISC standards development community for developing, governing, and publishing the standards. iSHARE is a cloud-based MDR configured for the CDISC standards that includes a number of standards management and development tools. Prior to accessing the tool, CDISC standards team members receive both on-line and interactive iSHARE training. Each standards development project works with the SHARE Metadata Curators to create and publish new CDISC standards. As new standards, and new versions of existing standards, are created iSHARE provid
Read more