Lightweight Data Source Integration for websites

To reduce the development required to integrate websites with GenomeSpace, we have created a lightweight data source integration method suitable for use by websites and web applications.

Web Site Requirements

To use this method, websites must be able to support the following:

  • add an iFrame to a page
  • provide a unsecured URL to any file to be sent to GenomeSpace

How It Works

The GenomeSpace server provides a page fragment (https://gsui.genomespace.org/jsui/upload/loadUrlToGenomespace.html) that has the minimum functionality needed to send data to GenomeSpace via a URL that the GenomeSpace server uploads.  When an application includes this fragment, it handles the basic communication with the servers to:

  1. Login or recognize a previously logged in user.
  2. Select a directory or subdirectory in the GenomeSpace user's home directory.
  3. Set and change the file name.
  4. Tell the GenomeSpace server to upload the file to the designated directory and name.

From the point of view of the website, it simply needs to open this URl in a new window (see below)  and set the default file name and URL as parameters.  Optionally, it can also provide a Javascript method to call back when the file submission is successful.

 

An example HTML page using this mechanism can be found on the GSUI server at https://gsui.genomespace.org/jsui/uploaddialog.html. 

Example of Use

 

The following HTML is for the example page that will open the page fragment in a new dialog.

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Testing GS </title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
        <META HTTP-EQUIV="Pragma" CONTENT="no-cache">
        <META HTTP-EQUIV="Expires" CONTENT="-1">
        <script src="https://gsui.genomespace.org/jsui/js/jquery-1.7.2.min.js" type="text/javascript"></script>
        <script src="./upload/gsuploadwindow.js" type="text/javascript"></script>
       
</head>
<body>
<div id="uploadLink">Click <a href="#" onclick="uploadUrlByGetToGS();return false;">here to upload</a> by sending a URL</div>

 <script type="text/javascript">      
       
        function uploadUrlByGetToGS(){
               var dest = "http://www.broadinstitute.org/~liefeld/Achilles_v2.4_SampleInfo_small.txt";
               var onComplete = function(savePath){
                alert('outer Saved to GenomeSpace as ' + savePath);
               };
               var onError = function(savePath){
                        alert('outer ERROR saving to GenomeSpace as ' + savePath);
               };
               gsUploadByGet({
                url: dest,
                   filename: 'TheFileName.txt',
                   successCallback: onComplete,
                   errorCallback: onError
               });
               return false;
        };
    </script>
</body>
</html>


 

And the function in the included library just looks like this;  You can include the library or recreate this in your code

function gsUploadByGet(config){
    // expect an object with url, filename (optional), successCallback(optional), errorCallback (optional)
    
     var gsUploadUrl = jsuiRoot +"/upload/loadUrlToGenomespace.html?uploadUrl=";
       var dest = encodeURIComponent(config.url);
       var filenameParam = "";
       if (config['filename'] != null){
          filenameParam = "&fileName="+config.filename;
       }    
      
       var newWin = window.open(gsUploadUrl + dest + filenameParam, "GenomeSpace Upload", "height=340px,width=550px");
     newWin.focus();
     
     if (config['successCallback'] != null) newWin.setCallbackOnGSUploadComplete = config['successCallback'];
        
     if (config['errorCallback'] != null) newWin.setCallbackOnGSUploadError = config['errorCallback'];     
    
}

Note the two parameters being passed in: "uploadUrl" and "fileName".  UploadUrl is required and this is the URL GenomeSpace will try to do an HTTP GET on.  As a result this must not be protected by any authorization scheme or the GET will fail.  If you need to be able to upload files with full control over security, we suggest that you use the REST API directly and/or the CDK.

The fileName parameter is optional and will provide the default file name in the page fragment.  if no fileName parameter is provided, the dialog will use the end of the URL (everything after the last slash) as the default filename.

Why in a new window?

In this example we use a new window (as opposed to a JQuery load() call for example) because of the need for the upload page to be able to do page redirects if the user is not already logged into GenomeSpace. In this case, the uploader redirects the page to the main GenomeSpace OpenID login page, processes the login, and then redirects back.  In a seperate window, this is restricted to the new window; however, if this as done in the main application page body, the entire page would be redirected for the GenomeSpace login which would generally be undesirable.