Secure Data Connector (Deprecated)

Secure Data Connector Developer's Guide Tutorial: Google Visualization

This guide helps you write gadgets that visualize data from a private network. Using the Google Visualization API with Secure Data Connector (SDC) enables you to use existing gadgets to visualize data from your private network, or alternatively enables you to create customized gadgets for users of your network.

Note: Only visualization gadgets within Google Sites can only make use of the SDC. For information on creating a gadget in Google Sites, see Secure Data Connector Developer's Guide Tutorial: Gadgets.

Contents

  1. Google Visualization API
    1. Visualization Gadgets
  2. Accessing Private Data
    1. Using Public Gadgets
    2. Writing Customized Private Gadgets
  3. Accessing Private Data
  4. Example Gadget

What is the Google Visualization API?

The Google Visualization API lets you access multiple sources of structured data that you can display, choosing from a large selection of visualizations. Google Visualization API enables you to expose data stored on a data-store that is connected to the web, as a visualization-compliant datasource. Thus you can create reports and dashboards as well as analyze and display your data through the wealth of available visualization applications.

Visualization Gadgets

A visualization gadget is a gadget that uses the Google Visualization API to display data. The Google Visualization API provides methods to simplify data source access to support simple and interactive gadgets that update in real time when source data is modified. Using SDC, visualization gadgets can display public data or data that is available on your private network. Visualization gadgets usually provide a gadget preference called Get query data source url. This selection defines the unique URL of the visualization-compliant data source that the gadget uses. When creating a customized gadget, you can hide the data source url in the gadget code instead of exposing a preference that users can edit. The Google Visualization API provides methods to simplify data source access. These methods support simple and interactive gadgets that can update after modifying the data source data.

Back to top

Accessing Private Data

When the data you wish to visualize resides in your private network, visualization gadgets can access the data using the gadgets.io.makeRequest API and SDC.

When visualizing data that is accessible only on your private network, you can use a publicly available gadget that you configure to display data from your private network, or create a custom gadget. In both cases your data is secure and users can access the gadget normally. The advantage of a custom gadget is meeting user needs versus a public gadget that may be more generic.

Using Publicly Available Gadgets

You can adapt any available Google gadget to display private data using gadgets.io.makeRequest and SDC. The following example shows how to add a bar chart visualization gadget and adjust it to display private data.

  1. Log in to your Google Sites domain. Create a new page or edit an existing page.
  2. Click Insert > Gadgets > More as shown in the following illustration:



  3. Click Add gadget by URL:



  4. Enter the URL of the gadget. For this example, Google provides an XML definition for a bar chart gadget at http://www.google.com/ig/modules/bar-chart.xml. To find other public gadgets, see the Google Visualization API Gadget Gallery.
    Click Add.

  5. The Setup your gadget properties window appears. Customize the gadget's properties:



  6. For the Data source URL field, enter a URL that is accessible by SDC from your private network.

    Append tqrt=makerequest to the end of the Data source URL that you specify to indicate to Google Apps that you want to use makeRequest and SDC to access private data.

    Adding the tqrt=makerequest parameter to the data source URL creates an implicit makeRequest query with the following parameters:

    params['OAUTH_ENABLE_PRIVATE_NETWORK'] = 'true';
    params['OAUTH_ADD_EMAIL'] = 'true';
    params[gadgets.io.RequestParameters.AUTHORIZATION] = gadgets.io.AuthorizationType.SIGNED;
    params[gadgets.io.RequestParameters.CONTENT_TYPE] = gadgets.io.ContentType.Text;
    

  7. The other parameters are specific for the bar chart gadget. You may leave them empty and use the default settings.
    Click OK to view the visualization.

In the example we used a general purpose gadget to visualize private data. This gadget allows the user to configure the data source via the Data source url parameter. We added a parameter to the URL to indicate the use of makerequest. Not all gadgets allow that flexibility, as they might access data through a non-configurable URL. In these cases you may need to write a customized gadget to access data on your internal network.

Writing Customized Private Gadgets

For more information on visualization gadgets see Creating Visualization Gadgets.

The Google Visualization API provides a layer for gadgets to communicate with data sources residing on the private network. Accessing data is done using gadgets.io.makeRequest or through the visualization.Query API, which wraps the gadgets.io.makeRequest API. Public gadgets normally use the visualization.Query API to fetch data from the data source url that a user specifies. If you are writing a new gadget for your private network, you can use the visualization.Query API with its explicit makeRequest method, or use the gadgets.io.makeRequest API.

Writing gadgets for use with makeRequest and SDC is almost identical to writing public gadgets. The only difference is accessing the data. For a public gadget, you create a query object and use the send method to fetch the data source data. The send method takes the name of your response listener, as follows:

