Healthwise Knowledgebase Integration APIcdn-clientdocs.healthwise.org/hrcresources/iAPI/Implementation... · Revision History for the Knowledgebase Integration API Implementation

Healthwise® KnowledgebaseIntegration API

Product, Implementation, and Administration Guide Release Spring 2017

http://www.healthwise.org/


Published by:

Healthwise, IncorporatedBox 1989Boise, Idaho 83701

Last Updated: May 2017

Release Spring 2017

© 1995-2017 Healthwise, Incorporated.

Healthwise, Healthwise for every health decision, and the Healthwise logo are trademarks of Healthwise, Incorporated. Otherproduct and company names mentioned herein may be the trademarks of their respective owners.

Product, Implementation, and Administration Guide Release Spring 2017 ContentsHealthwise Knowledgebase Integration API

1.800.706.9646 3 www.healthwise.org

Contents

Chapter 1: Product Overview.......................................................................... 5Content Description......................................................................................................................................5

Healthwise Knowledgebase............................................................................................................. 5Healthwise® Patient Instructions...................................................................................................... 6Healthwise Care Support Pages......................................................................................................7Video Library.................................................................................................................................... 7Service URI and Authentication.......................................................................................................7

Chapter 2: Implementation...............................................................................9Metadata Service......................................................................................................................................... 9

Supported Code Systems................................................................................................................ 9Healthwise Facets.......................................................................................................................... 10Task Context.................................................................................................................................. 11Metadata Service Status Codes.................................................................................................... 15

KnowledgeContent Service........................................................................................................................ 16KnowledgeContent Service Request Parameters..........................................................................16KnowledgeContent Service Return Values....................................................................................17KnowledgeContent Service Status Codes.....................................................................................19

Resource Service....................................................................................................................................... 20Resource Service Request Parameters........................................................................................ 20References to Resources.............................................................................................................. 20

Print Service............................................................................................................................................... 21Print Request Options....................................................................................................................21Print Service Response Formats................................................................................................... 23

Browse Service or A to Z Lists................................................................................................................. 25List Prefix Enumeration Request Format.......................................................................................26List Prefix Enumeration Response Format....................................................................................27Enumeration of Documents by Prefix Request Format................................................................. 27Enumeration of Documents by Prefix Response Format.............................................................. 28

Category Service........................................................................................................................................28Category Enumeration Request Format........................................................................................ 28Category Enumeration Response Format..................................................................................... 29Category Documents Enumeration Request Format.....................................................................29Category Documents Enumeration Response Format.................................................................. 30

Inventory Service........................................................................................................................................30Inventory Service Request Format................................................................................................ 30Inventory Service Response Format............................................................................................. 31

Reporting.................................................................................................................................................... 32Tracking Using Healthwise Web Tracking.....................................................................................32

Chapter 3: Administration..............................................................................33Healthwise Support Services..................................................................................................................... 33

Account Management.................................................................................................................... 33Emergency Support Services........................................................................................................ 33

Regular Maintenance................................................................................................................................. 34

Product, Implementation, and Administration Guide Release Spring 2017 Revision HistoryHealthwise Knowledgebase Integration API


Revision HistoryRevision History for the Knowledgebase Integration API Implementation Guide

Publication Date Date ChangeReleased to Product

HealthwiseMarketing Release

Location and Description of Changes

May 2017 May 2, 2017 11.3 through current Added Revision History to guide.

Added Bengali to the list of available languages in Healthwise PatientInstructions.

Product, Implementation, and Administration Guide Release Spring 2017 Product OverviewHealthwise Knowledgebase Integration API Content Description


Chapter 1

Product OverviewTopics:

● Content Description

The Healthwise® Integration API is a set of Web services providing access to Healthwise content through asearch and document retrieval Representational State Transfer (REST) interface.

The Integration API follows the HL7 Infobutton Standard. Because this standard is open-ended, this documentdefines which HL7 code systems are supported in search requests, which formats are returned by documentrequests, and other similar challenges that accompany developing to standards.

This guide is intended for use by a software engineer who is either implementing systems that access theIntegration API or evaluating the Integration API. Knowledge of REST web services, XML, and general softwareconcepts is required.

Content DescriptionThe Integration API currently retrieves the Healthwise® Knowledgebase, Healthwise® Patient Instructions,Healthwise® Care Support Pages, and Healthwise® Video Library. Your specific configuration determines thecontent retrieved through the search process.

Healthwise KnowledgebaseThe Healthwise Knowledgebase is a comprehensive resource of decision-making information to help medicalconsumers. The Knowledgebase content is evidence-based, unbiased, and up to date.

Topics are organized according to how people learn and how they use information to become wise about health.People can research diagnosed conditions, medical tests, medications, treatment options, and key decisionpoints. Ultimately, the Healthwise Knowledgebase supports decisions about when a problem can be treatedat home, when to see a doctor, and which treatment option is best for each individual. To learn more, go towww.Healthwise.org.

The Knowledgebase content is delivered in valid XML format that parses against a supplied schema and adheresto W3C standards. Content is delivered with a separate file for each document, a separate document for eachrank 1 and rank 2 document, and each frame and definition document. Documents contain sections. At theparagraph level or section body level, content is transformed into XHTML and contains HTML tags.

Information about the content is delivered as attributes and metadata. Some information is delivered in a pre-builtformat that matches how the information is presented in the Healthwise Hosted product. If clients like this look,using the pre-built format provides a shortcut.

To learn more, refer to the Healthwise® Knowledgebase XML Product, Implementation, and AdministrationGuide.




Healthwise® Patient InstructionsPatient Instructions are education materials intended for patients at the point of care in an inpatient, outpatient, oremergency department setting.

The Patient Instructions documents are unique from other types of patient education materials. In addition tohealth care instructional content, the Patient Instructions provide information to the patient about where to findadditional content in the Healthwise Knowledgebase, which is installed separately on your web site. PatientInstructions also provide a URL address to that information.

Patient Instructions are comprised of Healthwise-written content. Patient Instructions might include the followingsections:

● Your Care Instructions● How can you care for yourself at home?● When should you call?● How can you learn more about your condition?

Some topics might contain additional sections specific to that topic. Patient Instructions documents are generallyone to two pages.

Go to Web

Included with Healthwise Patient Instructions is the Go-to-Web feature that lets consumers reading Healthwiseprinted materials easily access online Knowledgebase topics for related information. Consumers are promptedto go online through the use of a call to action such as Where Can You Learn More?, URL addresses, and codewords included in the printed piece. The printed URL address on the page takes the consumers to an entry-pointweb page where they begin their interaction with a website hosting the Knowledgebase. This entry page closelyresembles the search page in your implementation of the Healthwise Knowledgebase. Code words are printedon the Patient Instructions document and are entered into the search field on the entry point web page by theconsumer. This code word is linked either to multiple target documents or to a single specific target document.If you have not licensed the Healthwise Knowledgebase, consumers can be directed to a hosted, non-brandedversion of the Knowledgebase.

To learn more, refer to the Healthwise® Patient Instructions XML Product, Implementation, and AdministrationGuide.

Available Translations

A subset of Patient Instructions is available in the following languages:

Arabic ar-US

Bengali bn-US

Bosnian bs-US

Chinese zh-US

Haitian-Creole ht-US

Korean ko-US

Persian (Farsi) fa-US



Polish pl-US

Portuguese pt-US

Russian ru-US

Somali so-US

Tagalog tl-US

Vietnamese vi-US

