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/cgibin/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
31 Misc 3
2 Ref ID
12 Volume
32 Address
3 Title, primary
13 Title, secondary
33 Web/URL
4 Authors, primary 14 Authors, secondary
series
34 Link To PDF
5 Date, primary
15 Issue
35 Link To Full-text
6 Notes
16 Pub Place
36 Related Links
7 Keywords
17 Publisher
37 Image(s)
8 Reprint
18 User Def 1
secondary
9 Start Page
19 User Def 2
10 End Page
20 User Def 3
21 User Def 4
22 User Def 5
23 Title, series
24 Authors,
25 Abstract
26 ISSN/ISBN
27 Availability
28 Date,
29 Misc 1
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/XMLSchemainstance"
xmlns:SOAPSDK3="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAPENV="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)
Note: The "record"
its type explicitly set
allow RM to handle
data is base64-encoded,
= "Success" or "Failure"
parameter to WriteRecord must have
to "string" or "base64", to
it accordingly. Use "base64" if the
and "string" otherwise.
7.
"CreateRecord"
SOAP parameters in:
1. version (string) =
2. database (string)
3. record (xmlstring)
format.
"1.0"
=
"Sample"
=
The record in RSXML
SOAP Results back:
recID (xmlstring) = "<RecordID database="Sample"
recNum="879"/>"
Note: The "record"
its type explicitly set
allow RM to handle
data is base64-encoded,
parameter to CreateRecord must have
to "string" or "base64", to
it accordingly. Use "base64" if the
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="weburls"/><FIELD id="34" name="Link To PDF" tag="pdfurls"/><FIELD id="35" name="Link to Full-text " tag="texturls"/><FIELD id="36" name="Related Links" tag="relatedurls"/><FIELD id="37" name="Image(s)" tag="imageurls"/><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="reftype"/><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="weburls"/><FIELD id="34" name="Link To PDF" tag="pdfurls"/><FIELD id="35" name="Link to Full-text " tag="texturls"/><FIELD id="36" name="Related Links" tag="relatedurls"/><FIELD id="37" name="Image(s)" tag="imageurls"/><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="