function sendQuery() {
  // Create and send the query
  gadgetHelper = new google.visualization.GadgetHelper();
  var query = gadgetHelper.createQueryFromPrefs(prefs);

  // Send the query with a callback function
  query.send(handleQueryResponse);
}

For a private gadget that accesses resources through makeRequest and SDC, you should use the query.makeRequest() method:

function sendQuery() {
  // Create and send the query.
  gadgetHelper = new google.visualization.GadgetHelper();
  var query = gadgetHelper.createQueryFromPrefs(prefs);

  // Send the query with a callback function
  query.makeRequest(handleQueryResponse);
}

You can also specify additional parameters to the makeRequest call. Look at the Query API.

Note: If you use the send method and append a tqrt=makerequest parameter to the end of the data source URL, the call actually issues a query.makeRequest call to the same URL. This is convenient if you cannot edit the gadget's source code.

Example Gadget

The following is an example gadget XML file that uses a bar chart visualization to visualize data from a public text file. The text file is used as data source and returns a data table containing four columns, the first of type Text and the other columns are of type Number. The data displays as an image bar chart visualization.

<?xml version="1.0" encoding="UTF-8"?>
<Module>
  <ModulePrefs
      title="Sample Gadget for SDC">
    <Require feature="settitle" />
    <Require feature="idi" />
    <Require feature="locked-domain" />
  </ModulePrefs>

  <Content type="html"><![CDATA[
  <div id="loading"><img src="http://www.google.com/ig/images/spinner.gif" /></div>
  <div id="chart"></div>

  <script src="http://www.google.com/jsapi" type="text/javascript"></script>

  <script type="text/javascript">
    _IG_RegisterOnloadHandler(loadVisualizationAPI);

    // Loads the Visualization API
    function loadVisualizationAPI() {
      google.load('visualization', '1', {packages: ['imagebarchart']});
      google.setOnLoadCallback(initialize);
    };

    // Sends query
    function initialize() {
      var query =
        new google.visualization.Query("http://code.google.com/securedataconnector/docs/tutorials/planets.txt");
      query.send(responseHandler);
    };

    function responseHandler(response) {
      document.getElementById('loading').style.display = 'none';

      var container = document.getElementById('chart');
      var visualizationObject =
          new google.visualization.ImageBarChart(container);
      var dataTable = response.getDataTable();

      var options = {
        width: document.body.clientWidth,
        height: document.body.clientHeight
      };

      visualizationObject.draw(dataTable, options);
    };
  </script>

  ]]>
  </Content>
</Module>

To summarize this example by using this gadget. We will now add this gadget to our site page, and modify it to use private data.
  1. Log in to your Google Sites domain. Create a new page or edit an existing page.
  2. Click Insert > Gadgets > More.
  3. Click Add gadget by URL:
  4. Enter the URL of the gadget: http://code.google.com/securedataconnector/docs/tutorials/sample_visualization.xml
  5. Notice that there are no parameters required except the width and height of the gadget.
    Enter the required size and click OK to add the gadget to the page.
  6. The following gadget appears:

Modifying the Gadget to Access Data on Private Network

Note: This section assumes you have Installed the SDC. If SDC is not currently installed, you should complete that activity before returning to this tutorial to complete the remaining sections.

To modify the gadget to access data on your private network, change the query URL to point to an internal data source. Take the datasource from the previous example and save the file to your internal network as planets.txt.

Make the URL visible to the gadget by specifying the text file URL in the resourceRules.xml file that accompanies the SDC. Specify your user name so that you can access the CSV file. For example, to enable access to user Polly Hedra for the URL at the corp.example.com server, create a resourceRules.xml file as follows (or add the <rule> code block to the existing resourceRules.xml file).

<resourceRules>
  <rule repeatable="true">
    <ruleNum>1</ruleNum>
    <agentId>all</agentId>
    <viewerEmail repeatable="true">pollyhedra@example.com</viewerEmail>
    <url>http://www.example.com/contacts.csv</url>
    <apps>
      <service>Gadget</service>
      <appId>http://code.google.com/securedataconnector/docs/tutorials/sample_visualization.xml</appId>
    </apps>
  </rule>
</resourceRules>

For more information on the resourceRules.xml file and starting or restarting SDC, see Configuring.

If you want to implement your own internal data source, see the Google Visualization API document, Implementing a Data Source.

Continuing with the example, modify the following code segment:

    // Sends query
    function initialize() {
      var query =
        new google.visualization.Query("http://code.google.com/securedataconnector/docs/tutorials/planets.txt");
      query.send(responseHandler);
    };
With this:
    // Sends query
    function initialize() {
      var query = new google.visualization.Query("http://www.corp.example.com/planets.txt");
      query.makeRequest(responseHandler);
    };

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.