Integrating with Other Systems

There are many different ways that you can integrate LabTrove with other systems that you use. For example, you can export your content from the Notebook for use in other locations or from which to extract content such as URLs. For more information about how to export your Entries from LabTrove and the different formats available, see the Exporting content from a notebook section below.

You can also share templates that you have created with others in your community by using the myExperiment website. For more information, and steps for including your templates on the myExperiment website, see the Sharing templates using myExperiment section below.

You can also connect LabTrove directly to sensors and instruments in your workplace or the environment by writing your own plugins to LabTrove. Using a plugin you can create, edit, and add data to Entries automatically. For example, you could create a new Entry each time an instrument completes an analysis of a sample, or each time the temperature in a room changes by a specified amount. For more information about connecting other devices to LabTrove, see the Writing plugins for LabTrove section below.

Exporting content from a notebook

In LabTrove you can export content from the Notebook to be used in other systems or for other purposes. There are two options for exporting the contents of the Notebook:

Export a single Entry
Export a whole Notebook or multiple Entries

In addition to the number of Entries that you can export, the options for exporting also determine the file type that is exported. If you choose to export a single Entry you can select to export an image of the Entry or an XML representation of the Entry. If you select to export a whole Notebook or multiple Entries the format of the export is HTML together with resources from the Notebook.

Exporting an individual post

You can choose to export an individual Entry as either an XML file or a PNG image file. You can choose whether to include details of attached data files on the Entry in the XML file export option.

Exporting an Entry as an XML File

To export a Entry as an XML file:

Locate the Entry you want to export, and click on the title to display the Entry page.
In the This Post section on the navigation menu, click the link XML under the Export: heading.

In some browsers the XML file is automatically opened in the browser when you click on the link. To download the XML file, right click the link and select the appropriate option to download the file to your file system.

If you want to include references to information about data files attached to the Entry, click the With Files link instead. The XML contains an attached_data section with URLs to XML information about the data files attached to the post. You can use these URLs to get additional XML information about the attached data files.

For more information about the XML elements and their contents, see the XML format for a Post section below.

Exporting an Entry as an ELN Item Manifest

To export a Entry as an ELN Item Manifest:

Locate the Entry you want to export, and click on the title to display the Entry page.
In the This Post section on the navigation menu, click the Item Manifest link under the Export: heading.

Exporting an image of an Entry

You can export an image of a Entry as a PNG file. To export a PNG file from a Entry:

Locate the Entry you want to export, and click on the title to display the Entry page.
In the This Post section on the navigation menu, click the PNG Image link under the Export: heading.

A PNG file is created showing the contents of the Entry including any attached files. Comments are not included. In some browsers the PNG file is automatically opened in the browser when you click on the link. To download the PNG file, right click the link and select the appropriate option to download the file to your file system.

Exporting multiple posts

You can export a whole Notebook or multiple Entries in a Notebook if you are the owner of the Notebook. The Notebook or Entries together with comments are exported as a zip file of HTML files and related resources such as images. The package also contains an index page. The index page is a list of all the Entries in your Notebook if you choose to export All Posts or it is the selected Entry if you choose to a specific Entry when you export. Owing to the evolution of LabTrove Notebooks from a blog-based system, some internal variables do still use the term blog.

Exporting all the Entries in a Notebook

To export all the entries in a notebook:

In the Notebook, select Export Blog from the This Blog section in the navigation menu.
For Index Post, ensure the option All Posts is selected.
Click Start export to begin the export. The Export Blog Processing page is displayed.
When the export has completed, the Status is displayed as Complete and the zip file is available to download.
Download the zip file to your file system.

If you return to the Notebook and click Export Blog again, the Export Blog Processing page is displayed again with your zip file.

tip

If it looks like the export is not working, try opening a new browser window and click Export Blog. Often the zip file is displayed ready to be downloaded.

Extract the contents of the zip file to view the HTML files. Open the index.html file to see a link to all the Entries in your Notebook. You can now view the contents of your Notebook offline.

