Version: 2011.01.25

Krames StayWell External Web Service Documentation

This method has been deprecated.
Use the SearchContent() method instead.

DocumentSearch Method

This Method will return a small amount of meta-data for each document that matches the supplied criteria. For a document to be included, it must match all the specified criteria. For multi-valued criteria, the document must match at least one of the supplied values. For instance if two age groups are supplied in the criteria, a document matches if it is mapped to either one or both of the age groups even if it is also mapped to additional age groups.

Please note that if the search criteria identifies a large result set you should expect a longer response time.

Parameter name: XMLRequest

Expects an XML document in this format:

<SearchCriteria ReturnAdditionalTitles="false" IncludeBlocked="false">
	<Paging PageSize="10" and PageNumber="1" />
	<FullText LogicalOperator="And">pain</FullText>
	<Title IncludeAdditionalTitles="true">heart</Title>
	<ByLetter IncludeAdditionalTitles="true">A</ByLetter>
	<PostingDate>2003-11-01</PostingDate>
	<EndPostingDate>2003-12-31</EndPostingDate>
	<Language code="en"/>
	<Gender>Male</Gender>
	<AgeGroups>
		<AgeGroup>Adult (18+)</AgeGroup>
		<AgeGroup>Senior</AgeGroup>
	</AgeGroups>
	<ContentTypes>
		<ContentType ContentTypeId="6"/>
		<ContentType ContentTypeId="2"/>
	</ContentTypes>
	<Subtopics>
		<Subtopic RootSubtopicId="22"/>
		<Subtopic RootSubtopicId="32"/>
		<Subtopic SubtopicId="44"/>
		<Subtopic SubtopicId="47"/>
	</Subtopics>
	<MeSHList>
		<MeSH code="D003324"/>
		<MeSH code="D006331"/>
	</MeSHList>
	<ICD9List>
		<ICD9 code="785.0"/>
		<ICD9 code="495.1"/>
	</ICD9List>
	<CPTList>
		<CPT code="93314"/>
		<CPT code="4242"/>
	</CPTList>
	<Servicelines>
		<Serviceline ServicelineKeyword="alergy" PageKeyword="alergy" Audience="Adult" />
		<Serviceline ServicelineKeyword="dermatology" PageKeyword="alergy" Audience="Adult" />
	</Servicelines>
</SearchCriteria>

At least one of the child elements is required; a request with just <SearchCriteria/> will no longer return all content available to the license (please use the new ListAllDocuments method for this). The order of the elements is not important.

The optional attribute "ReturnAdditionalTitles" will add a document's AdditionalTitles to the returned XML if its' value is set to "true". If this attribute is not included, the value is assumed to be "false".

The optional attribute "IncludeBlocked" will cause the results to include documents that are licensed to, but have been "blocked" by the client. If this attribute is not included, the default value is "false". It may be useful to include blocked documents in search results for client-base administrative or monitoring tools, but generally not for end-user applications.

  • The FullText element specifies the word list to match in the content's Body field. The required attribute "LogicalOperator" specifies how the word list is treated in the search; a value of “And” means that all words in the word list must match, a value of “Or” means that one or more of the words in the word list must match. Quoted phrases may also be included: 
    <SearchCriteria>
		<FullText LogicalOperator="And">"heart disease" liver</FullText>