Healthwise Care Support PagesHealthwise Care Support Pages are one to two page, full-color educational materials that reinforce orsupplement disease and care management telephone coaching. Care Support Pages can also support wellnessprograms.

Care Support Pages are delivered as PDF documents, available in both English and Spanish, they answerquestions about health. Because Care Support Pages are short, they are affordable to print and deliver via mailor to email through a secure portal. Care Support Pages cover major chronic conditions, wellness areas, andmoments in care.

Care Support Pages have specific layout requirements to support client customizations, such as branding andmailing bar codes.

To learn more, refer to the Healthwise® Care Support Pages Implementation and Branding Guide.

Video LibraryThe Video Library offers short-length videos covering a variety of high-value health topics.

The Video Library offers two methods for consumers to access the videos:

● Through the Knowledgebase where the entire inventory of videos is available for viewing.● Through your website where videos are available outside of the Healthwise Knowledgebase.

If you purchased the Healthwise Video Library as an add-on to the Knowledgebase, you receive both methodsfor consumer access.

Consumer abstracts for videos display both within the Video Library and within search results. The Play buttonappears when the consumer moves the pointer over the video thumbnail.

Service URI and AuthenticationWhen subscribing or evaluating the API, a service URI is provided. The service URI might require authentication.This document is available at the root of the service URI.

Authentication

A Healthwise application key is required to use the service. The key is provided by Healthwise and must beadded to the query string of any requests. The key is added to the query string using the hw.key attribute. Thefollowing code snippets show query strings.



Note: You must replace [service URI] and HealthewiseApplicationKey with the appropriate values.

[service URI]/Metadata?…&hw.key=HealthwiseApplicationKey (GET)

[service URI]/Metadata?hw.key=HealthwiseApplicationKey (POST)

[service URI]/KnowledgeContent/hwid?hw.key=HealthwiseApplicationKey

If a key is required but not provided on the request, the service returns a HTTP 403 status code (Forbidden).

Contact Healthwise to obtain the required application key.

Product, Implementation, and Administration Guide Release Spring 2017 ImplementationHealthwise Knowledgebase Integration API Metadata Service


Chapter 2

ImplementationTopics:

● Metadata Service● KnowledgeContent Service● Resource Service● Print Service● Browse Service or A to Z Lists● Category Service● Inventory Service● Reporting

You can implement several API services to provide access to Healthwise content.

Metadata ServiceThe Metadata Service is used to search the Healthwise content resources. A search request returns an Atom1.0 feed containing links to relevant documents. The links are valid KnowledgeContent Service requests. TheHealthwise Integration API supports both POST and GET requests, as specified by the HL7 Infobutton standard.

Supported Code SystemsThe Knowledgebase documents use medical code systems to provide relevant search results.

The following information will be used for providing relevant search results, if present in the request:

● MainSearchCriteria

— ICD-10-CM (2.16.840.1.113883.6.90 | 2.16.840.1.113883.6.3) - supported.— ICD-10-PCS (2.16.840.1.113883.6.4 ) - supported.— ICD-9-CM (2.16.840.1.113883.6.103) - supported.— CPT (2.16.840.1.113883.6.12.1) - supported.— SNOMED (2.16.840.1.113883.6.96).— RxNorm (2.16.840.1.113883.6.88).— LOINC (2.16.840.1.113883.6.1).— NDC (2.16.840.1.113883.6.69) - supported— Healthwise Facet (2.16.840.1.113883.3.342.1.102) - supported. See Healthwise Facets for more

information.— Search criteria without a code and code system, but with display name or original text, is used for term

searches.



— For search criteria with unknown code systems the display names will be concatenated together and aterm search performed.

— When no exact matches are found for a term search the results returned might be for a fuzzy match.Fuzzy match search results are indicated on the root feed element by the attribute hw:match-type="Fuzzy".

● PatientContext

— Patient gender (2.16.840.1.113883.5.1) - supported.— Patient age (2.16.840.1.113883.6.1) - supported.

● Task context—see Task Context for more information about how task context is used to deliver moretargeted search results.

● Patient (informationRecipient) language is used to determine localization of search results. If no Patientlanguage is supplied, Provider (performer) language is used. If no language is specified, English is used bydefault. Available languages depend on the content you have licensed from Healthwise and the hw.key youare using.

The request must have at least one mainSearchCriteria to be valid.

If more mainSearchCriteria sections are provided, a search algorithm attempts to provide the best possibleresults. Multiple values of the same code system, for example, multiple ICD-9 codes returns results OR'edtogether. Results that are relevant for multiple codes in the request are returned before results that are onlyrelevant to a single code.

If multiple code systems are provided, search results are returned based on the following algorithm:

● If one or more ICD-9 code systems are present but no CPT codes, the search uses ICD-9 codes, OR'ing theresults, and ignoring any other codes in the request. Medical condition topics are favored in the results.

● Otherwise, if one or more CPT code systems are present but no ICD-9, the search uses CPT codes, OR'ingthe results, and ignoring any other codes in the request. Medical test topics are favored in the results.

● Otherwise, if both CPT and ICD-9 codes are present in the request, the search uses both ICD-9 and CPTcodes, OR'ing the results, and ignoring any other codes in the request. No particular document type isfavored in the results.

● Otherwise, if an unspecified code system is present but no ICD-9, CPT, or NDC codes, the search does aterm search, concatenating the display names of the codes, and ignoring any other codes in the request.

● Otherwise, if the only available codes are unsupported code systems, the search does a term search, andconcatenates all the display names of the codes.

Patient demographics information acts as a filter on the search results. If age or gender is provided, the resultsare filtered such that only documents that match the patient demographics information are returned.

Note: The task context might change the type of search performed. For example, a task context ofMLREV (Medication List Review) filters search results to medications topics.

Some applications make multiple requests to get meaningful search results, even though a request can containmultiple codes. For example, to show relevant results for a condition represented with an ICD9 code and resultsfor a procedure represented by a CPT code, two separate requests are made so that the application can showthe results separately in the UI.

Healthwise FacetsHealthwise facets can be provided as part of the request.

The code system used is 2.16.840.1.113883.3.342.1.102.



The facet and the value must be provided in the code value, separated by a colon (:). The following code sampleshows a request with the condition facet and a facet value of condition1:

Metadata?msc.v.cs=2.16.840.1.113883.3.342.1.102&msc.v.c=condition:condition1

You can include multiple mainsearchcriteria on the request to pass in multiple facets and facet values and tocombine these values with other codes.

Task ContextUse any of the supported HL7 Infobutton task contexts to further refine search results. Task context representsthe task that a user is trying to perform in a clinical information system when initiating a contextual searchtransaction. Task context is one of the context dimensions that help predict the information needs that a usermight have while using a clinical information system.

The following table describes how the task context affects search results from the Healthwise Integration API.

Task Context Name Mnemonic Search Filter By Content Typea

Laboratory Test Order Entry

Laboratory Results Review

Microbiology Results Review

Microbiology Organisms Results Review

Microbiology Sensitivity Test Results Review

Radiology Report Review

Pathology Report Review

Radiology Report Entry

Pathology Report Entry

LABOE

LABRREV

MICRORREV

MICROORGRREV

MICROSENSRREV

RADREPREV

PATREPREV

RADREPE

PATREPE

Healthwise Knowledgebase:

● Medical test topics

● Test detail topics

Patient Instructions

Care Support Pages

Medication Order Entry

Medication List Review

Medication Administration

MEDOE

MLREV

MARWLREV


● Drug detail topics

● Multum drug information

Patient Instructions, might include drug information

