HW CME DTD Notes

Usage and tips

(last updated 1.26.11 LH)    Copyright (c) 2011 by the Board of Trustees of the Leland Stanford Junior University

• What's new in CME DTD v1.6?
• DOIs: Using DOIs in general
• Expiration dates
• Links: What options do I have for links?
  • Using PAP IDs in link URLs
  • Using DOIs in link URLs
• Links: Tips on using the <highlight> tag effectively
• Naming conventions for course IDs and quiz IDs.
• Reference numbers.
  • Credit categories
  • Evaluation reference numbers
  • Course flags
  • Quiz scoretypes and thresholds
• Related courses
• FAQs
• How do expiration dates work?
• Should I include entities in highlight matching? No, for H1O Yes, for H2O
• Are the words case-sensitive in highlight matching?
• Can I use a DOI in a link's URL?

Some small but important changes were made in v1.6 of the HW CME DTD.

• Introduction of the new related courses element; especially useful for designating corrections
• Format of the "id" attribute is more restricted; see "Naming Conventions" on this page
• The <qtl> element is now required in all quizzes; no longer optional
• Every file instance must contain a <course> element; no more <quiz>-only instances
• Each file instance must contain one and only one <course> element; no more multi-<course> instances
• Now allows the first resource in the course to be a <quiz> element
• Now allows a course with no virtual articles (see your HW content developer first)
• All "page" attributes in resources must now be sequential

There are four main types of links used in CME quizzes. These can all be mixed and matched as needed.

See or download the PDF of screenshot examples here. (large file)

• Highlighting links
• Pop-up hints
• Simple hyperlinks
• Explanation boxes
• Anchored, highlighting links

Highlighting links

• This link goes to a HW-hosted journal article, with a passage of text colored and bolded. The link finds the passage to highlight based on a unique "startmatch" and "endmatch" of the phrase to be highlighted. Display options for showing the links are submit, pass, or all. More on using the <highlight> tag here.
  
  Example:
  • <highlight locator="http://cme.oxfordjournals.org/cgi/content/full/bjarev;7/2/59" locator-type="urlopen" display="all"><startmatch>The hallmark of pulmonary hypertension</startmatch> <endmatch>right side of the heart.</endmatch><linktext>See the relevant text</linktext></highlight>

Pop-up hints

• The <hint> tag results in a pop-up javascript window. The window is width=300 x height=200, but resizable and scroll bars will show, if necessary. Typical usage of the <hint> is to give the user extra help to pass the quiz; however, the display options for <hint> are submit, pass, or all, just like the <highlight> tag, so it's your choice when to make it display. You cannot place a table or figure in the <hint> itself, but you could have a <linkref> inside the <hint> tag.
  
  Examples:
  • <hint display="submit">CDT is more sensitive and specific than the other tests listed. However, better results may be obtained with combined tests (e.g., CDT and gamma-glutamyltransferase GGT).</hint>


  • <hint display="all">Franklin JE, Leamon MH, Frances RJ: Substance-related disorders, in The American Psychiatric Publishing Textbook of Consultation-Liaison Psychiatry, 2nd ed. Edited by Wise MG, Rundell JR. Washington, DC, American Psychiatric Publishing, 2002, pp 417-454 <linkref locator-type="urlopen" locator="http://cme.psychiatryonline.org/cgi/content/full/psychcme;2003/1/2#ref1">[See this reference]</linkref></hint>

Simple hyperlinks

• If you want to link to an image or PDF or another webpage, and that resource is already online somewhere (hosted at HW or not), you can simply make a hyperlink directly to its URL with the tag <linkref>. Again, you have three options for display: submit, pass, or all.
  
  Example of a simple hyperlink:
  • <linkref locator="http://cme.oxfordjournals.org/cgi/content/full/bjarev;7/2/59" locator-type="urlopen" display="all">Full Text</linkref>
  
  
  Example of a simple email link:
  • <linkref locator="mailto:cme@hematology.org?subject=ABIM user ID and DOB" locator-type="email" display="all">cme@hematology.org</linkref>

Explanation boxes

• There is another tag, called <explanation>, which will show a boxed explanation on the same page as the quiz. This explanation is very similar to the pop-up hint, including the usual display options (submit, passed, all), except that it displays inline on the page instead of opening a pop-up window. These are most often shown after the user has passed a quiz.
  
  Examples:
  • <explanation display="passed">The essential feature of a specific phobia is marked and persistent fear of a specific object or situation. Exposure to the phobic stimulus provokes an immediate anxiety response that may appear as panic.</explanation>


  • <explanation display="passed">The correct answer is A. Statements B, C, and D are incorrect. Either albendazole or mebendazole is the treatment of choice and can be administered as a single tablet to all children, regardless of their size and age. <linkref locator-type="urlopen" locator="http://cme.nejm.org/cgi/content/full/nejm;355/22/2349">[See the answer here]</linkref></explanation>

