Notebook Browser 1.3 Developer Documentation (How-To)


Overview of REpresentational State Transfer (REST) Web Service API for Notebook Browser integration with Symyx Notebook

The REST web services enable integration between legacy Symyx notebooks (Process Notebook, Formulations Notebook, Discovery Notebook 4.1) and Symyx Notebook 6.6 and 6.7. To allow a client to browse legacy notebook repositories and search for documents across legacy notebook repositories, the REST web services API supports searching metadata fields, structures, and reactions, as well as full-text searching of indexed PDF documents.


Examples of Searches


URL Search Parameters

The URL for conducting a search can use any of the following parameters.

casNumber

Chemistry Abstract Service identifier of the material (exact match)

createdAfter

format is MM/dd/yyyy

createdBefore

format is MM/dd/yyyy

createdBy

the username of the person that created the reaction/document (exact match)

deptGroup

name of the department or group (exact match)

pdf

returns the PDF of the document if true. Default: false

material

a chimestring representation of a molecule to be searched

materialOper

the type of structure search to conduct (case insensitive). Valid values are STRUCTURE_EXACT OR STRUCTURE_SUB (default)

materialLabel

label of the material (chemical) to search for (case insensitive), such as acetone

materialLabelOper

operator. Valid values are case-insensitive: equals or contains (default)

project

name of the project to search for (case insensitive)

projectOper

operator. Valid values are case-insensitive: equals or contains (default)

reaction

a chimestring representation of a reaction to be searched

reactionOper

the type of reaction search to conduct. Valid values are case insensitive: RXN_FLEX for exact match, RXNSIM which returns all hits that are at least 80% similar in the reacting center portion, and at least 20% similar in the molecule portion, or RXN_RSS for Reaction Substructure Search, that is, finding structures that contain a substructure in a reaction (default).

role

the role (case insensitive) of the structure (used with material searches). For Process Notebook and Formulations Notebook, possible values are: reactant or product. For Discovery Notebook, possible values are: reactant, product, fsreactant, or fsproduct, where "fs" means fractional salt.

text

for full-text search for matching documents

To learn how to format the full-text search values in your URLs, including the use of escape characters and reserved words, see the Oracle 10g reference for Oracle Text, which has a section on Special Characters in Oracle Text Queries at http://download.oracle.com/docs/cd/B19306_01/text.102/b14218/cqspcl.htm#i1006181

title

the title of the document to search for (case insensitive)

titleOper

operator. Valid values are case-insensitive: equals or contains (default)

yield

a double

yieldOper

operator. Valid values are GT for greater than (>), GTE for greater than or equals (>=), LT for less than (<), LTE for less than or equals (<=), or EQUALS (default)

Browsing Legacy Notebooks

Notebook Browser provides a set of web services to allow a client to browse a legacy Symyx notebook. The web services return a set of objects including Repositories, Containers (Folders, Notebooks, Groups) and Documents.

Retrieving All Repositories

/Repositories/ GET - list all repositories returns:
	<repositories>
		<repository href="services/Repositories/Repository.b7f380af371cec41cd6a20ffdbceda12" id="Repository.b7f380af371cec41cd6a20ffdbceda12" name="Discovery Notebook">
			<type>Discovery Notebook</type>
			<containers />
		</repository>
		<repository href="services/Repositories/Repository.a9c88a844919f75cb4bce50ef1d72f34" id="Repository.a9c88a844919f75cb4bce50ef1d72f34" name="Formulations">
			<type>Formulations</type>
			<containers />
		 </repository>
		 <repository href="services/Repositories/Repository.49475481566f1173e79bc12c755f9517" id="Repository.49475481566f1173e79bc12c755f9517" name="Process Chemistry">
			 <type>Process Chemistry</type>
			 <containers />
		 </repository>
	</repositories>

Retrieving a Single Repository

/Repositories/{repositoryId} retrieves a single repository and all direct child objects. For Process Notebook, Formulations Notebook, and Discovery Notebook, the direct child objects are the top-level folders of the repository. All of the items in a repository are returned as the name, id, and a link to get the full object.
    <repository href="services/Repositories/Repository.b7f380af371cec41cd6a20ffdbceda12" id="Repository.b7f380af371cec41cd6a20ffdbceda12" name="Discovery Notebook">
    	   <type>Discovery Notebook</type>
    	   <containers>
    	       <container href="services/Repositories/Repository.b7f380af371cec41cd6a20ffdbceda12/Containers/Group.3" name="CROG" id="Group.3">
			       <repositoryId>Repository.b7f380af371cec41cd6a20ffdbceda12</repositoryId>
				   <type>Folder</type>
				   <parentId>Repository.b7f380af371cec41cd6a20ffdbceda12</parentId>
			   </container>
        ...
	   </containers>
    </repository>

Retrieving Containers

A container is any repository object, such as Folders, Notebooks and Groups, that can contain other objects.

The following URL accesses the specified container.

Format:

   /Repositories/{repositoryId}/Containers/{containerId}

Example:

http://[your_server]/NotebookBrowser/services/Repositories/Repository.a9c88a844919f75cb4bce50ef1d72f34/Containers/Folder.175d2e40-735c-4cc6-b243-75b589f33fb6

This URL retrieves a single Container from the repository with repositoryId and the Container with containerId.

All URLs must be submitted by GET requests.


Retrieving Folders

Example: /Repositories/{repositoryId}/Containers/Folder.1 would return a Folder in the repository with folderId.

The object returned in the response contains any direct child objects.

	<Container href="services/Repositories/Repository.a9c88a844919f75cb4bce50ef1d72f34/Containers/Folder.175d2e40-735c-4cc6-b243-75b589f33fb6"
	    name="Chemical"
	    id="Folder.175d2e40-735c-4cc6-b243-75b589f33fb6">
	  <repositoryId>Repository.a9c88a844919f75cb4bce50ef1d72f34</repositoryId>
	  <type>Folder</type>
		  <containers>
			  <container xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
			  xsi:type="folder"
			  href="services/Repositories/Repository.a9c88a844919f75cb4bce50ef1d72f34/Containers/Folder.ea7421f5-c2bb-489c-a941-6a51eef44287"
			  name="Jane Smith"
			  id="Folder.ea7421f5-c2bb-489c-a941-6a51eef44287">
			      <repositoryId>Repository.a9c88a844919f75cb4bce50ef1d72f34</repositoryId>
			      <type>Folder</type>
			  <containers />
			</container>
		  </containers>
	  </Container>

Retrieving Notebooks

Example:

/Repositories/{repositoryId}/Containers/Notebook.1

returns a Notebook in the repository with notebookId = Notebook.1

The object returned in the response contains any direct child objects.

	<notebook href="services/Repositories/Repository.c72a4c95a3e56576be033b0262502c01/Containers/Notebook.1" name="Chris Notebook 1" id="Notebook.1">
	    <repositoryId>Repository.c72a4c95a3e56576be033b0262502c01</repositoryId>
	    <type>Notebook</type>
	    <parentId/>
	    <documents>
			<document href="services/Repositories/Repository.c72a4c95a3e56576be033b0262502c01/Documents/1038342"
					  name="Clone of Rxn to produce Benzene•2[ClH]"
					  id="1038342">
				<repositoryId>Repository.c72a4c95a3e56576be033b0262502c01</repositoryId>
				<type>Document</type>
			</document>
	...

Retrieving Groups

Example:

/Repositories/{repositoryId}/Containers/Group.1

returns a Group in the repository with groupId = Group.1

	<Container href="services/Repositories/Repository.c72a4c95a3e56576be033b0262502c01/Containers/Group.1"
	    name="Symyx"
	    id="Group.1">
		<repositoryId>Repository.c72a4c95a3e56576be033b0262502c01</repositoryId>
		<type>Group</type>
		<parentId>Repository.c72a4c95a3e56576be033b0262502c01</parentId>
		<containers>
			<container xsi:type="folder" href="services/Repositories/Repository.c72a4c95a3e56576be033b0262502c01/Containers/User.1"
			name="Ada Admin" id="User.1">
			<repositoryId>Repository.c72a4c95a3e56576be033b0262502c01</repositoryId>
			<type>User</type>
			<parentId>Group.1</parentId>
		<containers/>
	</container>


Retrieving Users

/Repositories/{repositoryId}/Users/
retrieves all Users from a repository
/Repositories/{repositoryId}/Users/{userId}
retrieves a single User from a repository

Response for all users:

  <users>
	  <user href="services/Repositories/Repository.a9c88a844919f75cb4bce50ef1d72f34/Users/User.51a5916d-5355-4bfc-911f-096c303b036e"
	  name="Jane Smith"
	  id="User.51a5916d-5355-4bfc-911f-096c303b036e">
	  <repositoryId>Repository.a9c88a844919f75cb4bce50ef1d72f34</repositoryId>
	  <type>User</type>
	  ...

Response for a specified user:

  <user href="services/Repositories/Repository.a9c88a844919f75cb4bce50ef1d72f34/Users/User.51a5916d-5355-4bfc-911f-096c303b036e"
      name="Marie Curie"
      id="User.51a5916d-5355-4bfc-911f-096c302a025a">
      <repositoryId>Repository.a9c88a844919f75cb4bce50ef1d72f34</repositoryId>
      <type>User</type>
  </user>

Retrieving Documents

Retrieve a document as a PDF, which includes any images.

http://your_server/NotebookBrowser/services/Repositories/Repository.8046968f-fde9-84cb-78cb-c1f5aa984d0d/Documents?documentId=Document.12ff4172-37d7-4b58-8d95-e4c465ad1ddf&properties=true&materials=true&reaction=true&xml=true

Retrieve multiple documents (in this case, three) by assigning a set of documentId parameters, as shown in the URL.

http://your_server/NotebookBrowser/services/Repositories/Repository.8046968f-fde9-84cb-78cb-c1f5aa984d0d/Documents?documentId=Document.12ff4172-37d7-4b58-8d95-e4c465ad1ddf&documentId=Document.78248040-316a-40b6-a577-0d9e6d986d13&documentId=Document.eb2ebf05-3776-4a18-94db-5315f6cd2c9e&properties=true&materials=true&reaction=true&xml=true