Care Support Pages

Problem List Review

Diagnosis List Review

Problem List Entry

Diagnosis List Entry

PROBLISTREV

DIAGLISTREV

PROBLISTE

DIAGLISTE


● Medical Condition Topics (Major, Mini, Symptom,ConditionCenter, Special, Actionset, Decisionpoint, Otherdetail,Surgicaldetail, NCI*)

Patient Instructions, might include drug information

Care Support Pages

This filter is applied when a search request is passed using an NDCunknown code, unspecified code, or both. If an ICD-9 or CPT codeis present, the default search logic for those codes is applied.

a. Content returned is subject to content licensed.



Search results are not filtered or modified for the remainder of the task contexts.

To include a task context in a search request on the GET query string, pass the mnemonic in the taskContext.c.cparameter. The taskContext.c.dn is ignored. The following code samples shows an example of thetaskContext.c.c parameter:

&taskContext.c.c=MLREV

To include a task context in a POSTed search request include the following XML in the request:

<taskContext classCode="ACT" moodCode="DEF"> <code code="MLREV" codeSystem="HL7-Infobutton" codeSystemName="HL7-infobutton" displayName="MedicationList Review"/></taskContext>

Note: Only the code attribute is examined to determine the task context, /taskContext/code[@code].

Example of GET RequestMetadata requests can include patient demographic information and medical codes.

The following code sample shows a metadata request for groupId127 using patient demographics for age andgender and three ICD-9 codes. The patient in this example is a 4-year-old boy with ear pain.

[service-uri]//Metadata?knowledgeRequestNotification.effectiveTime.v=20090909&assignedEntity.name.r=groupId127&patientPerson.administrativegendercode.cs=2.16.840.1.113883.5.1&patientPerson.administrativegendercode.c=m&age.c.c=30525-0&age.c.cs=2.16.840.1.113883.6.1&age.v.u=a&age.v.v=4&mainsearchcriteria.v.cs0=2.16.840.1.113883.6.103&mainsearchcriteria.v.ot0=388.70&mainsearchcriteria.v.c0=388.70&mainsearchcriteria.v.dn0=ear%20pain,unspecified&mainsearchcriteria.v.cs1=2.16.840.1.113883.6.103&mainsearchcriteria.v.ot1=460&mainsearchcriteria.v.c1=460&mainsearchcriteria.v.dn1=common%20cold%20(uri)&mainsearchcriteria.v.cs2=2.16.840.1.113883.6.103&mainsearchcriteria.v.ot2=381.00&mainsearchcriteria.v.c2=381.00&mainsearchcriteria.v.dn2=acute%20nonsuppurative%20otitis%20media&taskContext.c.c=PROBLISTREV

For readability, the following code sample shows the same query parameters without delimiters and escapecodes:

knowledgeRequestNotification.effectiveTime.v = 20090909assignedEntity.name.r=groupId127patientPerson.administrativegendercode.c = MpatientPerson.administrativegendercode.cs = 2.16.840.1.113883.5.1patientPerson.administrativegendercode.csn = AdministrativeGenderpatientPerson.administrativegendercode.dn = Maleage.c.c = 30525-0age.c.cs = 2.16.840.1.113883.6.1age.c.csn = LNage.c.dn = AGEage.v.v = 4age.v.u = amainsearchcriteria.v.c0 = 388.70mainsearchcriteria.v.cs0 = 2.16.840.1.113883.6.103mainsearchcriteria.v.dn0 = Ear pain, unspecifiedmainsearchcriteria.v.c1 = 460mainsearchcriteria.v.cs1 = 2.16.840.1.113883.6.103mainsearchcriteria.v.dn1 = Common cold (URI)



mainsearchcriteria.v.c2 = 381.00mainsearchcriteria.v.cs2 = 2.16.840.1.113883.6.103mainsearchcriteria.v.dn2 = Acute nonsuppurative otitis mediataskContext.c.c = PROBLISTREVhw.key = [application key]

The request comprises demographics values and three mainSearchCriteria. Each mainSearchCriteria encodesone ICD9 code. Results comprise documents that are relevant to these conditions and the patient age andgender information.

Paging support is achieved using the following proprietary query string parameters.

● hw.page—page number requested (0-based)● hw.results.page—number of search results per page● hw.results.max—maximum number of results

An application uses these parameters to let a user navigate search results one page at a time. The values shouldreflect the needs of the application.

You can use hw.results.max without hw.page and hw.results.page. If no paging parameters areincluded, all search results are returned in one response.

You might include the following code snippet on the query string to control page values:

&hw.results.max=200&hw.page=2&hw.results.page=30

Note: You can use the same query string parameters to control pagination of search results forPOST requests. There are no corresponding XML elements in the POST data.

Example of POST RequestCode sample of a POST request.

You can use the GET request query string parameters to control pagination of search results for POST requests.See Example of GET Request for more information.

Important: Element and attribute names are case sensitive.

<v3:knowledgeRequestNotification xmlns:v3="urn:hl7-org:v3"> <v3:effectiveTime value="20090909"> </v3:effectiveTime> <v3:holder> <v3:assignedEntity> <v3:name representation="groupId127" /> </v3:assignedEntity> </v3:holder> <v3:subject1> <v3:patientContext> <v3:patientPerson> <v3:administrativeGenderCode code="M" codeSystem="2.16.840.1.113883.5.1" codeSystemName="AdministrativeGender" displayName="Male"> </v3:administrativeGenderCode> </v3:patientPerson> <v3:subjectOf> <v3:age> <v3:code code="30525-0" codeSystem="2.16.840.1.113883.6.1" codeSystemName="LN"



displayName="AGE"> </v3:code> <v3:value value="4" unit="a"> </v3:value> </v3:age> </v3:subjectOf> </v3:patientContext> </v3:subject1> <v3:subject2> <v3:taxkContext classCode="ACT" moodCode="DEF"> <v3:code code="PROBLISTREV" codeSystem="HL7-Infobutton" displayName="Problem List Review"/> </v3:taxkContext> <v3:mainSearchCriteria> <v3:value code="388.70" codeSystem="2.16.840.1.113883.6.103" displayName="Ear pain, unspecified"> <v3:originalText>Ear pain, unspecified</v3:originalText> </v3:value> </v3:mainSearchCriteria> </v3:subject2></v3:knowledgeRequestNotification>

Example of Metadata Service Return ValueThe Metadata service returns an Atom 1.0 feed with search results, in accordance with the HL7 Infobuttonstandard.

The following code sample shows an example return value.

<?xml version="1.0" encoding="utf-8" ?><?XML:NAMESPACE PREFIX = [default] http://www.w3.org/2005/Atom NS="http://www.w3.org/2005/Atom" /><feed xmlns="http://www.w3.org/2005/Atom" xmlns:hw="http://www.healthwise.org/2009/DocumentInfo"> <LINK rel="self" href="http://cppdev.healthwise.org/IBAdapter/Metadata?…"> <id>tag:healthwise.org,2010-05-24:[uri without the service uri]</id> <logo>[url to png file with Healthwise logo]</logo> <icon>[url to png file with Healthwise logo]</icon> <updated>[date/time the search index was created]</updated> <author> <name>Healthwise, Incorporated</name> </author> <generator version="0.0.0.0."> Healthwise, Incorporated </generator>

