Purpose and Scope

Org Service currently provides the following two gadgets:

1. Remote Groups gadget - provides a list of remote groups.
2. See Also Groups gadget - provides a list of related groups and the ability to add/remove relationships between groups.

Contents:

• Terminology
• Gadget Overview
• Gadget Service
• API Guidelines
• Remote Groups Gadget
• See Also Groups Gadget

Terminology

Gadgets use the following terminology:

• Hub - An nGenera Collabaration Web Application.
• BSG RA GUID- aka BSG Reference Architecture Globally Unique Identifier. A unique string that identifies each consumer. BSG RA GUIDs have the form: 6b0c73c0-bsga-kali-rome-001b7744e04a. In the Ruby language you can produce a similarly formatted identifier using the UUIDTOOLS library command: UUID.timestamp_create().to_s.
• Authentication Token- The authentication token of the originating session.
• Group - a group managed by the Org Service.
• OpenSocial - a common set of API specifications for social network applications.
• OpenSocial Container - a site that can host OpenSocial applications.

Gadget Overview

A Gadget is a mini-application that is developed using HTML and Javascript. Gadgets developed at nGenera are served through the gadget service which is based on the Apache Shindig server which is an open source implementation of the OpenSocial specification.

Gadget Service

Gadgets are rendered by making requests to the Gadget service which is available at http://gadget.ngenplatform.com/gadgets/ifr

The following parameters may be passed to it on the querystring.

Parameters

• url: This is a required parameter and it refers to the location of the gadget specification file. This is an XML file - that contains HTML and Javascript - to define the gadget. Further information on the gadgets API can be found here
• up_*: Any parameter can be passed to the gadget service by prefixing it with "up_". It will then be accessible from the gadget container as a user preference. For example if a parameter named up_guid is passed then it can be accessed from the gadget's Javascript through prefs.getString('guid') i.e. the prefix is dropped when accessing the parameter.

API Guidelines

• All gadgets require the following parameter to be passed in as a parameter:

  Parameter	Description
  up_guid	bsgra_guid value appropriate to your consumer service.

Remote Groups Gadget

This gadget provides a list of groups on remote hubs. For a group to be visible as a remote group:

• It must have been published from the originating hub.
• It must have been subscribed to from the remote hub.

Parameters/User Preferences

• url: This is a required parameter and it is used to specify the location of the XML file used to generate the gadget. Its value in this case is http://organization.ngenplatform.com/gadgets/remote_groups?theme=kalivo
• up_guid: This is a required parameter and it refers to the BSGRA GUID of the hub whose remote groups are to be displayed.
• up_auth_session_index: This refers to the authentication token of the user making the request.

Usage

• nGenera Gadget Service

The complete url syntax for serving up this gadget from the Gadget Service is listed below.

http://gadget.ngenplatform.com/gadgets/ifr?up_auth_session_index=<authentication token value>&up_guid=<bsgra guid value>&url=http://organization.ngenplatform.com/gadgets/remote_groups?theme=kalivo



• Hosting on the iGoogle Container

Google provides a sandbox environment for developers to build and test their iGoogle gadgets. Perform the following steps to host this gadget on iGoogle.

• Go to http://www.google.com/ig/sandbox and sign up for the sandbox environment.
• After signing up the user enters the iGoogle sandbox environment. Click the "Add Stuff" link in the right hand corner above all the gadgets. Click on the "Add feed or gadget" link at the bottom of the menu on the left hand side and enter the following url and click on "Add":

http://organization.ngenplatform.com/gadgets/remote_groups?theme=kalivo

• An alert window will pop up informing the user that a feature not created by Google is being added and would the user like to proceed. Click on "OK" to continue.
• Click on the "Back to iGoogle home" link on the top left hand corner.
• The "Display Remote Groups" gadget will have been added to the main iGoogle page.
• In the top right hand corner of the gadget window click on the triangular icon. this will present a popup menu with several options. Select the "Edit Settings" option and provide a valid value for the BSGRA_GUID parameter.
• The gadget will refresh and display a list of remote groups that is accesible via the hub with the specified bsgra guid value.

Note that only remote groups that are visible to anonymous users will be displayed.

See Also Groups Gadget

This gadget displays a list of local and remote groups that a specific group has a "see also" relationship with. It also provides a mechanism to create and remove the "see also" relationship between the specified group and other groups. This can be useful for identifying other groups that a user may be interested in based on a specific group.

The groups are displayed based on the following criteria.

• Local Groups: These are displayed based on the user performing the request. If its an Admin user - an administrator for all the hubs - then all groups are displayed. If it is a non-Admin user then all non-internal groups, that are visible and that the user is a member of will be displayed.
• Remote Groups: All remote groups that the hub is subscribed to will be displayed.

The gadget also displays a list of groups with whom a "see also" relationship can be established for the current group. This list is also based on the criteria defined above.

Parameters/User Preferences

• url: This is a required parameter and it is used to specify the location of the XML file used to generate the gadget. Its value in this case is http://organization.ngenplatform.com/gadgets/group_associations?theme=kalivo
• up_guid: This is a required parameter and it refers to the BSGRA GUID of the hub whose remote groups are to be displayed.
• up_group_guid: This is a required parameter and it refers to the guid of the group for which the "see also" relationships need to be retrieved/created/deleted.
• up_auth_session_index: This refers to the authentication token of the user making the request.

Usage

• nGenera Gadget Service

The complete url syntax for serving up this gadget from the Gadget Service is listed below.

http://gadget.ngenplatform.com/gadgets/ifr?up_auth_session_index=<authentication token value>&up_guid=<bsgra guid value>&up_group_guid=<group guid value>&url=http://organization.ngenplatform.com/gadgets/group_associations?theme=kalivo



• Hosting on the iGoogle Container (Will be implemented in a future release - 8.6.0)

Google provides a sandbox environment for developers to build and test their iGoogle gadgets. Perform the following steps to host this gadget on iGoogle.

• Go to http://www.google.com/ig/sandbox and sign up for the sandbox environment.
• After signing up the user enters the iGoogle sandbox environment. Click the "Add Stuff" link in the right hand corner above all the gadgets. Click on the "Add feed or gadget" link at the bottom of the menu on the left hand side and enter the following url and click on "Add":

  http://organization.ngenplatform.com/gadgets/group_associations?theme=kalivo

• An alert window will pop up informing the user that a feature not created by Google is being added and would the user like to proceed. Click on "OK" to continue.
• Click on the "Back to iGoogle home" link on the top left hand corner.
• The "See Also Groups" gadget will have been added to the main iGoogle page.
• In the top right hand corner of the gadget window click on the triangular icon. this will present a popup menu with several options. Select the "Edit Settings" option and provide valid values for the bsgra_guid and the group_guid parameters.
• The gadget will refresh and display a list of related local and remote groups, and the ability to create/remove new "see also" relationships.

© Copyright 2006-8 nGenera Corporation - All rights reserved. Version 3.3.0