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.

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.

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="" xmlns:nciodm="" xmlns:xlink="" xmlns:xsi="" 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="" xsi:schemaLocation=" 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.


Popular posts from this blog

Define-XML v2.1 – What do you think?

CDISC ODMv2 Development Progress: A 2018 Q1 Update

ODMv2: Renovating the ODM Standard