< Previous | Cookbook Contents

Overview

OpenSocial Component functionality in Notes and iNotes relies on several pieces of data that control what OpenSocial gadgets are allowed to render, how they are allowed to render, what information they are allowed to have access to on the network, and what authorization protocols they are allowed to use. These will be referred to as widget trust, gadget capabilities, proxy rules, and OAuth data, respectively. Much of this data is generated during the Widget approval process and is utilized during the Gadget rendering process. This article will detail the data that is created, where it is created, and when it is available to be utilized, with the purpose of educating administrators so they know at what point after Widget creation and approval the Widget will be able to work as expected in Notes and iNotes.

In each section below, several questions will be answered:

1. Where is this data stored?
2. When is this data read?
3. When is this data used?
4. Can the behavior of #2 be customized?

Note: Any data stored in the Credential Store application can be viewed there but it SHOULD NOT be modified in the credential store application itself. All modifications should occur through the Widget Catalog. For more information, see Widgets created from an OpenSocial gadget 9.0 or Widgets created from an OpenSocial gadget 9.0.1 and its child articles.

Widget Trust

As described in the Widget approval process, OpenSocial gadgets and Embedded Experiences require a Widget to be trusted by an administrator before they will work in the Notes and iNotes clients. Trust is established once an administrator approves the Widget in the catalog, signing the document in the process.

Widget Trust in Notes

1. Where is this data stored? The data is stored in a hidden column in the local replica of the Widget Catalog and is calculated when the widget document is approved and when the view updates. Once the Widget is installed, the data is stored on a per user basis in the palette store in the Notes workspace directory.
2. When is this data read? The data is read from the palette store when the My Widgets framework is initialized. The data is updated at Widget install time and the trust established at that time includes ACL and ECL checks. This data is only recalculated when the "Update Widgets" action is executed by the end user or when replication of the Widget Catalog pulls in a change, or if the Widget is removed.
3. When is this data used? The data is used when OpenSocial gadgets and Embedded Experiences render locally or remotely in Notes.
4. Can the behavior of #2 be customized? No.

Widget Trust in iNotes

1. Where is this data stored? The data is stored in a hidden column in the Widget Catalog replica on the iNotes server on a per widget basis and is calculated when the widget document is approved and when the view updates. Once the Widget is installed, the data is stored on a per user basis in a data document in the user's mail file.
2. When is this data read? The data is read from the user's mail file when the My Widgets framework is initialized. The data is updated using the data from the Widget Catalog when a Widget is installed. The data is also updated on a per user basis based on changes when the DOTS UpdateWidgetsTask runs or when the user runs "Update Widgets" or if the widget is removed.
3. When is this data used? The data in the user's mail file is used when OpenSocial gadgets or Embedded Experiences are rendered.
4. Can the behavior of #2 be customized? Yes. See "iNotes_WA_WidgetDataRefreshInterval" in the Notes.ini Settings for Customization section below. One can also execute the "Update Widgets" action in the My Widgets sidebar menu to force an update.

Gadget Capabilities

As described in the Gadget rendering process, OpenSocial gadgets and Embedded Experiences rely on capabilities to define what APIs they have access to at runtime. For OpenSocial gadgets, this correlates to the OpenSocial features the gadget is requesting to use. For Embedded Experiences, there are special capabilities that indicate if an OpenSocial gadget or web widget is able to render as an Embedded Experience in e-mail. The runtime checks occur in Notes for local rendering and on the Domino Server with Shindig for iNotes gadgets and Notes remote rendering. The Embedded Experiences capabilities check occurs client-side in iNotes and Notes, regardless of whether the rendering in Notes is local or remote.

Gadget Capabilities in Notes

1. Where is this data stored? The data is stored in the local replica of the Widget Catalog on a per widget basis. Once the Widget is installed, the data is stored on a per user basis in the palette store in the Notes workspace directory.
2. When is this data read? The data is read from the palette store when the My Widgets framework is initialized. The data is updated at Widget install time and when the "Update Widgets" action is executed by the end user or when replication of the Widget Catalog pulls in a change or widgets are removed.
3. When is this data used? The data is used to ensure that Embedded Experiences are trusted to render for both locally and remotely rendering Embedded Experiences. The data is also used at runtime when rendering OpenSocial gadgets locally in Notes.
4. Can the behavior of #2 be customized? There is no need to customize the behavior of #2, as all of the data is always current and does not rely on periodic refreshes.

Gadget Capabilities in iNotes

1. Where is this data stored? The data is stored in the Widget Catalog replica on the iNotes server on a per widget basis. Once the Widget is installed, the data is stored on a per user basis in a data document in the user's mail file. The data is also created, updated, or deleted on a per user basis based on changes when the DOTS UpdateWidgetsTask runs.
2. When is this data read? The data is read from the user's mail file when the My Widgets framework is initialized. The data is updated using the data from the Widget Catalog when a Widget is installed. The data is also updated on a per user basis based on changes when the DOTS UpdateWidgetsTask runs or when the user runs "Update Widgets" or if the widget is removed.
3. When is this data used? The data is used to ensure that Embedded Experiences are trusted to render.
4. Can the behavior of #2 be customized? Yes. See "iNotes_WA_WidgetDataRefreshInterval" in the Notes.ini Settings for Customization section below. One can also execute the "Update Widgets" action in the My Widgets sidebar menu to force an update.

