USDA VS|VTS

Why automated update?

Terminology is not a static beast: new species are discovered, new tests are developed, terminologists change their minds. This means that new terms WILL be added to the subsets, and some concepts WILL be retired or removed from the subsets. How can we all possibly keep up? More technology! The terminologists at Virginia Tech have developed a web service for automated distribution of updates. The form on the vocabulary page accesses that web service and returns either an XML format (recommended) or an optional CSV format file.

How does this web service work?

Each time a concept is requested or the terminologists retire a concept, the subsets at the Terminology Service are changed. Each day, an automated call from VS IT services to the web service which returns all concepts that have been added, and all concepts that have been retired (along with potential replacements for the retired concepts), in XML format. The XML files are processed updating the subsets used to validate messages.

So what do YOU do?

Accurate data transmission partially relies on accurate mapping of data to the standards (SNOMED, LOINC, HL7) that are required in the message. Initial mappings are a substantial portion of the process for intitiating messaging. However, maintaining these mappings is equally important. As the terminology changes, existing mappings may become inaccurate (mapped to now inactive terms). This negatively impacts the quality of the data coming into LMS. As validation efforts become more stringent, these inaccruate mappings can cause failed messages. It is important an internal plan is implemented for monitoring terminology changes and reviewing mappings accordingly. It is recommended that each messaging partner determine how frequently that can/should review mappings and then either manually download the updates using the tool on the vocabulary page, or set up their own automated procedures to call this webservice.

Note about .NET:

Issues have been discovered between .NET (and possibly other languages) and the Java based engine the drives our web services. It seems they disagree on how (or how not) to define XML document objects. Long story short, you can't call the web service above using .NET and retrieve an XML document. We have created an alternative web service that returns the XML as a string rather than a document object. It can be accessed at https://vtsl.vetmed.vt.edu/vs/ws/String/dataupdate.cfc?wsdl. All parameters are the same, only the return type is different.

Call Update Web Service directly:

The wsdl file for the web service is located at https://vtsl.vetmed.vt.edu/vs/ws/dataupdate.cfc?wsdl

Web service parameters:

URL: https://vtsl.vetmed.vt.edu/vs/ws/dataupdate.cfc
Methods:
- getaddedconcepts -
  
  Returns all concepts that have been added within a given time period. (The timeframe in question is given within the XML.) If you are an XML aficionado, by all means extract the added concepts with whatever tool you enjoy. Or, use your favorite XML editor (or Internet Explorer will do) to open the file so that you can view the concepts that have been added. If you have concepts in your internal lists that you could not map, you may find the correct term listed here. If all of your terms are happily mapped to the perfect matches, then you won't need to do anything.
- getretiredconcepts -
  
  Returns all concepts that have been retired (by subset) from the Terminology Service along with any potential replacements for those retired concepts and the type of replacement (SAME AS, REPLACED BY, MAYBE A). There is a 30 day grace period between the time that the Terminology Service retires concepts and the time that the NAHLN starts rejecting messages sent using the retired concepts. So you have 30 days from the time the NAHLN receives the Retired Concepts XML from the web service (and forwards it to you) to use this file to remove any mappings you may have to concepts that are retiring. Compare the list of retired concepts to your mappings, if you find any of them within your mapping, you'll have to re-map those concepts. Remember when we talked about the two types of substitution? ( section on "corrections" in SNOMED) This is where this will come into play. For the one-to-one "deterministic substitutions", there will be a single replacement concept for each retired concept, and it will have a "SAME AS" or "REPLACED BY" relationship with the retired concept. In these cases, all you have to do is replace the retired concept with the single replacement concept in your mapping. But there will, on occasion, be "ambiguous substitutions" where the relationship between the retired concept and the replacement concept is "MAY BE A" and more than one replacement concept might be given for each retired concept. With these, you will have to go back to the beginning and determine EXACTLY what your lab means when it uses that term. Hopefully one of the replacement concepts listed will match your usage and you can substitute the appropriate replacement concept, if not, it's time to visit the Terminology Discussions forum to post a request for help. There will also be times when a concept is retired with no replacement concept given. These are most likely concepts that were being used to "organize" hierarchies, but were never really intended to be used anyway and have been removed because they were invalid. If you find that you have mapped to a concept that was retired with no replacements, Contact us, and the terminologists will help you find your way.
Required parameters:
- startdate -
  Timestamp for beginning of the period desired.
- enddate -
  Timestamp for end of period desired.
- subset -
  Either "all" for all subsets, or the shortname of the subset desired. Each subset has a "short name" that is used for web service calls. If you send an inappropriate short name, you will receive an error message that includes the full list of proper short names so that you can correct your error. Click here for list of shortnames.

Sample http calls:

Get all new concepts added from 1/1/2018 10:00am to 2/28/2018 3:00pm:

https://vtsl.vetmed.vt.edu/vs/ws/dataupdate.cfc?method=getaddedconcepts&startdate=2018-01-01T10:00:00&enddate=2018-02-28T15:00:00&subset=all

Get all concepts retired from 1/1/2018 10:00am to 2/28/2018 3:00pm:

https://vtsl.vetmed.vt.edu/vs/ws/dataupdate.cfc?method=getretiredconcepts&startdate=2018-01-01T10:00:00&enddate=2018-02-28T15:00:00&subset=all

Get new concepts added to the taxonomy subset from 1/1/2018 10:00am to 2/28/2018 3:00pm:

https://vtsl.vetmed.vt.edu/vs/ws/dataupdate.cfc?method=getaddedconcepts&startdate=2018-01-01T10:00:00&enddate=2018-02-28T15:00:00&subset=species