Exporting selected Entries

Instead of exporting all the Entries in a Notebook you can choose to export a subset. For example, you might want to export all the Entries relating to a particular experiment. To export a subset of your Entries you must first create a Entry linking to all the Entries that you want to export. This Entry can be used as the Index Post. All the links to other Entries from the Index Post are exported and included in the zip file, together with their resources.

When you select a specific Index Post you can choose the depth of links to follow when the export is performed. For example, the default Follow Depth is 1. With this setting, all the Entries to which the Index Post is linked, are exported including Entries from Notebooks that you do not own. If you set a Follow Depth value of 2, all the links in these Entries will be followed and their associated Entries are included in the export. You can increase the Follow Depth to a value of 9. Increasing the value of the Follow Depth will increase the amount of time that the export takes and increase the number of Entries included in the export.

To export specific Entries and associated Entries:

In the Notebook, select Export Blog from the This Blog section in the navigation menu.
For Index Post, select the Entry you have chosen as the index page.
Select a Follow Depth. If you only want the Entries associated with the Index Post included in the export, leave the Follow Depth set to 1. If you want the export to include more associated Entries, increase the Follow Depth value for the depth of links to follow.
Click Start export to begin the export. The Export Blog Processing page is displayed.
When the export has completed, the Status is displayed as Complete and the zip file is available to download.
Download the zip file to your file system.

Extract the contents of the zip file to view the HTML files. Open the index.html file to see a link to all the Entries in your Notebook. You can now view the contents of your Notebook offline.

warning

The myExperiment website has been discontinued, and has been replaced by the WorkflowHub website. You can find out more about the WorkflowHub project and learn how to use it here. The instructions below are legacy instructions and will be updated soon.

The myExperiment platform provides a repository for workflows in a collaborative environment. In the laboratory notebook context, a workflow is an explicit and precise description of a scientific process. LabTrove templates represent steps in a workflow. As such, LabTrove templates are potentially very useful objects to share between researchers working with similar procedures and protocols. This topic tells you how to link LabTrove with myExperiment, by exporting the XML description of a template, together with authorship details and a representative image of the template, then uploading the XML file to myExperiment. From there, other users can share or import the template and use it in their own LabTrove Notebook.

For more information about myExperiment, refer to myExperiment: a repository and social network for the sharing of bioinformatics workflows.

Exporting a template from LabTrove

To create an XML package suitable for uploading to myExperiment, complete the following steps:

Login to your Trove
Select the Notebook that you want to work with
Select the template post that you want to export
Click PNG Image. LabTrove generates an image of the template as you view it in the LabTrove user interface, with a URI that includes the post identifier
Click XML (With Files). LabTrove generates an XML representation of the template, with a URI that includes the post identifier.

Uploading a LabTrove template to myExperiment

To upload the XML package you exported from LabTrove, complete the following steps:

Login to myExperiment.
In the New/Upload pane, select Workflow and click Go.
Type the path to the XML file of the template, or click Browse to locate the XML file.
By default, myExperiment will try to obtain descriptive metadata from the LabTrove template. If you want to supply your own description, select Enter custom metadata* and complete the appropriate fields.
(Optional) If you want to supply other metadata and settings, add tags to describe the LabTrove template and, if required, select the sharing and collaboration details.
Click Upload and Continue. The template is displayed in myExperiment.

Finding LabTrove templates in myExperiment

To search for LabTrove templates, complete the following steps:

Login to myExperiment.
In the Search field, type kind: (LabTrove templates)
Select Workflows from the drop-down menu
Click Search. A list of LabTrove templates is displayed.

Writing plugins for LabTrove

You can create your own applications to create and edit Posts. You can also write a plugin to automatically add data to a notebook. You can use these plugins to connect other devices to a E-notebook such as sensors or instruments, or you could create your own clients for the E-notebook.

The 'Using the Rest API' section below provides details of how to write a plugin using the HHTP POST request method.

