Access Keys:
Skip to content (Access Key - 0)

Portal

Portal 3.0 User's Guide

Contents

Using the caGrid Portal for the First Time

The caGrid Portal provides several ways to find data sets, people, tools, communities, and institutions that participate in caBIG®. These entities combine to form the caGrid Portal catalog. Each entity is called a catalog item in this documentation but can be a person, institution, shared query or other tool, or even a community built around a common interest in one of these entities.

The ways to find any catalog item include clicking an icon on the GoogleTM map on the home page, entering a term in the search box to search all caBIG® entities, or narrowing down the catalog by category types and area of focus.

Once you find an item in the catalog, the power of the caGrid Portal becomes apparent. Click any item in the search results to get all available details about that item, then interact with other users by suggesting a related item, providing a citation or hyperlink, adding a comment, or executing a shared query on selected data sets. The caGrid Portal is a true community application, providing access to popular social media tools to bookmark and share interesting items you have found.

Log In

If you already have an account with a caGrid identity provider such as Dorian or the NCI Authentication Service, you can use those account credentials to log in to the caGrid Portal. If you do not have such an account yet, you must register.

To log in to the caGrid Portal

  1. Click the Log In link at the top of the page.
  2. Enter your user name and password.
  3. Select the identity provider from which you received your user name and password.
    Note
    The identity providers that appear in this list are those that have registered with the caGrid Identity Federation Service.
  4. Click the Login button. Your Grid Identity appears.
    Note
    Your Grid Identity is composed of several codes that originate in the proxy certificate of the identity provider. For example: /O=caBIG/OU=caGrid/OU=LOA1/OU=NCI/CN=JSmith. In this case, O=Organization, OU=Organization Unit, and CN=Common Name. See Home for more information about Grid Identities.
  5. Click the << To Home Page link at the top of the page to start using the portal. You may want to begin by managing your profile and credentials.

Register as a New User

Registration is required for users who do not already have an account with a caGrid identity provider such as Dorian or the NCI Authentication Service. When you register, you create an account with the caGrid identity provider you are using, which is usually Dorian.

If you already have an account with a caGrid identity provider such as Dorian or the NCI Authentication Service, you do not need to register. You can just log in with the account information you use for that identity provider.

