----
h1. Portal 3.0 User's Guide
----
{cagridroundpanel}
{pre:class=cagridheaderfont}Contents{pre}
{toc:outline=true|exclude=Portal 3.0 User's Guide|style=none}
{cagridroundpanel}

{include:Using the caGrid Portal for the First Time}

h3. Log In{anchor:login}

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|#register].

*To log in to the caGrid Portal*
# Click the *Log In* link at the top of the page.
# Enter your user name and password.
# Select the identity provider from which you received your user name and password.
{info:title=Note}The identity providers that appear in this list are those that have registered with the caGrid Identity Federation Service.{info}
# Click the *Login* button. Your Grid Identity appears.
{info:title=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 [gts:Home] for more information about Grid Identities.{info}
# 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|#Manage Your Profile and Credentials].

h3. Register as a New User{anchor:register}

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*

# Click the *Register* link at the top of any caGrid Portal page. A window appears with fields for your contact information.
# 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 (~\!@#$%^&*()_-+={}\[\]\|:;<>,.?).
# 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.

h3. 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*
# After logging in to the Portal, click your name at the top of the page. Your profile appears.
# Click the *Edit* link. Your profile now has editable fields and the Contact Info tab is active.
# Change any of the information associated with your profile including contact information and whether or not that information is public.
# Click *Save*.

*To manage your credentials*
# After logging in to the Portal, click your name at the top of the page. Your profile appears.
# Click the *Edit* link. Your profile now has editable fields and the Contact Info tab is active.
# Click the *Credentials* tab to select it.
# Do the following for new credentials.
## 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.
## To register a new user, click *Register*. For more information, see [#Register as a New User].
# For existing credentials, select one in the list. You can now do the following tasks:
## Set this credential as your default credential by clicking *Set Default*. A confirmation message briefly appears.
## Delete this credential by clicking *Delete*.
## 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.
# Click *Save*.

h2. Understanding the caGrid Portal Home Page{anchor:homepage}

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:
* [Find a resource|#usingmap] with a geographic address on the map
* Click an item in lists of popular catalog entries
* [Enter a search term|#Search the Entire Catalog] into a Google{~}{^}TM{^}~\-like search box

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

h3. Grid Statistics{anchor:gridstatistics}

The grid statistics that appear next to the map are selected summaries of entries in the caGrid Portal catalog. The statistics are updated once daily and provide you with a quick reference to activity on the Portal. They do not represent all catalog entry types. For example, you may see the total number of data services, analytical services, and participant institutes in the Portal catalog but not other categories such as shared queries and information models, which appear when you [browse the catalog|#browsingcatalog]. The caGrid Portal administrator controls which categories appear in this list of grid statistics and how often they are updated.

!GridStatistics.png|alt=The Grid Statistics area of the caGrid Portal home page showing statistics for data services, analytical services, participant institutes, countArrays, countExperiments, and countSamples.!\\
_Grid Statistics area on the caGrid Portal home page_

h3. Data Set Categories{anchor:datasetcategories}

This list shows the data set categories that the Portal administrator has annotated with an area of focus. The [caGrid Index Service|metadata13: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.

h3. Top Contributors{anchor:topcontributors}

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.

h3. Top Ranked Entries{anchor:toprankedentries}

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.

h3. Latest Entries{anchor:latestentries}

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

* Click any entry to open its details page.

h2. Finding Entries in the caGrid Portal Catalog

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

You can also [browse the catalog|#browsingcatalog] by restricting your view to a category or area of focus.

h3. Search the Entire Catalog{anchor:searchingcatalog}

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{~}^®^~.

{info:title=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.{info}

*To search the entire caGrid Portal catalog*
# 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.
!CatalogSearchBox.gif|alt=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_
{info:title=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.
{info}
# 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.
# Click any result to see its details page.
!MapSearchResults.gif|alt=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_

h3. Browse the Catalog{anchor:browsingcatalog}

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*

# Click the !CatalogButton.gif|alt=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.
!CatalogAll.gif|alt=Screenshot of the first page of the full catalog of caGrid Portal. Lists include Catalog Types, Featured Catalog Entries, and Catalog Search Results.!
# 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.
# Click any entry to open its details page.

h2. Using the Map{anchor:usingmap}

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.

h3. Show Data on the Map{anchor:showingmapdata}

The following table explains what each map icon represents.
{div:class=horizscroll}
{cagridtable}
{table-row}
{th:class=confluenceTh|colspan=1}*Map Icon*{th}
{th:class=confluenceTh|colspan=1}*Represents*{th}
{table-row}
{table-row}
{cagridtablecell}!DataService.gif|alt=Icon for data services.!{cagridtablecell}
{cagridtablecell} Data Service. For example, caArray Svc, caTissueCore, and CaaersDataService.{cagridtablecell}
{table-row}
{table-row}
{cagridtablecell}!AnalyticalService.gif|alt=Icon for analytical services.!{cagridtablecell}
{cagridtablecell} Analytical Service. For example, caObr, EVSGridService41, and NHISAS2.{cagridtablecell}
{table-row}
{table-row}
{cagridtablecell}!ParticipantInstitute.gif|alt=Icon for participant institutes.!{cagridtablecell}
{cagridtablecell}Participant Institute. For example, University of Nebraska Medical Center - Eppley Cancer Center, Jackson Laboratory, and University of California Davis Cancer Center.{cagridtablecell}
{table-row}
{table-row}
{cagridtablecell}!HostingResearchCenter.gif|alt=Icon for hosting research centers.!{cagridtablecell}
{cagridtablecell}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. {cagridtablecell}
{table-row}
{cagridtable}
{div}

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|#browsingmapdata] by clicking a map icon.

h3. Adjust the View of the Map{anchor:viewingmap}

The Google{~}{^}TM{^}~ 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 !Plus.png|alt=Icon of the plus button.! button. To see more of the map, click the !Minus.png|alt=Icon of the minus button.! button.

{info:title=Note}To zoom in or out without using the mouse, press CTRL and !Plus.png|alt=Icon of the plus button.! to zoom in or CTRL and !Minus.png|alt=Icon of the minus button.! to zoom out.{info}

h3. Browse Data on the Map{anchor:browsingmapdata}

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.

!MapSingleResult.gif|alt=Map of the United States with icons showing the location of data services, analytical services, participant institutes, and hosting research centers. A callout information window associated with a point in Alabama reads "There are three services at this location. View." The word View is a link to a list of those three 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|#catalogentries] about that entry.

!MapSearchResults.gif|alt=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, these three centers have the category type of Grid Service Endpoints.!
\\
_Catalog entries associated with a map location_

h2. Working with Catalog Entries{anchor:catalogentries}

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*
* Click a catalog entry name in search results, such as the one in the image below.
!SingleSearchResult.gif|alt=Screenshot trimmed to show a single search result in a catalog search. Shows Abramson Cancer Center link in the search results.!
\\
_Catalog entry in a search results list_
\\Details about the entry appear.
!InstitutionDetails.gif|alt=Screenshot of the details page for a selected catalog entry. This selection was the Abramson Cancer Center and it includes a rating of four stars and a related entry (Joshua Phillips).!
\\
_Details about a catalog entry_
You can now interact with this entry in the following ways:
** [Bookmark or share|#bookmarkingsharing] the entry using a web-based tool.
** [Rate|#rating] the entry.
** [Add a citation|#citation] to the entry.
** [Add a hyperlink|#hyperlink] to the entry.
** [Associate a related entry|#relatedentry] in the caGrid Portal such as an institution, a data set, or a tool with the entry.
** [Upload files|#uploadfiles] associated with the entry.
** [Add a note|#addcommentsnotes] to the entry for others to read.
** [Execute a shared query|#sharedqueries] against selected data sets.
** [Edit a shared query's XML|#sharedqueries].
** [Edit|#editingdetails] the entry's other details.

h3. Bookmark and Share Catalog Entries{anchor:bookmarkingsharing}

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*
# Open a catalog entry's [details page|#catalogentries].
# Hover your mouse over the !BookmarkButton.gif|alt=Screenshot of the Bookmark button.! button. The Bookmark & Share window opens, showing a subset of the possible bookmarking and sharing options.
!BookmarkButtonandMenu.gif|alt=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 !BookmarkButton.gif|alt=Screenshot of the Bookmark button.! button (rather than just hovering your mouse over it).
!BookmarkandShare.gif|alt="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.
# 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.

{info:title=Note}For example, to email the caGrid Portal catalog entry to a colleague, open the entry's details page, hover your mouse over the !BookmarkButton.gif|alt=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*.{info}

h3. Rate an Entry{anchor:rating}

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|#addcommentsnotes] about it.

*To rate an entry*
# [Log in|#login] to the caGrid Portal.
# Open a catalog entry's [details page|#catalogentries].
# Review the catalog entry's details and consider its usefulness to the caBIG{~}^®^~\- community.
# 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.
!Ratings.gif|alt=Screen capture showing a five-star rating. A popup message provided by the rating tool says Awesome."!

h3. Add a Related Entry{anchor:relatedentry}

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*
# [Log in|#login] to the caGrid Portal.
# Open a catalog entry's [details page|#catalogentries].
# If the *Related Entries* tab is not already in focus, select it.
!CatalogEntryRelatedItemsTab.png|alt="Portion of the details page of a catalog entry. Screenshot is focused on the Related Entries tab. No related items have been added yet."!
# 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.
!AddRelatedItem.png|alt=Add Related Item window. Explanatory text at the top of the window reads "First, choose the kind of catalog entry for which you would like to describe a relationship. Then, select the kind of relationship that you would like to describe." "!
Relationships you can select are summarized in the table below.
{div:class=horizscroll}
{cagridtable}
{table-row}
{th:class=confluenceTh|colspan=1}*This catalog entry type*{th}
{th:class=confluenceTh|colspan=1}*Can relate to this catalog entry type*{th}
{table-row}
{table-row}
{cagridtablecell}Analytical Services{cagridtablecell}
{cagridtablecell}Information Model \\ Institution\\ Shared Query{cagridtablecell}
{table-row}
{table-row}
{cagridtablecell}Communities{cagridtablecell}
{cagridtablecell}Community\\Dataset \\ Person \\ Tool \\ Tool Deployment
{cagridtablecell}
{table-row}
{table-row}
{cagridtablecell}Data Services{cagridtablecell}
{cagridtablecell}Not applicable{cagridtablecell}
{table-row}
{table-row}
{cagridtablecell}Dataset{cagridtablecell}
{cagridtablecell}Community \\
Dataset\\
Information Model \\
Institution\\
Person\\
Terminology\\
{cagridtablecell}
{table-row}
{table-row}
{cagridtablecell}Information Models{cagridtablecell}
{cagridtablecell}Dataset\\
Grid Service Endpoint\\
Grid Service Interface\\
Shared Query {cagridtablecell}
{table-row}
{table-row}
{cagridtablecell}Institutions{cagridtablecell}
{cagridtablecell}Grid Service Endpoint\\
Knowledge Center\\
Person\\
Tool Deployment\\
Workspace
{cagridtablecell}
{table-row}
{table-row}
{cagridtablecell}Knowledge Centers{cagridtablecell}
{cagridtablecell}Institution\\
Person\\
Tool{cagridtablecell}
{table-row}
{table-row}
{cagridtablecell}Portlets{cagridtablecell}
{cagridtablecell}Not applicable{cagridtablecell}
{table-row}
{table-row}
{cagridtablecell}Shared Query{cagridtablecell}
{cagridtablecell}Grid Service Endpoint\\
Information Model\\
Shared Query {cagridtablecell}
{table-row}
{table-row}
{cagridtablecell}Terminology{cagridtablecell}
{cagridtablecell}Dataset{cagridtablecell}
{table-row}
{table-row}
{cagridtablecell}Tools{cagridtablecell}
{cagridtablecell}Information Model{cagridtablecell}
{table-row}
{cagridtable}
# From the Kinds of Catalog Entries list, select the destination entry type. The Kinds of Relationships options list appears.
!KindsofRelationships.png|alt=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.!
# Select an option from this list that further defines the kind of relationship your original entry has with the destination entry type.
# Click *Add*. The source entry's details page appears, with a new area where you can specify the related entry.
!AddRelatedItemDescription.png|alt=An information model's home page with an area for entering the description and name of a related grid service interface.!
# In the Description box, enter a description of how the two entries are related.
# 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.
!NameofRelatedCatalogEntry.png|alt=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.!
# Click *Save New Related Item*.
The related item now appears in the list of related items for this catalog entry.

h3. Add Comments {anchor:addcomment}

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*
# [Log in|#login] to the caGrid Portal.
# Open a catalog entry's [details page|#catalogentries].
# Click the *Comments* tab.
!CommentsTab.gif|alt=Screen capture of the Comments tab. Under a heading called Comments, there is an Add Comment button." "!
# Click the *Add Comment* button. The Add Comment window appears.
!AddCommentWindow.gif|alt=Screen capture of the Add Comment window. Includes a large text box where you enter your comment, as well as Cancel and Add Comments buttons." "!
# 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.
!CompletedComment.gif|alt="Screen capture of a completed sample comment."!
{info:title=Note}Only the Portal administrator can delete a comment. Comments cannot be edited.
{info}

h3. Add Entries to the caGrid Portal Catalog{anchor:addingdata}

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*
# [Log in|#login] to the caGrid Portal.
# View the caGrid Portal catalog by clicking any of the tabs in the top navigation area.
# 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.
!AddNewCatalogEntryWindow.gif|alt="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."!
# Select an entry type from the list.
# Click *Create*. A new catalog entry page appears.
!AddNewCatalogEntryMainPage.gif|alt="Window where you can add a new catalog entry."!
# In the first box, type a name for the new entry.
# In the second box, type a description for the new entry.
# Click in the *Area of Focus* box. The Area of Focus window appears.
!AreaofFocus.gif|alt="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."!
# Select the button next to each area of focus that applies to your new catalog entry.
# Click the *Add* button. The window containing the new entry's name, description, and area(s) of focus appears.
# Click the *Save* button. The new entry is now a part of the caGrid Portal catalog. The new entry's details page appears.
!MyNewEntryDetailsPage.gif|alt="Details page for the new catalog entry showing an Edit and a Delete link."!
{info:title=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.
{info}

h3. Edit a Catalog Entry's Details{anchor:editingdetails}

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*
# [Log in|#login] to the caGrid Portal.
# Open a catalog entry's [details page|#catalogentries].
# Click the *Edit* link in the upper left corner, under the caGrid Portal logo. The details page changes to edit mode.
# Make any changes you would like and then click the *Save* button.

h3. Delete a Catalog Entry{anchor:deletingcatalogentry}

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

*To delete a catalog entry*
# [Log in|#login] to the caGrid Portal.
# Open a catalog entry's [details page|#catalogentries].
# 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.
# Click *Yes* to delete the entry. It is immediately removed from the catalog.

h3. Hiding catalog entries.

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|#relatedentry] and [comments|#addcomment] to a shared query, as well as [bookmark or share|#bookmarkingsharing] it.

h3. View a Shared Query{anchor:viewsharedquery}

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*
# Click either the *Catalog* or the *Tools* tab.
# In the Catalog Type (All) category list, click *Shared Queries*.
# 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.
!SharedQueryHomePage.gif|alt="Page where you can view the name and description of a shared query, as well as its related items and comments."!

h3. Edit a Shared Query{anchor:editsharedquery}

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.

{info:title=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.{info}

*To edit a shared query*
# [Log in|#login] to the caGrid Portal.
# [View a shared query|#viewsharedquery].
{info:title=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.{info}
# Click the *Edit XML* link. An editable version of the shared query's home page appears.
!SharedQueryEditXML.gif|alt="Home page of the shared query showing editable fields for the shared query's name, description, and XML."!
# 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*.
!AreaofFocus.gif|alt="Dialog box showing the options for your area of focus selections. Options include Statistical Tools, Clinical Trials Management, Gene Expression, Proteomics, Other, Vocabularies, Biospecimens, Pathways, Imaging, Genome Annotation, Infrastructure, Translational Research, Data Sharing, and Microarray."!
# Click *Save*. The shared query's home page appears.
!SharedQueryHomePage.gif|alt="Page where you can view the name and description of a shared query, as well as its related items and comments."!

h3. Execute a Shared Query{anchor:executesharedquery}

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

*To execute a shared query*
# 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.
!SharedQuerySelectDataSources.gif|alt="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, a small window pops up that shows the data source's metadata including its version, type, active status, Center (such as CBIIT), URL, and secured status."!
# 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.
# Click the *Select* button. The shared query's home page appears.
# Click the *Execute Query* button. caGrid Portal attempts to run the query against the data source(s) you selected.
# 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.

h3. 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*
# [Execute a shared query|#executesharedquery].
# View the query results by clicking *View* next to the Query Results label.
# Click the result in the list that you want to export.
# Click *Export to Excel* or *Export to XML* as appropriate. Your browser prompts you to open or save the file.

h3. 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*
# Open the shared query's home page by searching for it in the caGrid Portal catalog.
# View the query results by clicking *View* next to the Query Results label.
# Click the result in the list that you want to delete.
# Click *Delete*. You are prompted to confirm the deletion of the query. Click *Yes*.

h2. Submitting Impromptu Queries
In addition to [using the Query Builder Portlet|#editsharedquery] or a [shared query|#usingsharedqueries] 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.

{info:title=Note}Impromptu queries do not contribute to the summary grid statistics on the caGrid Portal home page.{info}

h3. Submitting Impromptu Queries Using a Form

*To submit an impromptu query using a form*
# Enter the following URL in your browser's address bar: http://portal-demo.training.cagrid.org/cagridportlets/xml/form. The following form appears.\\
!ImpromptuQuery.png|alt="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_\\
# In the Query box, enter the query's XML code.
# 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|#browsingcatalog], 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.
{info:title=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.{info}
# Select the *Clear Previous Results* box if you do not want previous results to impact your new results.
# Click *Submit Query*. A URL appears. You can now use the XML on that page for other analyses.

h3. 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.

h2. 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|#catalogentries] 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.

h3. Create a caGrid Portal Community{anchor:createcommunity}

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

*To create a community*
# [Log in|#login] to the caGrid Portal.
# View the caGrid Portal catalog by clicking any of the tabs in the top navigation area.
# Add the new community to the catalog.
## Select any tab to show the caGrid Portal catalog.
## Click the *Add New Catalog Entry* button, which is at the top left, below the caGrid Portal logo.
!AddNewCatalogEntryWindow.gif|alt="Add New Category Entry window listing types of entries to create."!
## Select *Community* as the type of entry and then click *Create*. A new catalog entry page appears.
!AddNewCatalogEntryMainPage.gif|alt="Blank new catalog entry page with fields for name, description, and area of focus."!
## In the first box, type a name for the new entry.
{info:title=Note}Community names cannot contain any special characters.{info}
## In the second box, type a description for the new entry.
## Click in the *Area of Focus* box. The Area of Focus window appears.
!AreaofFocus.gif|alt="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."!
## Select the button next to each area of focus that applies to your new catalog entry. You may select more than one.
## Click the *Add* button. The window containing the new entry's name, description, and area(s) of focus appears.
## Click the *Save* button. The new community is now a part of the caGrid Portal catalog. The new community's details page appears.
!NewCommunity-CatalogEntry.gif|alt="Catalog page for the new community."!
# [Customize|#customizecommunity] the community by adding web content to it such as a wiki, calendar, document library for RSS feeds, and discussion forum.

h3. Customize a caGrid Portal Community{anchor:customizecommunity}

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*
# [Log in|#login] to the caGrid Portal.
# Click the *Communities* tab. If you do not see the community you want to customize, [search|#searchingcatalog] for it in the caGrid Portal catalog.
# Select the community you want to customize. The community's details page appears.
!NewCommunity-CatalogEntry.gif|alt="Catalog page for the new community."!
# Click the *Visit this Community\!* link. A blank new community template appears.
!NewCommunityPage.gif|alt="Blank new community template page."!
# 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_|http://docs.liferay.com/portal/5.2/official/liferay-administration-guide.pdf] 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.

h4. 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*
# Click the *Wiki* link at the top of the page. A blank community wiki page appears.
!NewWikiPage.gif|alt="Blank new community wiki page."!
# 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*
# 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.
# Click the *Add Wiki* button. The Wiki page appears.
# Add a name and description and set the permissions for the wiki.
# Click *Save*

h4. 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*
# Click the *Add Event* button. A page appears where you can provide all of the information for your event.
# 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. |
# Click *Save*. You can view calendar events by day, week, month, year, or in a simple list.

h4. 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.

!DocLibrary-Community.gif|alt="Blank new community document library."!

Below is one implementation of a community's document library.
!DocLibrary-Emory.gif|alt="The Emory University community's document library."!

h4. 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.

!Forums-Community.gif|alt="Blank new community forum page."!

*To post a new message thread*
# Click the Categories tab.
# Click a category.
# Click the *Post New Thread* button. A message editing form appears.
{info:title=Note}You can also use the editor to quote from messages that you are replying to, insert emoticons, add preformatted text, and more.{info}