Private Gadget Administrator's Guide

This guide provides information for administrators to use the Feed Server private gadget administrative tools: Feed Server Client Tool, the Private Gadget Editor, and the Domain Gadget Directory Manager. In addition, this guide describes the schemas for hosted feeds. Hosted feeds are provided by Google Apps.

The primary use for these tools is to support Google Gadget features for Google Apps for Your Domain Premier Edition and Education Edition. Open source software distribution for these products is available in either binary or source for use with Linux or Windows. The binary software distribution zip file is available on the Downloads tab of this site. Source code is available on the Source tab in the svn/trunk/resources folder.

Contents

• Overview
• Feed Server Client Tool
• FSCT Requirements
• FSCT Tasks
• Installing and Configuring FSCT
• FSCT Commands
• Troubleshooting FSCT
• Bad Request
• Gadget Already Exists
• Gadget Specified Could Not Be Fetched
• Invalid Credentials
• Not Found Exception
• Unauthorized Exception
• Using FSCT to Manage Private Gadgets
• Add a Private Gadget
• View Private Gadget Entry
• View All Gadgets
• Update a Private Gadget
• Delete a Private Gadget
• Publish a Private Gadget to the Private Directory
• Unpublish a Gadget
• Create a Private Gadget Category
• Delete a Private Gadget Category
• Using FSCT to Manage Feed Access
• Using High Level Tool
• For Per Domain Feeds
• For Per User Feeds
• General Command Syntax
• Using Low Level Tool
• Schemas of Hosted Feeds
• Private Gadget Editor
• Domain Gadget Directory Manager
• Add the DGDM Gadget to Google Sites
• Using DGDM

Overview

Private Gadgets are XML files that you can use with Google Sites and the Google Visualization API to display information. The google-feedserver site provides the following tools for administering private gadgets:

• Feed Server Client Tool (FSCT). Provides a set of Linux shell or Windows batch commands that you can run from the command line to retrieve or modify feeds. Use of the FSCT commands requires that you have previously installed the Java runtime environment, which is available from Java.Sun.com.
• Private Gadget Editor (PGE). You can use the PGE gadget to create private Google Gadgets that are accessible to your own domain.
• Domain Gadget Directory Manager (DGDM). You can use DGDM gadget to manage where gadgets appear in your domain's gadget directories.

This guide assumes an understanding of XML, Google Gadgets, and how to install a Java runtime environment to run Java programs from either a Linux or Windows command line.

Feed Server Client Tool

The Feed Server Client Tool (FSCT) provides feed administrators with a set of management tools for managing and serving feeds.

The FSCT provides the following:

• Binary distribution for easy setup and use
• Create, retrieve, update, and delete (CRUD) capabilities

The sections that follow enable you to install, configure, and use the FSCT.

FSCT Requirements

To use FSCT, you need the following:

• Linux (any distribution where Java programs can run) or Windows (XP or Vista)
• 512 MB RAM recommended
• 2 MB disk space for installation of the binary version
• JRE available from Java.com
• FSCT software binary download from http://code.google.com/p/google-feedserver/downloads/list

FSCT Tasks

You can use FSCT for the following tasks:

1. Manage feed entries: insert, retrieve, update, and delete
2. Retrieve feeds

Installing and Configuring FSCT

You can download the FSCT from a zip file that creates subordinate folders when extracted. FSCT provides a setup file that you edit and then run to configure your operating environment.

To install and configure FSCT:

1. Install JRE if you have not done so already.
2. Download the FSCT binary distribution zip file and extract the contents.
3. Use a text editor to edit the setupEnv.sh file for Linux or the setupEnv.bat file for Windows and set the following parameters (you can ignore the rest of the parameters in the setupEnv file):
   • FSCT_DOMAIN -- Set to the domain name of your Google Apps for Your Domain site.
   • FSCT_USER_NAME -- Specify the login name for your Google Account. For most administrative tasks, this needs to be an administrator account.
4. Test your installation by running the ./getFeed.sh Gadget in Linux or getFeed Gadget in Windows to view Google Gadgets in your domain's public gadget directory.

In setupEnv.sh for Linux or in setupEnv.bat for Windows, the following parameters are configurable:

• FSCT_DOMAIN -- Domain name
• FSCT_USER_NAME -- The user account to be used
• FSCT_FEED_BASE -- The feed URL base
• SERVICE_NAME -- The name of feed service
• AUTHN_URL_PROTOCOL -- Name of the protocol to use for authentication, either http or https
• AUTHN_URL -- The end point that handles authentication and grants authorization tokens to be used with each request

FSCT Commands

To use each command:

1. Ensure that setupEnv.sh for Linux or setupEnv.bat for Windows is correctly configured with your Google Apps for Your Domain user name and domain name.
2. Run the command from the command line specifying the proper syntax.

FSCT provides the following commands for Linux (file type of .sh) or Windows (file type of .bat). The Syntax column lists Windows batch command syntax. For Linux, preface commands with ./ and specify the .sh file extension, for example ./getFeed PrivateGadgetSpec:

<entity xmlns=""> 
  <name>hello-gadget</name>   <specContent>@hello.xml</specContent> </entity> 

The commands above are generic and works for any feed. The commands below are optimized for private gadget and directory operation.

Note:

1. All feeds have permissions defined on them. FSCT succeeds only if a user is allowed to perform the operation (so that a password can be entered).
2. Gadget name has to be unique in the gadget spec feed.

Troubleshooting FSCT

The following issues can occur while using FSCT commands.

Bad Request

The bad request error occurs if you try to add a gadget that already exists or if you specify an FSCT command with the incorrect parameters.

Exception in thread "main" com.google.feedserver.util.FeedServerClientException: com.google.gdata.util.InvalidEntryException: Bad Request invalid_input

You may need to scroll down through the list of gadgets in the Domain Gadget Directory Manager to find a gadget.

Gadget Already Exists

If a gadget has already been published and you attempt to publish the gadget more than once, the following error occurs:

Exception in thread "main" com.google.feedserver.util.FeedServerClientException: com.google.gdata.util.InvalidEntryException: Bad Request Gadget already exists

Gadget Specified Could Not Be Fetched

If a command specifies an incorrect feed or gadget name, the following error occurs:

Exception in thread "main" com.google.feedserver.util.FeedServerClientException: com.google.gdata.util.ServiceException: Internal Server Error Gadget specified could not be fetched

Ensure that you specified the correct feed name and that the gadget name exists. This error occurs for the 'getEntry' command.

Invalid Credentials

The invalid credentials error occurs when the FSCT is not correctly configured:

Exception in thread "main" com.google.gdata.client.GoogleService$InvalidCredentialsException: Invalid credentials

Ensure that you have edited setupEnv.sh for Linux or setupEnv.bat for Windows and have set the following values:

• FSCT_DOMAIN. Set to the domain name for your Google Apps for Your Domain account.
• FSCT_USER_NAME. Set to your user account name for your Google Apps for Your Domain account.

Not Found Exception

The resource not found error occurs if you enter incorrect command line information:

Exception in thread "main" com.google.feedserver.util.FeedServerClientException: com.google.gdata.util.ResourceNotFoundException: Not Found

This error can occur if the domain is not correct, or the entry or feed name is misspelled (feed and entry names are case sensitive in Linux and in Windows).

Unauthorized Exception

The forbidden service error occurs when an access control list (ACL) check fails:

Exception in thread "main" com.google.feedserver.util.FeedServerClientException: com.google.gdata.util.ServiceForbiddenException: Forbidden Unauthorized

Feeds that have ACLs set may prevent reading or writing by the account provided. You may be able to change the ACL for the resource by editing the ACL feed. For information on ACLs, see the Acl feed in the "Schemas of Hosted Feeds" section.

Back to top.

Using FSCT to Manage Private Gadgets

The FSCT commands enable you to perform the following tasks to manage private gadgets:

• Manage private gadgets and feeds
• Create private gadget categories
• Publish a private gadget to the Private Directory (for information on the Private Directory, see "Domain Gadget Directory Manager")
• Unpublish a private gadget from the Private Directory

Note: The commands shown in the sections that follow are for Linux. Windows users can enter the command itself without a file type. For example, to run the equivalent Windows command for ./insertEntry.sh, enter insertentry (Windows commands are not case sensitive). In the syntax statements that follow, the parameters are:

Add a Private Gadget