<entry> <summary>H1N1 flu, also called swine flu, is a type of influenza that is similar to the common flu. Like the common flu, the H1N1 flu comes on suddenly. Your child may suddenly develop a fever, chills, body aches, a headache, and a cough. The fever, chills, and b</summary> <LINK rel="alternate" type="application/atom+xml" href="[service- uri]/KnowledgeContent/bo1208?lang=en-us" hreflang=en-us hw:document-family="pi" hw:rank="1" hw:document-type="AfterVisit" hw:document-href="bo1208"> <LINK rel="alternate" type="text/xml" href="[service-uri]/ KnowledgeContent/bo1208?lang=en-us" hreflang=en-us hw:document-family="pi" hw:rank="1" hw:document-type="AfterVisit" hw:document-href="bo1208"> <LINK rel="alternate" type="application/atom+xml" href="[service- uri]/KnowledgeContent/bo1208?lang=es-us" hreflang=es-us hw:document-family="pi" hw:rank="1" hw:document-type="AfterVisit" hw:document-href="bo1208"> <LINK rel="alternate" type="text/xml" href="[service-uri]/ KnowledgeContent/bo1208?lang=es-us" hreflang=es-us hw:document-family="pi" hw:rank="1" hw:document-type="AfterVisit" hw:document-href="bo1208">



<id>tag:healthwise.org,2009-05-08:/KnowledgeContent/bo1208?lang=en-us</id> <updated>2009-05-08T12:00:00Z</updated> </entry>