Click on the following links to view examples of applications using the LabTrove APIs:

Using the Rest API

The LabTrove REST-like API enables you to add a post, edit an existing post, or add data to a post. To make calls to the LabTrove REST API, use the HTTP POST request method. This topic describes how to construct the POST request and provides examples of the XML data that you send in the body of the HTTP request. The examples topics also explain the XML response that LabTrove returns when you use its REST API.

You can use any programming method for accessing web servers.

Assembling the POST request

Construct the request string as:

/api/rest/<action>/uid/<uid>

where:

<action> can be: addpost | editpost | appendpost | adddata
<uid> is a hash code specific to your user ID. Locate your hash code as follows:

Login to your Trove.
Select a post that you created.
Click your author name at the bottom of the post. A page listing your posts, comments, and user information displays.
Scroll down to the bottom of the page, copy your Master UID hash code.
Paste the hash code into the request string.

Append the request string to the LabTrove server URL to construct the POST request. For example, to add a post to a notebook on the server located at http://www.ourexperiment.org/ issue the following request, followed by the XML data:

http://www.ourexperiment.org/api/rest/addpost/uid/your_hash_code

Sample PHP code for issuing an addpost request

<?php

$url = "http://www.ourexperiment.org/api/rest/addpost/uid/your_hash_code";  // Obtain your_hash_code as described above
$xml = <<<END
<?xml version="1.0" encoding="UTF-8"?> 
<post>
  Refer to the example in the 'Adding a post' topic below
</post>
END;

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST      ,1);
curl_setopt($ch, CURLOPT_POSTFIELDS    ,array("request"=>$xml));
curl_setopt($ch, CURLOPT_FOLLOWLOCATION  ,1);
curl_setopt($ch, CURLOPT_HEADER      ,0);  // DO NOT RETURN HTTP HEADERS
curl_setopt($ch, CURLOPT_RETURNTRANSFER  ,1);  // RETURN THE CONTENTS OF THE CALL
echo $response = curl_exec($ch);
 
?>

Examples of calls to the REST API

The following sections provide examples of the XML data that you send with each <action> and help you to understand the LabTrove response.

Adding a notebook entry using the REST API

In the request string, the <action> is addpost, for example: http://www.ourexperiment.org/api/rest/addpost/uid/<uid>

The XML data that you append to the request string comprises the mandatory information for the post, the content, and optional items such as metadata and attachments. For further information, read the notes associated with the following example of the XML data for an addpost request:

<?xml version="1.0" encoding="UTF-8"?> 
<post>        
  <title>Mandatory</title>
  <section>Mandatory - Read note 1</section>        
  <author>                
    <username> Mandatory - Read note 2</username>
  </author>        
  <content>                
    Mandatory - Read note 3
  </content>        
  <datestamp>Optional – Read note 4</datestamp> 
  <blog_sname>The short name of the target {{Blog}}</blog_sname>        
  <metadata> 
    <key>Optional – Read note 5</key>
  </metadata>        
  <attached_data>
    <data>Optional – Read note 6</data> 
  </attached_data> 
</post>

Notes:

Use either an existing Section value or a new value if you want to create a new Section.
The username must have a system account for the Trove and must have the appropriate authorisation level for the notebook.
The post content can include BBCode markup.
If you provide a datestamp, it must conform to the RFC-822 date-time specification.
Replace key with the name of the metadata key to which you are giving a value: you can use either an existing key or create a new key. For example, to assert that this post is about Test 42, use 42.
You can attach data to a post only if the data item has been uploaded previously. To find out how to obtain the identifier of the data item, refer to the Adding data topic.

For example, to attach the data item with data_id 5, use:

<data type="local">5</data>

To attach multiple data items, include a <data> element for each item. Note that local is the only type option available with the current implementation.

Understanding the response

LabTrove returns a response in XML format, structured as follows:

<?xml version="1.0" encoding="UTF-8"?>  
<result>      
  <success>Read note 1</success>
  <status_code>Read note 2</status_code>
  <post_id>Read note 3</post_id>
  <post_info>Read note 4</post_info>