Linux Syntax: ./insertGadgetSpec.sh feedName gadgetName gadgetSpecFile Windows Syntax: insertGadgetSpec feedName gadgetName gadgetSpecFile

To add a private gadget to your domain:

• Run ./insertGadgetSpec.sh PrivateGadgetSpec gadgetName gadgetSpecFile

After inserting the gadget, FSCT echoes back the inserted entity. For example:

    <?xml version="1.0" encoding="UTF-8" ?>
    <Module>
    <ModulePrefs title="Sample Enterprise Gadget" author="phedra" category="finance" />
    <Content type="html">
    <![CDATA[
    <a href="javascript:getData()">Get Data&lt;/a>
    <script type="text/javascript">
    function getData() {
    var params = {};
    ...

View Private Gadget Entry

Linux Syntax: ./getEntry.sh feedName gadgetName Windows Syntax: getEntry feedName gadgetName

To display the XML code for a single gadget:

• Run ./getEntry.sh PrivateGadgetSpec/gadgetName

The gadget entity displays in the console. (An entity refers to the contents of the gadget spec, which is defined with the <entity> element block.)

View All Gadgets

Linux Syntax: ./getFeed.sh feedName Windows Syntax: getFeed feedName

To display the XML code for all gadgets:

• To view gadget source, run ./getFeed.sh PrivateGadgetSpec
• To find a gadget ID, run ./getFeed.sh PrivateGadget

Gadget entities display in the console.

Note:

• By default, FSCT only returns a maximum of 20 entries. To retrieve more, use parameter "start-index=N" and "max-results=M" on the feed URL where N is a base-1 starting index and max-results is a number from 1 to 20.
• If there are many gadgets, the getFeed command listing can be many pages. In Windows, in the Command Prompt Properties menu, set the Screen Buffer Size to a number large enough to contain this output, such as to 9999 rows. You can then copy the data from the Command Prompt to an editor such as Notepad to search for a gadget entry.

An example getFeed listing of the PrivateGadget feed starts as follows:

<entities>
 <entity>
    <screenshot></screenshot>
    <submit_date>1237487950081</submit_date>
    <url>http://www.google.com/a/feeds/server/g/domain/example.com/PrivateGadgetSpec/hello.xml</url>
    <country>all</country>
    <id>http://feedserver-enterprise.googleusercontent.com/a/example.com/g/PrivateGadget/03655085350586526872</id>
    <author_email>developer@example.com</author_email>
    <title>hello world example</title>
    <thumbnail></thumbnail>
    <description></description>
    <localmetadata repeatable="true">
      <title>hello world example</title>
      <screenshot></screenshot>
      <thumbnail></thumbnail>
      <description></description>
      <language>all</language>
      <country>all</country>
    </localmetadata>
    <view repeatable="true">
      <name>default</name>
      <type>html</type>
    </view>
    <language>all</language>
    <item_type>gadget</item_type>
  </entity>
  ...

Update a Private Gadget

Linux Syntax: ./updateGadgetSpec.sh feedName gadgetName gadgetSpecFile Windows Syntax: updateGadgetSpec feedName gadgetName gadgetSpecFile

To update a gadget in the PrivateGadgetSpec feed source:

• Run ./updateGadgetSpec.sh PrivateGadgetSpec gadgetName gadgetSpecFile

The updated gadget entity displays in the console. This command enables you to change the XML code content in the for gadgetSpecFile the gadget. Any part of the gadget spec can be changed as well as the functionality for the gadget.

Delete a Private Gadget

Linux Syntax: ./deleteEntry.sh feedName gadgetName gadgetSpecFile Windows Syntax: deleteEntry feedName gadgetName

• Run ./deleteEntry.sh PrivateGadgetSpec gadgetName

Publish a Private Gadget to the Private Directory

Linux Syntax: ./publishGadget.sh privateDirectory feedName/gadgetName Windows Syntax: publishGadget privateDirectory feedName/gadgetName

• Run ./publishGadget.sh PrivateGadget PrivateGadgetSpec/gadgetName

Publishing a gadget is required for the gadget to appear in the Private Directory. Published gadgets can then be added to a Google Sites page by users in a domain within Google Apps for Your Domain Premier Edition or Education Edition.

Unpublish a Gadget

Linux Syntax: ./deleteEntry.sh PrivateGadget gadgetId Windows Syntax: deleteEntry PrivateGadget gadgetId

You can unpublish a gadget to remove it from domain's private gadget directory.

Note: To find the gadget you want to unpublish, you need to find its gadget ID value.

To unpublish a gadget:

1. Run the getFeed PrivateGadget command to locate a gadget's ID value (in the <id> element).

   For example:

       $ ./getFeed.sh PrivateGadget
       The password cannot be null or blank
       Password:
       <entities>
         <entity>
           <screenshot></screenshot>
           <submit_date>1237476364974</submit_date>
           <url>http://feedserver-enterprise.googleusercontent.com/a/example.com/g/PrivateGadgetSpec/mygadget.xml</url>
           <country>all</country>
           <id>http://feedserver-enterprise.googleusercontent.com/a/example.com/g/PrivateGadget/056536884581709698</id>
       ...

2. Run the deleteEntry command, specify the PrivateGadget feed source, and the gadget ID.

   For example:

       $ ./deleteEntry.sh PrivateGadget 056536884581709698
       The password cannot be null or blank
       Password:
   
       $

Create a Private Gadget Category

Linux Syntax: ./insertEntry.sh PrivateGadgetCategory entityFile Windows Syntax: insertEntry PrivateGadgetCategory entityFile

Note: For a gadget to appear in a category, the gadget spec must contain the category attribute in the <ModulePref> element.

For example:

<ModulePrefs title="Sample Enterprise Gadget" author="phedra" category="Finance" />

To create a gadget category:

1. Create an entity XML file for the category.

   An example financeEntity.xml entity file is:

       <entity xmlns="">
         <name>Finance</name>
         <category repeatable="true">
           <locale>en</locale>
           <displayName>Finance</displayName>
         </category>
       </entity>

2. Run the insertEntry.sh command for Linux or the insertEntry.bat command for Windows to add the category from the gadget to the Domain Gadget Directory Manager.

       ./insertEntry.sh PrivateGadgetCategory financeEntity.xml

Delete a Private Gadget Category

Linux Syntax: ./deleteEntry.sh PrivateGadgetCategory categoryName Windows Syntax: deleteEntry PrivateGadgetCategory categoryName

Deletes a gadget category.

For example:

./deleteEntry.sh PrivateGadgetCategory Finance

Back to top.

Using FSCT to Manage Feed Access

Using High Level Tool

For Per Domain Feeds

To set the ACLs of a resource, you execute a command like this:

./setAcl.sh PrivateGadgetSpec crud+john.doe@example.com

which adds create, retrieve, update and delete access to user john.doe@example.com to the per domain feed PrivateGadgetSpec.

To remove access, you use minus as opposed to plus. For example:

./setAcl.sh PrivateGadgetSpec d-john.doe@example.com

which removes delete access from user john.doe@example.com on per domain feed PrivateGadgetSpec.

You can verify the current ACLs by doing:

./getAcl.sh PrivateGadgetSpec

./getEntry.sh acl PrivateGadgetSpec

To set the ACLs for an entry, you would use <feedName>/<entryName> as the resource. For example,

./setAcl.sh PrivateGadgetSpec/hello.xml crud-john.doe@example.com

which removes all access from user john.doe@example.com on a specific private gadget call hello.xml.

For Per User Feeds

To set ACLs on per user resources, do exact the same as the above except use getUserAcl.sh and setUserAcl.sh. For example,

./setUserAcl.sh PrivateGadgetSpec r+jane.doe@example.com

adds read access to user jane.doe@example.com to current user's PrivateGadgetSpec feed.

There is also a specific tool for sharing user's own private gadget with other users. For example,

./shareUserGadget.sh hello.xml friend@example.com colleague@example.com

makes current user's own gadget hello.xml readable by friend@example.com and colleague@example.com.

To verify the ACLs on a specific user gadget, do the following:

./getUserEntry.sh acl PrivateGadgetSpec%2Fhello.xml

where "%2F" is "/" URL encoded.

To remove sharing, just use unshareUserGadget.sh.

General Command Syntax

getAcl.sh <resource>

getUserAcl.sh <resource>

setAcl.sh <resource> <acl>{,<acl>}*

setUserAcl.sh <resource> <acl>{,<acl>}*

shareUserGadget.sh <gadgetName> <principal>{,<principal>}*

unshareUserGadget.sh <gadgetName> <principal>{,<principal>}*

where resource is either <feedName> or <feedName>/<entryName>, acl in the format of {c,r,u,d}{+|-}<principal> and principal the email address of an individual or group.

For example,

setUserAcl.sh PrivateGadgetSpec/hello.xml crud+project1@example.com,r+partner.guy@partner.com

adds full access to users in group project1@example.com and read access to user partner.guy@partner.com to private gadget called hello.xml.

Using Low Level Tool

Every hosted feed has an access control list (ACL) associated with it to control which users can do which operations on the feed and its entries. All hosted feeds have a default ACL that allows domain users to read from a feed and the domain's administrators to write to the feed. You can override a default ACL to suit the needs of your domain.

The following is an example of setting the ACL for the PrivateGagetSpec feed, which is the aclEntity.xml listing:

<entity xmlns="">
  <name>PrivateGadgetSpec-acl</name>
  <resourceInfo>
    <resourceType>feed</resourceType>
    <resourceRule>PrivateGadgetSpec</resourceRule>
  </resourceInfo>
  <authorizedEntities repeatable="true">
    <operation>create</operation>
    <entities repeatable="true">DOMAIN_ADMIN</entities>
    <entities repeatable="true">gadget-dev@example.com</entities>
  </authorizedEntities>
  <authorizedEntities>
    <operation>retrieve</operation>
    <entities repeatable="true">DOMAIN_USERS</entities>
  </authorizedEntities>
  <authorizedEntities>
    <operation>update</operation>
    <entities repeatable="true">DOMAIN_ADMIN</entities>
    <entities repeatable="true">gadget-dev@example.com</entities>
  </authorizedEntities>
  <authorizedEntities>
    <operation>delete</operation>
    <entities repeatable="true">DOMAIN_ADMIN</entities>
    <entities repeatable="true">gadget-dev@example.com</entities>
  </authorizedEntities>
</entity>

Execute this command to create the ACL the first time:

./insertEntry.sh acl aclEntity.xml

Then the PrivateGadgetSpec feed can be:

• Inserted into by a domain's administrators, and all users on the group gadget-dev@example.com
• Retrieved by all users in the domain
• Updated by domain's administrators, and all users on the group gadget-dev@example.com
• Deleted from by domain's administrators, and all users on the group gadget-dev@example.com

You can use the previous example as a template to produce an entity file specific to your needs. Here are the valid values you can use for the "entities" element:

• DOMAIN_USERS: Any user in the domain
• DOMAIN_ADMIN: Any administrator of the domain
• DOMAIN_INDIVIDUAL: The current logged in user (has to belong to the domain and match the owner of the user feed)
• ANY_INDIVIDUAL: The current logged in user (has to match the owner of the user feed; can be out of the domain)
• ANYONE: Any logged in user, in or out of the domain
• User Email address: Any individual user's email address
• Group email address: Email address of a group (go to https://www.google.com/a/cpanel/example.com/GroupList to manage groups)

To update an ACL, execute the following command:

./updateEntry.sh acl PrivateGagetSpec-acl aclEntity.xml

If you want to change the ACL of another feed, for example, the PrivateGadgetCategory, create another ACL entity file and plug the feed name into the <resourceRule> element.

Back to top.

Schemas of Hosted Feeds

The following feed sources are available with Google Apps.

<entity xmlns="">
  <url>{internal URL to private gadget}</url>
</entity>

<entity xmlns="">
  <url>http://feedserver-enterprise.googleusercontent.com
/a/example.com/g/PrivateGadgetSpec/hello.xml</url>
</entity>

<entity xmlns="">
  <name>{unique name of category}</name>
  <category repeatable="true">
    <locale>en</locale>
    <displayName>{display name of category}</displayName>
  </category>
</entity>

<entity xmlns="">
  <name>Finance</name>
  <category repeatable="true">
    <locale>en</locale>
    <displayName>Finance</displayName>
  </category>
</entity>

<entity xmlns="">
  <name>{unique name of gadget}</name>
  <specContent>@{path to gadget spec file}</specContent>
</entity>

<entity xmlns="">
  <name>hello-gadget</name>
  <specContent>@hello.xml</specContent>
</entity>

<entity xmlns="">
  <name>{feedName}-acl</name>
  <resourceInfo>
    <resourceType>feed</resourceType>
    <resourceRule>{feedName}</resourceRule>
  </resourceInfo>
  <authorizedEntities repeatable="true">
    <operation>{operation}</operation>
    <entities repeatable="true">{principal}</entities>
    ...
  </authorizedEntities>
  ...
</entity>

<entity xmlns="">
  <name>PrivateGadgetSpec-acl</name>
  <resourceInfo>
    <resourceType>feed</resourceType>
    <resourceRule>PrivateGadgetSpec</resourceRule>
  </resourceInfo>
  <authorizedEntities repeatable="true">
    <operation>create</operation>
    <entities repeatable="true">DOMAIN_ADMIN</entities>
    <entities repeatable="true">gadget-dev@example.com</entities>
  </authorizedEntities>
  <authorizedEntities>
    <operation>retrieve</operation>
    <entities repeatable="true">DOMAIN_USERS</entities>
  </authorizedEntities>
  <authorizedEntities>
    <operation>update</operation>
    <entities repeatable="true">DOMAIN_ADMIN</entities>
    <entities repeatable="true">gadget-dev@example.com</entities>
  </authorizedEntities>
  <authorizedEntities>
    <operation>delete</operation>
    <entities repeatable="true">DOMAIN_ADMIN</entities>
    <entities repeatable="true">gadget-dev@example.com</entities>
  </authorizedEntities>
</entity>

Back to top.

Private Gadget Editor

The Private Gadget Editor (PGE) gadget enables you to create, change, and delete Google Gadgets. The PGE is a gadget that can be added only to a Google Sites page.

Private gadgets are usable only by Google Apps for Your Domain Premier Edition or Education Edition. Private gadgets are gadgets that are available only to users in a domain.

To add the PGE gadget to a Google Sites page:

1. Click Create new page.
2. Click Start Page and specify a page name.
3. Click one of the following choices to add the gadget:

   The Add personal gadgets link.

   In the Gadgets in this area are only visible to you dashed area.

   The Select a gadget window appears.
4. Click Add gadget by URL.
5. Click the edit box, type in this value, and click Add: http://google-feedserver.googlecode.com/svn/trunk/resources/gadgets/private-gadget-editor/spec.xml
6. In the gadget's title bar, click the maximize button to use the gadget in profile view.
7. To create a gadget, paste in a gadget in the editor. To edit an existing gadget, click Open URL to load a gadget spec from a public URL, or click Select to open to open an existing private gadget to edit.

After creating and saving a gadget in the PGE, use the Domain Gadget Directory Manager to publish the gadget to the domain's private gadget directory so that users can access it in Google Apps.

Back to top.

Domain Gadget Directory Manager

The Domain Gadget Directory Manager (DGDM) gadget enables domain administrators to manage a domain's public and private gadget directory. The DGDM is itself a gadget that you add to a Google Sites page. The DGDM gadget only works with Google Sites.

Add the DGDM Gadget to Google Sites

To add the DGDM gadget to a Google Sites page:

1. Start Google Sites
2. Click the Create new page button.
3. Click User Start Page and specify a page name.
4. Click the Add personal gadgets link. The Select a gadget window appears.
5. Click Add gadget by URL.
6. Click the edit box, type in this value, and click Add:

   http://google-feedserver.googlecode.com/svn/trunk/resources/gadgets/domain-gadget-directory-manager/spec.xml

Using DGDM

The Domain Gadget Directory Manager provides the following tabs:

• Private Directory. Allows an administrator to manage a domain's private gadget directory which is visible only to the domain. Administrators can publish private gadgets to the private gadget directory and/or unpublish from it.
• Private Categories. Allows an administrator to manage a domain's private gadget categories. Administrators can create or remove private categories under which private gadgets will appear. You can create a category for a gadget by setting the category attribute in the <ModulePrefs> element in gadget XML code.

  For example:

  <ModulePrefs title="View Data Gadget"
      category="Finance"
      ... />

  Choose a category that best matches the content of your gadget. Refer to this page for more details.

• Directory Preview. Preview directory changes when there is a delay after changes are made in DGDM (or FSCT) and when they appear in an end user's gadget directory UI.

Back to top.