To register as a new user

  1. Click the Register link at the top of any caGrid Portal page. A window appears with fields for your contact information.
  2. Enter information for each field. All fields except Street 2 are required. Note the following requirements for the user name and password
    • The user name must be between 4 and 15 characters.
    • A valid password must be between 4 and 15 characters, CANNOT contain a dictionary word, and MUST contain at least one upper case letter, at least one lower case letter, at least one number, and at least one symbol (~!@#$%^&*()_-+={}[]|:;<>,.?).
  3. Click Register. A message appears stating that your account is approved and that your current account status is active. You can now log in to the caGrid Portal page using your user name and password.

If your registration is not successful, a message explains the problem. Reasons for unsuccessful registration include duplicate user name, invalid user name, invalid password, and invalid email. Correct the problem and click Register again.

Manage Your Profile and Credentials

Once you log in to caGrid Portal, click your name at the top of the page to see your profile. Note that any time a proper name appears in the caGrid Portal catalog, you can click it to see its profile. You cannot edit anyone else's profile but your own.

If you belong to more than one cancer center, you may have multiple credentials that allow you to log in to caGrid Portal using different user names and passwords. If that is the case, add each credential to your profile so that you can use them as you prefer.

To manage your profile

  1. After logging in to the Portal, click your name at the top of the page. Your profile appears.
  2. Click the Edit link. Your profile now has editable fields and the Contact Info tab is active.
  3. Change any of the information associated with your profile including contact information and whether or not that information is public.
  4. Click Save.

To manage your credentials

  1. After logging in to the Portal, click your name at the top of the page. Your profile appears.
  2. Click the Edit link. Your profile now has editable fields and the Contact Info tab is active.
  3. Click the Credentials tab to select it.
  4. Do the following for new credentials.
    1. To add a credential for an existing user, click Add. Select an identity provider from the drop-down list, then enter a user name and a password. Click Authenticate. Once the identity provider accepts the credential, caGrid Portal displays in the list below.
    2. To register a new user, click Register. For more information, see Register as a New User.
  5. For existing credentials, select one in the list. You can now do the following tasks:
    1. Set this credential as your default credential by clicking Set Default. A confirmation message briefly appears.
    2. Delete this credential by clicking Delete.
    3. Refresh all of your credentials by clicking Refresh. Since some credentials time out after you use them for a while, you may need to periodically refresh them.
  6. Click Save.

Understanding the caGrid Portal Home Page

The caGrid Portal home page includes many ways for you to find caBIG®-related resources that are part of the caGrid Portal catalog. You can do the following:

Once you find an entry, you can interact with it in a number of ways including viewing its details, bookmarking it, rating it, and sharing it through email.

Grid Statistics

The grid statistics that appear next to the map are selected summaries of entries in the caGrid Portal catalog. The statistics provide you with a quick reference to activity on the Portal. They do not represent all catalog entry types. Four categories of grid statistics appear in this area: caBIG Site Statistics, caArray Statistics, caBIO Statistics, and caNanoLab Statistics. The caGrid Portal administrator controls which categories appear in this list of grid statistics and how often they are updated.

Click the link next to the caArray, caBIO, and caNanoLab values to see how the total number of elements (arrays, experiments, samples, pathways, genes, and characterizations) breaks down among relevant caGrid Portal data services. You can now work with these catalog entries.

Data Set Categories

This list shows the data set categories that the Portal administrator has annotated with an area of focus. The caGrid Index Service collects metadata on all services added to caGrid. Before you can view those services in the Portal, the Portal administrator must determine how they relate to other services. Assigning an area of focus to each new service makes it easier for Portal users to find related services.

  • Click a data set category to see a list of relevant catalog items.

Top Contributors

This list shows the people who have interacted with the Portal the most in a time period specified by the Portal administrator.

  • Click any person's name to open the details page about that person.

Top Ranked Entries

This list shows the catalog entries that Portal users like the most. Catalog entries that describe people will not appear in this list.

  • Click any entry in the list to open its details page.
  • To rate the entry, log in and then click one of the stars at the top of the page. Five stars is the top rating.

Latest Entries

This list shows the catalog entries that have been added most recently to the Portal.

  • Click any entry to open its details page.

Finding Entries in the caGrid Portal Catalog

You can access the entire caGrid Portal catalog by entering a search term into the Catalog Search box on the caGrid Portal home page.

You can also browse the catalog by restricting your view to a category or area of focus.

Search the Entire Catalog

At the top right of each Portal page is a Catalog Search box that you can use to find any entry in the caGrid Portal catalog. The catalog includes all data sets, people, tools, communities, and institutions that participate in caBIG®.

Note
The caGrid Portal uses Lucene to index catalog entries. In the event that your deployment has recently restarted, Lucene must load its index. You may notice a delay in your catalog search in this situation.

To search the entire caGrid Portal catalog

  1. Enter any word or part of a word into the Catalog Search box at the top of any Portal page. Search terms may include words associated with categories such as people, services, institutions, and tools such as shared queries.
    Screenshot of the Catalog Search box at the top of the caGrid Portal home page.
    Search the entire caGrid Portal catalog by entering a term or partial term in the Catalog Search box
    Note
    Search terms are case-insensitive and you can enter partial strings. Entering Cancer, cancer, or even can into the search field will return all catalog entries with the word Cancer in it. Entering only a partial string such as can may return additional catalog entries.
  2. Press Enter on the keyboard to begin the search. The Catalog Search Results page appears with all catalog entries that match your search term sorted by name on the right side of the page.
  3. Click any result to see its details page.
    Screenshot of catalog entries resulting from a search starting from the Catalog Search box on the home page. Three catalog entries resulted from this sample search.
    Catalog entries resulting from a search starting from the Catalog Search box on the home page

Browse the Catalog

The caGrid Portal catalog comprises all data sets, people, tools, communities, and institutions that participate in caBIG®. The caGrid Portal considers each of these entities a catalog entry and provides several ways for you to find them.

To browse the catalog

  1. Click the Catalog tab tab in the top toolbar. The full catalog of all data sets, people, tools, communities, and institutions that participate in caBIG® appears, organized alphabetically by name, with catalog search categories to the left. Note that you can page through the catalog using the links at the bottom of the page.
    Screenshot of the first page of the full catalog of caGrid Portal. Lists include Catalog Types
  2. Narrow down the list of catalog entries by clicking a category type or area of focus in the Catalog Search Categories list on the left side of the page. Catalog entries matching your selection appear in the Catalog Search Results. Featured Catalog Entries that may appear above the search results are determined by the caGrid Portal administrator.
  3. Click any entry to open its details page.

Using the Map

The map on the caGrid Portal home page shows the geographic locations of all data that are associated with a geographic address in the caGrid Portal catalog. For example, the address of the point of contact associated with a data service or analytical service appears on the map, as does the address of all participant institutes. When a location includes more than one catalog entry, this is noted using a different icon.

Click on the map icons to link to details about caBIG® services and participants. You can also restrict your view of the map to a type of service or participant institute by clicking a map icon in the legend.

Show Data on the Map

The following table explains what each map icon represents.

Map Icon Represents
Icon for data services. Data Service. For example, caArray Svc, caTissueCore, and CaaersDataService.
Icon for analytical services. Analytical Service. For example, caObr, EVSGridService41, and NHISAS2.
Icon for participant institutes. Participant Institute. For example, University of Nebraska Medical Center - Eppley Cancer Center, Jackson Laboratory, and University of California Davis Cancer Center.
Icon for hosting research centers. More than one type of service or participant institute is at this location. Click this icon on the map to see the details for each service or institute.

Limit your view of the map to only one catalog entry type (service or participant institute) by clicking an icon type in the legend. To reset the map and return to a view of all icons, refresh your browser page.

Browse data on the map by clicking a map icon.

Adjust the View of the Map

The GoogleTM map uses common panning and zooming controls. To move the map sideways or up and down, click the arrow buttons on the map. To get a closer view, click the Icon of the plus button. button. To see more of the map, click the Icon of the minus button. button.

Note
To zoom in or out without using the mouse, press CTRL and Icon of the plus button. to zoom in or CTRL and Icon of the minus button. to zoom out.

Browse Data on the Map

Click an icon on the map. If only one data or analytical service or participant institute is associated with that icon, that result appears in an information window along with a link you can follow to get more information about that entry. If more than one result is associated with the icon you clicked, the information window lets you know how many results exist and provides a link to see the whole list. The image below shows an information window listing the results at a hosting research center in Alabama.

Map of the United States with icons showing the location of data services
Map with an information window linking to a list of services at the selected location

If more than one data or analytical service or participant institute is associated with an icon on the map, you see these results in an information window on the map. Clicking the link in that information window opens a page listing all of the results for that one location. Each result includes a link you can click to see more details about that entry.

List of catalog entries associated with selected icon on the map. List includes three cancer centers. To the left of this catalog entries is a list of category types associated with the results. According to that list
Catalog entries associated with a map location

Working with Catalog Entries

While any user who logs into the caGrid Portal can add entries to the Portal's catalog, the caGrid Portal administrator can decide which of those entries to feature. Those featured entries appear at the top of the catalog list.

The details available for a catalog entry depend on the catalog type. For example, the details page for a Shared Query includes several ways for you to interact with the query including editing it, executing it against one or more data sets, associating other catalog entries (related entries) with it, and adding other information such as citations and comments. The details page for a person listed in the catalog is more limited than that but still includes the ability to add related entries and add other information such as citations, hyperlinks, files, and comments.

In addition to interacting with a catalog entry through the details page, you can bookmark it for future reference and even send it to a colleague through email.

To get details about a catalog entry

Bookmark and Share Catalog Entries

To encourage community growth and interaction, the caGrid Portal incorporates the AddThis bookmarking and sharing service. This service is available on the details page for any catalog entry.

To bookmark and share a catalog entry

  1. Open a catalog entry's details page.
  2. Hover your mouse over the Screenshot of the Bookmark button. button. The Bookmark & Share window opens, showing a subset of the possible bookmarking and sharing options.
    Screenshot of the Bookmark and Share menu that opens when you hover your mouse over the Bookmark button on any catalog entry's details page."
    • To see more bookmarking and sharing options, click the More... option within the Bookmark & Share window or click the Screenshot of the Bookmark button. button (rather than just hovering your mouse over it).
      Screenshot of the Bookmark and Share menu listing more but not all of the possible web services. A scrollbar prevents the reader from seeing all of the services.
    • Since the AddThis service is maintained externally to the caGrid Portal, possible bookmarking and sharing services may change at any time. Some of the hundreds of services offered include Email, Print, Digg, MySpace, Facebook, Twitter, Favorites Delicious, Google, Live, and StumbleUpon.
  3. Click any service to begin sharing it using that service's interface. If you have not already registered with a service, clicking it in the Bookmark & Share window takes you to the home page for the service, where you can learn more about it and register to use it.
Note
For example, to email the caGrid Portal catalog entry to a colleague, open the entry's details page, hover your mouse over the Screenshot of the Bookmark button. button, and then select Email. The Email a Friend dialog box appears in which you can enter To and From email addresses and the body of an email. The AddThis service automatically adds the URL of the caGrid Portal catalog entry to your message when you click Send.

Rate an Entry

Ratings indicate the popularity, usefulness, and quality of a catalog item from the point of view of people that use it. After rating an item, you may want to also add a comment about it.

To rate an entry

  1. Log in to the caGrid Portal.
  2. Open a catalog entry's details page.
  3. Review the catalog entry's details and consider its usefulness to the caBIG®- community.
  4. Click the number of stars corresponding to your rating of this catalog entry, with one star being the lowest rating and five stars being the highest rating. A message thanking you for rating the entry appears.
    Screen capture showing a five-star rating. A popup message provided by the rating tool says Awesome."

Add a Related Entry

The caGrid Portal is strengthened by the interconnectedness of the catalog entries. You can help build a community around an entry by noting which other entries are related to it.

To add a related entry

  1. Log in to the caGrid Portal.
  2. Open a catalog entry's details page.
  3. If the Related Entries tab is not already in focus, select it.
    Portion of the details page of a catalog entry. Screenshot is focused on the Related Entries tab. No related items have been added yet.
  4. Click the Add Related Item button. A popup window appears showing all entry types that you can relate to the entry you selected in Step 2.
    Add Related Item window. Explanatory text at the top of the window reads "First
    Relationships you can select are summarized in the table below.
    This catalog entry type Can relate to this catalog entry type
    Analytical Services Information Model
    Institution
    Shared Query
    Communities Community
    Dataset
    Person
    Tool
    Tool Deployment
    Data Services Not applicable
    Dataset Community
    Dataset
    Information Model
    Institution
    Person
    Terminology
    Information Models Dataset
    Grid Service Endpoint
    Grid Service Interface
    Shared Query
    Institutions Grid Service Endpoint
    Knowledge Center
    Person
    Tool Deployment
    Workspace
    Knowledge Centers Institution
    Person
    Tool
    Portlets Not applicable
    Shared Query Grid Service Endpoint
    Information Model
    Shared Query
    Terminology Dataset
    Tools Information Model
  5. From the Kinds of Catalog Entries list, select the destination entry type. The Kinds of Relationships options list appears.
    The Add Related Item window showing the kinds of relationships available between the original entry type and a grid service interface. Kinds of relationships include Grid Service Interface and Grid Service Endpoint.
  6. Select an option from this list that further defines the kind of relationship your original entry has with the destination entry type.
  7. Click Add. The source entry's details page appears, with a new area where you can specify the related entry.
    An information model's home page with an area for entering the description and name of a related grid service interface.
  8. In the Description box, enter a description of how the two entries are related.
  9. In the Related Entry box, enter the name of the related entry in the caGrid Portal catalog. As you begin typing, suggestions for the related entry's name appear below. Select the related entry from the list.
    Box for name of related entry contains only the letter c; page expands below that with suggestions of grid service interface entries. Suggestions begin with two that begin with the letter c.
  10. Click Save New Related Item.
    The related item now appears in the list of related items for this catalog entry.

Add Comments

You may find it useful to associate a comment with a catalog entry either for your own reference or for the benefit of the community that may find and use it.

To add a comment

  1. Log in to the caGrid Portal.
  2. Open a catalog entry's details page.
  3. Click the Comments tab.
    Screen capture of the Comments tab. Under a heading called Comments
  4. Click the Add Comment button. The Add Comment window appears.
    Screen capture of the Add Comment window. Includes a large text box where you enter your comment
  5. Enter the text of your comment into the box and then click Add Comments. The comment appears in the Comments tab. A sample completed comment appears below.
    Screen capture of a completed sample comment.
    Note
    Only the Portal administrator can delete a comment. Comments cannot be edited.

Add Entries to the caGrid Portal Catalog

The caGrid Portal pulls new caGrid services from the Globus-provided Index Service. The caGrid Portal administrator then adds metadata to these new services so that you can find them in the caGrid Portal catalog. The other way new entries can be added to the caGrid Portal catalog is when members of the caBIG® community add them directly to the catalog. Adding entries to the catalog allows others to find and interact with them.

To add an entry to the caGrid Portal catalog

  1. Log in to the caGrid Portal.
  2. View the caGrid Portal catalog by clicking any of the tabs in the top navigation area.
  3. Click the Add New Catalog Entry button, which is at the top left, below the caGrid Portal logo.
    !AddNewCatalogEntryButton.gif|alt="Portion of the caGrid Portal application, focusing on the Add New Catalog Entry button."!A small window appears, prompting you to select the type of entry to create.
    Small window that appears when you click the Add New Catalog Entry button. The window prompts you to select the type of entry to create and provides a list from which you can select an entry type.
  4. Select an entry type from the list.
  5. Click Create. A new catalog entry page appears.
    Window where you can add a new catalog entry.
  6. In the first box, type a name for the new entry.
  7. In the second box, type a description for the new entry.
  8. Click in the Area of Focus box. The Area of Focus window appears.
    Window that shows all of the possible areas of focus for the new catalog entry. Tab through to select as many as apply to the new entry.
  9. Select the button next to each area of focus that applies to your new catalog entry.
  10. Click the Add button. The window containing the new entry's name, description, and area(s) of focus appears.
  11. Click the Save button. The new entry is now a part of the caGrid Portal catalog. The new entry's details page appears.
    Details page for the new catalog entry showing an Edit and a Delete link.
    Note
    If you create a catalog entry, you may edit and delete it. You may not edit or delete a catalog entry you did not create.

Edit a Catalog Entry's Details

You can only edit those caGrid Portal catalog entries that you created. You can edit the name, description, and area(s) of focus for a caGrid Portal catalog entry.

To edit a catalog entry

  1. Log in to the caGrid Portal.
  2. Open a catalog entry's details page.
  3. Click the Edit link in the upper left corner, under the caGrid Portal logo. The details page changes to edit mode.
  4. Make any changes you would like and then click the Save button.

Delete a Catalog Entry

You can only delete those caGrid Portal catalog entries that you created.

To delete a catalog entry

  1. Log in to the caGrid Portal.
  2. Open a catalog entry's details page.
  3. Click the Delete link in the upper left corner, under the caGrid Portal logo. A window appears, prompting you to confirm deletion of the entry.
  4. Click Yes to delete the entry. It is immediately removed from the catalog.

Hiding Catalog Entries

Users who have been assigned the "Catalog Admin" role are able to hide catalog entries.

To hide a catalog entry

  1. Log in to the caGrid Portal.
  2. Open a catalog entry's details page.
  3. Click the Edit link in the upper left corner, under the caGrid Portal logo. The details page changes to edit mode.
  4. Click the Hide link next to the Hidden Items option.
    Catalog Admins can hide catalog entries
  5. Click the Save button.

Catalog Admins can hide catalog entries

Using Shared Queries

You can edit a shared query's XML in the caGrid Portal to create your own shared query that any caBIG® community member can execute against a data source. As with other caGrid Portal catalog entries, you can add related items and comments to a shared query, as well as bookmark or share it.

View a Shared Query

You do not need to log in to the caGrid Portal to view a shared query. You do need to log in to edit one.

To view a shared query

  1. Click either the Catalog or the Tools tab.
  2. In the Catalog Type (All) category list, click Shared Queries.
  3. Click a shared query in the list to view it. The shared query's home page, pictured below, lists the shared query's name and description as well as any related items or comments.
    "Page where you can view the name and description of a shared query

Edit a Shared Query

You can edit a shared query's name, description, associated image, area of focus, and XML source in the caGrid Portal.

You can only delete a shared query you created or edited.

Edit a Shared Query Using the Query Builder Portlet
While shared queries are editable in XML as explained in this section, you can also edit queries in the Query Builder Portlet. You can use the caGrid Portal to copy the shared query's XML, find the Query Building Portlet using the caGrid Portal catalog, and then edit and execute the query using the Portlet's graphical query building interface. Find the Portlet by clicking the Catalog tab and then clicking Portlets under Catalog Type, or by clicking the Tools tab and scrolling through the entries.

To edit a shared query

  1. Log in to the caGrid Portal.
  2. View a shared query.
    Note
    If you only want to execute the query, skip to step 6. You also do not need to log in before executing a shared query you did not edit.
  3. Click the Edit XML link. An editable version of the shared query's home page appears.
    "Home page of the shared query showing editable fields for the shared query's name
  4. Edit the shared query's name, description, area of focus, and XML as desired. To edit the shared query's area of focus, click in the Area of Focus box. In the window that appears, click the box next to each term that applies to this query, then click Add.
    "Dialog box showing the options for your area of focus selections. Options include Statistical Tools
  5. Click Save. The shared query's home page appears.
    "Page where you can view the name and description of a shared query

Execute a Shared Query

You can execute someone else's shared query against your own data source.

To execute a shared query

  1. To begin executing the edited shared query, click the View Data Sources button. A window appears, showing all data sources that are available for this shared query.
    "The Select Data Sources window showing links to each data source that is available for this query. If you hover your mouse over a data source in this window
  2. Click the checkbox next to each data service that you would like to query. Before doing so you may want to confirm that the data source is active. Hover your mouse over any data source in this list to open a small window showing the data source's metadata. This metadata includes the data source's version, type, active status, Center (such as CBIIT), URL, and secured status.
  3. Click the Select button. The shared query's home page appears.
  4. Click the Execute Query button. caGrid Portal attempts to run the query against the data source(s) you selected.
  5. To see the results, click View next to the Query Results label. The most recent result is at the top of the list. Click it to see its details.

Export a Shared Query to Excel and XML

After you execute a shared query, you can export the results to a file that you can use for other analyses.

To export a shared query to Excel and XML

  1. Execute a shared query.
  2. View the query results by clicking View next to the Query Results label.
  3. Click the result in the list that you want to export.
  4. Click Export to Excel or Export to XML as appropriate. Your browser prompts you to open or save the file.

Delete Shared Query Results

If you execute a shared query frequently, you may want to periodically delete the shared query results that appear on the shared query's home page.

To delete shared query results

  1. Open the shared query's home page by searching for it in the caGrid Portal catalog.
  2. View the query results by clicking View next to the Query Results label.
  3. Click the result in the list that you want to delete.
  4. Click Delete. You are prompted to confirm the deletion of the query. Click Yes.

Submitting Impromptu Queries

In addition to using the Query Builder Portlet or a shared query to query a data service within the caGrid Portal, you can submit impromptu queries. You build an impromptu query outside of the Portal, for example, in a report builder or an iPhone application, and execute it against a caBIG data source. Impromptu queries result in a static URL of the query results. Visiting that URL opens a page of XML. You can use that URL in any analysis that requires the output of the query.

The caGrid Portal provides two ways to submit impromptu queries: by completing a form with the necessary information to build the query, or by having a client (not necessarily a browser, though it must have access to the Internet) issue a POST request to the query URL at the command line. The result of either method is the same: a URL of the query results, as explained above.

Note
Impromptu queries do not contribute to the summary grid statistics on the caGrid Portal home page.

Submitting Impromptu Queries Using a Form

The impromptu query interface is intended to be a programmatic interface that is to be invoked by external API's/applications. An HTML form can also be used to invoke the impromptu query interface, but it will NOT use your Portal credentials or save the query results to your account, as the Query Builder Portlet or the shared query interfaces do.

To submit an impromptu query using a form

  1. Enter the following URL in your browser's address bar: http://portal-demo.training.cagrid.org/cagridportlets/xml/form. The following form appears.
    Form in which you can provide the query code and endpoint URL and select whether or not you want to run the query synchronously and clear previous results.
    Impromptu Query Form
  2. In the Query box, enter the query's XML code.
  3. In the Endpoint URL box, enter the URL to the caBIG data source against which you want to run the query. If you don't already know the URL of the caBIG data source you want to use, you can find it in the caGrid Portal. To do so, search for the data service, click the data service catalog item to open its details page, and then copy the URL for the data service that appears on that page. Paste that URL into the Endpoint URL box.
    Note
    Queries using Common Query Language (CQL) require an endpoint URL. Queries using Distributed Common Query Language (DCQL) do not require you to specify an endpoint URL.
  4. Select the Clear Previous Results box if you do not want previous results to impact your new results.
  5. Click Submit Query. A URL appears. You can now use the XML on that page for other analyses.
    Note
    Some browsers (Safari and Internet Explorer) will display an error when trying to display the CQL result XML. The query results should be visible when viewing the page source.

Submitting Impromptu Queries from the Command Line

This method of submitting impromptu queries is more technical and is intended for use by developers who are building their own tools.

What follows is an example of how a query can be submitted using cURL, a command line tool for transferring data with URL syntax. This example assumes that there is a CQL query stored in the file some_query.cql in the current directory.

curl -d "query=@some_query.cql&endpointUrl=http://cagrid.moffitt.org:8005/wsrf/services/cagrid/CaArraySvc" http://portal-demo.training.cagrid.org/cagridportlets/xml/form

The result is a URL of the query results. You can use it like this:

curl http://portal-demo.training.cagrid.org/cagridportlets/xml/view/JUST_AN_EXAMPLE

If the query is still executing, the response is empty. If the query has completed, the result is XML that follows the (D)CQL schema.

Submitting Impromptu Queries Programmatically

The impromptu query interface is a HTTP servlet that can be invoked from the command line or by writing some code in a programming language. The following pseudocode outlines the general logic of such a program.

 Construct HTTP URL urlA where urlA = url encode(Impromptu Servlet URL + cql XML)

 Invoke urlA 
  
 If return String save as urlB

 Invoke urlB for CQL ResultSet R1

 Parse R1

This above pseudocode can also be written as a short Java program that submits queries to the impromptu query interface and then checks for results.

package example;

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStreamWriter;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLConnection;
import java.net.URLEncoder;


public class ImpromptuQueryClient {

    //URL of caGrid Data Service
    private static final String GRID_SERVICE_URL = "http://cagrid.moffitt.org:8005/wsrf/services/cagrid/CaArraySvc";

    // CQL Query
    private static final String CQL_QUERY =
            "<ns1:CQLQuery xmlns:ns1=\"http://CQL.caBIG/1/gov.nih.nci.cagrid.CQLQuery\">\n" +
                    " <ns1:Target name=\"gov.nih.nci.caarray.domain.project.Experiment\"/>\n" +
                    " <ns1:QueryModifier countOnly=\"true\"/>\n" +
                    "</ns1:CQLQuery>";

    public static final String IMPROMPTU_URL = "http://portal-demo.training.cagrid.org/cagridportlets/xml/form";

    /**
     * Method that executes a query with the impromptu query
     * interface and prints the result
     *
     * @throws Exception Exception thrown during execution
     */

    public static void main(String[] args) throws Exception {

        //  encode form data
        String data = URLEncoder.encode("query", "UTF-8") + "="
                + URLEncoder.encode(CQL_QUERY, "UTF-8");

        data += "&" + URLEncoder.encode("endpointUrl", "UTF-8") + "="
                + URLEncoder.encode(GRID_SERVICE_URL, "UTF-8");

        data += "&" + URLEncoder.encode("clearPrevious", "UTF-8") + "="
                + URLEncoder.encode("true", "UTF-8");

        System.out.println("\n Submitting CQL query to Ad-hoc query Interface");
        URLConnection con = new URL(IMPROMPTU_URL)
                .openConnection();
        con.setDoOutput(true);
        OutputStreamWriter wr = new OutputStreamWriter(con.getOutputStream());
        wr.write(data);
        wr.flush();

        // Get the response
        BufferedReader rd = new BufferedReader(new InputStreamReader(con.getInputStream()));
        String line;

        String cqlResultUrl = null;

        while ((line = rd.readLine()) != null) {
            cqlResultUrl = line;
        }
        wr.close();
        rd.close();

        System.out.println("\n CQL Query Results will be available at " + cqlResultUrl);

        boolean result = false;

        //Loop through till results become available
        do {
            System.out.println("\n Will wait for 10 seconds before checking for results");

            Thread.currentThread().sleep(1);

            System.out.println("\n Checking for CQL Results");
            HttpURLConnection resultCon = (HttpURLConnection) new URL(cqlResultUrl)
                    .openConnection();
            BufferedReader cqlResult = new BufferedReader(new InputStreamReader(
                    resultCon.getInputStream()));

            while ((line = cqlResult.readLine()) != null) {
                if (line.length() > 0 && !line.equals("null")) {
                    System.out.println(line);
                    result = true;
                }
            }
        } while (!result);

        System.out.println("CQL executed successfully!!");
    }
}

To execute the java client, run the following command. 

 java ImpromptuQueryClient

Using caGrid Portal Communities

Using only the caGrid Portal, you can build a community of users. While a caGrid Portal community is an item you can annotate, bookmark, and share like any other item in the caGrid Portal catalog, you can easily build your caGrid Portal community to augment or even replace an internal collaboration platform such as an intranet.

Built using the popular and open source Liferay Portal enterprise web platform, caGrid Portal communities unite the power of caGrid with Web 2.0 and social computing tools such as document feeds, group calendar, wiki, message boards, and web content development tools.

The features you add to your communities share a common look and feel, security model, and architecture. Like with the rest of caGrid Portal, users can access communities on a variety of platforms including mobile devices.

Create a caGrid Portal Community

When you create a caGrid Portal community, you first add it to the caGrid Portal catalog, then customize it to add the social computing features you want.

To create a community

  1. Log in to the caGrid Portal.
  2. View the caGrid Portal catalog by clicking any of the tabs in the top navigation area.
  3. Add the new community to the catalog.
    1. Select any tab to show the caGrid Portal catalog.
    2. Click the Add New Catalog Entry button, which is at the top left, below the caGrid Portal logo.
      Add New Category Entry window listing types of entries to create.
    3. Select Community as the type of entry and then click Create. A new catalog entry page appears.
      "Blank new catalog entry page with fields for name
    4. In the first box, type a name for the new entry.
      Note
      Community names cannot contain any special characters.
    5. In the second box, type a description for the new entry.
    6. Click in the Area of Focus box. The Area of Focus window appears.
      Window that shows all of the possible areas of focus for the new catalog entry. Tab through to select as many as apply to the new entry.
    7. Select the button next to each area of focus that applies to your new catalog entry. You may select more than one.
    8. Click the Add button. The window containing the new entry's name, description, and area(s) of focus appears.
    9. Click the Save button. The new community is now a part of the caGrid Portal catalog. The new community's details page appears.
      Catalog page for the new community.
  4. Customize the community by adding web content to it such as a wiki, calendar, document library for RSS feeds, and discussion forum.

Customize a caGrid Portal Community

Customizing a caGrid Portal community involves selecting which functions you want to offer your community members. The caGrid Portal offers several functions from the Liferay Portal feature set that will make your community a place members will return to again and again.

To customize a caGrid Portal community

  1. Log in to the caGrid Portal.
  2. Click the Communities tab. If you do not see the community you want to customize, search for it in the caGrid Portal catalog.
  3. Select the community you want to customize. The community's details page appears.
    Catalog page for the new community.
  4. Click the Visit this Community! link. A blank new community template appears.
    Blank new community template page.
  5. Add one or more wikis, a document library, forums, calendar, and other web content to your community. Common procedures for these tasks follow. See Chapter 4, Liferay Collaboration Suite of the Liferay Portal Administrator's Guide for complete documentation of these features. While the initial configuration described in that guide has already been performed for the caGrid Portal, you can find more information than this guide provides for individual community features.

Add a Wiki to the Community

A wiki application allows users to create and edit documents and link them to each other. caGrid Portal community wiki supports WikiCreole as its syntax. Tips for this syntax appear on the page editing form, with a link to the full documentation if you want to use some of WikiCreole's advanced features.

You can import your data from other wikis into your community wiki. This allows you to migrate off of another wiki which you may be using and use the caGrid Portal wiki instead. You may want to do this if you are migrating your site from a set of disparate applications (i.e., a separate forum, a separate wiki, a separate content management system) to your caGrid Portal community, which provides all of these features.

To create a wiki page

  1. Click the Wiki link at the top of the page. A blank community wiki page appears.
    Blank new community wiki page.
  2. Click the This page is empty. Edit it to add some text. link and begin adding the text you want to appear on the wiki's home page. At the top of the wiki page is a list of links that allow you to navigate around the wiki, as follows.
    Wiki Links
    		Description
    FrontPage Takes you to the main page of the main wiki.
    Recent Changes Takes you to a page that shows all of the recently updated pages.
    All Pages Takes you to a flat, alphabetical list of all pages currently stored in the wiki.
    Orphan Pages This link takes you to a list of pages that have no links to them. This can happen if you take a link out of a wiki page in an edit without realizing it's the only link to a certain page. This area allows you to review wiki pages that are orphaned in this way so that you can re-link to them or delete them from the wiki if they are no longer relevant.
    Search Enter a term here and click the Search button to search for items in the wiki. If the search term is not found, a link appears that allows you to create a new wiki page on the topic you searched for.

To create a new wiki

  1. Click the Manage Wikis button (an image of a tool on a page) at the top left of the page to see a list of all wikis in this community.
  2. Click the Add Wiki button. The Wiki page appears.
  3. Add a name and description and set the permissions for the wiki.
  4. Click Save

Add a Calendar to the Community

The caGrid Portal Calendar can be used to manage a shared calendar or a group calendar. It includes features for events, event notification, repeatable events, and import and export to and from the standard iCalendar format.

To create a calendar event

  1. Click the Add Event button. A page appears where you can provide all of the information for your event.
  2. Provide the event information as follows.
    Event Information
    		Description
    Start Date/Time The date and time the event starts.
    Duration How long the event will last.
    All Day Event Check this box to disassociate time from the event and make it last all day.
    Time Zone Sensitive Leave this box checked to make sure that the portal keeps track of the event regardless of time zone.
    Title The title of the event.
    Description A description of the event.
    Type Select from a number of pre-configured event types. You can change these in the portal-ext.properties file.
    Repeat If the event repeats on a schedule, select the schedule.
    End Date If the event repeats on a schedule but there is an end to the set of meetings, enter the end date.
    Reminders Select whether to send a reminder, how long before the event to send it, and through what medium (email, text message, or instant message) to send it. Note that this feature is integrated with your profile on the portal, so you will need to fill out your mobile phone number and / or instant messenger IDs in order to use those features.
  3. Click Save. You can view calendar events by day, week, month, year, or in a simple list.

Add a Document Library to the Community

Your community members can store documents they want to share with others in the document library. All documents must be contained within a folder. The person who creates the folder can assign permissions to all documents in that folder. Permissions grant access to the documents by specified users, roles groups, organizations, or communities. Permissions include the ability to add documents, add shortcuts, add subfolders, delete items, assign permissions, update items, and view items.

Blank new community document library.

Below is one implementation of a community's document library.
The Emory University community's document library.

Add a Forum to the Community

caGrid Portal community forums provide a way for the community to track online discussions, including RSS feeds from other message boards and websites. They inherit all of the security features of caGrid Portal and include administrative functions for thread priorities, moving threads, nested discussion categories, banning users, and more.

Blank new community forum page.

To post a new message thread

  1. Click the Categories tab.
  2. Click a category.
  3. Click the Post New Thread button. A message editing form appears.
    Note
    You can also use the editor to quote from messages that you are replying to, insert emoticons, add preformatted text, and more.
Last edited by
Carolyn Kelley Klinger (545 days ago) , ...
Adaptavist Theme Builder Powered by Atlassian Confluence