<entry> <summary>Is this topic for you? This topic covers infections of the middle ear, commonly called ear infections. For information on outer ear infections, see the topic Ear Canal Problems (Swimmer's Ear). For information on inner ear infections, see the topic Labyrinthitis. What is a middle ear infection? The middle ear is the small </summary> <LINK rel="alternate" type="application/atom+xml" href="[service- uri]/KnowledgeContent/hw184385?lang=en-us" hreflang=en-us hw:document-family="kb" hw:rank="1" hw:document-type="major" hw:document-href="hw184385"> <LINK rel="alternate" type="text/xml" href="[service-uri]/ KnowledgeContent/hw184385.xml?lang=en-us" hreflang=en-us hw:document-family="kb" hw:rank="1" hw:document-type="major" hw:document-href="hw184385"> <id>tag:healthwise.org,2009-02-02:/KnowledgeContent/hw184385?lang=en-us</id> <updated>2009-02-02T12:00:00Z</updated> </entry></feed>

The following fields are used in the Atom 1.0 feed:

Feed UpdatedThe date that the search index was created.

Feed GeneratorThe version attribute identifies the version of the Healthwise Integration API.

Entry Links

Links to available content. There is one link element with an attribute of alternate for each format andlanguage in which the content is available. For type=application/atom+xml the resulting response is anatom feed containing the content in XHTML format. For type=text/xml the resulting response is the contentin XML format conforming to the HW-XML.xsd schema with complete metadata. The XML format alsocontains the prebuilt sections containing the content in XHTML format.

Each link also includes proprietary attributes that contain additional information about the target document.These attributes can be used by your application to construct links to other sites with Healthwise content orsend messages to other internal systems. The type=text/html indicates content available in HTML5 formattargeted for mobile environments. The proprietary attributes are in the Healthwise hw: namespace andinclude the following:

● hw:document-href—the Healthwise hwid● hw:document-type—the Healthwise document type● hw:rank—the Healthwise document rank● hw:document-family—the Healthwise document family, for example, kb, pi, caresupport, conversation

Entry IDThe date in the id field is the last updated date for the document.

Entry UpdatedThe date in the updated field is the last updated date for the document.

Metadata Service Status CodesMetadata service error conditions are conveyed using HTTP status codes.

Product, Implementation, and Administration Guide Release Spring 2017 ImplementationHealthwise Knowledgebase Integration API KnowledgeContent Service


The following HTTP status codes are returned by the service.

200 OK

Returned with successful request. In the case of zero search results, OK status is returned but with an emptyAtom feed.

400 BadRequest

Returned if the request is malformed. For example, if an unknown parameter is returned or for unspecifiedreasons.

403 Forbidden

Returned when the resource exists but access is not allowed for some reason such as licensing.

KnowledgeContent ServiceThe KnowledgeContent Service requests documents from a Healthwise content source. Documents are providedas XHTML fragments inside an Atom feed.

Documents are provided in one of the following formats:

Mimetype application/atom+xmlXHTML fragments inside an Atom feed.

Mimetype text/xmlXML conforming to the HW-XML.xsd schema. Contains all metadata and content in both XML and XHTMLformats.

Mimetype application/pdfA PDF representation of the Care Support Page document. This format is only used for CareSupport.

Mimetype text/htmlHTML5 version of the document. This is only available for some topics and is targeted at mobileenvironments.

KnowledgeContent Service Request ParametersHealthwise documents are identified by a unique Healthwise ID, or hwid. A document request must contain thehwid. Document requests might also contain language or environment parameters.

The following code snippet shows the format for a KnowledgeContent request.

[service-uri]/KnowledgeContent/[hwid]

The request supports the following parameters:

hwid

The unique Healthwise ID for the document that is requested.

The hwid can contain the format as a file extension, hwid.format. If the format is omitted, the documentis returned as application/atom+xml. Valid formats include XML, HTML, and PDF.



Query string: lang

The requested localization code for the document that is requested. The default is en-us.

The following code snippet shows a document request in default localization.

[service-uri]/KnowledgeContent/cpain

The following code snippet shows a document request for the Spanish localization.

[service-uri]/KnowledgeContent/cpain?lang=es-us

Query string: environment

The mobile environment for the document that is requested. This parameter retrieves the document in aformat that is prepared for mobile environments. This parameter is only supported in combination with theHTML format. The following code snippet shows a document request for mobile-ready HTML5 content.

[service-uri]/KnowledgeContent/[hwid].[format]?environment=mobile

KnowledgeContent Service Return ValuesThe return values from the KnowledgeContent service is unique for each document format.

Example of application/atom+xml FormatThe return value for an application/atom+xml document is an Atom 1.0 feed.

The following code sample shows the application/atom+xml format.

<?xml version="1.0" encoding="utf-8" ?><?XML:NAMESPACE PREFIX = [default] http://www.w3.org/2005/Atom NS="http://www.w3.org/2005/Atom" /><feed xmlns="http://www.w3.org/ 2005/Atom" xmlns:hw="http://www.healthwise.org/2009/DocumentInfo"> <LINK rel="self" href="[url_for_this_document]"> <id>tag:healthwise.org,[document update date]:[partial url for this document]</id> <logo>[url to png file with Healthwise logo]</logo> <icon>[url to png file with Healthwise logo]</icon> <author> <name>Healthwise, Incorporated</name> </author>

<updated>[date document was last updated, ISO 8601]</updated> <entry> <updated>[date document was last updated, ISO 8601]</updated> <id>tag:healthwise.org,[document update date]:[partial url for this document]</id> <rights>[copyright information]</rights>

<content type="xhtml"> <DIV xmlns="http://www.w3.org/1999/xhtml"> <DIV id=HwNavigationWrapper> [Optional; only for those document types that contain a nav-stack for the multiple sections] </DIV> <DIV id=HwContentWrapper class=HwContentWrapper> [xhtml fragment of document content] </DIV> <DIV class=HwLegal> [Copyright and Disclaimer information]



</DIV> </DIV> </content> <HW:HEAD> <HEAD xmlns="http://www.w3.org/1999/xhtml"> [An HTML head section containing the title, metadata, references to CSS resources, and JavaScript that sets variables used by Healthwise JavaScript] </HW:HEAD> </entry></feed>

The document is contained as XHTML in the /feed/entry/content element.

Note: The XHTML has a different name space than the containing elements. The XHTML isstructured as standard Healthwise XHTML. The XHTML markup contains class and id attributes onmost elements to enable flexible styling and interactivity using CSS and JavaScript.

When embedding the Healthwise XHTML in other pages or displaying directly in a web browser, the applicationmust ensure that any links inside the document are correctly formatted. In most cases this means that anyelements with a src or href attribute must be inspected and rewritten. All links have additional attributes in thehw namespace that enable robust rewriting to take place. The following code sample shows the markup for linksinside the document.

<DIV id=HwContentWrapper xmlns:hw="http://www.healthwise.org/2009/ DocumentInfo"> <A href="document/bo1208" hw:document-type="AfterVisit" hw:document-href="bo1208">… </A> <img src="resources/media/interface/hwlogo.png" hw:resource-path="media/interface/hwlogo.png" /></DIV>

The <a> element has two attributes in the hw namespace. These attributes should be used to create a new hrefattribute that matches the product in which the content is embedded. The original value of href should not beused because it might change in future revisions of the content. Resources such as images have a hw:resource-path attribute that must be used. In a similar manner, the src attribute on the image tag must be rewritten usingthe hw:resource-path attribute.

Example of text/xml FormatThe return value for an XML document conforms to the HW-XML.xsd schema.

The following code sample shows the text/xml format.

<?xml version="1.0" encoding="utf-8" ?><?XML:NAMESPACE PREFIX = [default] http://www.w3.org/2005/Atom NS="http://www.w3.org/2005/Atom" /><hw.doc version="Q2_10" type="Special" pagetype="content" manufacturingversion="x.x.x.x" contentversion="x.x.x" xml:lang="en-us" hwcontent="true" rank="1" hwid-content="zx1780"> <doc.meta-data> <meta-data.title>Colds</meta-data.title> [complete metadata for the document] </doc.meta-data> <doc.prebuilt> [XHTML prebuilt sections as described above] </doc.prebuilt> <doc.sections> <doc.section hwid-content="zx1781"> [Content for section] </doc.section> </doc.sections></hw.doc>



Refer to the Healthwise® Knowledgebase and Healthwise® Spanish Knowledgebase - XML Product,Implementation, and Administration Guide for complete details on the XML document format.

Example of text/html FormatThe return value for a text/html document is HTML5 format.

The HTML5 is formatted as XML so that the document can be transformed. The HTML5 format does not containany non-closed tags, attribute values are enclosed in quotes, and so forth. The following code sample show theHTML5 markup.

<!DOCTYPE html><html> <head> (header) </head> <body> <div class="HwElement">(content) </div> </body> </html>

The markup returned contains links to resources and other documents. Most of the links must be rewritten by theapplication that uses the content. For this purpose, the link elements have attributes with information about thelink.

Refer to the Healthwise® Knowledgebase and Healthwise® Spanish Knowledgebase - Responsive HTMLProduct, Implementation, and Administration Guide for complete details on the HTML format.

Example of application/pdf FormatThe return response for the application/pdf document is a binary stream containing the PDF representation of thedocument.

KnowledgeContent Service Status CodesKnowledgeContent service error conditions are conveyed using HTTP status codes.

The following HTTP status codes are returned by the service.

200 OK

Returned with successful request.

400 BadRequest

Returned if the request is malformed. For example, if an unknown parameter is returned or for unspecifiedreasons.

403 Forbidden

Returned when the resource exists but access is not allowed for some reason such as licensing.

404 Not Found

Returned when the requested hwid cannot be found in the given localization.

Product, Implementation, and Administration Guide Release Spring 2017 ImplementationHealthwise Knowledgebase Integration API Resource Service


Resource ServiceThe Resource service retrieves images and other resources via the API.

Resource Service Request ParametersHealthwise resources are identified by a unique name and the relative path to the resource. A resource requestmust contain the relative path, the name (including extension) and may also contain a required language.

The following code snippet shows the format for a Resource request.

[service-uri]/resource/version/[path to resource]/[resource-name]

The Resource request supports the following parameters:

Query string: rel

The requested version for the resource that is requested.

The following code snippets show the format for a resource request that specifies the 10.8 version of theresource.

[service-uri]/resource/9.8/inc/control/main.js

[service-uri]/resource/inc/control/main.js?rel=9.8

Query string: lang

The requested localization code for the resource that is requested. The default is en-us.

The following code snippet shows the format for a resource request in the default localization.

[service-uri]/resource/media/medical/hw/h9991278_001_pi.jpg

The following code snippet shows the format for a resource request for the Spanish version of the resource.

[service-uri]/resource/media/medical/hw/s_h9991278_001_pi.jpg?lang=es-us

References to ResourcesAny resource that is part of the product has the attributes required to create a complete reference to theresource.

The following code sample shows the markup for a reference to an image.

<img alt="Illustration of the anatomy of the eye" height="130" src="[service-uri]/resource/media/medical/hw/h9991278_001_pi.jpg?lang=en-us" hw:resource-path="media/medical/hw/h9991278_001_pi.jpg" width="130" hw:release-quarter="11.0" />

References to resources have an hw:resource-path attribute that must be used to create the reference to theresource. The original href or src should not be used.

The hw:release-quarter attribute on links to resource, such as images, JavaScript, or CSS, must be used tocreate the request for the resource from the iAPI. In the case of JavaScript and CSS the resources might notwork with versions of content for which they are not intended.

Product, Implementation, and Administration Guide Release Spring 2017 ImplementationHealthwise Knowledgebase Integration API Print Service


Print ServiceThe Print service creates print-ready versions of Healthwise content. The Print service collects many documentstogether into one print fulfillment; specifies a header, a footer, and cover page; and applies CSS to style thepresentation.

The format of the response is specified in the print request. The Print service supports the following formats:

● PDF—Use Adobe® Acrobat® or an alternative PDF viewer to view or print.● XHTML—Use the browser print functionality to print.● XML—Content must be transformed by an application into a printable format such as XHTML or PDF.

The following code snippet shows a print request that is issued by postin an XML request to the API print URI:

[service-uri]/healthwise/print

Note: Printing does not support HTTP GET requests.

Print Request OptionsThe Print request supports several options that can determine the document format, document layout, documentstyling, and client information.

Fulfillment Documents

The Print service can request multiple documents by collecting the Healthwise hwids into thefulfillment.documents element. Both the id and lang attributes are required to identify the requested Healthwisedocument.

Layout Elements

The layout elements specify page headers, footers, and a cover page. The content for these sections is specifiedas XHTML markup in the corresponding body element. Wrapping the headers, footers, and cover page contentin div elements facilitates stying using CSS. The XHTML in the body is inserted into the markup that is used togenerate the printed document.

Possible values for the repeat attributes for headers and footers are:

FIRSTThe contents of body displays on the first page of the entire document only. This value is not supported forthe footer.

LASTThe contents of body displays on the last page of the entire document only. This value is not supported forthe header.

DOCUMENTThe contents of body displays on the last page of the entire document only. This value is not supported forthe header.

ALLThe contents of body displays on all pages of the document.



Note: Using images for branding headers and footers provides the most control over the output.

Due to the precise layout requirements for Care Support Pages, the top and bottom one inch of the page arereserved for branding markup. These areas are left blank if no header or footer are supplied.

style.css.url Property

The style.css.url property specifies the full URL of a CSS provided by the client. This URL must be publiclyaccessible. The defined styles are applied to the printed documents when requesting either XHTML or PDFformat. You can also use the CSS to override existing styles applied by Healthwise. Refer to XHTML PrintResponse Format to determine which classes and ids to override. Inspecting the content markup might also helpdetermine which elements to apply CSS styles to.

style.font.size Property

Note: Changing sizes might result in poor presentation of content, especially for Care SupportPages.

The style.font.size property controls the size of the font in the printed document. Possible values are small,medium, large, or extra large

client.name Property

The client.name property only applies to Healthwise Patient Instructions. The name specified by theclient.name property is inserted into the document disclaimer. For example, Care instructions adapted underlicense by client name. This information can be XHTML.

client.disclaimer Property

The client.disclaimer property only applies to Healthwise Patient Instructions. The XHTML contentcontained in this property displays in the printed document below the Healthwise disclaimer.

pi.gotoweb.url Property

The pi.gotoweb.url property only applies to Healthwise Patient Instructions. The URL provided is insertedinto the Where can you learn more? box at the end of each Healthwise Patient Instruction. For example,"Where can you learn more? Go to http:// this.url.com Enter xxxx in the search box to…"

page.numbers Property

The page.numbers property turns on or off printing page numbers in the top right corner. The format is Page xof y. Supported values are true to turn on page numbers or false to turn off page numbers. The default value isfalse.

time.stamp Property

The time.stamp property turns on or off printing the date and time that the document was printed in the lowerright corner. Supported values are true to turn on page numbers or false to turn off page numbers. The defaultvalue is false.

Example of Print RequestThe print request markup includes options and properties that control the document appearance.



The following code sample shows the markup for a print request including all options and properties.

<hw.fulfillment format="pdf|xhtml|xml"> <fulfillment.documents> <fulfillment.document id="abdpn" lang="en-us"/> <fulfillment.document id="cpain" lang="en-us"/> <fulfillment.document id="aa6664" lang="en-us"/> </fulfillment.documents> <fulfillment.layout> <layout.coverpage> <body> <div class='CoverPage'> <p>Please read the following documents carefully.</p> <p>Call <b>800-555-1212</b> if you have any questions.</p> </div> </body> </layout.coverpage> <layout.header repeat="ALL"> <body> <div class='Header'> <table> <tr> <td><img src='http://www.somehost.com/Images/Logo.gif'/></td> <td>The Johnson Group<br/>123 Main St.<br/>Anytown, ID 83702</td> </tr> </table> </div> </body> </layout.header> <layout.footer repeat="LAST"> <body> <div class='Footer' style='color: Blue'>The Johnson Group (800-555-1212)</div> </body> </layout.footer> </fulfillment.layout></hw.fulfillment><fulfillment.property id="style.css.url">http://www.somehost.com/Styles/Print.css</fulfillment.property><fulfillment.property id="style.font.size">medium</fulfillment.property><fulfillment.property id="client.name">The <b>Johnson</b> Group</fulfillment.property><fulfillment.property id="client.disclaimer"> <div class='ClientDisclaimer'>The <b>Johnson</b> Group disclaims any warranty or liability for your use of this information.</div></fulfillment.property><fulfillment.property id="pi.gotoweb.url">http://www.thejohnsongroup.com/healthwise/search</fulfillment.property><fulfillment.property id="page.numbers">true</fulfillment.property><fulfillment.property id="time.stamp">true</fulfillment.property>

Print Service Response FormatsThe Print service supports several response formats, including PDF, XHTML, and XML.

PDF Print Response FormatFor PDF format, the HTTP header Content-Type attribute is set to application/pdf. The body of the responsecontains the raw bytes comprising the PDF document.

The PDF document is created directly from the XHTML version. To change the document presentation, refer theclasses and IDs described in XHTML Print Response Format to determine where you might want to apply CSS.



XHTML Print Response FormatFor XHTML format, the HTTP header Content-Type attribute is set to application/xhtml+xml. The body of theresponse contains the XHTML markup for all of the requested content.

The following code sample shows the structure and markup for the XHTML response.

<?xml version="1.0" encoding="utf-8"?><html> <head>  </head> <body> <table> <thead id='HwTHead'> <tr> <div id='HwPrintHeader'> </div>  </tr> </thead> <tbody id='HwTBody'> <tr> <div id='HwCoverPage'> </div> <div id='HwOuterPrintWrapper'> <div class='HwPrintDocumentWrapper'> <div class='HwContentTitle'> </div> <div class='HwTOCWrapper'> <div class='HwTOCTitle'></div> <ol class='HwTOCList'> <li class='HwTOCListItem'> </li> </ol> </div>  <div class='HwContent'> <div class='HwMainDocument'>  <div class='HwMainDocumentSections'> <div id='sec-abc' class='HwNavigationSection'> </div>  </div>  <div class='HwCreditsWrapper'> </div> <div class='HwLegalWrapper'> <div class='HwLegal'> </div> <div class='HwClientLegal'> </div> </div> </div>  </div> </div>   </div>  </tr> </tbody> <tfoot id='HwTFoot'> <tr> <div id='HwPrintFooter'> </div>  </tr> </tfoot> </table> </body></html>

Product, Implementation, and Administration Guide Release Spring 2017 ImplementationHealthwise Knowledgebase Integration API Browse Service or A to Z Lists


XML Print Response FormatFor XML format, the HTTP header Content-Type is set to text/xml. The body of the response contains thecontent of the print request in XML format.

The <hw.doc> element contains the document. The <hw.doc> element follows the Healthwise schema, HW-XML.xsd. See KnowledgeContent Service for additional information.

The following code samples shows the structure and markup of the XML response.

<hw.fulfillment> <fulfillment.tableofcontents> <tableofcontents.document hwid=" lang="> <title></title> </tableofcontents.document> </fulfillment.tableofcontents> <fulfillment.layout> <layout.coverpage> <coverpage.body></body> </layout.coverpage> <layout.header repeat="> <header.body></body> </layout.header> <layout.footer repeat="> <footer.body></body> </layout.footer> </fulfillment.layout> <fulfillment.document hwid=" lang="> <document.body> <hw.doc hwid-content=" xml:lang=" rank=" type="></hw.doc> </document.body> </fulfillment.document></hw.fulfillment>

Browse Service or A to Z ListsThe Browse service lets you build alphabetical or A to Z lists of the titles of Healthwise content. The Browseservices supports building lists to the first two letters. For example, you can retrieve a list of all documentsstarting with letters AA, AB, AC, AD, AE, and so on.

Creating A to Z lists is a two-step process.

1. The Browse service retrieves a list of possible letters. This list is referred to as List Prefix Enumeration.2. After the list of letters for which documents exist is retrieved, the documents with titles that begin with those

letters are retrieved.

Healthwise includes alternative titles in the metadata for most rank 1 and rank 2 documents. These alternativetitles are designed to make content easier to locate in these alphabetical lists. A Healthwise document might belisted under more than one title in the alphabetical lists.

Note: Creating the lists are expensive calls; application caching of the results is encouraged. Thevalues do not change during a given quarterly release.



List Prefix Enumeration Request FormatThe List Prefix Enumeration request generates the list of possible letters available in the A to Z list. You cangenerate a list based on the first letter or the first two letters. You can also narrow the list using optional queryparameters.

Important: Only GET requests are supported. POST is not supported.

The following code snippet shows the request format to generate the list of first letters.

[service-uri]/healthwise/list

The following code snippet shows the request format to generate the list of first two letters, where a representsany item returned from the [service-uri]/healthwise/list.

[service-uri]/healthwise/list/a

You can use the following optional query parameters to narrow the list or to create a specific list.

lang=[language]

The localization code for the request. The default is en-us.

The following code snippet shows the format for a request in the default localization.

[service-uri]/healthwise/list

The following code snippet shows the format for a request for the Spanish version.

[service-uri]/healthwise/list?lang=es-us

gender=[male|female]

The gender for the request. Supported values are male, female, and both. The default is both.

The following code snippet shows the format for a request for letters that apply to male-only content.

[service-uri]/healthwise/list?gender=male

age=[age]

The age for the request. Supported values can be in years or months. Ages in months must be followed bym. The default is all.

The following code snippet shows the format for a request for letters that apply to an age of 10 years.

[service-uri]/healthwise/list&age=10

The following code snippet shows the format for a request for letters that apply to an age of 2 months.

[service-uri]/healthwise/list&age=2m

collection=[collection]

The collection or group of Healthwise document types for the group.



The following code snippet shows the format for a request for documents from the Health Topics collection.

[service-uri]/healthwise/list?collection=healthtopics

The following list describes the collection name and the document types each includes:

● HEALTHTOPICS—Major, Mini, Symptom, Actionset, Decision Point, Surgical Detail, Other Detail, NCI● MEDICAL TESTS—Medical Test, Test Detail● MEDICATIONS—Drug Detail, Multum● ALTERNATIVEMEDICINE—CAM (Complementary and Alternative Medicine)

List Prefix Enumeration Response FormatThe List Prefix Enumeration response is XML format.

The following code sample shows the response format for a partial list of first letters where there is no content forletters C through P. The underscore value refers to non-alphabetic characters, such as numbers or symbols.

<?xml version="1.0" encoding="utf-8" ?><?XML:NAMESPACE PREFIX = [default] http://www.w3.org/2005/AtomNS = "http://www.w3.org/2005/Atom" /> <items> <item letter="_"> </item> <item letter="a"> </item> <item letter="b"> </item> <item letter="q"> </item> </items>

The following code sample shows the response format for the list of second letters.

<?xml version="1.0" encoding="utf-8" ?><?XML:NAMESPACE PREFIX = [default] http://www.w3.org/2005/AtomNS = "http://www.w3.org/2005/Atom" /><items> <items> <item letter="a"> <item letter="_"> </item> <item letter="a"> </item> <item letter="b"> </item> <item letter="c"> </item> <item letter="d"> </item>  <item letter="z"> </item> </item> </items>

The values for each prefix can be passed into subsequent requests of the Browse service to further enumeratedocument titles that start with the prefix letter. See Enumeration of Documents by Prefix Request Format foradditional information.

Enumeration of Documents by Prefix Request FormatTo retrieve a list of all document titles that start with a specified prefix, you must create a Metadata request.

The API uses a proprietary code system to indicate that the request is to enumerate document titles that startwith the specified prefix. The code system value for list prefix requests is 2.16.840.1.113883.3.342.1.100. SeeMetadata Service for additional information. Both GET and POST are supported for this request.

Product, Implementation, and Administration Guide Release Spring 2017 ImplementationHealthwise Knowledgebase Integration API Category Service


The following GET request code sample shows a Metadata request for all documents that begin with the CAprefix.

[service-uri]/Metadata?knowledgeRequestNotification.effectivetime.v=20090909&mainsearchcriteria.v.cs0=2.16.840.1.113883.3.342.1.100&mainsearch criteria.v.c0=ca

For readability, the following code sample shows the query parameters without delimiters and escape codes.

knowledgeRequestNotification.effectiveTime.v = 20090909mainsearchcriteria.v.cs0 = 2.16.840.1.113883.3.342.1.100mainsearchcriteria.v.c0 = ca

Note: You cannot combine document prefix enumeration requests with other search criteria. Forexample, including an age does not return results filtered by age. The one exception to this rule issupport for filtering the result by Healthwise collection. See List Prefix Enumeration Request Formatfor a description of collections. Add the ?collection=[collectionname] parameter to thequery string to filter the results by collection. If you use a POST the query string must be used for thecollection filter.

Enumeration of Documents by Prefix Response FormatThe response to document prefix enumeration requests is the same Atom 1.0 feed as normal search requests.See Example of Metadata Service Return Value for a code sample.

Category ServiceHealthwise assigns all of the rank 1 and rank 2 documents to categories. The Category service enumerates all ofthe categories and the documents in each category.

Category Enumeration Request FormatThe Category Enumeration request generates the list of available categories. You can also narrow the list usingoptional query parameters.

Important: Only GET requests are supported. POST is not supported.

The following code snippet shows the request format to enumerate all of the categories.

[service-uri]/healthwise/category

You can use the following optional query parameters to narrow the list or to create a specific list.

lang=[language]

The localization code for the request. The default is en-us.

The following code snippet shows the format for a request in the default localization.

[service-uri]/healthwise/category

Product, Implementation, and Administration Guide Release Spring 2017 ImplementationHealthwise Knowledgebase Integration API Category Service


The following code snippet shows the format for a request for the Spanish version.

Note: Healthwise includes English, en-us, categories in the metadata for Spanish documents.This list will contain both the English categories and the Spanish categories.

[service-uri]/healthwise/category?lang=es-us

gender=[male|female]

The gender for the request. Supported values are male, female, and both. The default is both.

The following code snippet shows the format for a request for categories that apply to male-only content.

[service-uri]/healthwise/category?gender=male

age=[age]

The age for the request. Supported values can be in years or months. Ages in months must be followed bym. The default is all.

The following code snippet shows the format for a request for categories that apply to an age of 10 years.

[service-uri]/healthwise/list&age=10

The following code snippet shows the format for a request for categories that apply to an age of 2 months.

[service-uri]/healthwise/list&age=2m

Category Enumeration Response FormatThe Category Enumeration Response is XML format.

The following code sample shows the response format. You can pass the values of each category intosubsequent requests of the Category service to enumerate the documents in each category.

Note: Some characters must be URL-escaped if they are not valid characters in URL addresses,such as spaces.

<?xml version="1.0" encoding="utf-8" ?><?XML:NAMESPACE PREFIX = [default] http://www.w3.org/2005/AtomNS = "http://www.w3.org/2005/Atom" /> <items> <item>Allergies</item> <item>Asthma</item> <item>Back and neck pain</item> <item>Blood and lymph</item> <item>Bones, joints and muscles</item>  </items>

Category Documents Enumeration Request FormatTo retrieve a list of all documents in a specific category, you must create a metadata request.

Product, Implementation, and Administration Guide Release Spring 2017 ImplementationHealthwise Knowledgebase Integration API Inventory Service


The API uses a proprietary code system to indicate that the request is to enumerate documents in the specifiedcategory. The code system value for category requests is 2.16.840.1.113883.3.342.1.101. See Metadata Servicefor additional information. Both GET and POST are supported for this request.

The following GET request code sample shows a Metadata request for all documents that belong to the Allergiescategory.

[service-uri]/Metadata?knowledgeRequestNotification.effectivetime.v=20090909&mainsearchcriteria.v.cs0=2.16.840.1.113883.3.342.1.100&mainsearch criteria.v.c0=Allergies

For readability, the following code sample shows the query parameters without delimiters and escape codes.

knowledgeRequestNotification.effectiveTime.v = 20090909mainsearchcriteria.v.cs0 = 2.16.840.1.113883.3.342.1.101mainsearchcriteria.v.c0 = Allergies

You must provide the exact value of the name in the enumerated list of categories for subsequent requests fordocuments in a category.

When you request the enumerated list of Spanish categories, the equivalent Spanish category namefor Allergies is Alergias = [Allergies]. You must provide the exact value, Alergias = [Allergies], in themainsearchcriteria.v.c0 parameter when you request documents in the Spanish category.

Note: You cannot combine category document enumeration requests with other search criteria. Forexample, including an age does not return results filtered by age.

Category Documents Enumeration Response FormatThe response to category document enumeration requests is the same Atom 1.0 feed as normal searchrequests. See Example of Metadata Service Return Value for a code sample.

Inventory ServiceThe Inventory service lets you retrieve a list of content in the form of HWIDs that you have licensed. The licensedcontent is determined from the Healthwise API key that receive or obtain from Healthwise.

The list contains the HWID, path, type, status, and possibly a forward HWID for deleted documents.

Important: Only GET requests are supported. POST is not supported

Inventory Service Request FormatThe Inventory service request generates a list of Healthwise content that your organization licenses.

Important: Only GET requests are supported. POST is not supported

The following code snippet shows the request format to enumerate all of the documents.

[service-uri]/healthwise/inventory?hw.key=[key]&localization=[localization]

Product, Implementation, and Administration Guide Release Spring 2017 ImplementationHealthwise Knowledgebase Integration API Inventory Service


The Healthwise API key, hw.key parameter, is required for the Inventory service. To specify a localization valueother than en-us pass the localization value in the localization query string parameter.

Inventory Service Response FormatThe Inventory service response is XML format.

The following code sample shows the response format for the Inventory service request.

<?xml version="1.0" encoding="utf-8" ?><?XML:NAMESPACE PREFIX = [default] http://www.w3.org/2005/Atom NS = "http://www.w3.org/2005/Atom" /><hw.content> <content.status type="documentType" hwid-content="hwid" forward="hwid" update-type="updatetype" status="status" filename="../xml/folderName/FolderName/filename.xml"> </content.status> …</hw.content>

If your organization licensed the Video Library, some entries in the techdocs file have a subtype of video. Thefollowing code sample shows the response for video content.

<hw.content> <content.status hwid-content="ab13012" type="MultiMedia" status="updated" update-type="content" subtype="video"> <title>Depression: Using Your Inner Strengths</title> </content.status> ...</hw.content>

The <content.status> element supports the following attributes.

hwid-contentIndicates the HWID of the document.

typeIndicates the Healthwise document type. Refer to the Healthwise® Knowledgebase and Healthwise®

Spanish Knowledgebase Product, Implementation and Administration Guidefor a description of Healthwisedocument types.

statusIndicates the status of the documents. Possible values include the following:

● unchanged—no changes for this release.● added—this document is new this release.● updated—this document was updated for this release.● deleted—this document was deleted this release.

update-typeIndicates the type of update if the status is updated. Possible values include the following:

● metadata—only metadata was changed.● content—the content of the document was changed.

Product, Implementation, and Administration Guide Release Spring 2017 ImplementationHealthwise Knowledgebase Integration API Reporting


forwardIf the status of a given document is deleted, the forward attribute lists the hwid of the appropriatereplacement document. If a document with a status of deleted is requested from the KnowledgeContentservice the forwarded document is automatically returned.

ReportingReporting topic usage to Healthwise is required by some license agreements. Refer to your license agreementfor reporting requirements. Contact Healthwise with questions.

Tracking Using Healthwise Web TrackingThe Patient Instructions implement web tracking features for optional use in reporting and web analytics. Minimal configuration is required, and other tracking methods can be used if desired. If you are interested inactivating this feature, contact Healthwise to initiate the process of approval and implementation.

The JavaScript sends a tracking event with some data every time a page is loaded or an action occurs thatwarrants a tracking event.

To set up tracking, the custom.js script must listen to the tracking event and call a tracking service to save theevent. To set up tracking, make the following changes to custom.js:

Important: Set $hw.trackingSuffix = "test"; for testing and $hw.trackingSuffix ="prod"; for production.

1. Set $hw.trackingSuffix for your environment.2. Change <Client Token> to your client token.3. Remove /* and */ to activate the Healthwise web tracking variable.4. Make sure the org.healthwise.analytics.insights.deliveryOption.set parameter value is correct for your

product.

Note: You might need to add this parameter to the custom.js file.

The following code sample shows where to make changes to the custom.js for an English productionenvironment.

//<HwTracking>$hw.trackingSuffix = "prod";$hw.setConfig('tracking', { clientToken: '<Client Token>', suffix: $hw.trackingSuffix }); //<HwInsights> //sets the collector service endpoint depending on the environment (TEST or prod) /* var splunkEndpoint = ($hw.trackingSuffix == "prod") ? "https://insights.healthwise.net/track" : https://insights.healthwise.net/track org.healthwise.analytics.insights.featureFlipper.enable(); org.healthwise.analytics.insights.collectorService.set(splunkEndpoint); org.healthwise.analytics.insights.deliveryOption.set("ixapi"); */ //</HwInsights>//</HwTracking>

Product, Implementation, and Administration Guide Release Spring 2017 AdministrationHealthwise Knowledgebase Integration API Healthwise Support Services


Chapter 3

AdministrationTopics:

● Healthwise Support Services● Regular Maintenance

After the Knowledgebase is implemented for your organization, you will need to maintain the Knowledgebase.

Healthwise Support ServicesThe Healthwise account management team is available and ready to assist you throughout the implementationprocess and to provide continued support.

Account ManagementYour account management team is available at 1.800.706.9646 from 8:00 a.m. to 5:00 p.m. Mountain Time,Monday through Friday with the exception of major holidays.

Your Healthwise account management representative is available to assist you with any of the following issues:

● Suggestions for Healthwise to enhance any Healthwise product.● Comments about Healthwise products that you receive from your members.● Questions about the quarterly release process and updates to content.● Usage report submission process, if supported by your Healthwise product. Refer to your license agreement

to determine the reporting requirements for your organization.● Technical issues that must be escalated to Healthwise technical support. Technical issues with Healthwise

products should be directed to a designated contact at your organization. Any issues that this contact cannotresolve should be forwarded to Healthwise.

The Healthwise technical support team is available to assist you with the following issues:

● Questions about your Healthwise product, such as implementation details, usability, system performance, orreports.

● Second-line support assistance for your members. Initial support for members is always provided by yourorganization. If assistance is required, the designated contact should call Healthwise.

● Availability of the API.

Emergency Support ServicesEmergency after hours telephone support for service disruption of Healthwise products is available at1.800.706.9646.

Note: Only use the Emergency Support Service when the API is not accessible.

Product, Implementation, and Administration Guide Release Spring 2017 AdministrationHealthwise Knowledgebase Integration API Regular Maintenance


The emergency support team is available to assist you with the following issues:

Note: First, verify that only the Healthwise products are not accessible. Try searching for otherInternet sites. If other sites are accessible, but you cannot connect with the Knowledgebase, contacttechnical support.

● The API is not accessible.● Second-line support assistance for your members. Initial support for members is always provided by your

organization. If assistance is required, the designated contact should call Healthwise.

Regular MaintenanceHealthwise reserves Tuesday evenings from 6:00 p.m. until Midnight, Mountain Time for regular maintenanceon our systems. Most maintenance functions do not require service interruption. On rare occasions, yourconsumers might see a short interruption of service while we perform certain maintenance tasks; however,those interruptions will not exceed our commitment to you of providing excellent access to our product. If anymaintenance task requires restricted access to the Healthwise products, we will give you advance notice.