Anchored, highlighting links

• A less commonly used type of link is actually a set of two: a simple hyperlink in the CME XML, with special parameters attached to the URL, plus an anchoring tag in the article's XML or SGML. The result is a highlighted passage of text, similar in appearance to the effect of the <highlight> tag, described above. In some conditions, the link+anchor approach just suits the situation better than <highlight> does. For instance, if the objective is to highlight only section headers or titles that are very short, which would be hard to match by means of a string.
  
  The simple hyperlink in the CME XML and the anchor tag in the XML or SGML find each other by means of an ID. The ID must be known at the time of the production of both the article content and the CME content -- so the correct ID attributes will match up.
  
  Examples of the link in the CME XML:
  • <linkref locator="http://cme.psychiatryonline.org/cgi/content/full/focus;5/2/151?quiz_ans_id=5#5" locator-type="urlopen" display="all">See the answer in context</linkref>

<linkref locator="http://cme.aappublications.org/cgi/content/full/neoreviews;11/2/e64?quiz_ans_id=q1_1#q1_1" locator-type="urlopen" display="all">[Go to preferred response in text for question #1]</linkref>
  
  
  Note the special parameter ?quiz_ans_id=# at the end of the URL in the above examples.
  
  
  
  Examples of the anchor tag in the article SGML (based on ARTHW SGML DTD):
  • <exref qq="5">TREATMENT FOR OPIOID DISORDERS</exref>
  • <exref qq="q1_1">Facilitated diffusion transfers critical nutrients, such as glucose.</exref>
  
  
  Read more about the <exref> tag in the HW SGML DTD here.
  
  
  
  Examples of the anchor tag in the article XML (based on NLM XML DTD):
  • <named-content content-type="cme-highlight" id="q6">TREATMENT FOR OPIOID DISORDERS</named-content>
  • <named-content content-type="cme-highlight" id="q1_1">Facilitated diffusion transfers critical nutrients, such as glucose.</named-content>
  
  
  Note that in the NLM DTD, the attribute "id" must begin with a letter, not a number.

The usual way to identify an article in a link is with the volume/issue/page ID, prefixed by the journal code, e.g.: "rheumatology;46/1/16"

In the case of PAP (publish ahead of print) articles, you may not yet have a v/i/p style ID. Using the PAP ID in the URL of the link will insure that the user is always served the most recent version of the PAP article. It does this by using the master PAP ID.

• Not all articles have PAP.
• A PAP article has a master ID, and its own version ID.
• Subsequent versions will have their own version ID.
• If/when the final version goes to print, that version ID will contain v/i/p.
• All versions are connected via the master ID. By using the master ID in a URL, the link will always go to the most recent version of all the PAP versions of the article.
• Examples:
  • fulltext: "http://cme.oxfordjournals.org/cgi/content/full/rheumatology;kel352"
  • abstract: "http://cme.oxfordjournals.org/cgi/content/abstract/rheumatology;kel352"
  • PDF: "http://cme.oxfordjournals.org/cgi/reprint/rheumatology;kel352"

The usual way to identify an article in a link is with the volume/issue/page ID, prefixed by the journal code, e.g.: "rheumatology;46/1/16"

Sometimes the v/i/p of an article is not known at the time of production, but the DOI is. You may use a DOI-style URL in the <linkref> or <highlight> tag instead of the usual v/i/p ID, and it will resolve to the most current version of that article.

• Not all articles have a DOI.
• Linking to an article by DOI will resolve it to the current version (through the master ID, if present).
• By default, the DOI style URL will resolve to fulltext.
• You can specify views other than fulltext in the DOI-style URL, with an option at the the end of the URL.
• Examples:
  • fulltext: "http://cme.oxfordjournals.org/cgi/doi/?doi=10.1093/rheumatology/kel352"
  • fulltext: "http://cme.oxfordjournals.org/cgi/doi/?doi=10.1093/rheumatology/kel352&view=full"
  • abstract: "http://cme.oxfordjournals.org/cgi/doi/?doi=10.1093/rheumatology/kel352&view=abstract"
  • PDF: "http://cme.oxfordjournals.org/cgi/doi/?doi=10.1093/rheumatology/kel352&view=reprint"

When full volume/issue/page information for article resource IDs are not known, you may want to use a DOI to identify an article as a resource in a course, or to use in a link's URL.

DOIs may be used in three different tags:

• <articleref>
• <linkref>
• <highlight>

"10.1093/bjaceaccp/mki062"

• In the <articleref> tag, it should look like this (substitute the appropriate DOI and page attributes):   

  <articleref id="10.1093/bjaceaccp/mki062" page="1"></articleref>

• In the <linkref> tag, it should look like this (substitute the appropriate domain, DOI and other attributes):   

  <linkref locator="http://cme.oxfordjournals.org/cgi/doi/?doi=10.1093/bjaceaccp/mki062" locator-type="urlopen" display="all">Full Text</linkref>

• In the <highlight> tag, it should look like this (substitute the appropriate domain, DOI and other attributes):   

  <highlight locator="http://cme.oxfordjournals.org/cgi/doi/?doi=10.1093/bjaceaccp/mki062" locator-type="urlopen" display="all">
  <startmatch>The hallmark of pulmonary hypertension</startmatch><endmatch>right side of the heart.</endmatch>
  <linktext>See the relevant text</linktext></highlight>

Some answers and examples on the <startmatch> and <endmatch> matching for the <highlight> tag.

• First things to know
• Case-sensitive
• Punctuation
• Bold, italics, underline
• Superiors, inferiors
• Hyperlinks, other HTML encoding
• Entities

First things to know:

• The startmatch phrase and the endmatch phrase must be unique in the article. Use at least 4-6 words, per phrase, and test for uniqueness with a "find" and "find next" in the article. It is important that the phrase be a unique match to make the link work. When using words that are repeated frequently throughout the article, you may need to use a longer phrase to make a unique match.
• You may highlight cells within a table, but this is often unreliable, as phrases within table cells are often short and non-unique. We recommend instead that you highlight words in the table caption or figure caption.
• You may highlight text within a list item (aka, <LI> tag), but you cannot highlight all the items in a list with one link. For example, to highlight each bullet item in a 3-item list, you would have to make three highlight links, one for each list item. Or, you may want to highlight the text immediately preceding the bullet items, so the user can intuit to read the following bullet items.
• The highlighting goes from starting phrase to ending phrase, so you can span paragraphs, flow around a figure, cross headings, etc.
• Since this is unidirectional, you may start using <highlight> tags in the quiz anytime, with no need to put any tags in the article as anchors.

Case-sensitive: Letters are case sensitive, so include capitalization where necessary.

Example.
Phrase in article looks like:
  

"Time-related predicted prevalence of AF or atrial flutter..."

<startmatch>Time-related predicted prevalence of AF or atrial flutter</startmatch>

"...short-term precipitating factors in a person's environment."

<endmatch>short-term precipitating factors in a person's environment.</endmatch>

"Figure 1. Algorithm Summarizing the Clinical Approach to..."

<startmatch>Figure 1. Algorithm Summarizing the Clinical Approach to</startmatch>

"...specific information about balance and gait abnormalities.27"

<endmatch>specific information about balance and gait abnormalities.27</endmatch>

<endmatch>specific information about balance and gait abnormalities.</endmatch>

"...to the prevention of falls is presented in Figure 1."

<startmatch>to the prevention of falls is presented in Figure 1.</startmatch>

H1O: For H1O journals, entities are stripped out.
Either replace the entity with a space, or with nothing.
In general, we recommend avoiding inclusion of entities where you can. Since the startmatch phrase and endmatch phrase only need to be unique in the article, you should be able to avoid entities in most cases.


Example.
Phrase in article looks like:
  

"...self management and cognitive–behavioral approaches," (Note, the dash is actually the entity –)

<endmatch>self management and cognitive behavioral approaches,</endmatch>

<endmatch>self management and cognitivebehavioral approaches,</endmatch>

H2O: For H2O journals, entities are NOT stripped out.
In H2O journals, the entity is considered part of the text. Use an XML-compatible numbered unicode entity. Don't use named ISO entities.
Still, we recommend avoiding inclusion of entities where you can. Since the startmatch phrase and endmatch phrase only need to be unique in the article, you should be able to avoid entities in most cases.


Example.
Phrase in article looks like:
  

"...self management and cognitive–behavioral approaches," (Note, the dash is actually the entity ߝ)

<endmatch>self management and cognitive&#2013;behavioral approaches,</endmatch>

Evaluations use special codes

The following values deal primarily with evaluation-type quizzes, recently added to the dtd. NOTE that regular quizzes will not use these values!

Tag: <quiz>
Attribute: scoretype

• 411 = "evaluation_all_answers" - This quiz is an evaluation, and all questions must be answered.
• 419 = "evaluation_no_check" - This quiz is an evaluation, and all questions are optional (meaning, the user really only needs to push the "submit" button to "pass" the quiz-evaluation).

Tag: <question>
Attribute: type

• 1 = "one_correct" - shows radio buttons (implied if no type is specified)
• 2 = "one_correct_dropdown" - shows a dropdown
• 3 = "multiple_correct" - shows checkboxes

Tag: <answer>
Attribute: type

• 1 = "multiple_choice" (implied if no type is specified)
• 2 = "text" - shows a <textarea> a multiline area for text entry. We can define the number of rows and columns, which in turn defines the maximum number of characters the user may input.
• 3 = "text_short" - shows <input type=text> limited to a single line of text. We can define the size of the box, as well as the maximum number of characters the user may input.

Flags tell the CME system to do a variety of special behaviors at runtime, mostly to do with display to the user. Flags apply to the course as whole and are part of the course metadata.

Use the flag ID number (not its name) in the XML. Seek advice from your HighWire content developer before using flags.

The position of the <flag> tagging is important; it should come after the closing credit tag, and before the closing courseinfo tag.

Example.

... 
</credit>
 <flags>
   <flag id="4"/>
   <flag id="6"/>
 </flags>
</courseinfo>
...

Number	Name of flag	Description of flag
1	case_study	Inclusive flag which includes the multipart_course, hide_source_articles, show_next_prev, and show_nav_bar flags
2	multipart_course	Suppresses things like the /cgi/cme link and "CME Results for " on quiz pages
3	hide_source_articles	Suppresses the article list on quiz pages
4	show_next_prev	Shows the next | prev arrows
5	show_nav_bar	Shows the case-report-style right hand nav bar
6	show_up_in_next_prev	Shows the up arrow between Prev and Next
7	bypass_tokens	Bypasses the normal token checks and deductions when taking a course
8	repeat_buttons	Causes the quiz submission form buttons to be repeated every few questions taking a quiz

A threshold is the minimum percentage score a user must achieve to pass a quiz. Threshold is an attribute on the <quiz> tag. For a 70% threshold to pass, simply use "70" as the treshold attribute.

Scoretype is another attribute on the <quiz> tag. This tells the CME system how to grade the user's quiz. By far, the most common scoretype for <quiz> is "24", plus a threshold attribute. If the threshold is to pass is "0", use scoretype "11" without a threshold attribute.

Other, less frequently used scoretypes exist; ask your HighWire content developer if you need a more unusual scoretype than these.

<quiz id="shempcme_quiz;testQuiz" scoretype="24" threshold="70">

<quiz id="shempcme_quiz;testQuiz" scoretype="11">

Evaluations use the scoretypes either "411" or "419". See more information on evaluations here.

This documentation is under construction.


Top

Course IDs

The "id" attribute on the <course> element should always follow this format: [sitecode]_course;[string]

Example of a course ID:

• <course id="shempcme_course;abc-123">

• Do not use slashes "/" or backslashes "\" in the course ID attribute. Underscores and hyphens are acceptable.
• Do not use periods, commas, or semicolons, beyond the single semicolon separating the prefix from the character string.
• Limit the character string to the right of the semicolon to 30 characters or less.

Quiz IDs

The "id" attribute on the <quiz> element should always follow this format: [sitecode]_quiz;[string]

Example of a quiz ID:

• <quiz id="shempcme_quiz;abc-123">

• Do not use slashes "/" or backslashes "\" in the quiz ID attribute. Underscores and hyphens are acceptable.
• Do not use periods, commas, or semicolons, beyond the single semicolon separating the prefix from the character string.
• Limit the character string to the right of the semicolon to 30 characters or less.

Evaluation-quiz IDs

The "id" attribute on the <quiz> element for an evaluation should always follow this format: [sitecode]_quiz;eval-[string]

Example of an eval-quiz ID:

• <quiz id="shempcme_quiz;eval-abc-123">

• Do not use slashes "/" or backslashes "\" in the quiz-eval ID attribute. Underscores and hyphens are acceptable.
• Do not use periods, commas, or semicolons, beyond the single semicolon separating the prefix from the character string.
• Limit the character string to the right of the semicolon to 30 characters or less.

Beginning with v1.6, courses can now be designated as related to another course. This is especially helpful for post-production corrections to a previously published course.

The element is: <relatedcourse>

There are two required attributes on this element:

• type
• id

• corrects
• similar

Examples

<relatedcourse type="corrects" id="shempcme_course;abc-123"/>

<relatedcourse type="similar" id="shempcme_course;abc-123"/>

Top

Expiration dates

Courses may expire on a certain date, or may never expire (date set to "12/31/9999").

Courses will expire at 12:00 AM on the date specified.

For example, if you want a course to expire at midnight between Dec 31 2005 and Jan 1 2006, you would use the date "01/01/2006" for the <expdate>. If you use "12/31/2005", the course will expire one day earlier than you intended.

Credit categories also have expiration dates. This is to accomodate multiple kinds of credit offered on one course, which may have differing expiration dates. If the course has only one credit category offered, we recommend keeping the course expiration date and the credit category expiration date synced.

When the last credit category on the course expires, the course as a whole will expire.


Top

Return to CME DTD index page

Return to CME index page

Return to HW schema index page