</SearchCriteria>
    This example would return all documents where the body contains the phrase “heart disease” and the body also contains the word "liver".
  • The Title element specifies the text to match in the "Regular Title". If the optional attribute "IncludeAdditionalTitles" is set to true, the search will match "Inverted Titles" and associated titles in the Additional Title table as well. This is a substring search not a word-by-word search, so searching for "a" in the title will return many documents: any document whose title(s) contains the letter "a".
  • The ByLetter element specifies a letter to filter the search results by. If a document's Inverted Title (or Regular Title if Inverted Title isn't present) begins with the designated letter the document will be returned in the results. If the optional attribute “IncludeAdditionalTitles” is set to true, the search will match associated titles in the Additional Title table that begin with the designated letter as well. This element now also recognizes “#” as a valid letter and will return documents that begin with a number if specified.
  • The PostingDate element specifies the date to match in the content's PostingDate field. The format of this content is defined by the XML Schema and is in the format YYYY-MM-DD.
  • The EndPostingDate element, specified with the PostingDate element, defines a range of dates to match in the content's PostingDate field. If EndPostingDate is specified but PostingDate is not, EndPostingDate is ignored. If PostingDate is specified but EndPostingDate is not, the date must match exactly. If they are both specified, the date must be between the two supplied dates.
  • The Language element specifies the language of the documents to match. Currently, the following two international standard language codes are used: "en" for English and "es" for Spanish.
  • The Gender element specifies the gender to match in the content's Gender field. Current options for this element are "All", "Female", and "Male". Specifying “All” is different than leaving this element out. When All is specified, only those documents which apply to both men and women are returned. If the criteria is omitted, documents which apply to just men, just women or men and women are returned.
  • The AgeGroups element specifies the age categories to limit the search by. Current options for AgeGroup are:
    • Infant (0 - 11 mo)
    • Childhood (11 mo - 12 yrs)
    • Teen (12 - 18 yrs)
    • Adult (18+)
    • Senior
    Multiple age groups can be supplied and documents can be mapped to multiple age groups. For instance if the search is limited to “Senior”, and a particular document were mapped to Teen, Adult and Senior, it would be returned, but a document mapped only to Adult would not. If the search criteria were both Infant and Childhood, and a particular document were mapped to Childhood and Teen, it would be returned.
  • The ContentTypes element specifies the list of ContentTypeIds to limit the search by. Multiple ContentType elements can be used. For instance, to search only through news, use 
    		<ContentTypes>
				<ContentType ContentTypeId="6"/>
		</ContentTypes>.
    To search through news and the wellness library, use 
    		<ContentTypes>
				<ContentType ContentTypeId="6"/> 
				<ContentType ContentTypeId="1"/>
		</ContentTypes>
    A list of all available content type IDs can be provided on request.
  • The Subtopics element allows limiting the search to certain standard collections or certain subtopics within standard collections. If the RootSubtopicId attribute is specified, the entire collection is searched. If the SubtopicId attribute is used, only documents within that subtopic (but no child subtopics) are searched. The RootSubtopicIds can be obtained from the ListCollections method on Collections.svc. Any number of Subtopic elements can be included in the search request. If a document is part of at least one of the referenced subtopics (or collections) it is included in the results as long as it matches the other specified criteria.
  • The MeSHList element specifies the list of MeSH Unique IDs to limit the search by. Multiple MeSH elements can be specified; the results will include all documents that match at least one of the supplied MeSH Unique IDs.
  • The ICD9List element specifies the list of ICD9 codes to limit the search by. Multiple ICD9 elements can be specified; the results will include all documents that match at least one of the supplied ICD9 codes.
  • The CPTList element specifies the list of CPT codes to limit the search by. Multiple CPT elements can be specified; the results will include all documents that match at least one of the supplied CPT codes.
  • The Servicelines element specifies the list of Serviceline data to limit the search by. The three attributes (ServicelineKeyword, PageKeyword, and Audience) are all optional. The search results will include all documents that match at least one of the supplied Servicelines, if more than one is specified.
  • A Paging element is used in both the request and the response.
    • In the request it allows the content to be returned in pages. 
      				<Paging PageNumber="1" PageSize="10" />
      PageNumber tells the web service which page of data to return. PageSize is used to specify the number of documents per page.
    • In the response it shows information about the number of pages and documents returned. 
      				<Paging TotalDocs="15" PageSize="10" Pages="2" Page="1" />

DocumentSearch Specific Usage

DocumentSearch method SOAP request: 
POST /sitename/Documents.svc/DocumentSearch HTTP/1.1
Host: external.ws.staywell.com
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://ws.staywell.com/DocumentSearch"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
		xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Body>
		<SearchCriteria ReturnAdditionalTitles="true|false" xmlns="http://external.ws.staywell.com">
			<FullText LogicalOperator="And | Or">string</FullText>
			<Title IncludeAdditionalTitles="true|false">string</Title>
			<PostingDate>XmlDate</PostingDate>
			<EndPostingDate>XmlDate</EndPostingDate>
			<Language code="en | es"/>
			<Gender>All | Female | Male</Gender>
			<AgeGroups>
				<AgeGroup>Infant (0 - 11 mo) | Childhood (11 mo - 12 yrs) | Teen (12 - 18 yrs) | Adult (18+) | Senior</AgeGroup>
				<AgeGroup>Infant (0 - 11 mo) | Childhood (11 mo - 12 yrs) | Teen (12 - 18 yrs) | Adult (18+) | Senior</AgeGroup>
			</AgeGroups>
			<ContentTypes>
				<ContentType ContentTypeId="int"/>
				<ContentType ContentTypeId="int"/>
			</ContentTypes>
			<Subtopics>
				<Subtopic RootSubtopicId="int"/>
				<Subtopic RootSubtopicId="int"/>
				<Subtopic SubtopicId="int"/>
			</Subtopics>
			<MeSHList>
				<MeSH code="MeSHUniqueId"/>
				<MeSH code="MeSHUniqueId"/>
			</MeSHList>
			<ICD9List>
				<ICD9 code="ICD9Code"/>
				<ICD9 code="ICD9Code"/>
			</ICD9List>
			<CPTList>
				<CPT code="CPTCode"/>
				<CPT code="CPTCode"/>
			</CPTList>
			<Servicelines>
				<Serviceline ServicelineKeyword="string" PageKeyword="string" Audience="string" />
				<Serviceline ServicelineKeyword="string" PageKeyword="string" Audience="string" />
			</Servicelines>
		</SearchCriteria>
	</soap:Body>
