User\'s Guide

![](media/image1.jpeg){width="3.5694444444444446in"
height="1.3263888888888888in"}

This is a U.S. Government work. February 19, 2009

caBIG® Open Source Software License caGrid 1.2

**Copyright Notice.** Copyright 2009 The Ohio State University Research
Foundation (\"OSURF\"), Argonne National Laboratory (\"ANL\"),
SemanticBits LLC (\"SemanticBits\"), and Ekagra Software Technologies
Ltd. (\"Ekagra\") (\"caBIG® Participant\"). The caGrid 1.3 software was
created with NCI funding and is part of the caBIG® initiative. The
software subject to this notice and license includes both human readable
source code form and machine readable, binary, object code form (the
\"caBIG® Software\").

This caBIG® Software License (the \"License\") is between caBIG®
Participant and You. \"You\" (or \"Your\") shall mean a person or an
entity, and all other entities that control, are controlled by, or are
under common control with the entity. \"Control\" for purposes of this
definition means (i) the direct or indirect power to cause the direction
or management of such entity, whether by contract or otherwise, or (ii)
ownership of fifty percent (50%) or more of the outstanding shares, or
(iii) beneficial ownership of such entity.

**License.** Provided that You agree to the conditions described below,
caBIG® Participant grants You a non-exclusive, worldwide, perpetual,
fully-paid-up, no-charge, irrevocable, transferable and royalty-free
right and license in its rights in the caBIG® Software, including any
copyright or patent rights therein, to (i) use, install, disclose,
access, operate, execute, reproduce, copy, modify, translate, market,
publicly display, publicly perform, and prepare derivative works of the
caBIG® Software in any manner and for any purpose, and to have or permit
others to do so; (ii) make, have made, use, practice, sell, and offer
for sale, import, and/or otherwise dispose of caBIG® Software (or
portions thereof); (iii) distribute and have distributed to and by third
parties the caBIG® Software and any modifications and derivative works
thereof; and (iv) sublicense the foregoing rights set out in (i), (ii)
and (iii) to third parties, including the right to license such rights
to further third parties. For sake of clarity, and not by way of
limitation, caBIG® Participant shall have no right of accounting or
right of payment from You or Your sublicensees for the rights granted
under this License. This License is granted at no charge to You. Your
downloading, copying, modifying, displaying, distributing or use of
caBIG® Software constitutes acceptance of all of the terms and
conditions of this Agreement. If you do not agree to such terms and
conditions, you have no right to download, copy, modify, display,
distribute or use the caBIG® Software.

1.  Your redistributions of the source code for the caBIG® Software must
    retain the above copyright notice, this list of conditions and the
    disclaimer and limitation of liability of Article 6 below. Your
    redistributions in object code form must reproduce the above
    copyright notice, this list of conditions and the disclaimer of
    Article 6 in the documentation and/or other materials provided with
    the distribution, if any.

```{=html}
<!-- -->
```
1.  Your end-user documentation included with the redistribution, if
    any, must include the following acknowledgment: \"This product
    includes software developed by the Ohio State University Research
    Foundation (\"OSURF\"), Argonne National Laboratory (\"ANL\"),
    SemanticBits LLC (\"SemanticBits\"), and Ekagra Software
    Technologies Ltd. (\"Ekagra\").\" If You do not include such
    end-user documentation, You shall include this acknowledgment in the
    caBIG® Software itself, wherever such third-party acknowledgments
    normally appear.

2.  You may not use the names \"The Ohio State University Research
    Foundation\", \"OSURF\", \"Argonne National Laboratory\", \"ANL\",
    \"SemanticBits LLC\", \"SemanticBits\", \"Ekagra Software
    Technologies Ltd.\", \"Ekagra\", \"The National Cancer Institute\",
    \"NCI\", \"Cancer Biomedical Informatics Grid\" or \"caBIG®\" to
    endorse or promote products derived from this caBIG® Software. This
    License does not authorize You to use any trademarks, service marks,
    trade names, logos or product names of either caBIG® Participant,
    NCI or caBIG®, except as required to comply with the terms of this
    License.

3.  For sake of clarity, and not by way of limitation, You may
    incorporate this caBIG® Software into Your proprietary programs and
    into any third party proprietary programs. However, if You
    incorporate the caBIG® Software into third party proprietary
    programs, You agree that You are solely responsible for obtaining
    any permission from such third parties required to incorporate the
    caBIG® Software into such third party proprietary programs and for
    informing Your sublicensees, including without limitation Your
    end-users, of their obligation to secure any required permissions
    from such third parties before incorporating the caBIG® Software
    into such third party proprietary software programs. In the event
    that You fail to obtain such permissions, You agree to indemnify
    caBIG® Participant for any claims against caBIG® Participant by such
    third parties, except to the extent prohibited by law, resulting
    from Your failure to obtain such permissions.

4.  For sake of clarity, and not by way of limitation, You may add Your
    own copyright statement to Your modifications and to the derivative
    works, and You may provide additional or different license terms and
    conditions in Your sublicenses of modifications of the caBIG®
    Software, or any derivative works of the caBIG® Software as a whole,
    provided Your use, reproduction, and distribution of the Work
    otherwise complies with the conditions stated in this License.

5.  THIS caBIG® SOFTWARE IS PROVIDED \"AS IS\" AND ANY EXPRESSED OR
    IMPLIED WARRANTIES (INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
    WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT AND FITNESS FOR A
    PARTICULAR PURPOSE) ARE DISCLAIMED. IN NO EVENT SHALL THE OHIO STATE
    UNIVERSITY RESEARCH FOUNDATION (\"OSURF\"), ARGONNE NATIONAL
    LABORTORY (\"ANL\"), SEMANTICBITS LLC (\"SEMANTICBITS\"), AND EKAGRA
    SOFTWARE TECHNOLOGIES LTD. (\"EKAGRA\") OR ITS AFFILIATES BE LIABLE
    FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
    CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
    SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
    BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    caBIG® SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

[]{#refheading___toc222720998 .anchor}Document Change History

The following is the revision history for this document.

  -------------------------------------------------------------------------
  Date           Version   Description                    Revised By
  -------------- --------- ------------------------------ -----------------
  February 18,   2.3       Replaced title page logo,      Carolyn Kelley
  2009                     version number, and copyright. Klinger

  October 6,     2.1.2     Added information about the    Manav Kher
  2008                     tests that the Service         
                           Diagnostics portlet performs.  

  October 3,     2.1.1     caBIG is a registered          John Eisenschmidt
  2008                     trademark (except in license   
                           agreement). Edits about        
                           Diagnostic portlet and target  
                           grid.                          

  October 2,     2.1       Draft 2.1 Revision             Carolyn Kelley
  2008                                                    Klinger

  June 29, 2008  2.0.2.3   Final 2.02 Revision            Carolyn Kelley
                                                          Klinger

  June 26, 2008  2.0.2.2   Updated Revision History,      John Eisenschmidt
                           Acknowledgements, and link to  
                           this guide. Copyedited text.   

  June 23, 2008  2.0.2.1   Updated for caGrid Portal      Carolyn Kelley
                           2.0.2.                         Klinger

  January 9,     2.0.1     Updated for caGrid Portal 2.0. Eddie VanArsdall
  2008                                                    
  -------------------------------------------------------------------------

Contents

[Document Change History ii](#refheading___toc222720998)

[Illustrations vii](#__RefHeading___Toc222720999)

[About This Guide 1](#__RefHeading___Toc222721000)

[Purpose 1](#purpose)

[Audience 1](#audience)

[Prerequisites 1](#prerequisites)

[Topics Covered 2](#topics-covered)

[Text Conventions Used 2](#text-conventions-used)

[Credits and Resources 3](#credits-and-resources)

[Chapter 1 About the caGrid Portal 4](#about-the-cagrid-portal)

[Purpose of the caGrid Portal 4](#purpose-of-the-cagrid-portal)

[caGrid Portal Features 4](#cagrid-portal-features)

[Discovery 4](#discovery)

[Service Metadata Exploration 5](#service-metadata-exploration)

[Data Service Query 6](#data-service-query)

[Accessing caBIG® Community Portlets
6](#accessing-cabig-community-portlets)

[Browsing caBIG® Tools 6](#browsing-cabig-tools)

[Query Sharing 6](#query-sharing)

[caGrid Account Registration 7](#cagrid-account-registration)

[Grid Status Overview 8](#grid-status-overview)

[News and Events 8](#news-and-events)

[Visual Overview of the caGrid Portal Home Page
9](#visual-overview-of-the-cagrid-portal-home-page)

[Chapter 2 Registering and Logging In 11](#registering-and-logging-in)

[About Registration 11](#about-registration)

[Registering for a Login Account 12](#registering-for-a-login-account)

[Logging in with Your caGrid Portal Account
14](#logging-in-with-your-cagrid-portal-account)

[Logging in with Your NIH Account 16](#logging-in-with-your-nih-account)

[About the Welcome Menu 16](#about-the-welcome-menu)

[Chapter 3 Using the Map Portlet 17](#using-the-map-portlet)

[About the Map Portlet 17](#about-the-map-portlet)

[Selecting a Category View 18](#selecting-a-category-view)

[Selecting a Service, Participant, or POC
19](#selecting-a-service-participant-or-poc)

[Selecting a Data Service. 19](#selecting-a-data-service.)

[Selecting an Analytical Service. 21](#selecting-an-analytical-service.)

[Selecting a Participant Institute.
22](#selecting-a-participant-institute.)

[Selecting a Hosting Research Center.
24](#selecting-a-hosting-research-center.)

[Selecting a POC. 25](#selecting-a-poc.)

[Chapter 4 Using the Discovery Portlet 27](#using-the-discovery-portlet)

[About the Discovery Portlet 27](#about-the-discovery-portlet)

[Viewing Data in a List or a Map 28](#viewing-data-in-a-list-or-a-map)

[Using the List View Subtab 28](#using-the-list-view-subtab)

[Using the Map View 31](#using-the-map-view)

[Searching for Services, Participants, and POCs
32](#searching-for-services-participants-and-pocs)

[Searching for a Service 32](#searching-for-a-service)

[Searching for a Participant 36](#searching-for-a-participant)

[Searching for a POC 37](#searching-for-a-poc)

[Viewing Details for Services, Participants, and POCs
39](#viewing-details-for-services-participants-and-pocs)

[Viewing Details for Services 39](#viewing-details-for-services)

[Viewing Details for a Participant
42](#viewing-details-for-a-participant)

[Viewing Details for a POC 43](#viewing-details-for-a-poc)

[Using the Service Diagnostics Portlet
43](#using-the-service-diagnostics-portlet)

[About the Service Diagnostics Portlet
43](#about-the-service-diagnostics-portlet)

[Running Diagnostic Tests 45](#running-diagnostic-tests)

[Interpreting Results of Diagnostic Tests
45](#interpreting-results-of-diagnostic-tests)

[Chapter 5 Using the Data Service Query Portlet
47](#using-the-data-service-query-portlet)

[About the Data Service Query Portlet
47](#about-the-data-service-query-portlet)

[Query-Building Scenarios 48](#query-building-scenarios)

[Scenario 1: Starting without a URL or Query
48](#scenario-1-starting-without-a-url-or-query)

[Scenario 2: Starting with a URL but No CQL Query
49](#scenario-2-starting-with-a-url-but-no-cql-query)

[Scenario 3: Starting with a URL and a CQL Query
49](#scenario-3-starting-with-a-url-and-a-cql-query)

[Building a Query Using the Query Builder Tool
50](#building-a-query-using-the-query-builder-tool)

[Building CQL Queries 50](#building-cql-queries)

[Building DCQL Queries 55](#building-dcql-queries)

[About the History Tab 65](#about-the-history-tab)

[Working with Shared Queries 67](#working-with-shared-queries)

[Sharing a Query 67](#sharing-a-query)

[Searching for a Shared Query 69](#searching-for-a-shared-query)

[Chapter 6 Using the Community Portlet 71](#using-the-community-portlet)

[About JSR 168 and the Liferay Portal
71](#about-jsr-168-and-the-liferay-portal)

[Accessing the Community Portlet 71](#accessing-the-community-portlet)

[Deploying a Community Portet 72](#deploying-a-community-portet)

[Chapter 7 Using Other Portal Features 73](#using-other-portal-features)

[Using the News Portlet 73](#using-the-news-portlet)

[About the caGrid Links Portlet 75](#about-the-cagrid-links-portlet)

[Using the caGrid Status Portlet 76](#using-the-cagrid-status-portlet)

[Viewing Details for a Recently Registered Service or Participant
77](#viewing-details-for-a-recently-registered-service-or-participant)

[Viewing a List of Participants or Services
77](#viewing-a-list-of-participants-or-services)

[About the Calendar Portlet 78](#about-the-calendar-portlet)

[Chapter 8 Using the caBIG® Tools Portlet
81](#using-the-cabig-tools-portlet)

[About the caBIG® Tools Portlet 81](#about-the-cabig-tools-portlet)

[Sorting caBIG® Tools 82](#sorting-cabig-tools)

[Viewing caBIG® Tool Details 85](#viewing-cabig-tool-details)

[Index 87](#__RefHeading___Toc222721080)

[]{#__RefHeading___Toc222720999 .anchor}Illustrations

[Figure 1‑1. caGrid Portal home page 9](#__RefHeading___Toc222721081)

[Figure 2‑1. Register links 12](#__RefHeading___Toc222721082)

[Figure 2‑2. Registration page 13](#__RefHeading___Toc222721083)

[Figure 2‑3. Successful login message 14](#__RefHeading___Toc222721084)

[Figure 2‑4. Welcome message with Logout link
15](#__RefHeading___Toc222721085)

[Figure 2‑5. Welcome menu 16](#__RefHeading___Toc222721086)

[Figure 3‑1. Map portlet 17](#__RefHeading___Toc222721087)

[Figure 3‑2. Categories list 18](#__RefHeading___Toc222721088)

[Figure 3‑3. Callout balloon for a data service center
20](#__RefHeading___Toc222721089)

[Figure 3‑4. Discovery Portlet showing details for a selected data
service 20](#__RefHeading___Toc222721090)

[Figure 3‑5. Callout balloon for a selected participant
22](#__RefHeading___Toc222721091)

[Figure 3‑6. Discovery portlet showing details for a participant
institute 23](#__RefHeading___Toc222721092)

[Figure 3‑7. Callout balloon for an analytical service center
24](#__RefHeading___Toc222721093)

[Figure 3‑8. List of hosting research centers with More Details links
25](#__RefHeading___Toc222721094)

[Figure 4‑1. Directory tab \> List View subtab -- results for All
Services category 29](#__RefHeading___Toc222721095)

[Figure 4‑2. Map View subtab 31](#__RefHeading___Toc222721096)

[Figure 4‑3. Services subtab with the Simple search mode selected
33](#__RefHeading___Toc222721097)

[Figure 4‑4. Services subtab with Advanced search mode selected
33](#__RefHeading___Toc222721098)

[Figure 4‑5. Discovered services 34](#__RefHeading___Toc222721099)

[Figure 4‑6. Services subtab with the EVS search mode selected
35](#__RefHeading___Toc222721100)

[Figure 4‑7. Results of an EVS search 35](#__RefHeading___Toc222721101)

[Figure 4‑8. Discovered services 36](#__RefHeading___Toc222721102)

[Figure 4‑9. Participants subtab 37](#__RefHeading___Toc222721103)

[Figure 4‑10. POCs subtab 38](#__RefHeading___Toc222721104)

[Figure 4‑11. Details for a selected data service
39](#__RefHeading___Toc222721105)

[Figure 4‑12. Selecting a UML class for a query
40](#__RefHeading___Toc222721106)

[Figure 4‑13. Details for a selected analytical service
41](#__RefHeading___Toc222721107)

[Figure 4‑14. Details for a selected participant
42](#__RefHeading___Toc222721108)

[Figure 4‑15. Details for a selected POC
43](#__RefHeading___Toc222721109)

[Figure 4‑16. Service Diagnostics portlet on the Services tab
44](#__RefHeading___Toc222721110)

[Figure 4‑17. URL field in the Service Diagnostics portlet
45](#__RefHeading___Toc222721111)

[Figure 4‑18. Successful result in the Service Diagnostics portlet
45](#__RefHeading___Toc222721112)

[Figure 4‑19. Unsuccessful result in the Service Diagnostics portlet
46](#__RefHeading___Toc222721113)

[Figure 5‑1. Starting a query from a selected result
48](#__RefHeading___Toc222721114)

[Figure 5‑2. Working query 49](#__RefHeading___Toc222721115)

[Figure 5‑3. Query Builder subtab with selected UML class ArrayDesign
50](#__RefHeading___Toc222721116)

[Figure 5‑4. Attributes and associations for selected class
52](#__RefHeading___Toc222721117)

[Figure 5‑5. Specifying a predicate and value for a selected attribute
53](#__RefHeading___Toc222721118)

[Figure 5‑6. Query Builder subtab with added criterion
53](#__RefHeading___Toc222721119)

[Figure 5‑7. Query XML tab 54](#__RefHeading___Toc222721120)

[Figure 5‑8. History tab with query information
54](#__RefHeading___Toc222721121)

[Figure 5‑9. Query Builder specifying a service and URL
56](#__RefHeading___Toc222721122)

[Figure 5‑10. Services with the same UML class to aggregate from
56](#__RefHeading___Toc222721123)

[Figure 5‑11. Summary of data services selected for aggregation
57](#__RefHeading___Toc222721124)

[Figure 5‑12. History tab with query information
57](#__RefHeading___Toc222721125)

[Figure 5‑13. Query Builder specifying a service and URL
58](#__RefHeading___Toc222721126)

[Figure 5‑14 Query Builder tool with selected NucleicAcidSequence class
58](#__RefHeading___Toc222721127)

[Figure 5‑15 Tree view of attributes and associations for the
NucleicAcidSequence class 59](#__RefHeading___Toc222721128)

[Figure 5‑16 Query criterion tree view for caBIO NucleicAcidSequence
class 60](#__RefHeading___Toc222721129)

[Figure 5‑17 Service information for semantically equivalent UML class
60](#__RefHeading___Toc222721130)

[Figure 5‑18 Selecting the join condition
61](#__RefHeading___Toc222721131)

[Figure 5‑19 Entering criterion value for Organism scientificName
attribute 61](#__RefHeading___Toc222721132)

[Figure 5‑20 Enter criterion value for Gene name attribute
62](#__RefHeading___Toc222721133)

[Figure 5‑21 Complete federated query for caBIO NucleicAcidSequence
class 62](#__RefHeading___Toc222721134)

[Figure 5‑22 XML federated query for caBIO NucleicAcidSequence class
63](#__RefHeading___Toc222721135)

[Figure 5‑23 History Tab with the running DCQL query
63](#__RefHeading___Toc222721136)

[Figure 5‑24 Results of federated query for caBIO NucleicAcidSequence
class 64](#__RefHeading___Toc222721137)

[Figure 5‑25. Results tab showing query results
65](#__RefHeading___Toc222721138)

[Figure 5‑26. Form for adding a query name and description
68](#__RefHeading___Toc222721139)

[Figure 5‑27. Saved query 68](#__RefHeading___Toc222721140)

[Figure 5‑28. Shared Queries tab \> Find Shared Queries subtab -- Search
form 69](#__RefHeading___Toc222721141)

[Figure 6‑1. Community Portlet, caBIO Portlet example
71](#__RefHeading___Toc222721142)

[Figure 7‑1. News links 74](#__RefHeading___Toc222721143)

[Figure 7‑2. News page 75](#__RefHeading___Toc222721144)

[Figure 7‑3. Status portlet 76](#__RefHeading___Toc222721145)

[Figure 7‑4. Calendar portlet 78](#__RefHeading___Toc222721146)

[Figure 8‑1.Tools portlet 82](#__RefHeading___Toc222721147)

[Figure 8‑2. caBIG® tools sorted by Area of Focus
83](#__RefHeading___Toc222721148)

[Figure 8‑3. caBIG® tool details 86](#__RefHeading___Toc222721149)

[]{#__RefHeading___Toc222721000 .anchor}About This Guide

This section introduces you to the *caGrid Portal 2.2 User\'s Guide* and
provides an orientation to using the guide. It also includes support
contact information.

Topics in this chapter include:

-   Purpose on this page

-   Audience on page [1](#purpose)

-   Prerequisites on page [1](#prerequisites)

-   Topics Covered on page [2](#topics-covered)

-   Text Conventions Used on page [2](#text-conventions-used)

-   Credits and Resources on page [3](#credits-and-resources)

## Purpose {#purpose .unnumbered}

This guide introduces you to the caGrid Portal. It explains how to use
the portal features to do the following:

-   Discover caGrid services, caBIG® participants, and caGrid points of
    contact

-   Explore the service metadata of a discovered service

-   Build queries using the CQL and DCQL query languages

-   Share queries and search for shared queries

-   Access community portlets

-   Register for an account so that you can interact with secure caGrid
    services

-   View the status of caGrid services

-   View caGrid-related news using the portal or using an RSS
    2.0-compliant news reader

-   View a calendar of caGrid-related events.

## Audience {#audience .unnumbered}

This guide is intended for the following users:

-   Non-developer members of the caBIG® community

-   caGrid service developers

-   Anyone interested in caBIG® and caGrid

## Prerequisites {#prerequisites .unnumbered}

To get the most out of this guide, you should have the following skills:

-   Ability to browse the Internet using a Web browser

-   Understanding of caGrid metadata concepts (for building queries)

## Topics Covered {#topics-covered .unnumbered}

This brief overview explains what you will find in each chapter and
appendix.

-   Chapter 1, About the caGrid Portal (p.
    [4](#about-the-cagrid-portal)), provides an overview of the caGrid
    Portal and its feature set.

-   Chapter 2, Registering and Logging In (p.
    [11](#registering-and-logging-in)) covers the registration process
    and the procedures for logging in as a new portal user or an NIH
    user.

-   Chapter 3, Using the Map Portlet (p. [17](#using-the-map-portlet)),
    explains how to use the Map portlet to select a service or
    institution and link to more detailed information.

-   Chapter 4, Using the Discovery Portlet (p.
    [27](#using-the-discovery-portlet)), explains how to use the
    Discovery portlet to browse, search, and view details for caGrid
    services, caBIG® participants, and caGrid POCs.

-   Chapter 5, Using the Data Service Query Portlet (p.
    [47](#using-the-data-service-query-portlet)), explains how to use
    the Data Service Query portlet to build and share queries.

-   Chapter 6, Using the Community Portlet (p.
    [71](#using-the-community-portlet)), explains how to access portlets
    developed by the caBIG® community within the caGrid Portal.

-   Chapter 7, Using Other Portal Features (p.
    [73](#using-other-portal-features)), covers the News, caGrid Links,
    Grid Status, and Calendar portlets.

-   Chapter 8, Using the caBIG® Tools Portlet (p.
    [81](#using-the-cabig-tools-portlet)), explains how to use the
    caBIG® Tools portlet to sort and browse caBIG® tools.

## Text Conventions Used {#text-conventions-used .unnumbered}

This section explains conventions used in this guide. The various
typefaces represent interface components, keyboard shortcuts, toolbar
buttons, dialog box options, and text that you type.

  ----------------------------------------------------------------------------
  Convention            Description                    Example
  --------------------- ------------------------------ -----------------------
  **Bold**              Highlights names of option     Click **Search**.
                        buttons, check boxes,          
                        drop-down menus, menu          
                        commands, command buttons, or  
                        icons.                         

  URL                   Indicates a Web address.       http://domain.com

  text in [Small        Indicates a keyboard shortcut. Press
  Caps]{.smallcaps}                                    [Enter]{.smallcaps}.

  text in [Small        Indicates keys that you press  Press
  Caps]{.smallcaps} +   simultaneously.                [Shift]{.smallcaps} +
  text in [Small                                       [Ctrl]{.smallcaps}.
  Caps]{.smallcaps}                                    

  *Italics*             Highlights references to other See *Figure 4.5*.
                        documents, sections, figures,  
                        and tables.                    

  ***Italic boldface    Represents text that you type. In the **New Subset**
  monospace*** type                                    text box, enter
                                                       ***Proprietary
                                                       Proteins***.

  **Note:**             Highlights information of      **Note:** This concept
                        particular importance.         is used throughout this
                                                       document.

  { }                   Surrounds replaceable items.   Replace {last name,
                                                       first name} with the
                                                       Principal
                                                       Investigator's name.
  ----------------------------------------------------------------------------

## Credits and Resources {#credits-and-resources .unnumbered}

+----------------------+-----------------------+-----------------------+
| caGrid Portal        |                       |                       |
| Development and      |                       |                       |
| Management Teams     |                       |                       |
+======================+=======================+=======================+
| Development          | Quality Assurance     | Program and Project   |
|                      |                       | Management            |
+----------------------+-----------------------+-----------------------+
| Joshua Phillips ^2^  | Aynur Abdurazik ^3^   | Krishnakant Shanbhag  |
|                      |                       | ^1^                   |
+----------------------+-----------------------+-----------------------+
| Manav Kher ^2^       |                       | John Eisenschmidt ^4^ |
+----------------------+-----------------------+-----------------------+
|                      | Documentation         |                       |
+----------------------+-----------------------+-----------------------+
|                      | Carolyn Kelley        |                       |
|                      | Klinger ^5^           |                       |
+----------------------+-----------------------+-----------------------+
|                      |                       |                       |
+----------------------+-----------------------+-----------------------+
| 1.  NCI Center for   | 2.  SemanticBits, LLC | 3.  Science           |
|     Biomedical       |                       |     Applications      |
|     Informatics and  |                       |     International     |
|     Information      |                       |     Corporation       |
|     Technology       |                       |     (SAIC)            |
|     (CBIIT)          |                       |                       |
+----------------------+-----------------------+-----------------------+
| 4.  5AM Solutions    | 5.  Lockheed Martin   |                       |
|                      |     Management System |                       |
|                      |     Designers         |                       |
+----------------------+-----------------------+-----------------------+

  -----------------------------------------------------------------------
  Contacts and Support    
  ----------------------- -----------------------------------------------
  NCICB Application       <http://ncicbsupport.nci.nih.gov/sw/>\
  Support                 Telephone: 301-451-4384\
                          Toll free: 888-478-4423

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

# About the caGrid Portal

This chapter introduces you to the caGrid Portal and describes its
feature set.

Topics in this chapter include:

-   Purpose of the caGrid Portal on this page

-   caGrid Portal Features on this page

-   Visual Overview of the caGrid Portal Home Page on page
    [9](#visual-overview-of-the-cagrid-portal-home-page)

## Purpose of the caGrid Portal {#purpose-of-the-cagrid-portal .unnumbered}

The caGrid Portal is a Web-based application that enables you to
discover and interact with the services that are available on the caGrid
infrastructure. The portal serves as the primary visualization tool for
the caGrid middleware and provides a standards-based platform for
hosting caBIG®-related tools. It also serves as a caBIG® information
source. Using the caGrid portal, you have instant access to information
about caBIG® participants, caGrid points of contact (POCs), and
caGrid-related news and events.

## caGrid Portal Features {#cagrid-portal-features .unnumbered}

The following sections discuss the various caGrid Portal features:

-   Discovery on this page

-   Service Metadata Exploration on page
    [5](#service-metadata-exploration)

-   Data Service Query on page [6](#data-service-query)

-   Accessing caBIG® Community Portlets on page
    [6](#accessing-cabig-community-portlets)

-   *Browsing caBIG® Tools* on page [6](#browsing-cabig-tools)

-   Query Sharing on page [6](#query-sharing)

-   caGrid Account Registration on page
    [6](#cagrid-account-registration)

-   Grid Status Overview on page [8](#grid-status-overview)

-   News and Events on page [8](#news-and-events)

### Discovery {#discovery .unnumbered}

One of the goals of the caGrid infrastructure is to enable you to easily
discover and access services. To achieve this goal, caGrid services
register with a central index service. This service allows other
applications to locate caGrid services and retrieve the necessary
information for interacting with those services.

The caGrid Portal uses caGrid component APIs to provide an interface
that you can use to query information gathered from one or more index
services. Regardless of whether you are a service developer or
non-developer, you can use this interface to determine how to use and
benefit from caGrid.

In addition to service information, the portal also provides information
about caBIG® participant institutions and caGrid points of contact
(POCs). The goal is to enable you to quickly determine who the point of
contact is for specific activities and easily obtain contact information
for that person.

The process of locating services, participants, and POCs is known as
*discovery*. The portal provides the following modes of discovery: *map
view*, *directories*, *keyword search, and EVS search.* The following
subsections describe these modes.

Once you discover a service, you can also run diagnostic tests on it to
check the service\'s status in the caGrid Portal, availability of the
service, service metadata, and index service.

#### Map View {#map-view .unnumbered}

The portal home page displays a map of the U.S. that shows the
geographic location of services and participant institutions. You can
click the icon for a service or institution and link to more detailed
information.

#### Categories {#categories .unnumbered}

Services, participants, and POCs are grouped into categories. You can
browse these categories and click hyperlinks that lead to more detailed
information.

#### Keyword Search {#keyword-search .unnumbered}

The portal provides an intuitive, keyword search interface that enables
you to enter one or more keywords and match them against one or more
fields.

#### EVS Search {#evs-search .unnumbered}

This feature allows the user to enter free text that the Portal matches
against concepts found in the NCI Thesaurus. As you type characters into
the search field, the Portal presents candidate concepts. After you
select a concept, the Portal starts the search. Services whose metadata
refer to the concept or any sub-concept are presented in the search
results.

### Service Metadata Exploration {#service-metadata-exploration .unnumbered}

To support the caBIG® goals of syntactic and semantic interoperability,
caGrid services expose a rich, standard set of metadata. This metadata
not only describes the operations that the services support; it also
links the data types that those operations use to concepts defined in
the NCICB Enterprise Vocabulary Services (EVS), common data elements
defined in the Cancer Data Standards Repository (caDSR), and XML schemas
defined in the Global Metadata Exchange (GME) service.

caGrid services that support the caGrid Query Language (CQL) also expose
an XML representation of the UML domain model that the service supports.
This model is also linked to the EVS, caDSR, and GME. While caGrid
services support standard Web service APIs for retrieving metadata, the
caGrid project provides client API components that facilitate the
process.

The portal uses caGrid client APIs to build an interface that enables
you to explore caGrid service metadata. You can view the semantic
descriptions that come from the EVS, the data type descriptions from the
caDSR, and XML schemas that are registered with the GME. The interface
makes it easier for you to determine whether a service meets your needs
and what is necessary to interact with the service.

### Data Service Query {#data-service-query .unnumbered}

caGrid services that support CQL are known as *data services*. They
expose a UML domain model, support a query operation that processes CQL
queries against that domain model, and return XML documents that contain
serialized instances of the UML classes defined in the domain model.
These serialized instances conform to the XML schemas that are
registered with the GME.

The portal provides an interface that enables you to select a service
and target UML class, build a query, execute the query, view the results
in tabular form, and export to a Microsoft Excel or XML document. While
using the discovery tool or while exploring service metadata, you can
select the service and UML class to be queried. You can then use a
graphical query-building interface to construct CQL or DCQL, or you can
manually type the query text.

If you are a registered caGrid Portal user (discussed under caGrid
Account Registration on this page), the portal maintains a complete
history of your queries so that you can always retrieve and work with
previously executed queries. The results of all queries that you execute
during a single session (while your browser is open) are available for
viewing.

### Accessing caBIG® Community Portlets {#accessing-cabig-community-portlets .unnumbered}

Developers in the caBIG® community may create Java Specification Request
168 (JSR 168) compliant portlets and then deploy them to the caGrid
Portal. This provides an instant hosting environment for custom
applications that may be of value to the entire caBIG® community.

### Browsing caBIG® Tools {#browsing-cabig-tools .unnumbered}

To increase the cancer research community\'s access to key
bioinformatics tools, platforms, and data, the caGrid Portal exposes the
same inventory of applications, software tools, database technologies,
and Web-based applications that appear on the [caBIG® Community
Website](https://cabig.nci.nih.gov/tools/toolsearch_view). As on the
caBIG® website, caGrid users can search for these tools based on name,
compatibility level, keyword, area of focus, workspace, and technical
specifications.

### Query Sharing {#query-sharing .unnumbered}

Although data service domain models are linked to semantic metadata and
data type specifications, you still need to do a fair amount of
exploring to construct useful queries. If you have query-building
knowledge, the portal enables you to share that knowledge with the rest
of the community. Any portal user can publish CQL queries and provide
documentation to accompany the query. Others can search for CQL queries
based on the target service, the target UML class, the creator of the
query, or the associated name and description of the query.

For more information on queries, see Using the Data Service Query
Portlet on page [47](#using-the-data-service-query-portlet).

### caGrid Account Registration {#cagrid-account-registration .unnumbered}

The caGrid security infrastructure, known as GAARDS, uses an
authentication approach that is based on Public Key Infrastructure
(PKI). PKI requires that users have an X.509 certificate and private
key, also known as *grid credentials*.

The caGrid Dorian service is used to provide users with grid
credentials. To obtain grid credentials, you must register either with
the Dorian service or another Identity Provider (IdP) that has
established a trust relationship with Dorian.

Secure caGrid services apply an authorization policy to incoming
requests based on the identity of the client (*i.e.*, the user who is
making the request). The identity is determined through the
authentication process by inspecting the client's grid credentials. So,
in order to interact with secure services, caGrid users need to obtain
grid credentials.

While nearly all the functionality that the portal provides is available
to un-authenticated users, only authenticated users can share queries
and maintain a query history across browser sessions. The portal uses
GAARDS to authenticate users. So, to use the query sharing and
persistent query history features, you need to obtain grid credentials.

The portal provides an interface that enables you to register for an
account with the caGrid Dorian service that is hosted by the NCICB. This
service provides a Level of Assurance 1 (LOA1), which means anyone can
request an account and the request will automatically be approved. Once
your request is approved, you can provide log in to the portal using
your username and password. The portal will then use the grid
credentials obtained from Dorian when interacting with secure caGrid
services.

### Grid Status Overview {#grid-status-overview .unnumbered}

The caGrid Portal provides a quick, visual description of the scale and
activity of caGrid. The map on the front page of the portal not only
indicates where services are being hosted, but whether those services
are currently running. Icons of various colors indicate the service
status.

In addition to the map, a status portlet presents up-to-date counts of
all participants, all services, data services, and analytical services.
It also provides links to more information about the five most recently
registered services.

### News and Events {#news-and-events .unnumbered}

A news portlet on the front page of the portal displays a running list
of the latest caGrid-related news items. You can click each item to link
to the full news article. You can also click a link to subscribe to the
news feed using your browser or any other RSS 2.0-compliant news feed
reader.

The portal provides a news feed editor application that is available to
the portal administrator. This application can be used to maintain one
or more RSS news channels.

The portal home page also includes a full-featured calendar application.
This application enables you to browse through caGrid-related events by
day, week, month, and year. A portal administrator can import and export
calendar events using the standard iCal format, which is described at
<http://tools.ietf.org/html/rfc2445>.

## Visual Overview of the caGrid Portal Home Page {#visual-overview-of-the-cagrid-portal-home-page .unnumbered}

The caGrid Portal is located at
[http://cagrid-portal.nci.nih.gov/web/guest/home](http://cagrid-portal-qa.nci.nih.gov/web/guest/home).
This address launches the portal home page, shown in Figure 1-1.

Each numbered callout represents one of the features discussed in caGrid
Portal Features on page [4](#cagrid-portal-features).

![](media/image2.png){width="6.192361111111111in"
height="6.080555555555556in"}

[]{#__RefHeading___Toc222721081 .anchor}Figure 1‑1. caGrid Portal home
page

For a description of each numbered callout in Figure 1-1, see Table 1-1
on page [10](#_Ref185567963).

+---------+------------------------------------------------------------+
| Callout | Feature/Description                                        |
| Number  |                                                            |
+=========+============================================================+
| 1       | Main Navigation Bar with four links:                       |
|         |                                                            |
|         | -   **Home**: Returns to the home page from any other      |
|         |     portal page.                                           |
|         |                                                            |
|         | -   **Services**: Opens the Tools page, where you can use  |
|         |     the Discovery and Data Service Query tools to search   |
|         |     for services, participant institutions, and POCs, and  |
|         |     run diagnostic tests on services. You can also build   |
|         |     and share queries from this page.                      |
|         |                                                            |
|         | -   **Tools**: A directory of caBIG® tools is provided     |
|         |     here.                                                  |
|         |                                                            |
|         | -   **Community**: Access community developed portlets.    |
|         |                                                            |
|         | -   **News**: Displays a News page with announcements and  |
|         |     links to caGrid-related news.                          |
|         |                                                            |
|         | -   **Register** page: Enables you to register as a caGrid |
|         |     Portal user.                                           |
+---------+------------------------------------------------------------+
| 2       | **caGrid Status** portlet: Provides a quick, visual        |
|         | description of the scale and activity of caGrid.           |
+---------+------------------------------------------------------------+
| 3       | **Map** portlet with legend: Shows the geographic location |
|         | of services and participant institutions. You can click    |
|         | the icon for a service or institution and link to more     |
|         | detailed information.                                      |
+---------+------------------------------------------------------------+
| 4       | **Portal Sitemap**: Click any link to go to that page of   |
|         | the portal.                                                |
+---------+------------------------------------------------------------+
| 5       | **Calendar**: Enables you to browse through caGrid-related |
|         | events by day, week, month, and year.                      |
+---------+------------------------------------------------------------+
| 6       | **Log In and Register** links: Links for logging in with   |
|         | your existing account, or registering as a caGrid Portal   |
|         | user.                                                      |
+---------+------------------------------------------------------------+
| 7       | **News** portlet: Enables you to link to caGrid-related    |
|         | news stories and subscribe to the caGrid News Feed.        |
+---------+------------------------------------------------------------+
| 8       | **caGrid Links** portlet: Lists links to external          |
|         | caGrid-related sites. Each link destination opens a new    |
|         | window or tab.                                             |
+---------+------------------------------------------------------------+

[]{#_Ref185567963 .anchor}Table 1‑1. Description of feature callouts in
Figure 1-1

# Registering and Logging In

Although you can freely browse and use the caGrid Portal without logging
in to an established account, consider becoming a *registered* user.
This chapter explains the benefits of registration, the procedure for
registering, and the procedures for logging in as a new portal user or
an NIH user.

Topics in this chapter include:

-   About Registration on this page

-   Registering for a Login Account on page
    [12](#registering-for-a-login-account)

-   Logging in with Your caGrid Portal Account on page
    [14](#logging-in-with-your-cagrid-portal-account)

-   Logging in with Your NIH Account on page
    [15](#logging-in-with-your-nih-account)

-   About the Welcome Menu on page [15](#about-the-welcome-menu)

## About Registration {#about-registration .unnumbered}

As discussed in caGrid Account Registration on page
[6](#cagrid-account-registration), becoming a registered caGrid Portal
user gives you Grid credentials so that you can interact with caGrid
services. If you are a registered user, the portal maintains your query
history from previous sessions and enables you to share queries with
other users. In addition, future releases of the portal will enable you
to further customize your user experience.

**Note:** If you already have a login account through the National
Institutes of Health (NIH), you can log in to the portal using your
existing credentials. For more information, see Logging in with Your NIH
Account on page [15](#logging-in-with-your-nih-account).

## Registering for a Login Account {#registering-for-a-login-account .unnumbered}

To register for a caGrid Portal login account, follow these steps:

1.  Click either of the following **Register** links:

-   The link appearing on the main navigation toolbar, or

-   The link appearing in the upper right of the home page.

shows pointers to both links.

![](media/image3.png){width="6.190277777777778in"
height="1.6402777777777777in"}

[]{#__RefHeading___Toc222721082 .anchor}Figure 2‑2. Register links

The Registration page appears, as shown in Figure 2-3.

![](media/image4.png){width="5.059722222222222in"
height="4.402083333333334in"}

[]{#__RefHeading___Toc222721083 .anchor}Figure 2‑3. Registration page

6.  Complete the registration fields.

**Note:** Pay special attention to the password constraints. A password
cannot be a dictionary word and must be constructed as follows:\
\
**Length:** 10 to 20 characters (10-character minimum)\
\
**Characters:** at least one uppercase letter, one lowercase letter, one
number, and one of the following symbols:\
\~! @ \# \$ % \^& \* ( ) \_ { } \[ \] \| : ; \< \> , . ?

7.  When you are finished, click **Submit**.

-   If your username or password did not conform to the required
    constraints, an invalid username or password message appears in red.

-   If your submission was successful, the following message appears in
    green: *Your account was approved, your current account status is
    Active.*

**Note:** Although you are still on the Registration page, do not click
**Submit** again if you received a successful confirmation message.

8.  Do either of the following:

-   Click the **Home** link on the navigation bar to return to the home
    page, or

-   Click the **Log In** link to log in using the account that you just
    created.

9.  Log in by following the instructions in Logging in with Your caGrid
    Portal Account on page
    [14](#logging-in-with-your-cagrid-portal-account).

## Logging in with Your caGrid Portal Account {#logging-in-with-your-cagrid-portal-account .unnumbered}

To log in with your caGrid Portal (non-NIH) account, follow these steps:

1.  If you are not currently viewing the home page, click the **Home**
    link on the navigation bar.

```{=html}
<!-- -->
```
10. Click the **Log In** link in the upper right corner of the page.

11. Enter your username and password.

12. Ensure that the **Identity Provider** field shows **NCICB Dorian**.

13. Click **Log In**.

-   If your login is not recognized, the following message appears:\
    *Invalid username and/or password.*

-   If your login was successful, the following message appears:\
    *You are logged in as: {your name}*

![](media/image5.png){width="3.0520833333333335in" height="1.46875in"}

[]{#__RefHeading___Toc222721084 .anchor}Figure 2‑4. Successful login
message

14. Click the **\<\< To Full Page** link to return to the home page.

In the upper right corner of the home page, a welcome message confirms
that you are logged in.

**Note:** At the end of your session, be sure to log out by (1) clicking
the **Log Out** link below the welcome message, or (2) clicking the
drop-down arrow to the right of the Welcome message and selecting **Sign
Out**.

![](media/image6.jpeg){width="3.0840277777777776in"
height="1.6847222222222222in"}

[]{#__RefHeading___Toc222721085 .anchor}Figure 2‑5. Welcome message with
Logout link

## Logging in with Your NIH Account {#logging-in-with-your-nih-account .unnumbered}

To log in with your NIH account, follow these steps:

1.  If you are not currently viewing the home page, click the **Home**
    link on the navigation bar.

```{=html}
<!-- -->
```
15. Click the **Log In** link in the upper right corner of the page.

16. Enter your username and password.

17. Ensure that the Identity Provider field shows **NCICB Authentication
    Service**.

18. Click **Log In**.

-   If your login is not recognized, the following message appears:\
    *Invalid username and/or password.*

-   If your login was successful, the following message appears:\
    *You are logged in as: {your name}*

19. Click the **\<\< To Full Page** link to return to the home page.

In the upper right corner of the home page, a welcome message confirms
that you are logged in. (See Figure 2-5 on page
[14](#__RefHeading___Toc222721085).)

**Note:** At the end of your session, be sure to log out by clicking the
**Log Out** link below the welcome message.

## About the Welcome Menu {#about-the-welcome-menu .unnumbered}

The Welcome message in the upper right corner of the caGrid Portal
includes a drop-down menu with four commands:

-   **Home:** Returns to the home page

-   **Sign Out:** Logs you out of the caGrid Portal

-   **My Places:** Links to public pages.

![](media/image7.jpeg){width="2.9in" height="2.2in"}

[]{#__RefHeading___Toc222721086 .anchor}Figure 2‑6. Welcome menu

# Using the Map Portlet

As discussed in Chapter 1, the caGrid Portal home page includes a Map
portlet that shows the geographic location of services and participant
institutions in the United States. This chapter explains how to use the
Map portlet to select a service or institution and link to more detailed
information.

Topics in this chapter include:

-   About the Map Portlet on this page

-   Selecting a Category View on page [18](#selecting-a-category-view)

-   Selecting a Service, Participant, or POC on page
    [19](#selecting-a-service-participant-or-poc)

## About the Map Portlet {#about-the-map-portlet .unnumbered}

The Map portlet provides a visual perspective of caGrid services,
participants, and POCs. It serves as an access point for getting started
with discovery.

As shown in Figure 3-7, the map is preceded by a **Categories**
drop-down list and a legend explaining the map icons. The next two
sections explain the list and the icons.

![](media/image8.png){width="5.197916666666667in"
height="3.504861111111111in"}

[]{#__RefHeading___Toc222721087 .anchor}Figure 3‑7. Map portlet

The Map portlet uses the Google Maps API and has standard Google Maps
navigation features. These include navigation arrows, zoom in (+) and
zoom out (-) buttons, and the "grabbing hand" mouse pointer
![](media/image9.png){width="0.22916666666666666in"
height="0.22916666666666666in"} for moving around the map.

## Selecting a Category View {#selecting-a-category-view .unnumbered}

The **Categories** list enables you to filter the map view to show
specific categories. The default view, shown as a series of dashes
(\-\-\--), displays all participant institutes.

![](media/image10.png){width="2.7604166666666665in"
height="2.0722222222222224in"}

[]{#__RefHeading___Toc222721088 .anchor}Figure 3‑8. Categories list

The list also provides the following views:

-   All Services

```{=html}
<!-- -->
```
-   Data Services

-   Analytical Services

```{=html}
<!-- -->
```
-   All Participants

```{=html}
<!-- -->
```
-   Clinical Trials Management Systems

-   Integrative Cancer Research

-   In Vivo Imaging

-   Tissue Banks and Pathology Tools

-   Architecture

-   Vocabulary and Common Data Elements

-   Data Sharing and Intellectual Capitol

-   Documentation and Training

-   Strategic Planning

```{=html}
<!-- -->
```
-   All Points of Contact (not currently available)

To select a category view, follow these steps:

1.  Click the drop-down arrow to the right of the **Categories** list.

```{=html}
<!-- -->
```
20. Select a category from the list.

## Selecting a Service, Participant, or POC  {#selecting-a-service-participant-or-poc .unnumbered}

Map portlet icons are clickable links. Table 3-2 lists each icon type
and includes a cross-reference to the relevant section for working with
the selected type.

**Note:** Icons for active entities appear in dark blue. Identical icons
appearing in gray indicate inactive entities. Those appearing in red
indicate partially active entities. Table 3-2 shows only icons for
active entities.

+------+---------------------------------------------------------------+
| Icon | Description                                                   |
+------+---------------------------------------------------------------+
| ![]  | Data Service                                                  |
| (med |                                                               |
| ia/i | See Selecting a Data Service on this page.                    |
| mage |                                                               |
| 11.p |                                                               |
| ng){ |                                                               |
| widt |                                                               |
| h="0 |                                                               |
| .260 |                                                               |
| 4166 |                                                               |
| 6666 |                                                               |
| 6666 |                                                               |
| 7in" |                                                               |
| hei  |                                                               |
| ght= |                                                               |
| "0.2 |                                                               |
| 2916 |                                                               |
| 6666 |                                                               |
| 6666 |                                                               |
| 6666 |                                                               |
| in"} |                                                               |
+------+---------------------------------------------------------------+
| ![]  | Analytical Service                                            |
| (med |                                                               |
| ia/i | See Selecting an Analytical Service on page                   |
| mage | [21](#selecting-an-analytical-service.).                      |
| 12.p |                                                               |
| ng){ |                                                               |
| widt |                                                               |
| h="0 |                                                               |
| .260 |                                                               |
| 4166 |                                                               |
| 6666 |                                                               |
| 6666 |                                                               |
| 7in" |                                                               |
| hei  |                                                               |
| ght= |                                                               |
| "0.2 |                                                               |
| 3958 |                                                               |
| 3333 |                                                               |
| 3333 |                                                               |
| 3334 |                                                               |
| in"} |                                                               |
+------+---------------------------------------------------------------+
| ![]  | Participant Institute:                                        |
| (med |                                                               |
| ia/i | See Selecting a Participant Institute on page                 |
| mage | [22](#selecting-a-participant-institute.).                    |
| 13.p |                                                               |
| ng){ |                                                               |
| widt |                                                               |
| h="0 |                                                               |
| .260 |                                                               |
| 4166 |                                                               |
| 6666 |                                                               |
| 6666 |                                                               |
| 7in" |                                                               |
| hei  |                                                               |
| ght= |                                                               |
| "0.2 |                                                               |
| 3958 |                                                               |
| 3333 |                                                               |
| 3333 |                                                               |
| 3334 |                                                               |
| in"} |                                                               |
+------+---------------------------------------------------------------+
| ![]  | Hosting Research Center                                       |
| (med |                                                               |
| ia/i | See Selecting a Hosting Research Center on page               |
| mage | [24](#selecting-a-hosting-research-center.).                  |
| 14.p |                                                               |
| ng){ | **Note:** A hosting research center represents one or more    |
| widt | services (data or analytical) that are hosted at the same     |
| h="0 | location.                                                     |
| .260 |                                                               |
| 4166 |                                                               |
| 6666 |                                                               |
| 6666 |                                                               |
| 7in" |                                                               |
| hei  |                                                               |
| ght= |                                                               |
| "0.2 |                                                               |
| 2916 |                                                               |
| 6666 |                                                               |
| 6666 |                                                               |
| 6666 |                                                               |
| in"} |                                                               |
+------+---------------------------------------------------------------+
| ![]  | Point of Contact (POC)                                        |
| (med |                                                               |
| ia/i | The Map portlet does not currently display POC information.   |
| mage | For more information on finding and viewing details for a     |
| 15.p | POC, see the following sections:                              |
| ng){ |                                                               |
| widt | -   Searching for a POC on page [37](#searching-for-a-poc)    |
| h="0 |                                                               |
| .260 | -   Viewing Details for a POC on page                         |
| 4166 |     [43](#viewing-details-for-a-poc)                          |
| 6666 |                                                               |
| 6666 |                                                               |
| 7in" |                                                               |
| hei  |                                                               |
| ght= |                                                               |
| "0.2 |                                                               |
| 3958 |                                                               |
| 3333 |                                                               |
| 3333 |                                                               |
| 3334 |                                                               |
| in"} |                                                               |
+------+---------------------------------------------------------------+

Table 3‑2. Map icon descriptions for active entities

### Selecting a Data Service. {#selecting-a-data-service. .unnumbered}

To locate and view details for a data service, follow these steps:

21. Select the **Data Services** category from the drop-down list.

The map refreshes to show only data services.

22. Click a **data service** icon to select the represented service.

A callout balloon appears above the icon. The balloon displays the
following information:

-   a link to more details

-   the name of the hosting center

-   the current status of the hosting center (active, inactive, or
    partially active).

Figure 3-9 shows the results of clicking the NCICB hosting center
*GridPIR*.

![](media/image16.png){width="3.329861111111111in"
height="2.297222222222222in"}

[]{#__RefHeading___Toc222721089 .anchor}Figure 3‑9. Callout balloon for
a data service center

23. Click the underlined link.

The Services page appears with the **Details** tab and **Service**
subtab of the Discovery portlet selected, as shown in Figure 3-10.

![](media/image17.png){width="3.6284722222222223in"
height="2.4090277777777778in"}

[]{#__RefHeading___Toc222721090 .anchor}Figure 3‑10. Discovery Portlet
showing details for a selected data service

For more information about the Discovery portlet and the Service subtab,
see Viewing Details for Services on page
[39](#viewing-details-for-services).

### Selecting an Analytical Service. {#selecting-an-analytical-service. .unnumbered}

24. Select the **Analytical Services** category from the drop-down list.

The map refreshes to show only analytical services.

**Note:** The portal represents some analytical services using the
**analytical service** icon
![](media/image12.png){width="0.2604166666666667in"
height="0.23958333333333334in"}. Others that are part of a group of
services in the same geographic location show a **hosting research
center** icon ![](media/image14.png){width="0.2604166666666667in"
height="0.22916666666666666in"}. You can find analytical services by
clicking either icon, but the results will differ slightly, as explained
in the next step.

25. Click the appropriate icon:

-   If you clicked the **analytical service** icon
    ![](media/image12.png){width="0.2604166666666667in"
    height="0.23958333333333334in"}, the callout balloon displays the
    same information used for a data service center (shown in Figure 3-9
    on page [20](#__RefHeading___Toc222721089)):

```{=html}
<!-- -->
```
-   a link to more details

-   the name of the hosting center

-   the current status of the hosting center (active, inactive, or
    partially active).

Click the details link to view more information on the **Service**
subtab of the Discovery portlet, as shown in Figure 3-10 on page
[20](#__RefHeading___Toc222721090).

-   If you clicked the **hosting research center** icon
    ![](media/image14.png){width="0.2604166666666667in"
    height="0.22916666666666666in"}, follow the steps explained in
    Selecting a Hosting Research Center on page
    [24](#selecting-a-hosting-research-center.).

### Selecting a Participant Institute. {#selecting-a-participant-institute. .unnumbered}

26. Select the **All Participants** category from the drop-down list, or
    select a specific sub-category (for example, **Clinical Trials
    Management Systems**).

The map refreshes to show only the selected participant category.

27. Click a **Participant Institute** icon
    ![](media/image13.png){width="0.2604166666666667in"
    height="0.23958333333333334in"} to select the represented service.

A callout balloon appears above the icon. The balloon displays the
following information:

-   a participant name link

-   a URL to the participant's home page.

Figure 3-11 shows an example of a callout balloon for Lombardi
Comprehensive Cancer Center.

![](media/image18.png){width="2.5006944444444446in"
height="1.9319444444444445in"}

[]{#__RefHeading___Toc222721091 .anchor}Figure 3‑11. Callout balloon for
a selected participant

28. Click the participant name link (top link).

The Services page appears with the **Details** tab and **Participant**
subtab selected, as shown in Figure 3-12.

![](media/image19.png){width="5.125in" height="4.333333333333333in"}

[]{#__RefHeading___Toc222721092 .anchor}Figure 3‑12. Discovery portlet
showing details for a participant institute

For more information about the information available on this page, see
Viewing Details for a Participanton page
[42](#viewing-details-for-a-participant).

### Selecting a Hosting Research Center. {#selecting-a-hosting-research-center. .unnumbered}

1.  Find a **Hosting Research Center** icon
    ![](media/image14.png){width="0.2604166666666667in"
    height="0.22916666666666666in"}, then click the icon.

A callout balloon appears above the icon. The balloon displays the
following information:

-   the number of services available at the selected location

-   a **View** link.

Figure 3-13 shows an example of a callout balloon for a hosting research
center.

![](media/image20.png){width="2.8604166666666666in" height="1.9625in"}

[]{#__RefHeading___Toc222721093 .anchor}Figure 3‑13. Callout balloon for
an analytical service center

29. Click the **View** ink.

The Services page appears with the **Directory** tab and **List View**
subtab selected. The **List View** subtab displays a list of services.

30. In the list at the bottom of the page, do the following:

```{=html}
<!-- -->
```
a.  Locate the service that you want to view.

b.  Select the **More Details...** link on the right, as shown in Figure
    3-14.

![](media/image21.png){width="5.104166666666667in" height="4.25in"}

[]{#__RefHeading___Toc222721094 .anchor}Figure 3‑14. List of hosting
research centers with More Details links

For more information about the information available on the List View
subtab, see Viewing Details for an Analytical Service on page
[40](#viewing-details-for-an-analytical-service).

31. Click the **Home** link in the upper left to return to the home
    page.

### Selecting a POC. {#selecting-a-poc. .unnumbered}

As explained in Selecting a Category View on page
[18](#selecting-a-category-view), the Map portlet does not currently
display POC information. For more information on finding and viewing
details for a POC, see the following sections:

-   Searching for a POC on page [37](#searching-for-a-poc)

-   Viewing Details for a POC on page [43](#viewing-details-for-a-poc)

# Using the Discovery Portlet

In Chapter 1, the Discovery section on page [4](#discovery) introduced
you to the concept of *discovery*. This chapter introduces the Discovery
portlet, which enables you to discover caGrid services, caBIG®
participants, and caGrid POCs. It also includes information about the
Service Diagnostics portlet, which you can use to learn the status of
any caGrid service.

Topics in this chapter include:

-   About the Discovery Portlet on this page

-   Viewing Data in a List or a Map on page
    [28](#viewing-data-in-a-list-or-a-map)

-   *Searching for Services, Participants, and POCs* on page
    [32](#searching-for-services-participants-and-pocs)

-   Viewing Details for Services, Participants, and POCs on page
    [39](#viewing-details-for-services-participants-and-pocs)

-   Using the Service Diagnostics Portlet on page
    [43](#using-the-service-diagnostics-portlet)

## About the Discovery Portlet {#about-the-discovery-portlet .unnumbered}

The Discovery portlet offers a versatile interface for browsing,
searching, and viewing metadata. The interface includes drop-down lists,
keyword entry fields, and search field selection boxes.

The various Discovery portlet features are available in a series of tabs
with subtabs. Table 7-7 describes each tab and its subtabs.

  -----------------------------------------------------------------------
  Feature              Description
  -------------------- --------------------------------------------------
  Directory tab        Enables you to browse for services, participants,
                       or POCs by selecting directories from a drop-down
                       list. You can use a List view or Map view
                       (discussed below).

  List View subtab     Displays browsing results in a paginated list.
                       Each result includes a link for viewing more
                       details (metadata). When you hover your mouse over
                       a service result, a popup window appears that
                       displays the service\'s name, version, type,
                       activity status, URL, and secured status.

  Map View subtab      Displays selected items on a map of the U.S. and
                       enables you to link to further information. This
                       tab works the same way as the Map portlet
                       discussed in Chapter 3 on p.
                       [17](#using-the-map-portlet).

  Search tab           Enables you to search for services, participants,
                       and POCs using keywords and search fields.

  Services subtab      Used to search for a service by entering one or
                       more keywords and selecting fields to constrain
                       the search. This tab includes both a simple and
                       advanced field set.

  Participants subtab  Used to search for a participant by entering one
                       or more keywords and selecting fields to constrain
                       the search.

  POCs subtab          Used to search for a POC by entering one or more
                       keywords and selecting fields to constrain the
                       search.

  Details tab          Displays metadata for a selected service,
                       participant, or POC.

  Service subtab       Displays metadata for a selected service.

  Participant subtab   Displays metadata for a selected participant.

  POC subtab           Displays metadata for a selected POC.
  -----------------------------------------------------------------------

Table 4‑3. Discovery portlet tab descriptions

## Viewing Data in a List or a Map {#viewing-data-in-a-list-or-a-map .unnumbered}

Use the **Directory** tab when you want to select a category and view
its results in a list or on a map. This tab has two subtabs: **List
View** and **Map View**. The next two sections explain how to use these
subtabs.

### Using the List View Subtab {#using-the-list-view-subtab .unnumbered}

The **List View** subtab enables you to select a category from the
**Directories** list and view the results in a paginated results list.
You can also select a saved result set from your current browser
session.

Figure 4-15 shows the List View subtab with results displayed for the
**All Services** category. The result list displays ten results per
page. Note that each result includes a **More Details** link. Data
services also include a **Query** link that enables you to build a query
for the selected service.

![](media/image22.png){width="5.302083333333333in"
height="4.260416666666667in"}

[]{#__RefHeading___Toc222721095 .anchor}Figure 4‑15. Directory tab \>
List View subtab -- results for All Services category

To view results for a selected category, follow these steps:

1.  Select the **Directory** tab.

```{=html}
<!-- -->
```
32. Select the **List View** subtab.

33. Do either of the following:

-   Select a category from the **Directories** list; or

-   Select a result set from the **Search Results** list.

The results appear in the lower area of the subtab.

34. Use the browse buttons to page through the list:

-   Click the **Forward** button
    ![](media/image23.png){width="0.17708333333333334in"
    height="0.17708333333333334in"} to page forward.

-   Click the **Back** button
    ![](media/image24.png){width="0.17708333333333334in"
    height="0.17708333333333334in"} to page backward.

-   Click the **Return**
    ![](media/image25.png){width="0.19791666666666666in"
    height="0.17708333333333334in"} to return to the beginning of the
    list.

-   Click the **Skip to End**
    ![](media/image26.png){width="0.19791666666666666in"
    height="0.17708333333333334in"} to skip to the end of the list.

35. To view details for a result, click the **More Details** link.

For more information about viewing details for a result, see Viewing
Details for Services, Participants, and POCs on page
[39](#viewing-details-for-services-participants-and-pocs).

36. If the results include data services and you want to build a query
    for a selected service, click the **Query** link.

For more information about building queries, see Building a Query Using
the Query Builder Tool on page
[50](#building-a-query-using-the-query-builder-tool).

### Using the Map View {#using-the-map-view .unnumbered}

After you select a category and view the results, you can switch to the
**Map View** subtab for a graphical view of the results. Or, instead of
starting with the List View subtab, you can start with the Map View
subtab and select a category or result set using its drop-down lists.

To view search results using the Map View subtab, follow these steps:

1.  Use the **List View** subtab to select a category and display the
    results.

For complete instructions, see Using the List View Subtab on page
[28](#using-the-list-view-subtab).

37. Click the **Map View** subtab.

The map displays the results as shown in Figure 4-16.

![](media/image27.png){width="4.091666666666667in"
height="3.936111111111111in"}

[]{#__RefHeading___Toc222721096 .anchor}Figure 4‑16. Map View subtab

The Map View subtab functions exactly like the Map portlet. For more
information, see the following sections in Chapter 3, Using the Map
Portlet, on page [17](#using-the-map-portlet).

-   About the Map Portlet on page [17](#about-the-map-portlet)

-   Selecting a Category View on page [18](#selecting-a-category-view)

-   Selecting a Service, Participant, or POC on page
    [19](#selecting-a-service-participant-or-poc)

## Searching for Services, Participants, and POCs {#searching-for-services-participants-and-pocs .unnumbered}

The **Search** tab provides a comprehensive solution for finding caGrid
services, caBIG® participants, or and caGrid POCs. Each entity has its
own search subtab.

The following topics explain how to use each subtab to execute a search:

-   Searching for a Service on this page [32](#searching-for-a-service)

-   Searching for a Participant on page
    [36](#searching-for-a-participant)

-   Searching for a POC on page [37](#searching-for-a-poc)

### Searching for a Service {#searching-for-a-service .unnumbered}

Use the **Services** subtab to search for a service. You have three
options for how to perform the search: Simple, Advanced, and EVS.

The Simple and Advanced search modes involve entering one or more
keywords and then optionally selecting fields to narrow your results.
The Simple search mode includes standard metadata fields while the
Advanced search mode expands the available fields by including metadata
from the domain model that services expose.

Using the EVS search mode involves entering concept names from the NCI
Thesaurus. You can then find services that are related to these
concepts. As you type each character in a concept name, the
concept-based discovery Portlet suggests concepts that you can select.
Results include all services involving the selected concept.

All searches use sub-string, case-insensitive matching.

For more information, see Performing a Simple or Advanced Search on page
[32](#performing-a-simple-or-advanced-search) and Performing an EVS
Search on page [34](#performing-an-evs-search).

#### **Performing a Simple or Advanced Search** {#performing-a-simple-or-advanced-search .unnumbered}

To perform a Simple or an Advanced search, follow these steps:

1.  Click the **Search** tab.

```{=html}
<!-- -->
```
38. Click the **Services** subtab.

39. Select the **Simple** or the **Advanced** search option. The
    Advanced search option includes more fields by which you can narrow
    your search results.

Figure 4-17 shows the layout of the Services subtab when the Simple
search mode is selected.

![](media/image28.png){width="3.609027777777778in"
height="2.267361111111111in"}

[]{#__RefHeading___Toc222721097 .anchor}Figure 4‑17. Services subtab
with the Simple search mode selected

Figure 4-18 shows the layout of the Services subtab when the Advanced
search mode is selected.

![](media/image29.png){width="3.640972222222222in" height="2.28125in"}

[]{#__RefHeading___Toc222721098 .anchor}Figure 4‑18. Services subtab
with Advanced search mode selected

40. Enter one or more keywords in the **Keyword** field.

41. Optionally, restrict your search by selecting one or more fields in
    the **Search Fields** selection box.

**Note:** If you do not select any fields in the Simple or Advanced
search modes, caGrid Portal includes all fields in its search.\
\
To select consecutive fields in the **Search Fields** selection box,
select a field, press and hold the [Shift]{.smallcaps} key, and then
select the last field. To select fields that are not consecutive, select
a field, press and hold the [Ctrl]{.smallcaps} key, and then select
additional fields.

42. Click **Search**. The results appear in the lower area of the
    subtab.

![](media/image30.png){width="3.6486111111111112in" height="3.0125in"}

[]{#__RefHeading___Toc222721099 .anchor}Figure 4‑19. Discovered services

43. Use the browse buttons to page through the list:

-   Click the **Forward** button
    ![](media/image23.png){width="0.17708333333333334in"
    height="0.17708333333333334in"} to page forward.

-   Click the **Back** button
    ![](media/image24.png){width="0.17708333333333334in"
    height="0.17708333333333334in"} to page backward.

-   Click the **Return**
    ![](media/image25.png){width="0.19791666666666666in"
    height="0.17708333333333334in"} to return to the beginning of the
    list.

-   Click the **Skip to End**
    ![](media/image26.png){width="0.19791666666666666in"
    height="0.17708333333333334in"} to skip to the end of the list.

44. To view details for a result, click the **More Details** link. For
    more information about viewing details for a result, see Viewing
    Details for Services, Participants, and POCs on page
    [39](#viewing-details-for-services-participants-and-pocs).

**Note:** When you hover your mouse over a service result, a popup
window appears that displays the service\'s name, version, type,
activity status, URL, and secured status.

45. If the results include data services and you want to build a query
    for a selected service, click the **Query** link. For more
    information about building queries, see Building a Query Using the
    Query Builder Tool on page
    [50](#building-a-query-using-the-query-builder-tool).

#### **Performing an EVS Search** {#performing-an-evs-search .unnumbered}

To perform an EVS search, follow these steps:

1.  Click the **Search** tab.

```{=html}
<!-- -->
```
46. Click the **Services** subtab.

47. Select the **EVS** search option.

Figure 4-17 shows the layout of the Services subtab when the EVS search
mode is selected.

![](media/image31.png){width="3.13125in" height="2.8875in"}

[]{#__RefHeading___Toc222721100 .anchor}Figure 4‑20. Services subtab
with the EVS search mode selected

48. Discover services by entering concept names into the **Keyword**
    field. As you type each letter, the auto completer searches concepts
    relevant to services in the Portal. If it doesn\'t find a match, it
    looks up concepts in the NCI Thesaurus.

49. Select the concept matching the services you want to discover and
    then press [Enter]{.smallcaps}. The concept code, concept
    definition, and relevant services for the selected concept appear in
    the tab.

Figure 4-21 shows the results of an EVS search.

![](media/image32.png){width="3.6381944444444443in" height="2.43125in"}

[]{#__RefHeading___Toc222721101 .anchor}Figure 4‑21. Results of an EVS
search

50. Click the link noting how many services match the concept you
    selected. The results appear in the lower area of the subtab.

![](media/image30.png){width="3.6486111111111112in" height="3.0125in"}

[]{#__RefHeading___Toc222721102 .anchor}Figure 4‑22. Discovered services

51. Use the browse buttons to page through the list:

-   Click the **Forward** button
    ![](media/image23.png){width="0.17708333333333334in"
    height="0.17708333333333334in"} to page forward.

-   Click the **Back** button
    ![](media/image24.png){width="0.17708333333333334in"
    height="0.17708333333333334in"} to page backward.

-   Click the **Return**
    ![](media/image25.png){width="0.19791666666666666in"
    height="0.17708333333333334in"} to return to the beginning of the
    list.

-   Click the **Skip to End**
    ![](media/image26.png){width="0.19791666666666666in"
    height="0.17708333333333334in"} to skip to the end of the list.

52. To view details for a result, click the **More Details** link. For
    more information about viewing details for a result, see Viewing
    Details for Services, Participants, and POCs on page
    [39](#viewing-details-for-services-participants-and-pocs).

53. If the results include data services and you want to build a query
    for a selected service, click the **Query** link. For more
    information about building queries, see Building a Query Using the
    Query Builder Tool on page
    [50](#building-a-query-using-the-query-builder-tool).

### Searching for a Participant {#searching-for-a-participant .unnumbered}

Use the **Participants** subtab to search for a participant by entering
one or more keywords and selecting fields to constrain the search. The
search form includes a **Keyword** field and a **Search Fields**
selection box, as shown in Figure 4-23.

![](media/image33.png){width="4.579166666666667in" height="2.80625in"}

[]{#__RefHeading___Toc222721103 .anchor}Figure 4‑23. Participants subtab

To search for a participant, follow these steps:

1.  Click the **Search** tab.

```{=html}
<!-- -->
```
54. Click the **Participants** subtab.

55. Enter one or more keywords in the **Keyword** field.

56. Select fields from the **Search Fields** selection box.

**Note:** If you do not select search fields, all of the fields are used
in the search.

57. Click **Search**.

The results appear in the lower area of the subtab.

58. Use the browse buttons to page through the list:

-   Click the **Forward** button
    ![](media/image23.png){width="0.17708333333333334in"
    height="0.17708333333333334in"} to page forward.

-   Click the **Back** button
    ![](media/image24.png){width="0.17708333333333334in"
    height="0.17708333333333334in"} to page backward.

-   Click the **Return**
    ![](media/image25.png){width="0.19791666666666666in"
    height="0.17708333333333334in"} to return to the beginning of the
    list.

-   Click the **Skip to End**
    ![](media/image26.png){width="0.19791666666666666in"
    height="0.17708333333333334in"} to skip to the end of the list.

59. To view details for a result, click the **More Details** link.

For more information about viewing details for a result, see Viewing
Details for Services, Participants, and POCs on page
[39](#viewing-details-for-services-participants-and-pocs).

### Searching for a POC {#searching-for-a-poc .unnumbered}

Use the **POCs** subtab to search for a POC by entering one or more
keywords and selecting fields to constrain the search. The search form
includes a **Keyword** field and a **Search Fields** selection box, as
shown in Figure 4-24.

![](media/image34.png){width="4.607638888888889in"
height="2.7527777777777778in"}

[]{#__RefHeading___Toc222721104 .anchor}Figure 4‑24. POCs subtab

To search for a POC, follow these steps:

1.  Click the **Search** tab.

```{=html}
<!-- -->
```
60. Click the **POCs** subtab.

61. Enter one or more keywords in the **Keyword** field.

62. Select fields from the **Search Fields** selection box.

**Note:** If you do not select search fields, all of the fields are used
in the search.

63. Click **Search**.

The results appear in the lower area of the subtab.

64. Use the browse buttons to page through the list:

-   Click the **Forward** button
    ![](media/image23.png){width="0.17708333333333334in"
    height="0.17708333333333334in"} to page forward.

-   Click the **Back** button
    ![](media/image24.png){width="0.17708333333333334in"
    height="0.17708333333333334in"} to page backward.

-   Click the **Return**
    ![](media/image25.png){width="0.19791666666666666in"
    height="0.17708333333333334in"} to return to the beginning of the
    list.

-   Click the **Skip to End**
    ![](media/image26.png){width="0.19791666666666666in"
    height="0.17708333333333334in"} to skip to the end of the list.

65. To view details for a result, click the **More Details** link.

For more information about viewing details for a result, see Viewing
Details for Services, Participants, and POCs on page
[39](#viewing-details-for-services-participants-and-pocs).

## Viewing Details for Services, Participants, and POCs {#viewing-details-for-services-participants-and-pocs .unnumbered}

The **Details** tab displays metadata for services, participants, and
POCs. The following topics discuss the level of detail for each entity:

-   Viewing Details for Services on this page

-   Viewing Details for a Participant on page
    [42](#viewing-details-for-a-participant)

-   Viewing Details for a POC on page [43](#viewing-details-for-a-poc)

### Viewing Details for Services {#viewing-details-for-services .unnumbered}

caGrid Services provide a standard set of metadata. This metadata
includes descriptions of the service's operations, information about the
hosting research center and, if the service is a data service, the
complete domain model that is supported by the service.

In addition, data types that the service operations use are defined by
XML schemas and are registered with the Global Metadata Exchange (GME)
service.

#### Viewing Details for a Data Service {#viewing-details-for-a-data-service .unnumbered}

To view details for a data service, follow these steps:

1.  Use the **Directory** or **Search** tabs to find the desired data
    service.

For more information, see the following topics:

-   Using the List View Subtab on page [28](#using-the-list-view-subtab)

-   Searching for a Service on page [32](#searching-for-a-service)

66. Click the **Details** tab.

Details for the selected data service appear on the **Service** subtab,
as shown in Figure 4-25.

![](media/image35.png){width="4.116666666666666in"
height="2.908333333333333in"}

[]{#__RefHeading___Toc222721105 .anchor}Figure 4‑25. Details for a
selected data service

67. Click the plus sign preceding each top-level of metadata to drill
    down to the sub-levels.

For example, when viewing details for a data service, you can drill down
through the complete domain model that the service supports. You can
then select a class for a query by clicking the **Select For Query**
button, as shown in Figure 4-26.

![](media/image36.png){width="3.579861111111111in"
height="4.1194444444444445in"}

[]{#__RefHeading___Toc222721106 .anchor}Figure 4‑26. Selecting a UML
class for a query

#### Viewing Details for an Analytical Service {#viewing-details-for-an-analytical-service .unnumbered}

To view details for an analytical service, follow these steps:

1.  Use the **Directory** or **Search** tabs to find the desired
    analytical service.

For more information, see the following topics:

-   Using the List View Subtab on page [28](#using-the-list-view-subtab)

-   Searching for a Service on page [32](#searching-for-a-service)

68. Click the **Details** tab.

Details for the selected analytical service appear on the **Service**
subtab, as shown in Figure 4-27.

![](media/image37.png){width="4.094444444444444in"
height="3.390972222222222in"}

[]{#__RefHeading___Toc222721107 .anchor}Figure 4‑27. Details for a
selected analytical service

69. Click the plus sign preceding each top-level of metadata to drill
    down to the sub-levels.

**Note:** Analytical services do not include a domain model.

### Viewing Details for a Participant {#viewing-details-for-a-participant .unnumbered}

To view details for a participant, follow these steps:

1.  Use the **Directory** or **Search** tabs to find the desired
    participant.

For more information, see the following topics:

-   Using the List View Subtab on page [28](#using-the-list-view-subtab)

-   Searching for a Participant on page
    [36](#searching-for-a-participant)

70. Click the **Details** tab.

Details for the selected participant appear on the **Participant**
subtab, as shown in Figure 4-28.

![](media/image38.png){width="4.113194444444445in"
height="3.2284722222222224in"}

[]{#__RefHeading___Toc222721108 .anchor}Figure 4‑28. Details for a
selected participant

### Viewing Details for a POC {#viewing-details-for-a-poc .unnumbered}

To view details for a POC, follow these steps:

1.  Use the **Directory** or **Search** tabs to find the desired POC.

For more information, see the following topics:

-   Using the List View Subtab on page [28](#using-the-list-view-subtab)

-   Searching for a POC on page [37](#searching-for-a-poc)

71. Click the **Details** tab.

Details for the selected POC appear on the **POC** subtab, as shown in\
Figure 4-29.

![](media/image39.png){width="4.090277777777778in"
height="2.676388888888889in"}

[]{#__RefHeading___Toc222721109 .anchor}Figure 4‑29. Details for a
selected POC

## Using the Service Diagnostics Portlet {#using-the-service-diagnostics-portlet .unnumbered}

The Service Diagnostics portlet runs basic diagnostic tests on any
caGrid service, allowing service developers to check the health of their
service or diagnose service advertisement issues.

### About the Service Diagnostics Portlet  {#about-the-service-diagnostics-portlet .unnumbered}

Access the Service Diagnostics portlet at the bottom of the Services
tab.

![](media/image40.png){width="5.260416666666667in"
height="4.169444444444444in"}

[]{#__RefHeading___Toc222721110 .anchor}Figure 4‑30. Service Diagnostics
portlet on the Services tab

The Service Diagnostics portlet runs the following tests:

-   Check the status of the caGrid service in the Portal. Status(s) in
    the Portal can be one of the following:

```{=html}
<!-- -->
```
-   **Active** -- Service is valid and responding.

-   **Inactive** -- Service is not online or not advertising to the
    Index Service.

-   **Banned** -- Service has been banned from the Portal by the Portal
    admin. Contact [CBIIT Application
    Support](http://ncicb.nci.nih.gov/support) for banning/unbanning
    services in the Portal.

-   **Dormant** -- Service has not been active for a prolonged period of
    time. Dormant and banned services are not visible in the Portal.

See this [caGrid
Wiki](http://www.cagrid.org/wiki/CaGrid:FAQ#How_does_the_Portal_assign_Status_to_a_Service.3F)
page for more information on service status(s).

-   Checks that the service that is being diagnosed is available by
    trying to query it for the caGrid Metadata resource property. This
    diagnosis will fail if any of the following is true:

```{=html}
<!-- -->
```
-   caGrid service being diagnosed is not online or not accessible on
    the Internet.

-   caGrid Service being diagnosed is not configured.

-   caGrid Service being diagnosed is configured with a host certificate
    not trusted by caGrid Portal. See the [caGrid Wiki -
    GAARDS](http://www.cagrid.org/wiki/GAARDS:Main) page for more
    details.

```{=html}
<!-- -->
```
-   Retrieves the caGrid service metadata and validates the service
    metadata against the expected XML Schema. See the [caGrid Wiki -
    Metadata](http://www.cagrid.org/wiki/CaGrid:MetadataModels) page for
    more information on caGrid Service Metadata.

-   Checks the caGrid Index Service to ensure that the service is
    advertising correctly. See [caGrid Wiki - Index
    Service](http://www.cagrid.org/wiki/CaGrid:IndexService) for more
    information

### Running Diagnostic Tests {#running-diagnostic-tests .unnumbered}

To run diagnostic tests on a service, follow these steps:

1.  In the URL field, enter the URL of the service you want to check.\
    ![](media/image41.png){width="5.083333333333333in"
    height="1.4583333333333333in"}

[]{#__RefHeading___Toc222721111 .anchor}Figure 4‑31. URL field in the
Service Diagnostics portlet

72. Click ![](media/image42.png){width="0.71875in"
    height="0.23958333333333334in"}. The Portal runs diagnostic tests
    and reports the results.\
    ![](media/image43.png){width="5.125in"
    height="2.8229166666666665in"}

[]{#__RefHeading___Toc222721112 .anchor}Figure 4‑32. Successful result
in the Service Diagnostics portlet

### Interpreting Results of Diagnostic Tests {#interpreting-results-of-diagnostic-tests .unnumbered}

If you enter an incorrect or malformed URL for a service, the Service
Diagnostics portlet indicates this in the test results. Click
![](media/image44.png){width="0.1875in" height="0.1875in"} where it is
available to view more information about a diagnostic result or function
in the portlet.

![](media/image45.png){width="5.78125in" height="2.5416666666666665in"}

[]{#__RefHeading___Toc222721113 .anchor}Figure 4‑33. Unsuccessful result
in the Service Diagnostics portlet

See <http://www.cagrid.org/wiki/CaGrid:How-To:TroubleshootIndexService>
to review problems that can prevent proper advertisement and
registration of a service to the Index Service.

# Using the Data Service Query Portlet

The Data Service Query portlet enables you to query services that
support the CQL query language. This chapter explains how to build and
share queries.

Topics in this chapter include:

-   About the Data Service Query Portlet on this page

-   Query-Building Scenarios on page [48](#query-building-scenarios)

-   About the History Tab on page [64](#about-the-history-tab)

-   Working with Shared Queries on page
    [66](#working-with-shared-queries)

## About the Data Service Query Portlet {#about-the-data-service-query-portlet .unnumbered}

Using the Data Service Query portlet, you can build and execute a query
(CQL or DCQL), view the results in tabular form, and export to Microsoft
Excel or XML form. As long as you are a registered portal user, the
portal maintains a complete history of your queries so that you can
always retrieve and work with your previously executed queries.

The Data Service Query portlet interface is organized in a series of
tabs. Table 5-4 describes each tab.

+-----------------+----------------------------------------------------+
| Tab             | Description                                        |
+-----------------+----------------------------------------------------+
| Select UML      | Enables you to enter a URL for a selected data     |
| Class           | service and view a list of UML classes.            |
+-----------------+----------------------------------------------------+
| Query           | Provides two subtabs:                              |
|                 |                                                    |
|                 | -   **Query Builder**, which provides a graphical  |
|                 |     interface for building CQL and DCQL queries    |
|                 |                                                    |
|                 | -   **Query XML**, which enables you to enter a    |
|                 |     data service URL and query directly and then   |
|                 |     execute or share the query                     |
+-----------------+----------------------------------------------------+
| History         | Shows all of your stored queries.                  |
+-----------------+----------------------------------------------------+
| Results         | Displays query results in tabular or XML form.     |
+-----------------+----------------------------------------------------+
| Shared Queries  | Provides a **Find Shared Queries** subtab that     |
|                 | includes both a **Keyword** field and a **Search   |
|                 | Fields** selection box. You can use these tools to |
|                 | search for shared queries.                         |
+-----------------+----------------------------------------------------+

Table 5‑4. Data Service Query portlet tab descriptions

**Tip:** For more information about CQL and DCQL concepts, see
<http://www.cagrid.org/mwiki/index.php?title=Data_Services:CQL> and
http://www.cagrid.org/wiki/Federated_Query:DCQL.

## Query-Building Scenarios {#query-building-scenarios .unnumbered}

To execute a query, you need the following:

-   The URL of the caGrid data service to which the query will be sent

-   The query itself

The portal provides several approaches for specifying these
requirements. The following scenarios explain each approach.

### Scenario 1: Starting without a URL or Query {#scenario-1-starting-without-a-url-or-query .unnumbered}

If you do not have the service URL or the query, follow these steps:

1.  Locate a service using either the **Directory** or **Search** tab of
    the Discovery portlet.

For more information, see Searching for a Service on page
[32](#searching-for-a-service).

73. If you want to view metadata for a UML class before selecting it for
    a query, follow substeps 2a through 2d. Otherwise, skip to step
    3**:**

```{=html}
<!-- -->
```
a.  Click the **More Details** link for the desired service.

```{=html}
<!-- -->
```
c.  Expand the **Domain Model**.

d.  Drill down to the metadata for a selected class.

e.  Click **Select for Query**.

```{=html}
<!-- -->
```
74. To select the desired service from the results list, follow these
    steps:

```{=html}
<!-- -->
```
a.  Click the **Query** link for the desired service.

On the Data Service Query portlet \> **Select UML Class** tab, the
**Service URL** field displays the URL for the selected service. A list
of UML classes appears below the field, as shown in Figure 5-34.

![](media/image46.png){width="5.260416666666667in"
height="1.7291666666666667in"}

[]{#__RefHeading___Toc222721114 .anchor}Figure 5‑34. Starting a query
from a selected result

f.  Click the desired UML class.

On the Data Service Query portlet, the **Query** tab \> **Query
Builder** subtab displays a working query, as shown in Figure 5-35.

![](media/image47.png){width="5.09375in" height="2.4479166666666665in"}

[]{#__RefHeading___Toc222721115 .anchor}Figure 5‑35. Working query

### Scenario 2: Starting with a URL but No CQL Query {#scenario-2-starting-with-a-url-but-no-cql-query .unnumbered}

If you have the service URL but no CQL query, follow these steps:

1.  On the Data Service Query portlet, click the **Select UML Class**
    tab.

```{=html}
<!-- -->
```
75. Enter the URL in the **Service URL** field.

76. Click **Select**.

77. Click the desired UML class from the list.

The **Query** tab \> **Query Builder** subtab displays a working query.

### Scenario 3: Starting with a URL and a CQL Query {#scenario-3-starting-with-a-url-and-a-cql-query .unnumbered}

If you have both the URL and the CQL query, follow these steps:

1.  On the Data Service Query portlet, click the **Query** tab.

```{=html}
<!-- -->
```
78. Click the **Query XML** subtab.

79. Enter the URL in the **URL** field.

80. Enter the CQL query in the **Query** text field.

81. Click **Submit Query**.

## Building a Query Using the Query Builder Tool {#building-a-query-using-the-query-builder-tool .unnumbered}

caGrid data services all use a uniform query language, Common Query
Language (CQL), to express queries against a data source using an object
oriented language.

To express queries over a combination of caGrid data services, you must
use Distributed caBIG® Query Language (DCQL) instead. DCQL queries
include two types, aggregate and distributed.

You can use the Query Builder tool to create both CQL and DCQL queries.

This section includes the following topics:

-   Building CQL Queries, below

-   Building DCQL Queries on page [54](#building-dcql-queries)

### Building CQL Queries {#building-cql-queries .unnumbered}

The **Query** tab \> **Query Builder** subtab provides a graphical
interface for building queries. Although you can use this tool without
knowing CQL, you can more easily use the tool if you understand CQL
concepts. You can learn more at
<http://www.cagrid.org/mwiki/index.php?title=Data_Services:CQL>.

To use the Query Builder subtab, you must first select the service and
URL as explained in Scenario 1: Starting without a URL or Query on page
[48](#scenario-1-starting-without-a-url-or-query). After you have
selected a UML class for the query, the Query Builder tab resembles
Figure 5-36.

![](media/image47.png){width="4.6194444444444445in"
height="2.2222222222222223in"}

[]{#__RefHeading___Toc222721116 .anchor}Figure 5‑36. Query Builder
subtab with selected UML class ArrayDesign

To modify and submit the query, follow these steps:

1.  Click **Edit Query Modifiers** to select one of the options
    described in\
    Table 5-5.

+----------------------+-----------------------------------------------+
| Option               | Description                                   |
+----------------------+-----------------------------------------------+
| Object               | Returns full results from the data service.   |
+----------------------+-----------------------------------------------+
| Count Only (the      | Returns only the count of objects that match  |
| default)             | specified criteria.                           |
+----------------------+-----------------------------------------------+
| Distinct Attribute   | Returns the unique value of one of the        |
|                      | following attributes of the UML class being   |
|                      | queried:                                      |
|                      |                                               |
|                      | -   clusterID                                 |
|                      |                                               |
|                      | -   fullName                                  |
|                      |                                               |
|                      | -   id                                        |
|                      |                                               |
|                      | -   symbol                                    |
|                      |                                               |
|                      | You can select only one of these attributes.  |
+----------------------+-----------------------------------------------+
| Selected Attributes  | Displays the same four attributes offered by  |
|                      | the Distinct Attribute option, but enables    |
|                      | you to select multiple attributes. If you     |
|                      | select this modifier, the results will        |
|                      | include only these attribute values for each  |
|                      | object in the result set.                     |
+----------------------+-----------------------------------------------+

Table 5‑5. Options for editing query modifiers

82. When you have finished editing modifiers, click **Update**.

The Result Type updates to show the selected attributes.

83. To add a criterion to the query, click **Add Criterion**.

The Query Builder subtab displays a list of attributes and associations
for the selected class, as shown in Figure 5-37.

![](media/image48.png){width="4.627777777777778in"
height="5.345833333333333in"}

[]{#__RefHeading___Toc222721117 .anchor}Figure 5‑37. Attributes and
associations for selected class

84. Select an attribute.

A form appears with the name of the selected attribute.

85. Set the predicate by selecting it from the drop-down list.

86. Enter a value.

The form should now resemble Figure 5-38.

![](media/image49.png){width="4.597916666666666in" height="2.40625in"}

[]{#__RefHeading___Toc222721118 .anchor}Figure 5‑38. Specifying a
predicate and value for a selected attribute

87. Click **Update**.

The Query Builder subtab should now resemble Figure 5-39.

![](media/image50.png){width="4.588888888888889in"
height="2.4680555555555554in"}

[]{#__RefHeading___Toc222721119 .anchor}Figure 5‑39. Query Builder
subtab with added criterion

Although you can add multiple criteria to a query, the Query Builder
does not currently support logical OR groupings other than for multiple
values specified for the same criterion. Currently, the tool groups all
criteria using a logical AND. If you specify multiple values for a
specific criterion, the tool creates multiple criteria and groups them
by OR. To further edit your query, you can export it to XML format.

**Note:** Once you export a CQL query to XML, you cannot edit the query
and then switch back to using the Query Builder tool.

88. (Optional) To export your query to XML format, follow these steps:

```{=html}
<!-- -->
```
a.  Click **Export to XML**.

The **Query XML** tab appears in front. The **URL** field displays the
service URL, and the **Query** field displays the XML structure for the
query.

g.  Edit the XML structure as needed.

![](media/image51.png){width="5.559027777777778in"
height="4.040277777777778in"}

[]{#__RefHeading___Toc222721120 .anchor}Figure 5‑40. Query XML tab

89. When you have finished building the query, click **Submit Query**.

The **History** tab appears in front. This tab displays the query State,
Start Time, Finish Time, and Service, as shown in Figure 5-41.

![](media/image52.png){width="5.125in" height="1.7916666666666667in"}

[]{#__RefHeading___Toc222721121 .anchor}Figure 5‑41. History tab with
query information

For more information about the History tab, see About the History Tab on
page [64](#about-the-history-tab).

### Building DCQL Queries {#building-dcql-queries .unnumbered}

caGrid supports federated queries through a infrastructure service
called the Federated Query Processor (FQP) and a language known as
Distributed caGrid Query Language (DCQL). FQP service supports the
execution of DCQL queries.

After you build DCQL queries using the Query Builder tool, the Portal
then asynchronously executes them against an available FQP service.

There are two types of DCQL queries that you can construct in the caGrid
Portal: aggregate and distributed. Aggregate queries aggregate similar
data from multiple services. Distributed queries have distributed joins
across multiple services on the grid.

The following sections explain how to create aggregate (below) and
distributed join queries using DCQL (on page
[57](#building-distributed-dcql-queries)).

#### Building Aggregate DCQL Queries {#building-aggregate-dcql-queries .unnumbered}

Aggregate queries run against two or more data services and return an
aggregated result set.

General steps for building an aggregate DCQL query in the caGrid Portal
are as follows:

1.  Discover caGrid Data Services providing a UML Class name.

```{=html}
<!-- -->
```
90. Constrain the query using some query criteria.

91. Determine possible aggregation scenarios.

92. Execute the aggregate query.

For example, an aggregate query might involve retrieving all
ArrayDesigns from the caArray data service hosted at Georgetown
University **and** the caArray data service hosted at NCICB.

To build this aggregate DCQL query, follow these steps:

1.  Select the service and URL for the query as explained in Scenario 1:
    Starting without a URL or Query on page
    [48](#scenario-1-starting-without-a-url-or-query).

![](media/image53.png){width="5.104166666666667in"
height="2.4270833333333335in"}

[]{#__RefHeading___Toc222721122 .anchor}Figure 5‑42. Query Builder
specifying a service and URL

93. Click **Aggregate Query**. All services with the chosen UML class,
    in this case ArrayDesign, appear.

![](media/image54.png){width="5.104166666666667in"
height="2.1666666666666665in"}

[]{#__RefHeading___Toc222721123 .anchor}Figure 5‑43. Services with the
same UML class to aggregate from

94. Select the checkboxes for all of the services from which to
    aggregate the chosen UML class.

95. Click **Add Targets**. A summary of the data services you selected
    for the aggregate query appears.

![](media/image55.png){width="4.597916666666666in" height="2.5in"}

[]{#__RefHeading___Toc222721124 .anchor}Figure 5‑44. Summary of data
services selected for aggregation

96. Click **Submit Query**. The **History** tab appears in front. As
    shown in Figure 5-45, this tab displays the query state, start time,
    finish time, and service. The service is in this case is the
    Federated Query Processor.

![](media/image56.png){width="5.09375in" height="1.4791666666666667in"}

[]{#__RefHeading___Toc222721125 .anchor}Figure 5‑45. History tab with
query information

For more information about the History tab, see About the History Tab on
page [64](#about-the-history-tab).

#### Building Distributed DCQL Queries {#building-distributed-dcql-queries .unnumbered}

Distributed queries link semantically equivalent domain objects across
multiple data services. You can construct DCQL queries manually and
execute them through a command line. The caGrid Portal helps in
visualizing the possible joins and then providing the tool to build DCQL
queries that contain cross-service joins.

The following text describes how the caGrid portal can be used to query
a grid service in a federated fashion. See
[here](http://gforge.nci.nih.gov/plugins/scmcvs/cvsweb.php/~checkout~/cagrid-1-0/Documentation/docs/portal/portal2/presentations/portal_movie_annual_meeting_2008.zip?rev=1.1;content-type=application%2Foctet-stream;cvsroot=cagrid-1-0)
for a video that covers most of the same information.

The steps involved are:

1.  Select a caGrid data service.

2.  Select a UML class from the selected data service to query on.

3.  Specify query criteria on the selected UML class by specifying join
    conditions based on a UML class from a second caGrid data service.

4.  Execute the distributed join query and view the results.

We can correlate data between services by doing a distributed join. For
example, we can retrieve all NucleicAcidSequence objects from the
caBIO32 grid service hosted at NCI/CBIIT where they are related to the
proteins that we retrieve from the GridPIR grid service hosted at
Georgetown University.

When building a query against the model of one service, the portal
automatically displays UML classes in other models if they have at least
on concept code in common. The service name next to the UML class name
indicates the source of the UML class. Classes that share a concept code
are most likely to also contain attributes that can be used as a join
condition.

To build this aggregate DCQL query, follow these steps:

1.  Select the service and URL for the query as explained in Scenario 1:
    Starting without a URL or Query on page
    [48](#scenario-1-starting-without-a-url-or-query).

![](media/image57.png){width="3.4715277777777778in"
height="3.161111111111111in"}

[]{#__RefHeading___Toc222721126 .anchor}Figure 5‑46. Query Builder
specifying a service and URL

2.  Select the **gov.nih.nci.cabio.domain.NucleicAcidSequence** class.

![](media/image58.png){width="3.7444444444444445in"
height="1.9013888888888888in"}

[]{#__RefHeading___Toc222721127 .anchor}Figure 5‑47 Query Builder tool
with selected NucleicAcidSequence class

3.  Click the **Add Criterion** button. All of the possible criteria
    (class attributes and associations) appear as shown in Figure 5-49.

![](media/image59.png){width="3.7444444444444445in"
height="2.982638888888889in"}

[]{#__RefHeading___Toc222721128 .anchor}Figure 5‑48 Tree view of
attributes and associations for the NucleicAcidSequence class

4.  Expand the **NucleicAcidSequence** class tree node by selecting the
    **geneCollection** association. Further expand the tree by selecting
    the **proteinCollection** association as shown in Figure 5-49.

![](media/image60.png){width="3.0569444444444445in"
height="4.002777777777778in"}

> []{#__RefHeading___Toc222721129 .anchor}Figure 5‑49 Query criterion
> tree view for caBIO NucleicAcidSequence class
>
> Hovering the mouse over any service name that is next to a UML class
> provides further information about the service.

![](media/image61.png){width="5.249305555555556in"
height="1.742361111111111in"}

> []{#__RefHeading___Toc222721130 .anchor}Figure 5‑50 Service
> information for semantically equivalent UML class

97. Select the Protein class from the **GridPIR** service. The Protein
    class belongs to an external service (**GridPIR**) and is considered
    a foreign association in DCQL.

98. Expand the "foreign" UML class node. The Join Condition dialog box
    appears.

99. Select the Local Attribute as uniProtCode and the Foreign Attribute
    as uniprotkbEntryName as shown in Figure 5-51.

![](media/image62.png){width="4.040277777777778in" height="2.70625in"}

> []{#__RefHeading___Toc222721131 .anchor}Figure 5‑51 Selecting the join
> condition

100. Expand the tree by selecting the **organismCollection** association
     tree node on the Protein class. Click the **scientficName**
     attribute of the Organism class. This lets you specify a value on
     the scientificName criterion for the Protein class as shown in
     Figure 5-52.

![](media/image63.png){width="3.7423611111111112in"
height="1.9902777777777778in"}

[]{#__RefHeading___Toc222721132 .anchor}Figure 5‑52 Entering criterion
value for Organism scientificName attribute

101. Repeat steps 3-5. Select the **geneCollection** association tree
     node on the Protein class from **GridPIR.** Click the **name**
     attribute and enter **brca1** for the criterion as shown in Figure
     5-53.

![](media/image64.png){width="3.870138888888889in"
height="2.0166666666666666in"}

[]{#__RefHeading___Toc222721133 .anchor}Figure 5‑53 Enter criterion
value for Gene name attribute

> The complete query is shown in Figure 5-54.

![](media/image65.png){width="4.498611111111111in"
height="2.984027777777778in"}

[]{#__RefHeading___Toc222721134 .anchor}Figure 5‑54 Complete federated
query for caBIO NucleicAcidSequence class

102. Click the **Export To XML** button. The DCQL query appears in XML
     format, as shown in Figure 5-55.

![](media/image66.png){width="4.127777777777778in"
height="2.9833333333333334in"}

[]{#__RefHeading___Toc222721135 .anchor}Figure 5‑55 XML federated query
for caBIO NucleicAcidSequence class

103. Click **Submit Query**. The query starts executing asynchronously.
     The **History** tab shows the running query as shown below.

![](media/image56.png){width="4.125694444444444in"
height="1.1979166666666667in"}

[]{#__RefHeading___Toc222721136 .anchor}Figure 5‑56 History Tab with the
running DCQL query

After the query completes, the State text field automatically updates
from *Running* to *Complete*.

104. In the Operations list, select **View Results**. The **Results**
     tab appears where you see the results of the distributed join query
     as shown in Figure 5-57.

![](media/image67.png){width="3.875in" height="3.1708333333333334in"}

[]{#__RefHeading___Toc222721137 .anchor}Figure 5‑57 Results of federated
query for caBIO NucleicAcidSequence class

## About the History Tab {#about-the-history-tab .unnumbered}

As noted in the last section, when you run a query from the Query
Builder or Query XML subtabs, the **History** tab becomes the active
tab. This tab displays information about all of the queries you have
executed.

If are a registered caGrid Portal user, the History list displays all
queries that you have executed since you registered. If you are not
registered, then you will see only queries that you have executed during
the current browser session. The most recent query appears first.

The History tab also includes an **Operations** list, which includes the
following operations:

-   **View Results** -- Displays the query results in the **Results**
    tab in tabular format as shown in Figure 5-58. The result list shows
    ten results at a time and includes buttons for browsing by page,
    skipping to the end of the list, or skipping to the beginning of the
    list. The **Export to Excel** link allows you to open or save the
    query in an Excel (\*.xls) workbook and the **Export to XML** link
    allows you to open or save the query in XML format.

![](media/image68.png){width="3.567361111111111in"
height="2.6354166666666665in"}

[]{#__RefHeading___Toc222721138 .anchor}Figure 5‑58. Results tab showing
query results

-   **Reload** -- Reloads the query into the **Query XML** subtab, where
    you can edit the query or run it again.

-   **Delete** -- Removes the query from the query history.

Table 5-6 describes the remaining information displayed on the History
tab.

  -----------------------------------------------------------------------
  Option                 Description
  ---------------------- ------------------------------------------------
  State                  The current state of the query. The next five
                         rows list each status and explain what
                         operations you can perform while each status is
                         in effect.

  RUNNING                Indicates that the query is still running. You
                         can cancel or delete the query.

  COMPLETE               Indicates that the query completed successfully.
                         You can view results, reload, or delete the
                         query.

  ERROR                  Indicates that the query failed. You can view
                         the error, reload the query, or delete the
                         query.

  CANCELED               Indicates that you canceled the query. You can
                         reload or delete the query

  TIMED OUT              Indicates that the system canceled the query.
                         You can reload or delete the query

  Start Time             The time that the query started running,
                         displayed in hours, minutes, and seconds.

  Finish Time            The time that the query finished running,
                         displayed in hours, minutes, and seconds.

  Service                The name of the target service.
  -----------------------------------------------------------------------

Table 5‑6. History tab information

## Working with Shared Queries {#working-with-shared-queries .unnumbered}

If you are currently logged in, you can share new or previously executed
queries with other caGrid Portal users. This section explains how to
share a query and how to search for shared queries.

**Note:** Only CQL queries can be shared. DCQL queries cannot be shared
at this time.

### Sharing a Query {#sharing-a-query .unnumbered}

To share a query, follow these steps:

1.  If you are not currently using the Data Service Query portlet, click
    the **Services** tab on the main navigation bar.

```{=html}
<!-- -->
```
105. To share a *new* query, follow these steps:

```{=html}
<!-- -->
```
a.  Build the query as explained in Building a Query Using the Query
    Builder Tool on page
    [50](#building-a-query-using-the-query-builder-tool).

```{=html}
<!-- -->
```
h.  Skip to step 4.

```{=html}
<!-- -->
```
106. To share a *previously executed* query, follow these steps:

```{=html}
<!-- -->
```
a.  Click the **History** tab.

```{=html}
<!-- -->
```
i.  Select the **Re-load** command from the **Operations** drop-down
    list.

j.  Continue to the next step.

```{=html}
<!-- -->
```
107. On the **Query** tab \> **Query Builder** or **Query XML** subtab,
     click **Share Query**.

The **Shared Queries** tab \> **My Queries** subtab becomes the active
tab.

108. Enter a name and description for the query using the **My Queries**
     form shown in Figure 5-59.

**Note:** The name and description are required.

![](media/image69.png){width="4.835416666666666in"
height="3.0458333333333334in"}

[]{#__RefHeading___Toc222721139 .anchor}Figure 5‑59. Form for adding a
query name and description

109. Click **Save**.

A message confirms that the shared query has been successfully saved.

110. Click the **\<\< To shared queries list** link.

The **Shared Queries** tab \> **My Queries** subtab becomes the active
tab. Your saved, shared query is summarized at the bottom of the form.

![](media/image70.png){width="4.631944444444445in"
height="1.8770833333333334in"}

[]{#__RefHeading___Toc222721140 .anchor}Figure 5‑60. Saved query

The query summary shows the following information:

-   A slightly different version of **Operations** drop-down list\
    (see step 8)

-   Name

-   Target Service

-   Target UML Class

-   Shared Date

111. (Optional) Select any of the following options from the
     **Operations** drop-down list:

-   **Edit** -- Returns to the **Shared Queries** tab \> **My Queries**
    subtab, where you can edit the query name and description.

-   **Load** -- Runs the query and displays the **Query** tab \> **Query
    XML** subtab.

-   **View** -- Activates the **Shared Queries** tab \> **My Queries**
    subtab and shows the query in XML format.

### Searching for a Shared Query {#searching-for-a-shared-query .unnumbered}

You can search for shared queries using a keyword search and selected
constraints, including the target service, target UML class, and query
creator.

To search for a shared query, follow these steps:

1.  If you are not currently using the Data Service Query portlet, click
    the **Services** tab on the main navigation bar.

```{=html}
<!-- -->
```
112. Click the **Shared Queries** tab.

113. Click the **Find** **Shared Queries** subtab.

![](media/image71.png){width="4.597916666666666in"
height="2.7152777777777777in"}

[]{#__RefHeading___Toc222721141 .anchor}Figure 5‑61. Shared Queries tab
\> Find Shared Queries subtab -- Search form

114. Enter one or more keywords in the **Keyword** field.

115. Select desired search constraints in the **Search Fields**
     selection box.

**Note:** If you do not select search fields, all of the fields are
included in the search.

116. Click **Search**.

The query results appear in a paginated list.

117. (Optional) To edit, load, or view a found query, select an option
     from the **Operations** list.

# Using the Community Portlet

Developers in the caBIG® community may create Java Specification Request
168 (JSR 168) compliant portlets and then deploy them to the caGrid
Portal. This chapter provides references to community developers who may
want to develop such a portlet.

Topics in this chapter include:

-   About JSR 168 and the Liferay Portal on this page

-   *Accessing the Community Portlet* on this page

-   *Deploying a Community Portet* on page
    [72](#deploying-a-community-portet)

## About JSR 168 and the Liferay Portal {#about-jsr-168-and-the-liferay-portal .unnumbered}

The Java Community Process (JCP), an open, international,
community-based organization, created the JSR 168 in 2003 to enable
interoperability between portlets and portals.

The caGrid Portal was built on the Liferay Portal, an open-source portal
designed to deploy portlets that adhere to JSR 168. The caGrid Portal
can therefore host any JSR 168 compliant portlet application.

For more information about JSR 168, see
<http://jcp.org/en/jsr/detail?id=168/>. For more information about
Liferay, see http://www.liferay.com/.

## Accessing the Community Portlet {#accessing-the-community-portlet .unnumbered}

You can access all available community portlets on the Community tab.

![](media/image72.png){width="5.791666666666667in"
height="2.520138888888889in"}

[]{#__RefHeading___Toc222721142 .anchor}Figure 6‑62. Community Portlet,
caBIO Portlet example

At this time, only one portlet has been deployed within caGrid. The
number of community portlets will expand over time.

Get online help for each community portlet by clicking the question mark
icon in the portlet window.

## Deploying a Community Portet {#deploying-a-community-portet .unnumbered}

More information about developing and deploying a JSR 168 portlet in the
caGrid Portal are available in the Community Portlet Guide at
http://www.cagrid.org/wiki/Portal:2.1:CommunityPortlets.

Before submitting your portlet to the caGrid team, be sure to test it
locally. Instructions for deploying a JSR 168 compliant portlet into a
local installation of caGrid Portal are located in the Community Portlet
Guide.

# Using Other Portal Features

The previous chapters covered the main caGrid Portal features used for
discovering and querying caGrid services, caBIG® participants, and
caGrid POCs. The portal includes other useful portlets: *News*, *caGrid
Links*, *caGrid Status*, and *Calendar*. This chapter provides an
overview of the portlets.

Topics in this chapter include:

-   Using the News Portlet on this page

-   Using the caGrid Status Portlet on page
    [76](#using-the-cagrid-status-portlet)

-   *About the Calendar Portlet* on page
    [78](#about-the-calendar-portlet)

## Using the News Portlet {#using-the-news-portlet .unnumbered}

The caGrid Portal gives you the latest caGrid-related news through an
RSS news feed. You can view the latest news on the portal site using two
links:

-   The **News** portlet on the home page

The portlet displays news headlines as links. The posting date and time,
as well as a portion of the text follow each headline from the article.
Clicking a link opens the News page, where you can read the full
article.

-   The **News** link on the main navigation bar

This link takes you directly to the News page, shown in Figure 7-64 on
page [75](#__RefHeading___Toc222721144).

![](media/image73.png){width="2.5520833333333335in" height="4.375in"}

[]{#__RefHeading___Toc222721143 .anchor}Figure 7‑63. News links

On the News page, the main article appears in the middle area of the
page. Other article links are listed in the **Other News** section at
the bottom of the page.

![](media/image74.png){width="5.25in" height="4.479166666666667in"}

[]{#__RefHeading___Toc222721144 .anchor}Figure 7‑64. News page

**Note:** You can subscribe to the portal news feed directly from your
browser or using any RSS 2.0-compliant news reader.

## About the caGrid Links Portlet {#about-the-cagrid-links-portlet .unnumbered}

The caGrid Links portlet includes links to the following sites:

-   The caGrid Portal User\'s Guide at
    <https://gforge.nci.nih.gov/plugins/scmcvs/cvsweb.php/~checkout~/cagrid-1-0/Documentation/docs/portal/portal2/guides/caGrid-Portal_2.0.2_UsersGuide.pdf?rev=HEAD;content-type=text%2Fplain;cvsroot=cagrid-1-0>
    is the latest version of this guide.

-   caGrid Portal Wiki Pages at
    <http://www.cagrid.org/mwiki/index.php?title=Portal:Portal>. caGrid
    developers maintain these pages and use them to document all of the
    features of the caGrid Portal.

-   The caBIG® Community Website at <https://caBIG.nci.nih.gov/>. This
    site provides a comprehensive overview of caBIG®.

-   The caGrid Website at
    <https://cabig.nci.nih.gov/workspaces/Architecture/caGrid>. This
    site provides an overview of the caGrid.

-   The caGrid Wiki at
    <http://www.cagrid.org/mwiki/index.php?title=CaGrid>. This site
    provides a collaborative environment for caGrid users.

## Using the caGrid Status Portlet {#using-the-cagrid-status-portlet .unnumbered}

The caGrid Status portlet provides a quick, visual description of the
scale and activity of caGrid.

As shown in Figure 7-65, the Status portlet is located on the right side
of the home page, just below the **Login** and **Register** links.

![](media/image75.png){width="1.7597222222222222in"
height="2.9131944444444446in"}

[]{#__RefHeading___Toc222721145 .anchor}Figure 7‑65. Status portlet

The following table explains the information that the portlet provides.

  ------------- ---------------------------------------------------------
  Status Item   Description

  Service links Click the links to the five most recently registered
                services. Links open the Services page where you can use
                the Discovery portlet to view details for a specific
                service or select from a list view.

  Service info  Hover your mouse over any service to quickly see the
  popup window  service\'s name, type, status, hosting center, hosting
                center URL, and secured status.

  Type icons    Icons that denote the service type. See Selecting a
                Service, Participant, or POC on page
                [19](#selecting-a-service-participant-or-poc) for a table
                explaining each icon.

  Counts        Up-to-date counts of all participants, services, data
                services, and analytical services.

  Timestamp     Indicates the last time at which the portal aggregated
                data from the index service.
  ------------- ---------------------------------------------------------

### Viewing Details for a Recently Registered Service or Participant {#viewing-details-for-a-recently-registered-service-or-participant .unnumbered}

The upper half of the Status portlet lists the five most recently
registered services or participants with an identifying icon to the
right of each listed item.

To view details for an item, click the name of the item. The Services
page appears with the **Details** tab and **Service** subtab of the
Discovery portlet selected. From there you can drill down to more detail
as discussed in Chapter 4, Using the Discovery Portlet, on page
[27](#using-the-discovery-portlet).

### Viewing a List of Participants or Services {#viewing-a-list-of-participants-or-services .unnumbered}

The lower half of the Status portlet shows current counts for caGrid
participants and services. Here you can view totals for all
participants, all services, all data services, and all analytical
services.

To view a list of services or participants, click the underlined number
preceding each item. The Services page appears with the **Directory**
tab and **List View** subtab of the Discovery portlet selected. The list
display varies according to whether you selected a participant or
service. You can select a list item and drill down to more detail as
discussed in Using the List View Subtab on page
[28](#using-the-list-view-subtab).

## About the Calendar Portlet {#about-the-calendar-portlet .unnumbered}

Appearing at the bottom of the caGrid Portal home page, the Calendar
portlet provides dates of important caGrid-related events. Figure 7-66
shows this portlet as it appears on the home page.

![](media/image76.png){width="5.416666666666667in"
height="2.9006944444444445in"}

[]{#__RefHeading___Toc222721146 .anchor}Figure 7‑66. Calendar portlet

You can change the view of the calendar by clicking the various tabs
described in Table 7-7.

  --------------- ---------------------------------------------------------
  Tab             Description

  Summary         Shows a calendar on the left and a list of events on the
                  right.

  Day             Shows events for the selected day and enables you to
                  browse forward or backward in one-day increments.

  Week            Shows a seven-day view starting with the selected day and
                  enables you to browse forward or backward in seven-day
                  increments.

  Month           Shows the current month as a full-sized calendar.

  Year            Shows a calendar for each day of the current year.

  Events          Shows a listing of events, including the date, time,
                  title, and type. Click the event title to view details
                  for the event.

  Export/Import   Enables you to import a file and add an event to your
                  calendar.
  --------------- ---------------------------------------------------------

Table 7‑7. Description of Calendar portlet tabs

# Using the caBIG® Tools Portlet

The caBIG® Tools portlet allows you to access the same inventory of
tools that are available on the [caBIG® Community
Website](https://cabig.nci.nih.gov/tools/toolsearch_view). This chapter
explains how to browse those tools.

Topics in this chapter include:

-   About the caBIG® Tools Portlet on this page

-   Sorting caBIG® Tools on page [82](#sorting-cabig-tools)

-   Viewing caBIG® Tool Details on page [64](#about-the-history-tab)

## About the caBIG® Tools Portlet {#about-the-cabig-tools-portlet .unnumbered}

To expedite the cancer research community\'s access to key
bioinformatics tools, platforms, and data, the caBIG® Community Website
(<https://cabig.nci.nih.gov/inventory>) lists applications (tools) and
their documentation, as well as infrastructure and datasets used to
support the caBIG^®^ initiative. The inventory is updated as new items
are released.

The caGrid Portal provides another entry point into the tools component
of that inventory. When you click the caGrid **Tools** tab, the most
current list of caBIG® tools appears.

The caBIG® tools inventory includes over 40 software tools, database
technologies, and Web-based applications in the areas of clinical trials
management, biospecimens, imaging, genome annotation, proteomics,
microarrays, pathways, data analysis and statistical tools, data
sharing, infrastructure, vocabularies, and translational research. They
are based on open-source software and free. Download packages include
installation elements and documentation. In many cases training is also
offered.

As on the caBIG® website, caGrid users can search for these tools based
on name, compatibility level, keyword, area of focus, workspace, and
technical specifications.

The features of the caGrid Tools portlet are illustrated in Figure 8-67.

![](media/image77.png){width="6.197222222222222in"
height="4.8284722222222225in"}

[]{#__RefHeading___Toc222721147 .anchor}Figure 8‑67.Tools portlet

## Sorting caBIG® Tools {#sorting-cabig-tools .unnumbered}

While the caBIG® tools are sorted alphabetically by title by default,
you can change the sort order to more easily find and understand each
tool.

To sort caBIG® tools, follow these steps:

1.  If you are not currently using the Tools portlet, click the
    **Tools** tab on the main navigation bar. The Tools page appears.

```{=html}
<!-- -->
```
118. Click one of the sort headers at the top of the page. See Table 8-8
     for a description of each header.

The tools in the list are sorted by the selected header. The sort header
currently in effect is highlighted in red.

![](media/image78.png){width="5.776388888888889in"
height="2.0097222222222224in"}

[]{#__RefHeading___Toc222721148 .anchor}Figure 8‑68. caBIG® tools sorted
by Area of Focus

The following table explains each of the sort headers available in the
caBIG® Tools portlet.

+------------+---------------------------------------------------------+
| Sort       | Description                                             |
| Header     |                                                         |
+============+=========================================================+
| Title      | This is the name of the tool as chosen by the           |
|            | development team and the caBIG® Workspace who fostered  |
|            | the development. Tool titles are sorted alphabetically. |
+------------+---------------------------------------------------------+
| Area of    | The Area of Focus is the primary domain-specific        |
| Focus      | audience or technical area that the tool serves. Only   |
|            | one area is specified from the following choices:       |
|            |                                                         |
|            | -   Biospecimens                                        |
|            |                                                         |
|            | -   Data Analysis and Statistical Tools                 |
|            |                                                         |
|            | -   Clinical Trials Management                          |
|            |                                                         |
|            | -   Genome Annotation                                   |
|            |                                                         |
|            | -   Data Sharing                                        |
|            |                                                         |
|            | -   Infrastructure                                      |
|            |                                                         |
|            | -   Imaging                                             |
|            |                                                         |
|            | -   Pathways                                            |
|            |                                                         |
|            | -   Microarrays                                         |
|            |                                                         |
|            | -   Translational Research                              |
|            |                                                         |
|            | -   Proteomics                                          |
|            |                                                         |
|            | -   Other                                               |
|            |                                                         |
|            | -   Vocabularies                                        |
+------------+---------------------------------------------------------+
| Primary    | The caBIG® Workspace where the tool was originally      |
| Workspace  | developed and maintained. Only one area is specified    |
|            | from the following choices:                             |
|            |                                                         |
|            | -   ARCH (Architecture Workspace)                       |
|            |                                                         |
|            | -   CTMS (Clinical Trials Management Systems Workspace) |
|            |                                                         |
|            | -   DSIC (Data Sharing and Intellectual Capital         |
|            |     Workspace)                                          |
|            |                                                         |
|            | -   DT (Documentation and Training Workspace)           |
|            |                                                         |
|            | -   ICR (Integrative Cancer Research Workspace)         |
|            |                                                         |
|            | -   IMAG (Imaging Workspace)                            |
|            |                                                         |
|            | -   SP (Strategic Planning Workspace)                   |
|            |                                                         |
|            | -   TBPT (Tissue Banks and Pathology Tools Workspace)   |
|            |                                                         |
|            | -   VCDE (Vocabulary and Common Data Elements           |
|            |     Workspace)                                          |
+------------+---------------------------------------------------------+
| Maturity   | Developers of the tool are required to assign a         |
| Level      | maturity level assessment to the version of the tool.   |
|            | The tool maturity level must be classified as one of    |
|            | the following:                                          |
|            |                                                         |
|            | -   Development Phase                                   |
|            |                                                         |
|            | -   Beta-Test or Pilot Release Available (Pre-Adoption) |
|            |                                                         |
|            | -   Stable Release (Adoption in Progress)               |
|            |                                                         |
|            | -   Mature Product (Successfully Adopted)               |
+------------+---------------------------------------------------------+
| Com        | To aid in the creation of software that will be able to |
| patibility | interoperate within the caBIG® program, a set of        |
| Level      | compatibility guidelines was developed that spells out  |
|            | requirements for interoperability in areas of Interface |
|            | Integration, Vocabularies/Terminologies and Ontologies, |
|            | Information Models and Data Elements. Systems that meet |
|            | the requirements are said to be caBIG® Compatible       |
|            |                                                         |
|            | The levels of compatibility are:                        |
|            |                                                         |
|            | -   Gold Level Compatibility                            |
|            |                                                         |
|            | -   Silver Level Compatibility                          |
|            |                                                         |
|            | -   Bronze Level Certification                          |
|            |                                                         |
|            | -   Legacy                                              |
|            |                                                         |
|            | Learn more about compatibility at                       |
|            | <https://cabig.nci.nih.gov/guidelines_documentation>.   |
+------------+---------------------------------------------------------+
| caGrid     | caGrid is the distributed infrastructure built upon     |
| Enabled    | established standards and technologies that provides    |
|            | the concrete implementation for this interoperability   |
|            | to happen seamlessly. When systems are built following  |
|            | the caGrid specifications, these systems are able to    |
|            | discover, access and use other similarly built services |
|            | programmatically. These software systems are then       |
|            | called \"caBIG® Grid Enabled\".                         |
|            |                                                         |
|            | In terms of compatibility guidelines, \"caBIG® Grid     |
|            | Enabled\" applications would become the \"Gold\"        |
|            | compatible systems once the caBIG® Cross cutting work   |
|            | spaces start performing \"Gold\" compatibility reviews. |
+------------+---------------------------------------------------------+
| In         | -   Basic - Wizard or web browser application; minimal  |
| stallation |     technical assistance required                       |
| Level      |                                                         |
|            | -   Intermediate - technical assistance may be          |
|            |     required, download may require supporting           |
|            |     infrastructure or software                          |
|            |                                                         |
|            | -   Advanced - technical team required for installation |
+------------+---------------------------------------------------------+

Table 8‑8. Sort header options

## Viewing caBIG® Tool Details {#viewing-cabig-tool-details .unnumbered}

Click any tool in the list to view details about that tool. Details
about each tool are structured similarly and include the following
information next to the tool logo:

-   Product Summary

-   Demo Files & Exercises

-   Documentation & Training

-   Tool Download Files

-   End User Support Resources

-   Related caBIG® Tools.

-   Developer Institution(s) & Adopter Institution(s)

-   Related Articles

Figure 8-69 shows the home page for one caBIG® tool.

![](media/image79.png){width="6.191666666666666in"
height="3.6131944444444444in"}

[]{#__RefHeading___Toc222721149 .anchor}Figure 8‑69. caBIG® tool details

[]{#__RefHeading___Toc222721080 .anchor}Index

A

analytical service

selecting (Map portlet), 21

viewing details for, 40

C

caBIG® tools

sorting, 82

viewing details, 85

caBIG® Tools portlet, 81

Calendar portlet, about, 8, 78

Categories list (Map portlet), 18

Community portlet, about, 71

D

data service

query, about, 6

selecting (Map portlet), 19

viewing details for, 39

Data Service Query Portlet, about, 47

DCQL queries

aggregate, 55

building, 55

distributed, 57

Details tab

Participant subtab, 42

POC subtab, 43

Service subtab, 39

details, viewing

for caBIG® tools, 85

for data service, 39

for new participant, 77

for participant, 42

for POC, 43

diagnostics, service, 43

Directory tab

List View subtab, 28

Map View subtab, 31

Discovery portlet, about, 27

discovery, about, 4--5

E

events. *See* Calendar portlet

H

History tab, about, 65

home page, about, 9

hosting research center, selecting (Map portlet), 24

I

icons for Map portlet, 19

J

JSR 168, 71

L

Links portlet, about, 75

List View subtab, using, 28

logging in

as NIH user, 16

as registered user, 14

M

Map portlet

about, 17

analytical service, selecting, 21

Categories list, 18

data service, selecting, 19

hosting research center, selecting, 24

icons for, 19

participant institute, selecting, 22

POC, selecting, 25

Map View, using, 31

metadata

for analytical service, 40

for data service, 39

for participant, 42

for POC, 43

for services, 5

N

News portlet, about, 8, 73

P

participant

searching for, 36

viewing details for, 42

participant institute, selecting (Map portlet), 22

POC

searching for, 37

selecting (Map portlet), 25

viewing details for, 43

portlet

Calendar, 78

Community, 71

Data Service Query, 47

Discovery, 27

Links, 75

Map, 17

News, 73

Status, 76

Tools, 81

Q

query

building, 50

building a CQL, 50

building a distributed DCQL, 57

building an aggregate DCQL, 55

for data service, 6

portlet overview, 47

scenarios for building, 48

shared, searching for, 69

sharing

about, 6

procedure for, 67

R

registration

about, 11

procedure for, 12

technical details for, 7

S

Search tab

Participant subtab, 36

POC subtab, 37

Services subtab, 32

searching

for participant, 36

for POC, 37

for service, 32

for shared query, 69

service

analytical, viewing details for, 40

data, viewing details for, 39

searching for, 32

viewing details for, 39

service diagnostics, 43

Status portlet

about, 8

using, 76

W

Welcome menu, about, 16