Secure Data Connector (Deprecated)

Secure Data Connector Developer's Guide Tutorial: Gadgets

With the Secure Data Connector (SDC), users in your Google Apps can use gadgets that provide access to data from within your domain.

Note: Only gadgets within Google Sites can only make use of the SDC.

Contents

  1. Accessing Public Data
    1. Start Google Sites
    2. Start Creating the Gadget Specification
    3. Add a Function to Access Public Data
    4. Add a Function to Display the Data
    5. Check The Completed Gadget Specification
    6. List Your Gadget in Domain Directory Manager
    7. Add Your Gadget to a Google Sites Page
  2. Accessing Private Data
    1. Providing Private Data Access
      1. Download and Host the CSV File
    2. Modify the Gadget to Access Private Data
    3. Ensure that the Gadget Works

Accessing Public Data

This tutorial enables you to create a gadget that reads a comma-separated value (CSV) file and displays the results. CSV files that you use as input are made available on a network from a web server such as Apache Tomcat. The first part of this tutorial uses a public CSV file that Google provides. In the second part, you use a private data file that you need to copy the CSV file to a server on your network. Private data means data that resides behind a firewall and is accessed with a URL from a web server in your intranet.

Start Google Sites

To start developing your gadget:

  1. Start Google Sites for your domain and create a new page, such as http://sites.google.com/a/Your_Site_Domain -- Substitute your company's domain name for Your_Site_Domain, for example:
    http://sites.google.com/a/example.com/
    
  2. Specify a page name and indicate the page type as Start Page, which lets you expand the size of the gadget editor to be as wide as the page, which you can set in Step 6. When you create other pages on your site, you can also use the Web Page type, but you have to specify the exact width and height of the gadget.
  3. Click the Add personal gadgets heading or in the Gadgets in this area are only visible to you dashed area. The Select a gadget window opens.
  4. Click Add gadget by URL and enter the following URL for the Google Private Gadget Editor:
    http://google-feedserver.googlecode.com/svn/trunk/resources/gadgets/private-gadget-editor/spec.xml

    The Private Gadget Editor gadget appears.

  5. Note: The Private Gadget Editor is only supported in Firefox. If you don't have access to firefox, you can follow the instructions here to save private gadgets from the command line.

  6. Repeat Steps 3 and 4, except this time add the Directory Manager Gadget:
    http://google-feedserver.googlecode.com/svn/trunk/resources/gadgets/domain-gadget-directory-manager/spec.xml
    
  7. In each gadget's title bar, click the third button to expand the column width for the gadget to create a single column on the page.

Start Creating the Gadget Specification

To start creating the gadget specification (XML gadget code is referred to as a specification):

  1. Add the following lines to the Private Gadget Editor:

    <?xml version="1.0" encoding="UTF-8" ?>
    <Module>
      <ModulePrefs title="Sample Enterprise Gadget" author="Your_Name" category="Finance"
       thumbnail="http://code.google.com/securedataconnector/docs/tutorials/palmtrees.png" />
      <Content type="html">
        <![CDATA[
        <a href="javascript:getData()">Get Public Data</a>
        <script type="text/javascript">
    

    The first statements define the XML specification. The Content statement indicates that HTML content follows.

    The ModulePrefs statement indicates information about a gadget. Change Your_Name to your Google Apps account name. You can also change the category to another name if you want--for this tutorial, leave it as Finance. The category name makes more sense when we discuss the Google Domain Directory Manager. The thumbnail is a publicly-served picture of palm trees that you can use to identify your gadget in the list of gadgets in Google Sites. We discuss this later in the tutorial as well.

    The <a href anchor statement calls the getData function that we add in the next section.

    The script element introduces the JavaScript code that follows.

  2. Click Save and name the gadget as mygadget.xml.

Add a Function to Access Public Data

The getData function reads the public contacts.csv CSV file.

Add the following lines to your XML file:

function getData() {
  var params = {};
  params[gadgets.io.RequestParameters.CONTENT_TYPE] = gadgets.io.ContentType.TEXT;
  var url = "http://code.google.com/securedataconnector/docs/tutorials/contacts.csv";
  gadgets.io.makeRequest(url, function(response){log(response);}, params);
}

The first function, getData requests parameters from Google Gadgets, specifying that the content to request is text.

The var url statement provides a variable that indicates the location of the CSV file. The makeRequest call requests the CSV file through Google Gadgets.

Add a Function to Display the Data

Add the following lines to your XML file:

function log(m) {
  if (m && m.data) {
    alert(m.data);
  } else {
    alert(m);
  }
};

The log function displays the contents of the CSV file in a popup window as an alert.

Add the remaining statements to complete the gadget:

</script>
    ]]>
  </Content>
</Module>

Save your file.

Check the Completed Gadget Specification

The completed gadget specification appears as follows:

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Sample Enterprise Gadget" author="Your_Name" category="Finance"
   thumbnail="http://code.google.com/securedataconnector/docs/tutorials/palmtrees.png" />
  <Content type="html">
<![CDATA[
    <a href="javascript:getData()">Get Public Data</a>
    <script type="text/javascript">
function getData() {
  var params = {};
  params[gadgets.io.RequestParameters.CONTENT_TYPE] = gadgets.io.ContentType.TEXT;
  var url = "http://code.google.com/securedataconnector/docs/tutorials/contacts.csv";
  gadgets.io.makeRequest(url, function(response){log(response);}, params);
}
function log(m) {
  if (m && m.data) {
    alert(m.data);
  } else {
    alert(m);
  }
};
</script>
    ]]>
  </Content>
</Module>

Save your file.

List Your Gadget in Domain Directory Manager