</result>

Notes:

True if the request was successful, otherwise false.
For details of status codes and reason phrases, refer to 'Status codes' below.
The identifier of the post added.
URI for the xml version of the added post.

Editing a notebook entry

In the request string, the <action> is editpost, for example:

http://www.ourexperiment.org/api/rest/editpost/uid/<uid>

<?xml version="1.0" encoding="UTF-8"?> 
<post> 
  <id>Mandatory - Read note 1</id>     
  <title>Mandatory</title>
  <section>Mandatory - Read note 2</section>        
  <author>                
    <username>Mandatory - Read note 3</username>
  </author>        
  <content>                
    Mandatory - Read note 4
  </content>        
  <datestamp>Optional – Read note 5</datestamp> 
  <blog_sname>The short name of the target {{Blog}}</blog_sname>        
  <metadata> 
    <key>Optional – Read note 6</key>
  </metadata>        
  <attached_data>
    <data>Optional – Read note 7</data> 
  </attached_data>
  <edit_reason>Mandatory</edit_reason> 
</post>

Notes:

To find out how to obtain the identifier of the post that you want to edit, refer to 'Understanding the response' section below.
Use either an existing Section value or a new value if you want to create a new Section.
The username must have a system account for the Trove and must have the appropriate authorisation level for the notebook.
The post content can include BBCode markup.
If you provide a datestamp, it must conform to the RFC-822 date-time specification.
Replace key with the name of the metadata key to which you want to give a value: you can use either an existing key or create a new key. For example, to assert that this post is about Test 42, use <test>42</test>.
You can attach data to a post only if the data item has been uploaded previously. To find out how to obtain the identifier of the data item, refer to the Adding data topic. For example, to attach the data item with data_id 5, use:

<data type="local">5</data>

To attach multiple data items, include a <data> element for each item. Note that local is the only type option available with the current implementation.

Understanding the response

LabTrove returns a response in XML format, structured as follows:

<?xml version="1.0" encoding="UTF-8"?>  
<result>      
  <success>Read note 1</success>
  <status_code>Read note 2</status_code>
  <post_id>Read note 3</post_id>
  <post_info>Read note 4</post_info>
</result>

Notes:

true if the request was successful, otherwise false.
For details of status codes and reason phrases, refer to 'Status codes' below.
The identifier of the post supplied in the <id> element of the request.
URI for the xml version of the added post

Appending to a notebook entry

In the request string, the <action> is appendpost, for example:

http://www.ourexperiment.org/api/rest/appendpost/uid/<uid>

<?xml version="1.0" encoding="UTF-8"?> 
<post> 
  <id>Mandatory - Read note 1</id>     
  <title>Optional - will be appended to existing post title</title>
  <section>Optional - will be appended to existing post section</section>        
  <author>                
    <username>Mandatory - Read note 2</username>
  </author>        
  <content>                
    Optional - will be appended to existing post content
  </content>        
  <datestamp>Optional – Read note 4</datestamp> 
  <blog_sname>Mandatory - The short name of the target {{Blog}}</blog_sname>        
  <metadata> 
    <key>Optional – Read note 5</key>
  </metadata>        
  <attached_data>
    <data>Optional – Read note 6</data> 
  </attached_data>
  <edit_reason>Mandatory</edit_reason> 
</post>

Notes:

To find out how to obtain the identifier of the post that you want to edit, refer to the Understanding the response section in the Adding a post topic.
The username must have a system account for the Trove and must have the appropriate authorisation level for the notebook.
The post content can include BBCode markup.
If you provide a datestamp, it must conform to the RFC-822 date-time specification.
Replace key with the name of the metadata key to which you want to give a value: you can use either an existing key or create a new key. For example, to assert that this post is about Test 42, use <test>42</test>.
You can attach data to a post only if the data item has been uploaded previously. To find out how to obtain the identifier of the data item, refer to 'Adding data' below. For example, to attach the data item with data_id 5, use:

