Web Apps

HydroShare is designed to support data access from third-party web applications. A web app may be a webpage, a resource viewer, a data editor, or a complex scientific model that interacts with HydroShare data and resources using a public REST API. A web app connector is a special type of HydroShare resource that serves as a shortcut (or reference) to an external web application that operates on HydroShare data. Web app connector resources follow standard HydroShare resource sharing and access controls so may be shared with individual users, groups, or made public, in which case they are discoverable in a HydroShare search. However, web app connectors may not be permanently published as they contain connections to external URLs for which persistence cannot be guaranteed. 

Components of a Web App Connector

A web app connector contains specific metadata fields designed to give users flexibility and control in how they interact with external web applications. While not all of these fields are required, they provide a high level of user customization and fit a wide range of applications. A brief summary of these metadata fields and their purposes is provided below.

  • Supported Resource Types: A list of HydroShare resource types. The web app connector will only be able to operate on the resource types selected in this list. For generic web app connectors, all or nearly all of these will be selected, whereas few will be selected for highly specific applications. 
  • Supported Aggregation Types: A list of HydroShare content aggregation types that the web app will operate on. When a content aggregation is right-clicked, web apps are shown that can be launched to interact with that content. Only web apps that have enabled the chosen content aggregation type are listed. NOTE: If content aggregation types have been selected then the App-Launching Aggregation Level URL pattern needs to be provided to set the parameters to be passed when selected by right clicking.
  • Supported Resource Sharing Status: A list of HydroShare resource sharing statuses (e.g., Private, Public). The web app will only be able to operate on resources that match the selected sharing statuses.
  • Supported file extensions: The connector can appear on the right click menu for individual files in a resource for specified file extensions. NOTE: If this is set, the App-Launching File Level URL pattern needs to be provided to set the parameters to be passed when selected by right clicking.
  • App Home Page URL: This URL will be launched from the “Open” button on the web app resource landing page.
  • App-Launching Pattern URL: This URL will be launched from the “Open With” button on supported resource types with the designated sharing status. Parameters are set to control the passing of specific resource or user information to the web app associated with the URL. Parameters are designed so users can configure flexible URLs to launch apps that have different expectations (e.g., ${HS_RES_ID} to pass resource ID, ${HS_FILE_NAME} to pass file name). See details here. 
  • App-Launching Aggregation Level URL Pattern and App-Launching File Level URL Pattern: This URL will be launched from the right click for supported content type aggregations or file extensions. . URL parameters are set to control the passing of specific resource or content information to the web app on the launching URL.
  • Version: Optional field to record the web app version.
  • Icon URL: Optional link for an icon to represent the web app on menus and apps landing page. 
  • Testing Protocol URL: Optional URL to a website that describes how to test the app.
  • Help page URL: Optional URL to a website describing how to use the app.
  • Source code URL: Optional URL to a website including the app source code (e.g. github).
  • Issues page URL: Optional URL to a website where web app issues are recorded.
  • Mailing list URL: Optional URL to  a website mailing list for the app.
  • Roadmap: Development or roadmap planning for the web app.
  • Additional Metadata: Additional metadata may be added as user-specified key-value pairs. This is relevant for matching web app connectors with specific resources (see Appkey matching) or web apps that use iRODS (see below).  

Using a Web App Connector

Web app landing page

From a web app connector that you have access to, click the “Open Web App” button. This launches the App Home Page URL.

The landing page of the OpenDap web app connector. The title reads "OpenDap" and below this is a thumbs up icon in a green circle next to a message that says "This WebApp resource has been approved by HydroShare admin". To the right is a blue button labeled "Open Web App". Below this are the fields Authors, Owners, Resource Type, Created, Last Updated, Citation, Sharing status, Views, Downloads, +1 Votes, and Comments. Author is David Tarboton, owners are David Tarboton, Hong Yi, Tian Gan, and Michael J. Stanley.

Resource level “Open With”

From a resource where a resource level web app connection is established, click the Open with... button.

A resource titled "Web App Demo". To the right is the blue "open with" button. The drop down menu is open, showing HydroShare GIS, CUAHSI JupyterHub, and OpenDAP. Below are all of the same entry fields as above (author, owner, resource type).

Content type aggregation level right click

Right click on a content type aggregation and select the web app connection item.

Contents section containing two files, one multidimensional file called "SWE_time" and one jupyter notebook file called "TauDEM". SWE_time is selected and the right click menu is open. The right click menu contains the options: Open, download, get file URL, and OpenDAP. OpenDap is circled.