After you complete your gadget and visually verify that the code is correct, you can make your gadget available to Google Sites using the Domain Directory Manager (DDM). DDM adds gadgets to the private directory for users in your domain.

The way enterprise gadgets become usable is that you create the gadget in Private Gadget Editor and then make them visible using DDM. Make sure you've followed the instructions above to install the DDM. In the DDM:

  1. Click the Private Directories tab and locate the gadget you created.
  2. Click Publish. The gadget name then turns bold.
  3. You can leave your Google Sites open for the next section of this tutorial.

Add Your Gadget to a Google Sites Page

To add your gadget to Google Sites page:

  1. If you are still viewing the Domain Directory Manager, click Add personal gadgets. Otherwise, start Google Sites and click Create new page, create and name another Start Page, and when that page opens click Add personal gadgets. The Select a gadget window opens.
  2. In the left column of the window, locate the domain name of your Google Apps. Click the Finance category. (This is the category that you specified in the ModulePrefs statement's category attribute at the start of your gadget specification.)
  3. Locate your gadget by the palm trees picture, select the gadget, and click Add.
  4. Your gadget then appears on the page in its own box. The gadget appears with a link for Get Public Data. Click the link to view the data from the contacts.csv CSV file.
    The data appears in an alert message as follows:

    Gadget displays the CSV file data in an alert popup
  5. This completes the first part of this tutorial. You can now exit Google Sites or return to the Private Gadget Editor, make changes, and go to DDM to unpublish and republish your gadget to pick up the new changes.

Now that you have successfully completed your gadget, you can use other CSV data that you serve from your web server. You can also use a Google Docs Spreadsheet to enter test data and export the data as a CSV file that you can save in your local domain.

Accessing Private Data

The sections that follow explain what statements to add so that you can use your working gadget from the last section to now access a CSV file available on your web server.

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.

Providing Private Data Access

The sections that follow help you install the SDC and download the Google public contacts.csv file that you need to host on your site.

Download and Host the CSV File

Download the contacts.csv file.

Put the CSV file on a web server in your domain. The URL of the web server needs to be specific to your company.

Create a rule in resourceRules.xml for the location and access of the CSV file (or add the <rule> code block to the existing resourceRules.xml file). See Configuring for more information. For example, if Polly Hedra wants to access the CSV file, specify the following resource rule:

<resourceRules>
  <rule repeatable="true">
    <ruleNum>1</ruleNum>
    <agentId>sdc42-agent</agentId>
    <viewerEmail repeatable="true">pollyhedra@example.com</viewerEmail>
    <url>http://corp.example.com/unitteststatus.html</url>
    <urlMatch>URLEXACT</urlMatch>
    <apps>
      <service>Gadgets</service>
      <appId>http://feedserver-enterprise.googleusercontent.com/a/example.com/g/PrivateGadgetSpec/mygadget.xml</appId>
    </apps>
  </rule>
</resourceRules>

SDC uses resource rules to limit which users can access which corporate resources. The <resourceRules> element defines a source of information that is made available from a web server. The <rule> element defines what resources or applications that a Google App can access. This rule states that this is the first resource rule to be processed (by the <ruleNum>1 statement), that Polly Hedra may access the contacts.csv file at example.com (<url> statement).

Modify the Gadget to Access Private Data

To access private data, you need to replace the var url statement in your gadget so that the gadget requests authorization for accessing your internal network and then accesses the URL of the file on your organization's web server. When you use a gadget that accesses authenticated internal data, you will need to decode the makeRequest function and verify that the user is authorized to access the data. For more information and sample code see the OpenSocial guide for validating signed requests.

Remove the previous var url statement:

var url = "http://code.google.com/securedataconnector/docs/tutorials/contacts.csv";

Add these statements in the place of the var url statement that you just removed:

params['AUTHORIZATION'] = 'SIGNED'
params['OAUTH_ADD_EMAIL'] = 'true'
params['OAUTH_ENABLE_PRIVATE_NETWORK'] = 'true'
var url = "YOUR_URL";

Substitute YOUR_URL with the URL for the CSV file in your domain.

The params statement provides information for the makeRequest function to request the example Google feed source. The OAUTH_ADD_EMAIL object will include the current user's email address in the request. This is useful for authenticating with internal systems. The AUTHORIZATION object specifies the type of authentication to use for fetching content. In this case, the request is signed by the gadget container.

The completed gadget should appear as follows:

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Sample Enterprise Gadget" author="Your_Name" category="Finance"
   thumbnail="http://code.google.com/securedataconnector/docs/tutorials/palmtrees.png" />
  <Content type="html">
<![CDATA[
    <a href="javascript:getData()">Get Private Data</a>
    <script type="text/javascript">
function getData() {
  var params = {};
  params[gadgets.io.RequestParameters.CONTENT_TYPE] = gadgets.io.ContentType.TEXT;
  params['AUTHORIZATION'] = 'SIGNED';
  params['OAUTH_ADD_EMAIL'] = 'true'
  params['OAUTH_ENABLE_PRIVATE_NETWORK'] = 'true'
  var url = "YOUR_URL";
  gadgets.io.makeRequest(url, function(response){log(response);}, params);
}
function log(m) {
  if (m && m.data) {
    alert(m.data);
  } else {
    alert(m);
  }
};
</script>
    ]]>
  </Content>
</Module>

Save your file.

Ensure that the Gadget Works

As described in the earlier sections of this tutorial, return to Google Sites, use the Private Gadget Editor to make the changes to your gadget, add the gadget to the Domain Directory Manager, and put your gadget on a Google Sites page and test it. Note that the link in this gadget states, Get Private Data.

When you again see the following alert statement, the SDC is ready to use and you can now create gadgets for use by your domain users.

Gadget displays the CSV file data in an alert popup

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.