<data type="local">5</data>

To attach multiple data items, include a <data> element for each item. Note that local is the only type option available with the current implementation.

Understanding the response

LabTrove returns a response in XML format, structured as follows:

<?xml version="1.0" encoding="UTF-8"?>  
<result>      
  <success>Read note 1</success>
  <status_code>Read note 2</status_code>
  <post_id>Read note 3</post_id>
  <post_info>Read note 4</post_info>
</result>

Notes:

true if the request was successful, otherwise false.
For details of status codes and reason phrases, refer to 'Status codes' below.
The identifier of the post supplied in the <id> element of the request.
URI for the xml version of the added post.

Adding data

In the request string, the <action> is adddata, for example:

http://www.ourexperiment.org/api/rest/adddata/…

The XML data that you append to the request string comprises the description of the dataset and the data items that it contains, as illustrated by the following example of the XML data for an adddata request:

<?xml version="1.0" encoding="UTF-8"?>
<dataset>        
  <title>Mandatory – Descriptive name for the data item</title>        
  <data>  
    <dataitem>Read the Multiple data items section</dataitem> 
  </data> 
</dataset>

Multiple data items

A dataset comprises one or more files containing the same data but in different formats. For example, the main dataitem might be in a machine-readable format and the second dataitem might be in a human-readable format, such as .JPG.

Attributes:

main - identifies the principal dataitem in the dataset: main can take any value.
type - can be url, inline orfile: if type="url", LabTrove obtains the data by reference to the URL; if type="inline", LabTrove obtains the data by uploading the file type="file". The file can be uploaded as multipart/form-data file.
ext - identifies the file type by its extension.

Examples:

  <dataitem type="url" ext="pdf" filename="THESIS.pdf">http://url.of.file/THESIS.pdf</dataitem>                
  <dataitem type="inline" ext="txt" main="1" filename="yourData.txt"># base64 encoded#</dataitem>         
  <dataitem type="file" ext="txt" filename="yourData.txt"># the multipart file variable name #</dataitem>  

When you upload data inline, convert the content of the file to base64 encoded format and supply the resulting string as the body of the dataitem. LabTrove stores the data with the name yourData.txt. There is a file size limit of approximately 500KB when uploading data inline.

Understanding the response

LabTrove returns a response in XML format, structured as follows:

<?xml version="1.0" encoding="UTF-8"?>  
<result>      
  <success>Read note 1</success>
  <status_code>Read note 2</status_code>
  <data_id>Read note 3</data_id>
</result>

Notes:

true if the request was successful, otherwise false.
For details of status codes and reason phrases, refer to 'Status codes' below.
The identifier of the dataset added.

Status codes

Status codes returned by the REST API The LabTrove REST API returns status codes and reason phrases that comply with the HTTP conventions described in RFC 2616.

