Reference Manager 11
WSDL Documentation
July, 2004
Thomson ISI ResearchSoft

--------------------------------------------------
CONTENTS:
--------------------------------------------------
I. 	SOAP OPERATIONS
II.	XML SYNTAX
III.	DETAILED EXAMPLES

--------------------------------------------------
I. SOAP OPERATIONS
--------------------------------------------------

The SOAP Services in Reference Manager 11 provide the following operations:
* GetPublishedDatabases    -	Get a list of databases currently available via SOAP (WebPublisher).
* GetSearchableFields      -	Get a list of fields which can be searched (as configured in the RM host application).
* SearchAndReturnIDs       -	Search one or more databases and retrieve record IDs for matching records.
* SearchAndReturnRecords   -	Search one or more databases and retrieve matching records in XML format.
* ReadRecord               - 	Return an RM record in XML format.
* WriteRecord              -	Write an XML record back to the RM database.
* CreateRecord             -	Create a new record in the RM database from a given XML record.
* DeleteRecord             -	Delete a record from an RM database.
* GetOutputStyles          -	Get a list of output styles available in the RM host application.
* FormatRecords            -	Format a list of individual records according to a designated output style.
* FormatBibliography       -	Format a list of records as a bibliography according to a designated output style.
* Export                   -	Export a list of records in the designated output format.
* GetFieldInfo             -	Get a list of included fields and field names for a given reference type and database.
* GetReferenceTypes        -	Get a complete list of reference type names and fields for a given database.
* GetURLs                  - 	Get a list of the URLs used to link back to records retrieved from Internet databases.

Note: To use the SOAP Services WSDL file, you will need to edit one line to point to your running Web Publisher installation. Find the section near the end of the WSDL file that looks like this:

<service name="RSService">
  <port name="RSSoapServer" binding="y:RSSoapServer">
    <soap:address location="http://localhost/cgi-bin/RSSoapServer"/>
  </port>
</service>

