543 lines
No EOL
21 KiB
HTML
543 lines
No EOL
21 KiB
HTML
<!DOCTYPE HTML>
|
|
<html lang="en">
|
|
<head>
|
|
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
|
|
<meta charset="utf-8">
|
|
<title>Setting up VIVO to use OpenSocial Gadgets</title>
|
|
<link rel="stylesheet" href="./css/doc.css" media="screen">
|
|
</head>
|
|
<body>
|
|
<div id="branding" role="banner">
|
|
<h1 class="vivo-logo"><a href="/"><span class="displace">VIVO</span></a></h1>
|
|
</div>
|
|
<!-- Start of content -->
|
|
<div id="wrapper-content" role="main">
|
|
<h1>Setting up VIVO to use OpenSocial Gadgets</h1>
|
|
<small>
|
|
Instructions for connecting VIVO and Open Research Networking Gadgets
|
|
</small>
|
|
<p>
|
|
This document contains instructions on how to configure your VIVO
|
|
installation to use OpenSocial gadgets.
|
|
</p>
|
|
<p>
|
|
VIVO uses an extension of the OpenSocial protocols called
|
|
Open Research Networking Gadgets, or ORNG.
|
|
ORNG is a project of the Clinical & Translational Science Institute at the
|
|
University of California, San Francisco.
|
|
You can find out more about the ORNG project at their web site,
|
|
<a href="http://www.opengadgets.org/index.html">http://www.opengadgets.org/index.html</a>
|
|
</p>
|
|
<p>
|
|
ORNG supports gadgets using a modified version of Apache Shindig.
|
|
These instructions tell you how to install the ORNG Shindig web application,
|
|
and how to configure it to work with VIVO.
|
|
</p>
|
|
|
|
<hr/>
|
|
<h2 id="tableofcontents">Table of Contents</h2>
|
|
<toc>
|
|
<ol class="roman1">
|
|
<li> <a href="#installation">Installing and Configuring</a>
|
|
<ol class="roman2">
|
|
<li><a href="#database">Create database tables and procedures</a></li>
|
|
<li><a href="#config_files">Create configuration directory and key file</a></li>
|
|
<li><a href="#tomcat_settings">Modify Tomcat settings</a></li>
|
|
<li><a href="#vivo_settings">Configure VIVO</a></li>
|
|
<li><a href="#deploy">Run the deployment script</a></li>
|
|
<li><a href="#confirm">Does it work?</a></li>
|
|
</ol>
|
|
</li>
|
|
<li> <a href="#gadgets">Setting up the Gadgets</a>
|
|
<ol class="roman2">
|
|
<li><a href="#shindig_apps">The <em>shindig_apps</em> database table</a></li>
|
|
<li><a href="#shindig_app_views">The <em>shindig_app_views</em> database table</a></li>
|
|
</ol>
|
|
</li>
|
|
</ol>
|
|
</toc>
|
|
<hr/>
|
|
|
|
<h2 id="installation">I. Installing and Configuring</h2>
|
|
|
|
<h3 id="database">I.i. Create database tables and procedures</h3>
|
|
<p>
|
|
Shindig uses several database tables in MySQL to store its data:
|
|
which gadgets appear on which pages, how large are the gadgets,
|
|
what information applies to each individual, and more.
|
|
Shindig also creates stored procedures in MySQL. These are small
|
|
pieces of code that simplify the use of the database tables.
|
|
</p>
|
|
<p>
|
|
In the VIVO distribution directory, a file called
|
|
<em>vitro-core/opensocial/shindig_orng_tables.sql</em>
|
|
contains SQL commands that create the tables and
|
|
stored procedures for Shindig to use.
|
|
</p>
|
|
<p>
|
|
Tell MySQL to process this file with a command like this:
|
|
<pre>mysql -u <em>username</em> -p <em>database</em> < <em>sql_file</em></pre>
|
|
So, if your current directory is the VIVO distibution directory, and your
|
|
VIVO database is <em>vivoDb</em> and your MySQL user account is <em>vivoUser</em>,
|
|
then you might use the command this way:
|
|
<pre>mysql -u vivoUser -p vivoDb < vitro-core/opensocial/shindig_orng_tables.sql</pre>
|
|
MySQL will prompt you for the password for your MySQL user account, and then
|
|
process the file.
|
|
</p>
|
|
<p>
|
|
You may want to start your gadget collection with some example gadgets
|
|
that have been developed by the ORNG group. The file called
|
|
<em>vitro-core/opensocial/shindig_example_gadgets.sql</em>
|
|
contains SQL commands that will add these gadgets to your system's configuration.
|
|
</p>
|
|
<p>
|
|
If you want to load these example gadgets, you can use a command similar to the previous one:
|
|
<pre>mysql -u vivoUser -p vivoDb < vitro-core/opensocial/shindig_example_gadgets.sql</pre>
|
|
As before, MySQL will prompt you for the password for your MySQL user account, and then
|
|
process the file.
|
|
</p>
|
|
|
|
<h3 id="config_files">I.ii. Create configuration directory and key file</h3>
|
|
<p>
|
|
In your VIVO home directory, create a directory called <em>shindig</em>.
|
|
Under that, create directories called <em>conf</em> and <em>openssl</em>.
|
|
Your VIVO home directory will look something like this:
|
|
<pre> [VIVO home directory]
|
|
|
|
|
|--shindig
|
|
| |
|
|
| |--conf
|
|
| |
|
|
| |--openssl
|
|
|
|
|
|--solr
|
|
|
|
|
|--uploads</pre>
|
|
</p>
|
|
|
|
<p>
|
|
Shindig uses an encryption key to insure that the communication
|
|
between the gadget and the server is secure.
|
|
You should create a file that contains the encryption key,
|
|
and store that file in the <em>shindig/openssl</em> directory that you created.
|
|
</p>
|
|
<p>
|
|
On Unix-based systems (like Linux or Mac OS X), this command will create
|
|
an encryption key from a random seed:
|
|
<pre>dd if=/dev/random bs=32 count=1 | openssl base64 > <em>[key-file]</em></pre>
|
|
For example, if your VIVO home directory is <em>/usr/local/vivo/data</em>,
|
|
you might use the command this way:
|
|
<pre>dd if=/dev/random bs=32 count=1 | openssl base64 > /usr/local/vivo/data/shindig/openssl/securitytokenkey.txt</pre>
|
|
</p>
|
|
<p>
|
|
If your VIVO installation is installed on a machine that runs Microsoft Windows,
|
|
you will need to find another way to create an encryption key.
|
|
The easiest way might be to find a Unix-based machine,
|
|
issue the command above, and copy the resulting file to your Windows machine.
|
|
</p>
|
|
|
|
<h3 id="tomcat_settings">I.iii. Modify Tomcat settings</h3>
|
|
<p>
|
|
The Shindig application must know where to find the configuration file that you created in
|
|
Step I.
|
|
It must also know its own URL, so that URL can be inserted into the gadgets.
|
|
</p>
|
|
<p>
|
|
This information is provided through startup parameters in Tomcat.
|
|
With most installations of Tomcat, the "setenv.sh" or
|
|
"setenv.bat" file in Tomcat's bin directory is a convenient place to
|
|
set these parameters.
|
|
<em>If this file does not exist in Tomcat's bin directory, you can create it.</em>
|
|
</p>
|
|
<p>
|
|
Here is an example of the setenv file, showing only the Shindig requirements:
|
|
<pre>export CLASSPATH=/usr/local/vivo/data/shindig/conf
|
|
export CATALINA_OPTS='-Dshindig.host=localhost -Dshindig.port=8080'</pre>
|
|
This assumes that your setenv file was empty before starting this process,
|
|
and that you used the default location for the Shindig configuration file in Step I.
|
|
In fact, it's more common for the setenv file to contain other parameters besides
|
|
those used for Shindig. In that case, it might look more like this:
|
|
<pre>export CLASSPATH=/usr/local/vivo/data/shindig/conf
|
|
export CATALINA_OPTS='-Dshindig.host=localhost -Dshindig.port=8080 -Djava.awt.headless=true -Xms1024m -Xmx1024m -XX:MaxPermSize=128m'</pre>
|
|
</p>
|
|
|
|
<h3 id="vivo_settings">I.iv Configure VIVO</h3>
|
|
<p>
|
|
In the VIVO distribution directory, the file called <em>deploy.properties</em>
|
|
contains configuration options for the VIVO application.
|
|
You must set some additional parameters so VIVO will be able to communicate with Shindig.
|
|
</p>
|
|
<table border='1' bordercolor="#CCCCCC" cellspacing="5">
|
|
<tbody>
|
|
<tr>
|
|
<th>
|
|
Property Name
|
|
</th>
|
|
<th>
|
|
Example Value
|
|
</th>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="2">
|
|
The base URL that VIVO will use when contacting the ORNG Shindig application.
|
|
Usually, this is the same host and port number as VIVO itself,
|
|
with a context path of <em>shindigorng</em>
|
|
</td>
|
|
</tr>
|
|
<tr class="odd_row">
|
|
<td>OpenSocial.shindigURL</td>
|
|
<td>http://localhost:8080/shindigorng</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="2">
|
|
The host name and port number of the Token Service that ORNG shindig creates.
|
|
Note that a value of <em>localhost</em> or <em>127.0.0.1</em> will not work.
|
|
You must provide the actual host name of your machine, followed by <em>:8777</em>
|
|
</td>
|
|
</tr>
|
|
<tr class="odd_row">
|
|
<td>OpenSocial.tokenService</td>
|
|
<td>myhost.mydomain.edu:8777</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="2">
|
|
The path to a key file that will be used to generate security tokens. This is the
|
|
file that was created in Step I of this process.
|
|
</td>
|
|
</tr>
|
|
<tr class="odd_row">
|
|
<td>OpenSocial.tokenKeyFile</td>
|
|
<td>/usr/local/vivo/data/shindig/openssl/securitytokenkey.txt</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h3 id="deploy">I.v. Run the deployment script</h3>
|
|
<p>
|
|
At the command line, from the top level of the VIVO distribution
|
|
directory, type:
|
|
</p>
|
|
<pre> ant orng<br> </pre>
|
|
<p>
|
|
to configure the ORNG Shindig application and deploy it to Tomcat's webapps directory.
|
|
</p>
|
|
|
|
<h3 id="confirm">I.vi Does it work?</h3>
|
|
<p>
|
|
Start VIVO. Enter a search term in the search box, and view the results. Check the gadgets there.
|
|
Navigate to a person's profile page. Again, check for the expected gadgets.
|
|
</p>
|
|
<p>
|
|
If the gadgets do not appear as you expect, look for these symptoms,
|
|
and check for the corresponding possible causes.
|
|
</p>
|
|
<table>
|
|
<tr>
|
|
<th>Symptoms</th>
|
|
<th>Possible causes</th>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<ul>
|
|
<li>
|
|
Gadgets do not appear on Individual page or in search results.
|
|
</li>
|
|
<li>
|
|
Tomcat "localhost" log file contains an error message:
|
|
<pre>Unable to load properties: shindig.orng.properties</pre>
|
|
</li>
|
|
</ul>
|
|
</td>
|
|
<td>
|
|
<ul>
|
|
<li>Configuration file is not correctly named.</li>
|
|
<li>Tomcat's setenv file does not specify the correct CLASSPATH</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
<tr class="odd_row"><td colspan="2"></td></tr>
|
|
<tr>
|
|
<td>
|
|
<ul>
|
|
<li>
|
|
Dialog box appears in the browser with the message:
|
|
"Error 500 reading application data: internalError"
|
|
</li>
|
|
<li>
|
|
Tomcat "catalina" log file contains an error message:
|
|
<pre>java.sql.SQLException: Access denied for user</pre>
|
|
</li>
|
|
</ul>
|
|
</td>
|
|
<td>
|
|
<ul>
|
|
<li>
|
|
Configuration file contains incorrect value for one or more of these:
|
|
<ul>
|
|
<li>orng.dbURL</li>
|
|
<li>orng.dbUser</li>
|
|
<li>orng.dbPassword</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
<tr class="odd_row"><td colspan="2"></td></tr>
|
|
<tr>
|
|
<td>
|
|
<ul>
|
|
<li>
|
|
"Smoke tests" fail at startup.
|
|
<pre>Token key file for Shindig does not exist</pre>
|
|
</li>
|
|
<li>
|
|
Pages that display gadgets "hang" in the browser.
|
|
</li>
|
|
<li>
|
|
Tomcat "localhost" log file contains error messages, including:
|
|
<pre>com.google.inject.CreationException: Guice creation errors</pre>
|
|
</li>
|
|
</ul>
|
|
</td>
|
|
<td>
|
|
<ul>
|
|
<li>
|
|
<em>OpenSocial.tokenKeyFile</em> is not set in <em>deploy.properties</em>,
|
|
or the file does not exist at the specified location.
|
|
</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
<tr class="odd_row"><td colspan="2"></td></tr>
|
|
<tr>
|
|
<td>
|
|
<ul>
|
|
<li>
|
|
Gadgets do not appear on Individual page or in search results
|
|
</li>
|
|
<li>
|
|
vivo.all.log contains an error message:
|
|
<pre>MySQLSyntaxErrorException: Table 'vivo.shindig_apps' doesn't exist</pre>
|
|
</li>
|
|
</ul>
|
|
</td>
|
|
<td>
|
|
<ul>
|
|
<li>
|
|
MySQL does not contain the shindig tables.
|
|
<pre>shindig_orng_tables.sql</pre> was not processed.
|
|
</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
<tr class="odd_row"><td colspan="2"></td></tr>
|
|
<tr>
|
|
<td>
|
|
<ul>
|
|
<li>
|
|
Gadgets do not appear on Individual page or in search results
|
|
</li>
|
|
<li>
|
|
vivo.all.log contains an error message:
|
|
<pre>java.net.ConnectException: Connection refused</pre>
|
|
</li>
|
|
</ul>
|
|
</td>
|
|
<td>
|
|
<ul>
|
|
<li>
|
|
In <em>deploy.properties</em>, <em>OpenSocial.tokenService</em> is not set correctly.
|
|
</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
<tr class="odd_row"><td colspan="2"></td></tr>
|
|
</table>
|
|
|
|
<h2 id="gadgets">II. Setting up the Gadgets</h2>
|
|
|
|
<p>
|
|
VIVO will look at tables in MySQL to determine what gadgets should be made available,
|
|
where they should appear, how big they will be, and much more.
|
|
At this time, VIVO doesn't provide a user interface to edit the contents of these tables.
|
|
Administrators will need to use a MySQL admin client, or SQL commands, to set these
|
|
parameters.
|
|
</p>
|
|
<p>
|
|
The tables are named <em>shindig_apps</em> and <em>shindig_app_views</em>,
|
|
and are described in the following sections.
|
|
</p>
|
|
|
|
<h3 id="shindig_apps">II.i The <em>shindig_apps</em> database table</h3>
|
|
|
|
<table>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Usage</th>
|
|
</tr>
|
|
<tr>
|
|
<td>appid</td>
|
|
<td>int(11)</td>
|
|
<td>
|
|
Identifies the gadget.
|
|
In particular, this will be used to determine which rows in the
|
|
<em>shindig_app_views</em> table should apply to this gadget.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>name</td>
|
|
<td>varchar(255)</td>
|
|
<td>
|
|
A user-friendly name for the gadget.
|
|
This will be displayed in the gadget's "Title Bar".
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>url</td>
|
|
<td>varchar(255)</td>
|
|
<td>
|
|
The location where the gadget's contents and behavior are defined.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>PersonFilterID</td>
|
|
<td>int(11)</td>
|
|
<td>unknown</td>
|
|
</tr>
|
|
<tr>
|
|
<td>enabled</td>
|
|
<td>tinyint(1)</td>
|
|
<td>
|
|
If set to 0, this gadget will never be displayed.
|
|
If set to 1, it is displayed according to the rules in the <em>shindig_app_views</em> table.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>channels</td>
|
|
<td>varchar(255)</td>
|
|
<td>unknown</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h3 id="shindig_app_views">II.ii The <em>shindig_app_views</em> database table</h3>
|
|
|
|
<table>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Usage</th>
|
|
</tr>
|
|
<tr>
|
|
<td>appid</td>
|
|
<td>int(11)</td>
|
|
<td>
|
|
Determines which gadget in <em>shindig_apps</em> is affected by this rule.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>viewer_req</td>
|
|
<td>char(1)</td>
|
|
<td>
|
|
unknown
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>owner_req</td>
|
|
<td>char(1)</td>
|
|
<td>
|
|
unknown
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>page</td>
|
|
<td>varchar(50)</td>
|
|
<td>
|
|
What page does this rule apply to?
|
|
A single gadget might have several views, but no more than one view per page.
|
|
Recognized values are
|
|
<ul>
|
|
<li>
|
|
<em>individual</em> -- The profile page of an individual, when it is not in "edit" mode.
|
|
This applies when the viewer is not logged in, or does not have the right to edit the profile page.
|
|
</li>
|
|
<li>
|
|
<em>individual-EDIT-MODE</em> -- The profile page of an individual, when it is in "edit" mode.
|
|
This applies when the viewer is logged in as an administrator or other privileged user, or
|
|
as the owner of the profile page.
|
|
</li>
|
|
<li>
|
|
<em>search</em> -- The search results page.
|
|
</li>
|
|
<li>
|
|
<em>gadgetDetails</em> -- A page that contains only the selected gadget. This usually occurs when
|
|
the user clicks on an icon or a link that expands the gadget to full-page mode.
|
|
</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>view</td>
|
|
<td>varchar(50)</td>
|
|
<td>
|
|
What is the view-mode of the gadget? These are defined as part of the OpenSocial standards.
|
|
<ul>
|
|
<li>
|
|
<em>profile</em> -- The "standard" view, commonly used on the profile page of an individual
|
|
</li>
|
|
<li>
|
|
<em>small</em> -- The "condensed" view.
|
|
</li>
|
|
<li>
|
|
<em>home</em> -- The view which allows the user to change the gadget's settings.
|
|
</li>
|
|
<li>
|
|
<em>canvas</em> -- The "expanded", commonly used when the gadget is the only thing on a page.
|
|
</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>closed_width</td>
|
|
<td>int(11)</td>
|
|
<td>
|
|
How wide is the gadget when it is closed? (in pixels)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>open_width</td>
|
|
<td>int(11)</td>
|
|
<td>
|
|
How wide is the gadget when it is open? (in pixels)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>start_closed</td>
|
|
<td>tinyint(1)</td>
|
|
<td>
|
|
When the page is first loaded, is the gadget open or closed (1 = closed, 0 = open)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>chromeId</td>
|
|
<td>varchar(50)</td>
|
|
<td>
|
|
The gadget will be displayed on the page inside a <div> with this id.
|
|
Note: the page must contain this <div> and its contents
|
|
will be replaced with this gadget (or gadgets).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>display_order</td>
|
|
<td>int(11)</td>
|
|
<td>
|
|
If more than one gadget has the same chromeId, they will be displayed in order by this field.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
</div>
|
|
|
|
</body>
|
|
</html>
|
|
|