Some of the status codes are generic: LabTrove can return them for any action. Other codes are specific to the addpost and editpost`` actions; some are specific to the editpostaction only. There are no codes specific to theadddata``` action.

HTTP code 500 corresponds to Internal Server Error: LabTrove returns a variety of reason phrases for code 500.

Generic codes

OK				- Action successfully received, understood, and accepted
Unauthorised			- The UID has authorisation level 0 or is unknown
action: Action Not Found	- Check the spelling of the action
Received XML did not parse	- LabTrove could not understand the XML data

Codes for addpost and editpost

Unauthorised For that blog		- The UID is not authorised to add or edit posts on the E-notebook
Unauthorised to post as someone else	- The UID does not have Administrator authorisation level
blog or blog_sname not set		- Required information not supplied in XML data
blog not found				- The Trove has no E-notebook corresponding to the blog_sname supplied
Unknown author				- The Trove does not recognise the username supplied in the XML data
no title set				- Required information not supplied in XML data
no section set				- Required information not supplied in XML data
no author set				- Required information not supplied in XML data
no content set				- Required information not supplied in XML data

Codes for editpost only

Unauthorised to edit someone else's post	- The UID does not have Editor or Administrator authorisation level
blog post not found				- The Trove has no post corresponding to the post id supplied
no edit reason					- The mandatory edit_reason element was empty or was not supplied

XML Format for an Entry

If you choose to export an entry from a notebook in XML format, the following elements are recorded in the XML file for that entry:

Element

Description

identification number of the Post

rid

revision number

title

the title of the Post

section

the metadata description of the Post

author

stores author information

username	the authentication URL
name	the name of the author

content

stores the raw content of the Post

html

stores the HTML content (raw content + HTML tags)

datestamp

the datetime of the original Post

timestamp

the datetime of the most recent revision

blog

the id number of the E-notebook

key

the key associated with the Post

metadata

<key> elements where 'key' can be any name and the element contains the value of the 'key'

links

link data for the Post

uri	the URI of the Post
permalink	the permalink of the Post

formats

formats available for the Post

format

Mime type of resource (HTML, XML, or PNG) and associated URL

comments

stores the comments about the Post

id	identification number of the comment
author	author of the comment
title	title of the comment
content	raw content of the comment
html	html content (raw content plus HTML tags)
datestamp	the datetime of the comment

What to do next:

Integrating with Other Systems

Exporting content from a notebook

Exporting an individual post

Exporting an Entry as an XML File

Exporting an Entry as an ELN Item Manifest

Exporting an image of an Entry

Exporting multiple posts

Exporting all the Entries in a Notebook

Exporting selected Entries

Exporting a template from LabTrove

Uploading a LabTrove template to myExperiment

Finding LabTrove templates in myExperiment

Writing plugins for LabTrove

Using the Rest API

Assembling the POST request

Sample PHP code for issuing an addpost request

Examples of calls to the REST API

Adding a notebook entry using the REST API

Understanding the response

Editing a notebook entry

Understanding the response

Appending to a notebook entry

Understanding the response

Adding data

Multiple data items

Understanding the response

Status codes

Generic codes

Codes for addpost and editpost

Codes for editpost only

XML Format for an Entry

Funding

Useful Links

Connect

Integrating with Other Systems

Exporting content from a notebook​

Exporting an individual post​

Exporting an Entry as an XML File​

Exporting an Entry as an ELN Item Manifest​

Exporting an image of an Entry​

Exporting multiple posts​

Exporting all the Entries in a Notebook​

Exporting selected Entries​

Sharing templates using myExperiment​

Exporting a template from LabTrove​

Uploading a LabTrove template to myExperiment​

Finding LabTrove templates in myExperiment​

Writing plugins for LabTrove​

Using the Rest API​

Assembling the POST request​

Sample PHP code for issuing an addpost request​

Examples of calls to the REST API​

Adding a notebook entry using the REST API​

Understanding the response​

Editing a notebook entry​

Understanding the response​

Appending to a notebook entry​

Understanding the response​

Adding data​

Multiple data items​

Understanding the response​

Status codes​

Generic codes​

Codes for addpost and editpost​

Codes for editpost only​

XML Format for an Entry​

Funding

Useful Links

Connect

Exporting content from a notebook

Exporting an individual post

Exporting an Entry as an XML File

Exporting an Entry as an ELN Item Manifest

Exporting an image of an Entry

Exporting multiple posts

Exporting all the Entries in a Notebook

Exporting selected Entries

Sharing templates using myExperiment

Exporting a template from LabTrove

Uploading a LabTrove template to myExperiment

Finding LabTrove templates in myExperiment

Writing plugins for LabTrove

Using the Rest API

Assembling the POST request

Sample PHP code for issuing an addpost request

Examples of calls to the REST API

Adding a notebook entry using the REST API

Understanding the response

Editing a notebook entry

Understanding the response

Appending to a notebook entry

Understanding the response

Adding data

Multiple data items

Understanding the response

Status codes

Generic codes

Codes for addpost and editpost

Codes for editpost only

XML Format for an Entry