Change "localhost" to reflect your IP address (displayed on the "Configure" tab in RM's "Web Publisher" dialog), so that the URL looks like, for instance:

http://123.45.67.89/cgi-bin/RSSoapServer

To access the WSDL file from your SOAP client, use the URL:

http://123.45.67.89/wsdl/RSSoapServices.wsdl

where (again) 123.45.67.89 is replaced by your actual IP address.


--------------------------------------------------
II. XML SYNTAX
--------------------------------------------------
In Reference Manager SOAP Services, database records are represented in an XML format. This format is described in the RSXML DTD document (in the "Export" folder of your RM 11 installation).

In addition, XML is used throughout RM SOAP Services to represent information. Several operations require XML input to express a search query or formatting directive, while others return information (for instance, on Reference Types) expressed in XML. These syntaxes are described below.

1. Search

For the SearchAndReturnIDs and SearchAndReturnRecords operations, the searchExpression parameter uses the following XML syntax:

<query>
   <term field="Titles">dolphins</term>
<query>

* A list of searchable fields can be retrieved using the GetSearchableFields operation.
* Additional terms can be added using Boolean operators, i.e.:

<query>
   <AND>
      <term field="Authors">Angel*</term>
      <term field="Titles">ocean</term>
   </AND>
</query>



2. Sort

The SearchAndReturnIDs and SearchAndReturnRecords operations also require a sortKey parameter, which uses the following syntax:

<recordlist_sort>
   <key id="4" ascending="true"/>
</recordlist_sort>

* Up to three sort keys can be provided, each with their own "ascending" setting (for descending sort, set "ascending" to "false"), i.e.:

<recordlist_sort>
   <key id="4" ascending="true"/>
   <key id="3" ascending="true"/>
   <key id="5" ascending="false"/>
</recordlist_sort>

This will sort records first in alphabetical order by primary author, then in alphabetical order by title (i.e. records with the same author will be ordered by title), then in reverse date order.

* The ids which can be used for sort keys are as follows (this list is identical to the RM desktop application):

1 Ref Type          11 Periodical         21 User Def 4        31 Misc 3
2 Ref ID            12 Volume             22 User Def 5        32 Address
3 Title, primary    13 Title, secondary   23 Title, series     33 Web/URL
4 Authors, primary  14 Authors, secondary 24 Authors, series   34 Link To PDF
5 Date, primary     15 Issue              25 Abstract          35 Link To Full-text
6 Notes             16 Pub Place          26 ISSN/ISBN         36 Related Links
7 Keywords          17 Publisher          27 Availability      37 Image(s)
8 Reprint           18 User Def 1         28 Date, secondary
9 Start Page        19 User Def 2         29 Misc 1
10 End Page         20 User Def 3         30 Misc 2



3. Format

The FormatRecords and FormatBibliography operations each require an outputFormat parameter, which uses the following XML syntax:

<format_reflist>
   <destination>0</destination>
   <style>Annotated</style>
   <font name="Times New Roman" size="10"/>
   <title>Reference List</title>
   <numbering enabled="true" start="1"/>
   <optional-fields abstract="true" notes="false"/>
</format_reflist>

* destination: The type of text output desired. One of the following values:
	0	HTML
	1	RTF
	2	Plain text

* style: The RM Output Style, by name. Send "*default*" to use the default Web Publisher output style as configured in RM.

* font: (optional) The font name and size to use.

* title: (optional) For a bibliography, this will be used as a title at the top of the page.

* numbering: Indicate whether or not to number the items in the formatted list, and what number to start from. Defaults to "true" and "1".

* optional-fields: (optional) Indicate whether or not to include optional fields in the formatted output. Defaults to "false" for all optional fields.


4. Record IDs

Several operations either require or return record IDs as XML, i.e.:

<RecordID database="Sample" recNum="1131"/>

For operations such as ReadRecord that take a single record ID, these IDs can be used as-is, i.e. there is no need to parse out the attributes.

For operations that take a "recordList" parameter (i.e. FormatRecords, Export), provide a set of record IDs within <item> tags, i.e.:

<item>&lt;RecordID database="Sample" recNum="1131"/></item>
<item>&lt;RecordID database="Sample" recNum="373"/></item>

Tools such as the SOAP::Lite module for Perl will handle such lists transparently, allowing the record list returned from a Search operation to be simply passed into a format or export operation.


5. Reference Types and Fields

GetReferenceTypes will return information on reference types in the following format:

<REFERENCE_TYPES>
   <REFERENCE_FIELDS id="1" name="Journal">
      <FIELD id="1" name="Ref Type" tag="ref-type"/>
      <FIELD id="2" name="Ref ID" tag="rec-number"/>
      <FIELD id="3" name="Title" tag="title"/>
      (etc.)
   </REFERENCE_FIELDS>
   <REFERENCE_FIELDS id="2" name="Book, Whole">
      (etc.)
   </REFERENCE_FIELDS>
   (etc.)
</REFERENCE_TYPES>

* "name" indicates the name of the reference type or field as configured in the RM host application.
* "tag" indicates the corresponding element name in RSXML.

GetFieldInfo returns a similar XML structure describing the fields of one specified reference type.



--------------------------------------------------
III. DETAILED EXAMPLES
--------------------------------------------------

This section provides detailed examples of each of the SOAP operations.

* Suggestions are provided for possible variables. 
* All XML string examples have their less-than sign '<' encoded as '&lt;'. This is necessary whenever passing XML within a SOAP request. Some SOAP client tools will do this automatically.
* All RM SOAP Services operations require an initial "version" parameter. This parameter is always "1.0" for Reference Manager 11.

1.	"GetPublishedDatabases"
	SOAP parameters in: 
	1. version (string) = "1.0"
	
	SOAP results back:
	1. Count (short) = '2'
	2. List (array):
		For each Item:
		a. write = 'yes/no'
		b. read = 'yes/no'
		c. Text (string/database name) = "Sample" 

	Sample SOAP response returned:
	<?xml version="1.0" encoding="UTF-8" standalone="no"?>
	   <SOAP-ENV:Envelope 
	   xmlns:SOAPSDK1="http://www.w3.org/2001/XMLSchema" 
	   xmlns:SOAPSDK2="http://www.w3.org/2001/XMLSchema-instance"
	   xmlns:SOAPSDK3="http://schemas.xmlsoap.org/soap/encoding/"
	   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
	      <SOAP-ENV:Body SOAP-ENV:encodingStyle="">
	         <SOAPSDK4:GetPublishedDatabasesResults xmlns:SOAPSDK4="urn:RSSoap1.0">
	            <SOAPSDK4:Count>3</SOAPSDK4:Count>
	            <SOAPSDK4:List SOAPSDK2:type="SOAPSDK3:Array"SOAPSDK3:arrayType="SOAPSDK1:string[3]">
	               <SOAPSDK4:Item write="yes"read="yes">Sample</SOAPSDK4:Item>
	               <SOAPSDK4:Item write="yes"read="yes">Bach</SOAPSDK4:Item>
	               <SOAPSDK4:Item write="yes"read="yes">Caffeine</SOAPSDK4:Item>
	           </SOAPSDK4:List>
	        </SOAPSDK4:GetPublishedDatabasesResults>
	      </SOAP-ENV:Body>
	   </SOAP-ENV:Envelope>



2.	"GetSearchableFields"
	SOAP parameters in:
	1. version (string) = "1.0"

	SOAP Results back:
	1. Count (short) = '44'
	2. List (array): 
		A. Item[0] (string) = "Authors [4,14,24]"
		. . . . . . .
		Z. Item[43] (string) = "Image(s) [37]"

	Note: Field numbers will appear with the field name (as above) only if the RM host application is configured to display field numbers.



3.	"SearchAndReturnIDs"
	SOAP parameters in: 
	1. version (string) = "1.0"
	2. searchExpression (xmlstring)	=	"<query><term field="Keywords">dolphin</term></query>"
						Which gets sent as:
						"&lt;query>&lt;term field="Keywords">dolphin&lt;/term>&lt;/query>"
	3. databaseCount (short)	=	'1'
	4. sortKey (xmlstring)		=	"<recordlist_sort><key id='4' ascending='true'/></recordlist_sort>"
						Which gets sent as:
						"&lt;recordlist_sort>&lt;key id='4' ascending='true'/>&lt;/recordlist_sort>"
	5. maxRecords (long)		=	'0'  (Zero indicates no return record limit)
	6. databaseArray (array)
		A. item[0] (string/database name) =	"Sample" 

		
	SOAP results back:
	1. Count (short) = '110'
	2. results_list (array): 
		For each Item:
		a. Index (short) = '0'  (Indicates position in sorted list)   
		b. Database (string) = "Sample"
		c. Text (xmlstring/record ID) =  "<RecordID database="Sample" recNum="227"/>"  
		
	Note: The databaseArray parameter requires an array of database names. For SOAP clients that do not easily handle 
	array parameters, create the XML using <item> tags to delimit each name, i.e.

	<databaseArray>
	   <item>Sample</item>
	   <item>Bach</item>
	</databaseArray>



4.	"SearchAndReturnRecords"
	SOAP parameters in:
	1. version (string) = "1.0"
	2. searchExpression (xmlstring) =  	"&lt;query>&lt;term field="Keywords">dolphin&lt;/term>&lt;/query>"
	3. databaseCount (short)	=	'1'
	4. sortKey (xmlstring) 		= 	"&lt;recordlist_sort>&lt;key id='4' ascending='true'/>&lt;/recordlist_sort>"
	5. maxRecords (long) 		= 	'100'
	6. databaseArray (array):
		A. item[0] (string/database name) = "Sample" 

	SOAP Results back:
	1. Count (short) = '91'
	2. List (array)
		For each Item: The record in RSXML format.



5.	"ReadRecord"
	SOAP parameters in:
	1. version (string) 	=	"1.0"
	2. recordID (xmlstring)	=	"<RecordID database="Sample" recNum="75"/>"
					Which gets sent as:
					"&lt;RecordID database="Sample" recNum="75"/>"
	3. database (string) 	= 	"Sample"

	SOAP Results back:
	record = The record in RSXML format.

	Note: To preserve diacritical characters and 'escaped' punctuation, data returned from ReadRecord is encoded 
	using base64 encoding. Decode the returned data in order to view the XML record (some SOAP clients will
	detect and decode base64 automatically).



6.	"WriteRecord"
	SOAP parameters in:
	1. version (string) 	=	"1.0"
	2. recordID (xmlstring)	=	"<RecordID database="Sample" recNum="75"/>"
					Which gets sent as:
					"&lt;RecordID database="Sample" recNum="75"/>"
	3. database (string) 	= 	"Sample"
	4. record (xmlstring) 	= 	The record in RSXML format.

	SOAP Results back:
	recID (string) 	= "Success" or "Failure"

	Note: The "record" parameter to WriteRecord must have its type explicitly set to "string" or "base64", to
	allow RM to handle it accordingly. Use "base64" if the data is base64-encoded, and "string" otherwise.



7.	"CreateRecord"
	SOAP parameters in:
	1. version (string)	=	"1.0"
	2. database (string)	=	"Sample"
	3. record (xmlstring)	=	The record in RSXML format.

	SOAP Results back:
	recID (xmlstring) = "<RecordID database="Sample" recNum="879"/>"

	Note: The "record" parameter to CreateRecord must have its type explicitly set to "string" or "base64", to
	allow RM to handle it accordingly. Use "base64" if the data is base64-encoded, and "string" otherwise.



8.	"DeleteRecord"
	SOAP parameters in:
	1. version (string)	= 	"1.0"
	2. recordID (xmlstring) = 	"&lt;RecordID database="Sample" recNum="879"/>"
	3. database (string)	= 	"Sample"

	SOAP Results back:
	recID (string) = "Success"/"Failure"



9.	"GetOutputStyles"
	SOAP parameters in:
	1. version (string) = "1.0"

	Soap Results back:
	
	1. Count (short) = '731'
	2. List (array) 
		1. Item[0] (string) = "AAPG Bulletin"
		. . . . . . . . . 
		731. Item[730] (string) = "Zoologica Scripta"



10.	"FormatRecords"
	SOAP parameters in:
	1. version (string)	=	"1.0"
	2. recordList (array)  
		For example, with three records ...
			A. item[0] (xmlstring) = <RecordID database="Sample" recNum="227"/>
						Which gets sent as:
						&lt;RecordID database="Sample" recNum="227"/>
			B. item[1] (xmlstring) = <RecordID database="Sample" recNum="421"/>
						Which gets sent as:
						&lt;RecordID database="Sample" recNum="421"/>
			C. item[2] (xmlstring) = <RecordID database="Sample" recNum="431"/>
						Which gets sent as:
						&lt;RecordID database="Sample" recNum="431"/>
	3. outputStyle (string)	= 	"" (RM will use default style if none is provided)
	4. outputFormat (xmlstring) =	"<format_reflist>
					   <destination>0</destination>
					   <style>RM11WebPublisher</style>
					   <numbering enabled='false'/>
					</format_reflist>"
					Which gets sent as:
					"&lt;format_reflist>&lt;destination>0&lt;/destination>&lt;style>RM11WebPublisher&lt;/style>&lt;numbering enabled='false'/>&lt;/format_reflist>"

	SOAP results back 
	1. Count = '3'
	2. List (array) Formatted results, styled as per designated output style (this example returns HTML):
		A. item[0] (string) = "Brager, S., Wursig, B., Acevedo, A., and Henningsen, T.<p> Association patterns of bottle-nosed dolphins (tursiops- truncatus) in Galveston Bay, Texas<p> <b><i>Journal Of Mammalogy </b></i> Vol. 75p.431-437,  1994 <p>;"
		B. item[1] (string) = "Connor, R. C., Smolker, R. A., and Adams, A.<p>'Pop' goes the dolphin: a vocalization male bottlenose dolphins produce during consortships<p><b><i>Behaviour </b></i> Vol. 133p.643-662,  1996 <p>"
		C. item[2] (string) = "Connor, R. C., Richards, A. F., Smolker, R. A., and Mann, J.<p>Patterns of female attractiveness in Indian Ocean bottlenose dolphins coffee<p><b><i>Behaviour </b></i> Vol. 133p.37-69,  1996 <p>"



11.	"FormatBibliography"
	SOAP parameters in:
	1. version (string) = "1.0"
	2. recordList (array): 
		A. item[0] (xmlstring) = "<RecordID database="Sample" recNum="227"/>"
					Which gets sent as:
					"&lt;RecordID database="Sample" recNum="227"/>"
	3. outputStyle (string) = "" (RM will use default style if none is provided)
	4. outputFormat (xmlstring) =	"<format_reflist>
					   <destination>0</destination>
					   <style>RM11WebPublisher</style>
					   <numbering enabled='false'/>
					</format_reflist>"
					Which gets sent as:
					"&lt;format_reflist>&lt;destination>0&lt;/destination>&lt;style>RM11WebPublisher&lt;/style>&lt;numbering enabled='false'/>&lt;/format_reflist>"

	SOAP Results back:
	Bibliography (string) = Formatted bibliographty, styled as per designated output style (this example returns HTML):
	"<html><title></title><body>Brager, S., Wursig, B., Acevedo, A., and Henningsen, T.<p>Association patterns of bottle-nosed dolphins (tursiops- truncatus) in Galveston Bay, Texas<p><b><i>Journal Of Mammalogy </b></i> Vol. 75p.431-437,  1994 <p></body></html>"



12.	"Export"
	SOAP parameters in:
	1. version (string)	=	"1.0"
	2. recordList (array):  
		A. item[0] (xmlstring) = <RecordID database="Sample" recNum="227"/>
					 Which gets sent as:
					 &lt;RecordID database="Sample" recNum="227"/>
	3. outputFormat (string) =	"RIS"	


	SOAP Results back:
	1. ExportResults (string) = Exported records in the format specified in "outputFormat".

	Note: outputFormat can be one of the following:
		"RIS"		RIS tagged text format
		"Medlars"	Medlars tagged text format
		"Comma"		Comma-delimited text
		"Tab"		Tab-delimited text
		"XML"		RS XML format

	Note: To preserve diacritical characters and 'escaped' punctuation, data returned from Export is encoded 
	using base64 encoding. Decode the returned data in order to view the records (some SOAP clients will
	detect and decode base64 automatically).



13.	"GetFieldInfo"
	SOAP parameters in:
	1. version (string) = "1.0"
	2. database (string) = "Sample"
	3. refType (string) = "Journal"

	SOAP Results back:
	1. fields (xmlstring) = "<FIELDS><FIELD id="1" name="Ref Type" tag="ref-type"/><FIELD id="2" name="Ref ID" tag="rec-number"/><FIELD id="3" name="Title" tag="title"/><FIELD id="4" name="Authors" tag="authors"/><FIELD id="5" name="Pub Date" tag="year"/><FIELD id="33" name="Web/URLs" tag="web-urls"/><FIELD id="34" name="Link To PDF" tag="pdf-urls"/><FIELD id="35" name="Link to Full-text " tag="text-urls"/><FIELD id="36" name="Related Links" tag="related-urls"/><FIELD id="37" name="Image(s)" tag="image-urls"/><FIELD id="6" name="Notes" tag="notes"/><FIELD id="7" name="Keywords" tag="keywords"/><FIELD id="8" name="Reprint" tag="reprint-status"/><FIELD id="11" name="Journal Name" tag="secondary-title"/><FIELD id="12" name="Volume" tag="volume"/><FIELD id="15" name="Issue" tag="number"/><FIELD id="9" name="Start Page" tag="pages"/><FIELD id="10" name="End Page" tag="pages"/><FIELD id="25" name="Abstract" tag="abstract"/><FIELD id="26" name="ISSN/ISBN" tag="isbn"/><FIELD id="27" name="Availability" tag="availability"/><FIELD id="32" name="Address" tag="auth-address"/><FIELD id="18" name="User Def 1" tag="custom1"/><FIELD id="19" name="User Def 2" tag="custom2"/><FIELD id="20" name="User Def 3" tag="custom3"/><FIELD id="21" name="User Def 4" tag="custom4"/><FIELD id="22" name="User Def 5" tag="custom5"/></FIELDS>"
		
		. . . .


14.	"GetReferenceTypes"
	SOAP parameters in:
	1. version (string) = "1.0"
	2. database (string) = "Sample"

	Soap Results back:
	RefTypes (xmlstring) = "<REFERENCE_TYPES><REFERENCE_FIELDS id="1" name="Journal"><FIELD id="1" name="Ref Type" tag="ref-type"/><FIELD id="2" name="Ref ID" tag="rec-number"/><FIELD id="3" name="Title" tag="title"/><FIELD id="4" name="Authors" tag="authors"/><FIELD id="5" name="Pub Date" tag="year"/><FIELD id="33" name="Web/URLs" tag="web-urls"/><FIELD id="34" name="Link To PDF" tag="pdf-urls"/><FIELD id="35" name="Link to Full-text " tag="text-urls"/><FIELD id="36" name="Related Links" tag="related-urls"/><FIELD id="37" name="Image(s)" tag="image-urls"/><FIELD id="6" name="Notes" tag="notes"/><FIELD id="7" name="Keywords" tag="keywords"/><FIELD id="8" name="Reprint" tag="reprint-status"/><FIELD id="11" name="Journal Name" tag="secondary-title"/><FIELD id="12" name="Volume" tag="volume"/><FIELD id="15" name="Issue" tag="number"/><FIELD id="9" name="Start Page" tag="pages"/><FIELD id="10" name="End Page" tag="pages"/><FIELD id="25" name="Abstract" tag="abstract"/><FIELD id="26" name="ISSN/ISBN" tag="isbn"/><FIELD id="27" name="Availability" tag="availability"/><FIELD id="32" name="Address" tag="auth-address"/><FIELD id="18" name="User Def 1" tag="custom1"/><FIELD id="19" name="User Def 2" tag="custom2"/><FIELD id="20" name="User Def 3" tag="custom3"/><FIELD id="21" name="User Def 4" tag="custom4"/><FIELD id="22" name="User Def 5" tag="custom5"/></REFERENCE_FIELDS>(etc.)</REFERENCE_TYPES>"



15.	"GetURLs"
	SOAP parameters in:
	1. version (string) = "1.0"

	Soap Results back:
	1. Count (short) = '9'
	2. List (string)
		For each Item:
		a. App (string) = "PM"
		b. Text (string) = "http://www.ncbi.nlm.nih.gov/entrez/query.fcgi?cmd=Retrieve&amp;db=pubmed&amp;dopt=Citation&amp;list_uids="