Gadget Capabilities on the Domino Server with Shindig

1. Where is this data stored? The data is stored in the Credential Store application on the Domino Server with Shindig
2. When is this data read? The data is read when the web application defined by the com.ibm.fiesta.inotes OSGi bundle loads on the Domino Server with Shindig and every hour thereafter.
3. When is this data used? The data is used at runtime when rendering OpenSocial gadgets in iNotes and when rendering OpenSocial gadgets remotely in Notes.
4. Can the behavior of #2 be customized? Yes. See "SocialCapabilitiesRefreshInterval" in the Notes.ini Settings for Customization section below. One can also execute tell http osgi social refresh capabilities to force an update.

Proxy Rules

Proxy rules are used by Notes for local rendering and on the Domino Server with Shindig for iNotes and Notes remote rendering. For more information on proxy rules, see the "Proxy Settings" section of Widgets created from an OpenSocial gadget 9.0 or Widgets created from an OpenSocial gadget 9.0.1.

Proxy Rules in Notes

1. Where is this data stored? The data is stored in the local replica of the Widget Catalog
2. When is this data read? The data is read the when the web application defined by the com.ibm.fiesta.notes OSGi bundle loads in Notes, when Widget preferences for server or database name change, or when the local Widget Catalog replicates.
3. When is this data used? The data is used when an OpenSocial gadget attempts to make a network request. The request being attempted is checked against the whitelist defined by the proxy rules before being allowed to proceed.
4. Can the behavior of #2 be customized? There is no need to customize the behavior of #2, as all of the data is always current and does not rely on periodic refreshes.

Proxy Rules on the Domino Server with Shindig

1. Where is this data stored? The data is stored in the Credential Store application on the Domino Server with Shindig
2. When is this data read? The data is read when the web application defined by the com.ibm.fiesta.inotes OSGi bundle loads on the Domino Server with Shindig and every hour thereafter.
3. When is this data used? The data is used when an OpenSocial gadget attempts to make a network request. The request being attempted is checked against the whitelist defined by the proxy rules before being allowed to proceed.
4. Can the behavior of #2 be customized? Yes. See "SocialProxyRefreshInterval" in the Notes.ini Settings for Customization section below. One can also execute tell http osgi social refresh proxy to force an update

OAuth Information

As described in the Gadget rendering process, OpenSocial gadgets that use OAuth always render using the Domino Server with Shindig. This means that OAuth data is never read by the Notes client, nor is there ever a need to.

For more information, see the OAuth Configuration section of Widgets created from an OpenSocial gadget or Widgets created from an OpenSocial gadget 9.0.1.

Types of OAuth Information

Four types of OAuth information are stored in the Credential Store application. The OpenSocial Component supports both OAuth1.0a and OAuth2, and each version of OAuth has OAuth consumer and OAuth token information.

OAuth Consumer Information

The OAuth consumer information is what is configured during the Widget approval process.

1. Where is this data stored? The data is stored in the Credential Store application on the Domino Server with Shindig. It is pushed there by the "PushToCredStore" agent in the Widget Catalog
2. When is this data read? The data is read when the web application defined by the com.ibm.fiesta.inotes OSGi bundle loads on the Domino Server with Shindig and every hour thereafter.
3. When is this data used? The data is used when an OpenSocial gadget makes an OAuth request to a protected endpoint and an OAuth token does not already exist. The data is used to get an OAuth token.
4. Can the behavior of #2 be customized? Yes. See "SocialOAuthRefreshInterval" in the Notes.ini Settings for Customization section below. One can also execute tell http osgi social refresh oauthconsumers to force an update

OAuth Token Information

The OAuth access information is created dynamically as end users "do the OAuth dance" to authorize the applications on their own behalf.

1. Where is this data stored? The data is stored in memory and persisted in the Credential Store application on the Domino Server with Shindig
2. When is this data read? The data is read when the web application defined by the com.ibm.fiesta.inotes OSGi bundle loads on the Domino Server with Shindig and every hour thereafter.
3. When is this data used? The data is used when an OpenSocial gadget makes an OAuth request to a protected endpoint.
4. Can the behavior of #2 be customized? Yes. See "SocialOAuthRefreshInterval" in the Notes.ini Settings for Customization section below. One can also execute tell http osgi social refresh oauthtokens to force an update

Notes.ini Settings for Customization

Name	Valid Values	Default Value	Where to set	Description
iNotes_WA_WidgetDataRefreshInterval	A positive integer of milliseconds	3600000	The iNotes server(s)	The interval for how many miliseconds the iNotes client will wait until it tries to refetch the widget data from the server. The default is 1 hour.
SocialCapabilitiesRefreshInterval	A positive integer of minutes	60	The Domino Server(s) with Shindig	Interval in minutes at which to check for updates to Gadget Capabilities in order to refresh the cached information. A value of 0 or less disables the refresh check
SocialProxyRefreshInterval	A positive integer of minutes	60	The Domino Server(s) with Shindig	Interval in minutes at which to check for updates to proxy configuration rules. A value of 0 or less disables the refresh check
SocialOAuthRefreshInterval	A positive integer of minutes	60	The Domino Server(s) with Shindig	Interval in minutes at which to check for updates to OAuth client information. A value of 0 or less disables the refresh check

< Previous | Cookbook Contents