Establishing a connection between a resource, content aggregation, or file 

Ensure that the following conditions are met so that your web app appears as an option on the Open with... or right click menus:

  • The resource type is a specified type for the web app connector.
  • The resource sharing status matches that set for the web app connector
  • For right click menus, the content type or file extension is specified for the web app connector and the app-launching URLs are correctly entered.
  • The privacy settings for the resource and the web app connector are consistent and the user has access (shared, public, shared to group user is member of).
  • HydroShare requires a connectivity step to prevent unwanted web app connectors appearing on every user's Open with... and right click menus. Connectivity can be established via three mechanisms:
    • CUAHSI Approval 
    • User Selection
    • Appkey matching

CUAHSI Approval

To appear as an available web app for all users, a web app connector must be approved by CUAHSI, which requires that the app be of general interest to HydroShare users along with testing and documentation. CUAHSI-approved apps are indicated on the web app connector landing page, with a message that says "This WebApp resource has been approved by HydroShare admin" and appear in the HydroShare apps library. Contact help@cuahsi.org to request approval of a web app.

The approved app message, described above, next to a green thumbs up icon.

User Selection

A user adds a web app Connector to their personal Open with... options by clicking the icon in the web app Resource landing page. For example, Jupyter Notebook Viewer is a public web app created to connect to a third party Jupyter Notebook Viewer website. It is not CUAHSI-approved. For this app to appear on your menus, click the “Add WebApp to open with list” button on the web app connector landing page as illustrated below.  To access the "Add WebApp to open with list" option, navigate to the web app landing page through the Discover page. 

Web app resource with the title "Jupyter Notebook Viewer". Author and owner are David Tarboton. To the right of the title is the "Open web app" button. Below this button are the "add to my resources" tray icon, the 9 tile square "Add webapp to Open with" list" button, and the copy resource button. The add to open with button is circled in red.

This web app connector is configured to open any public .ipynb file with a file level right click.  As it is a third party website, it does not have a mechanism to interact with HydroShare login functionality to access private resources. For a user that has selected this web app, an .ipynb file meeting the criteria can be viewed using the Jupyter Notebook Viewer.

Appkey matching

Specific resources and specific web app connectors can be associated by setting a matching additional metadata entry with name “appkey”.

For example, Model My Watershed is a third party web app designed to interact with certain HydroShare content. It relies on the presence of specifically formatted files in a resource. The “View in Model My Watershed” web app connector was created to launch those files into the Model My Watershed application.  

Web App landing page titled "View in Model My Watershed". Owners are Stroud Water Research Center, David Tarboton, Anthony Kieth Aufdenkampe.

This web app connector has Additional Metadata with name “appkey” and value set to “model-my-watershed”.

The Additional Metadata section of the resource landing page. Subfields are "name" and "value". Under "name" is the word "appkey", and under Value is "model-my-watershed".

“Mission Creek” is a resource created by Model My Watershed. In its metadata, it also has an Additional Metadata with name “appkey” and value set to “model-my-watershed”. As a result, the Open with... options for Model My Watershed are enabled

A resource titled "Mission Creek". Over and author is David Tarboton. The "Open With" menu is expanded, and the options "View in Model my watershed", "edit in Model my watershed", "HydroShare GIS", "CUAHSI JupyterHub", and "OpenDap" are available. The first two options appear at the top and are circled in red.

Web Apps That Use iRODS

If an external web app uses an iRODS server for distributed data storage and management, HydroShare provides an option for the external iRODS server to federate with the HydroShare iRODS server to efficiently push requested data to a temporary directory managed by the external iRODS server via iRODS parallel file transfer. This requested data push operation via iRODS will only happen right before the external web app is launched so the requested data is ready to be consumed by the web app. To become federated with the HydroShare production system, the external web app institution is required to sign a federation agreement to take full responsibility of keeping its iRODS server operational and well-maintained. To indicate that HydroShare should perform the requested data push operation when launching a web app, add the following three Additional Metadata key-value pairs in the web app connector resource:

Name                                                            Value

------------------------------------------------------------------------

irods_federation_target_path                   target logical path in the federated iRODS server to which to push requested data in HydroShare

irods_federation_target_resource           target iRODS resource in the federated iRODS server to which to push requested data in HydroShare

require_user_authentication                    true if the web app requires user authentication and false otherwise. This Additional Metadata is optional, and if not provided, false will be the default option.