/Repositories/{repositoryId}/Documents?documentId={documentId}
retrieves a single document from a repository if the parameter is set to true as shown above with pdf=true.

Legacy Note:
In version 1.1, only one (1) document could be retrieved, and the syntax to specify the Document was different: http://your_server/NotebookBrowser/services/Repositories/Repository.a9c88a844919f75cb4bce50ef1d72f34/Documents/Document.f2da9551-d469-4574-b25e-30fcd880c4dd?properties=true&pdf=true

Parameters for the Documentation Service

documentId (new in 1.2)
the identifier for the document to retrieve
intermediateFile (new in 1.2)
returns the XML that Symyx Notebook 6.5 uses to import
materials
includes material data in the returned document if true. Default: false. See Material Properties of Retrieved Documents
pdf
includes a PDF (Base 64 encoded) in the returned document if true. Default: false
previewImage (new in 1.2)
includes the document's preview image (Base 64 encoded) if true. Default: false
previewImageHeight (new in 1.2)
specifies the height in pixels of the previewImage. Default: 250
previewImageWidth (new in 1.2)
specifies the width in pixels of the previewImage. Default: 645
properties
includes the document properties in the returned document if true. Default: false
reaction
includes reaction data in the returned document if true. Default: false.
xml
includes the XML representation the returned document if true. Default: false
Tip: Instead of setting any of these boolean parameters to false, omit the parameter.


XML Tags of Documents Returned

The web service returns a predefined set of XML elements and attributes, which means that the document returned in the response is a representation of the original legacy document. For example,
...
<document href="services/Repositories/Repository.a9c88a844919f75cb4bce50ef1d72f34/Documents/Document.f2da9551-d469-4574-b25e-30fcd880c4dd"
			 name="Trilayer Coated Tablet" id="Document.f2da9551-d469-4574-b25e-30fcd880c4dd">
<repositoryId>Repository.a9c88a844919f75cb4bce50ef1d72f34</repositoryId>
<type>Document</type>

<properties>
    <name>Trilayer Coated Tablet</name>
    <createdOn>01/31/2009</createdOn>
    <createdBy>vault.admin</createdBy>
    <version>2</version>
    <pageSet>5</pageSet>
    <type>LJ-AXF</type>
    <state>Checked In</state>
    <stage>In Progress</stage>
</properties>
<materials>...<materials>
<material>...<material>
<casNumber/>
<formula>C12 H22 O11</formula>
<molfile>...<molfile>
<reaction>...<reaction>
<previewImage>...</previewImage>
<documentXML>...</documentXML>
<intermediateFile>...</intermediateFile>

Material Properties of Retrieved Documents

The web service returns a material with the following property set. Some properties might not be populated with values.
Name
the name of the material
Role
the role of the material
Molfile
a Base 64 encoded molfile
Formula
the formula of the material
Molweight
the molecular weight of the material
Cas number
the CAS number of the material (for Process Notebook and Formulations Notebook)

Retrieving the Version Number of Symyx Notebook Browser on the Web Server

(new in 1.2):

Example:

http://your_server/NotebookBrowser/services/Version

The result might be:

1.2.0.153


Web Application Description Language (WADL) XML file

The Web Application Description Language XML file describes all the services provided and the types of parameters used. It is generated automatically and available on the server where Notebook Browser is deployed. For example, http://your_server/NotebookBrowser/services/application.wadl

The following WADL section lists the parameters that can be included for a Search method (Repositories/{repositoryId}/Search) in a GET request.
	<request>
                <param type="xs:string" style="query" name="repository"/>
		<param type="xs:string" style="query" name="text"/>
		<param type="xs:string" style="query" name="title"/>
		<param default="CONTAINS" type="xs:string" style="query" name="titleOper"/>
		<param default="RXN_RSS" type="xs:string" style="query" name="reactionOper"/>
		<param type="xs:string" style="query" name="reaction"/>
		<param default="STRUCTURE_SUB" type="xs:string" style="query" name="materialOper"/>
		<param type="xs:string" style="query" name="material"/>
		<param default="CONTAINS" type="xs:string" style="query" name="projectOper"/>
		<param type="xs:string" style="query" name="project"/>
		<param type="xs:string" style="query" name="createdBy"/>
		<param type="xs:string" style="query" name="createdAfter"/>
		<param type="xs:string" style="query" name="createdBefore"/>
		<param default="CONTAINS" type="xs:string" style="query" name="materialLabelOper"/>
		<param type="xs:string" style="query" name="materialLabel"/>
		<param type="xs:string" style="query" name="casNumber"/>
		<param default="EQUALS" type="xs:string" style="query" name="yieldOper"/>
		<param type="xs:string" style="query" name="yield"/>
		<param type="xs:string" style="query" name="deptGroup"/>
		<param type="xs:string" style="query" name="role"/>
	</request>