</soap:Envelope>
DocumentSearch method SOAP response: 
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
		xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Body>
		<DocumentList>
			<Paging TotalDocs="1370" PageSize="2" Pages="685" Page="1"/>
			<Document ContentTypeId="int" ContentId="string" IsCustom="bit">
				<Language code="en | es" />
				<RegularTitle xmlns="http://ws.staywell.com/markup">string</RegularTitle>
				<InvertedTitle xmlns="http://ws.staywell.com/markup">string</InvertedTitle>
				<Blurb xmlns="http://ws.staywell.com/markup">string</Blurb>
				<PostingDate>XMLDateTime</PostingDate>
				<Gender>All | Female | Male</Gender>
			</Document>
		</DocumentList>
	</soap:Body>
</soap:Envelope>
HTTP Post (searchString must be URL encoded) 
POST /sitename/Documents.svc/DocumentSearch HTTP/1.1
Host: external.ws.staywell.com
Content-Type: application/x-www-form-urlencoded
Content-Length: length

XMLRequest=searchString
HTTP Get (searchString must be URL encoded) 
GET /sitename/Documents.svc/DocumentSearch?XMLRequest=searchString HTTP/1.1
Host: external.ws.staywell.com
Example searchString values:

Return all licensed content containing the words "pain" and "angina"

<SearchCriteria><FullText LogicalOperator="And">pain angina</FullText></SearchCriteria>
Return all licensed content containing either "pain" or "angina" or both: 
<SearchCriteria><FullText LogicalOperator="Or">pain angina</FullText></SearchCriteria>
Return all licensed content containing "heart" in the title: 
<SearchCriteria><Title>heart</Title></SearchCriteria>
Return all licensed content of ContentType 1 or 2: 
<SearchCriteria><ContentTypes><ContentType ContentTypeId="1"/><ContentType ContentTypeId="2"/></ContentTypes></SearchCriteria>
Return all licensed content with a PostingDate of January 1, 2004: 
<SearchCriteria><PostingDate>2004-01-01</PostingDate></SearchCriteria>
Return all licensed content of ContentType 1 containing "heart" in the title and "pain" in the body: 
<SearchCriteria>
		<ContentTypes>
				<ContentType ContentTypeId="1"/>
		</ContentTypes>
		<Title>heart</Title> 
		<FullText LogicalOperator="And">pain</FullText>
</SearchCriteria>
Return all licensed content in the Diseases and Conditions Encyclopedia collection (RootSubtopicId 32) with the string “eat” in the title: 
<SearchCriteria>
		<Title>eat</Title> 
		<Subtopics> 
				<Subtopic RootSubtopicId="32"/> 
		</Subtopics> 
</SearchCriteria>
Example Results

DocumentSearch for "heart" in Title (format is identical for all DocumentSearch results)

<?xml version="1.0" encoding="utf-8"?>
<DocumentList xmlns="http://ws.staywell.com">
	<Document ContentTypeId="1" ContentId="1" IsCustom="0">
		<Language code="en"/>
		<RegularTitle xmlns="http://ws.staywell.com/markup">Helping the Heart Through Cardiac Rehab</RegularTitle>
		<Gender>All</Gender>
	</Document>
	<Document ContentTypeId="1" ContentId="12" IsCustom="0">
		<Language code="en"/>
		<RegularTitle xmlns="http://ws.staywell.com/markup">Heart Quiz for Women Only</RegularTitle>
		<Blurb>
			<p>What do you know about a woman's heart?</p>
		</Blurb>
		<Gender>Female</Gender>
	</Document>
	<Document ContentTypeId="6" ContentId="514918" IsCustom="0">
		<Language code="en"/>
		<RegularTitle xmlns="http://ws.staywell.com/markup">New Hope for People With Heart Failure</RegularTitle>
		<Gender>All</Gender>
		<PostingDate>2003-09-03T00:00:00.0000000-06:00</PostingDate>
	</Document>
	<Document ContentTypeId="22" ContentId="ClientHeart" IsCustom="1" Owner="ClientSiteName">
		<Language code="en"/>
		<RegularTitle xmlns="http://ws.staywell.com/markup">Visit Our Heart Health Center</RegularTitle>
		<Gender>All</Gender>
	</Document>
</DocumentList>