ShowTable of Contents
Introduction
Support for OpenSocial gadgets was introduced in IBM Notes and Domino 9.0 with the introduction of the OpenSocial Component and it opens up a world of possibilities for developers, most notably the ability to leverage embedded experiences in email in IBM Notes and iNotes. In addition to embedded experiences, the OpenSocial Component now makes it possible to build web applications, called gadgets, that run in IBM Notes 9.0.x, IBM iNotes 9.0.x, and in most cases IBM Connections 4.x. However as a developer you need an environment to test your gadgets in Notes and iNotes but configuring a development environment can sometimes be challenging for developers (after all most of us aren’t admins!). A deep dive on the configuration that needs to be done can be found in the
IBM Domino 9.0 Social Edition OpenSocial Component Deployment Cookbook. In most cases the level of detail in the Cookbook is more than a developer would need to setup their own environment. This article is not meant to replace the Cookbook but instead is meant to complement it. At the end of each section in this article we link back to the section in the Cookbook that provides more details on the steps you just completed. You should reference the cookbook if you have any questions while following this article.
Goal
The goal of this article is to provide the minimal number of steps necessary to install and configure the OpenSocial Component on IBM Notes and Domino 9.0.x. We will be setting up a
single Domino server that will act as our mail server and gadget rendering server. After you complete the steps below you should be able to render OpenSocial gadgets as standalone applications or as embedded experiences in email and URL embedded experiences (which is used to provide embedded experiences from XPages).
Installation
For a development environment the installation topography is fairly simple; you just need one Domino server and one Notes client, both of which can be installed on the same machine if you would like. For Domino there is a separate installer which adds the OpenSocial Component to Domino. For Notes the OpenSocial Component is included as part of the Notes installed and can be enabled during the Notes installation process. All of the OpenSocial functionality for iNotes is within the iNotes Forms file which is installed by default with your Domino 9 server. For more detailed information on installing the OpenSocial Component, see the
cookbook’s installation instructions.
After the installation completes and you have walked through the initial setup steps for your Notes client and Domino server, launch the Domino server and the Domino Administrator client.
Note: You will need a Domino Administrator and Domino Designer client to complete the configuration so please make sure you install those as well.
General Domino Configuration
Notes.ini Settings For Your Domino Server
In order to enable the OpenSocial functionality in iNotes you need to add a couple inis to your notes.ini file on your Domino server.
1. Navigate to your Domino installation directory and open the
notes.ini file.
2. Add the following ini settings:
iNotes_WA_EnableEE=1, iNotes_WA_LiveText=1, iNotes_WA_Widgets=1, iNotes_WA_OpenSocial=1.
3. Find the ini setting called
ServerTasks in the file.
4. Make sure both
DOTS and
HTTP are in the comma-separated list for the
ServerTasks; if they are not in the list, then add them.
5. Save and close the file.
Note: A server restart is required for these to take effect.
Programmability Restrictions
You need to change the programmability restrictions for your server to allow the admin to run certain restricted operations.
1. Open Domino Administrator.
2. Open the server document for your server.
3. Click
Security tab.
4. See the figure below for how you should configure the programmability restrictions:
5. Save and close the file.
Internet Email Addresses
All users who are going to be rendering OpenSocial gadgets in Notes or iNotes need to have internet email addresses. Follow
the instructions here to populate your users with internet email addresses if all or some of them may be missing.
SSO Configuration
The Notes client will use a Domino SSO account when rendering OpenSocial gadgets so we need to setup SSO on the Domino server in order for this to work.
1. Open the Domino Administrator client.
2. Open the
names.nsf database on your Domino server.
3. Under
Configuration -> Servers, select the
All Server Documents view
.
4. Click the
Web drop-down at the top of the view, and select
Create Web SSO Configuration.
5. The
Configuration Name field should already be filled out, if not make sure you give it a name.
6. In the
DNS Domain field, enter the domain of your server
For example if the URL to your server is
http://myserver.mydomain.com you would enter
.mydomain.com in the
DNS Domain field.
Notice the
. before
mydomain.com in the example, this is required and is not a mistake.
7. In the
Domino Server Names field, enter the canonical name of your server.
For example,
myserver/mydominodomain. You can also click the down arrow to select the server from the address book.
8. At the top of the
Web SSO Configuration document, click the
Keys drop-down.
9. Select
Create Domino SSO Key, this create a key for your SSO configuration.
10. Click
Save & Close.
You can edit this document at any time by opening the
names.nsf database on your server and navigating to
Configuration -> Web and then selecting the
Web Configurations view. You will see a Web SSO Configurations category in the view with your SSO configuration under it.
Now enable Multi-Server SSO and set it to use the SSO configuration document that you just created:
1. Close the
names.nsf database.
2. Open your server in the Domino Administrator client.
3. Go to the
Configuration tab.
4. Expand the
Server node in the outline and open the
Current Server Document.
5. Click the
Ports tab.
6. Select the
Internet Ports sub-tab.
7. Select the
Web sub-tab.
8. Make sure the
Name & Password field is set to
Yes for port 80.
9. Select the
Internet Protocols tab in the server document.
10. Select the
Domino Web Engine sub-tab.
11. Click the down arrow next to the
Session authentication field.
12. Select
Multiple Servers (SSO) from the selection dialog, and click
OK.
13. Click the down arrow next to the
Web SSO Configuration field.
14. Select the name of the SSO configuration document you created above (by default the name will be
LtpaToken), and click
OK to close the selection dialog.
15. Click
Save & Close to close the server document.
Create A Widget Catalog
The widget catalog acts as the centralized place for managing an organizations OpenSocial gadgets for Notes and iNotes. We need to create a widget catalog on your Domino server.
1. Open the Domino Administrator client.
2. Click
File -> Application -> New.
3. In the
Specify Template for New Application section at the bottom of the
New Application dialog, specify your server name in the
Server field and check
Show advanced templates.
In the template selector, find the
Widget Catalog (9) template and select it.
4. In the
Specify New Application Name and Location section of the
New Application dialog, specify your server name in the
Server field and fill out the
Title and
File name fields.
A typical title for the application is
Widget Catalog and a typical file name is
toolbox.nsf.
Your dialog will look something like this:
5. After you have the
New Application dialog filled out correctly, select
OK to create the application.
More detailed information about creating the widget catalog can be found in the
cookbook.
Creating A Credential Store Database
The credential store database is used to store various pieces of information related to OpenSocial gadgets. To create a credential store database on your Domino server follow these steps:
1. In the Domino Server console type keymgmt create nek social. The last parameter to the command (which is social in the prior command) can be whatever you would like.
2. In the Domino Server console type keymgmt create credstore social. The last parameter to this command must mach the last parameter from the command issued in step 1.
3. You should see some output in the console indicating the database was created successfully and there should now be a database called credstore.nsf in
/IBM_CredStore.
More information on how to create the credential store database can be found in the cookbook.
Configuring The Credential Store Database
To properly use the credential store database with OpenSocial gadgets, you need to make some modifications to the ACL of the database and create an encryption key for the database to use.
1. In the Domino Administrator client, open your server and select the Files tab.
2. Select the IBM_CredStore folder and right-click on the “OAuth Token Store” database (this is the name of the credential store database) and select Access Control -> Manage.
3. In the Access Control List, add your server's administrator ID and give it Manager access; then assign the ID to the [Admins] role.
Your server should already be in the Access Control List. Make sure you assign it the [Admins] role as well.
4. Click OK to close the ACL dialog.
5. Open the “OAuth Token Store” (credstore.nsf) database and select the Configuration view. You must do this with the administrator ID.
6. Click the button called Create Encryption Key (at the top of the view).
7. In the Create Encryption Key dialog, click the Create new encryption key button, and wait for confirmation that the key was created.
8. Click OK to close the New Encryption Key dialog; click OK again to close the Create Encryption Key dialog.
Note, there is no real indication in the database that the encryption key was successfully created, so do not worry if you don’t see any changes visually.
9. Close the OAuth Token Store database.
Configuring The Widget Catalog
There are a few things that need to be configured in the widget catalog in order to support rendering OpenSocial gadgets. The ACL of the database needs to be changed to have your administrator ID in it, and your administrator ID needs to be assigned to the [Admin] role. The catalog needs to be pointed to the location of the credential store database. Lastly, you need to enable a few agents in the catalog that must run in order to support OpenSocial gadgets.
1. In the Files tab of the Domino Administrator client, select the widget catalog you created, right-click, and then select Access Control -> Manage.
2. If your Domino server’s administrator ID is not already in the Access Control List, add it and assign it Manager access; then assign it to the [Admin] role.
3. Open the widget catalog with the administrator ID.
4. Select the Configuration view in the Administration folder.
5. In the Configuration view, click the Configure Credential Store button.
6. In the Configure Credential Store dialog, enter your server's canonical name (for example, myserver/mydominodomain), and the path to the credential store database (which should be IBM_CredStore\credstore.nsf). Alternatively, you can use the Browse button to pick the server and database.
7. Enable some agents in the Widget Catalog: With the Widget Catalog open in the Domino Administrator client click View -> Agents.
This opens Domino Designer to the Agents view. Alternatively you can open the Widget Catalog in Domino Designer, and then navigate to the Agents view yourself.
8. Enable the PushToCredStore agent: You can enable an agent by right-clicking the agent and selecting Enable.
When you enable an agent, you will be asked which server to run the agent on. Enter your server's canonical name (for example, myserver/mydominodomain) and click OK.
After enabling the agents, close the Domino Designer client.
Create A Managed Account
An SSO account needs to be created and pushed to the Notes client for use by the OpenSocial Component. In this section we will just create the account, we will add it to a policy that will push it to the client later.
1. Open the Domino Administrator client.
2. Open the names.nsf database from your Domino server.
3. Select People -> Policies -> Accounts in the database outline.
4. Click the Add Account button at the top of the Accounts view.
5. Click the Basics tab in the new account document.
6. In the Account name field, give the account a meaningful name.
7. Select Other from the selection dialog for the Account type field.
8. In the Account server name field, enter http:///fiesta/container; for example, http://myserver.mydomain.com/fiesta/container.
9. Select HTTP in the Protocol drop-down.
10. Choose Enabled from the selection dialog for the Use Domino single sign-on if available field.
11. Enter the host name of your server in the Domino single sign-on server field; for example, myserver.mydomain.com.
12. Select Disabled from the selection dialog for the Allow other accounts to use this log in information field.
13. Click the Advanced tab.
14. Click the down arrow next to the Authentication Type field.
15. In the selection dialog, enter DOMINO-SSO in the New Keyword field and click OK.
16. Make sure the Enforce SSL field is set to Yes.
17. Make sure the Enforce trusted sites field is set to Yes.
18. None of the fields on the Advanced tab should be set to Editable.
19. Click the Edit list button under the Add these name/value pairs to the Properties list section on the Advanced tab.
20. In the Item field, enter PreferredUsernameField.
21. In the Value field, enter fullname.
22. Click the Add/Modify Value
button and then click OK.
23. Click the Save & Close button.
Setting Up Policies
Create an Organizational policy with Desktop, Security, and Mail settings docs to enable OpenSocial support in Notes and iNotes.
1. Open the Domino Administrator client.
2. Select the People and Groups tab for your server and select Policies.
3. Click the Add Policy button at the top of the view.
4. On the Basics tab of the policy document, fill in the Policy name and Policy type fields. For the policy name you should put */dominodomain, where dominodomain is the Domino domain for your organization. For example if your Domino domain name is renovations, you would put */renovations.
5. For the Policy type field select Organization from the selector.
Create A Desktop Settings Document
1. In the Organization policy document, click New next to the Desktop field.
2. On the Basics tab of the Desktop settings document fill out the Name field. You can choose anything meaningful name you want, such as Desktop OpenSocial Settings.
3. Select the Widgets tab in the Desktop settings document.
4. In the widget catalog server field enter the canonical name of your server, such as myserver/dominodomain.
5. In the widget catalog name field, enter the name of the widget catalog NSF, such as toolbox.nsf.
6. Set the Gadget Server URL field to be the URL to your Domino server, for example http://myserver.mydomain.com.
7. For the Show the My Widgets panel in the sidebar field select Yes.
8. For the install Widgets from the catalog field select Enabled.
9. Adjust the rest of the fields as you see fit. Since this is a development server feel free to make everything as open as possible.
10. Select the Custom Settings tab in the Desktop policy document (you may have to use the arrow keys on the right hand side of the tab navigator to navigate to the Custom Settings tab).
11. Click the Notes.ini sub-tab.
12. Select the Edit list button.
13. In the Settings dialog enter ENABLE_EE in the Item field and 1 in the Value field. Also select Enforce and Set Initial Value.
Note: This step is only necessary if you are using a Notes 9.0 client. If you are not using Notes 9.0 you can skip to step 15.
14. Click the Add/Modify Value
button to store the setting.
15. Click OK to close the settings dialog. The Notes.ini sub tab should now look like this.
Note: If you upgrade all Notes clients in your organization to 9.0.1, the NOTES.INI setting ENABLE_EE=1 used in 9.0 is not required. If, however, you still have some clients running 9.0, continue to use a desktop settings policy to set ENABLE_EE=1 for all affected clients. Also, if you need to disable Embedded Experiences, you can set ENABLE_EE=0 in the policy. For more information, see the related topic on creating policies for the OpenSocial component. (source: What's new in IBM Domino 9.0.1 Social Edition?)
16. Click the Accounts tab in the Desktop policy document and then click the Update Links button.
17. Select All supported in the Accounts dialog and click OK. After clicking OK you should see the account you created above in the Account Links section.
18. Save and close the Desktop settings document.
19. Back in the Organizational policy document, select the new Desktop policy document you just saved from the selector for the Desktop Policy field.
Create A Security Settings Document
1. Open the Organizational policy document.
2. Next to the Security field click the New button.
3. On the Basics tab of the Security settings document fill out the Name field. You can use whatever name you would like.
4. Click the Execution Control List tab.
5. Click the Edit button next to the Admin ECL field.
6. In the Workstation Security: Execution Control List dialog, click the Add button.
7. Enter your Widget Catalog admin and make sure you give them the ability to configure Widget capabilities.
Your Widget Catalog admin should be your server admin; it was the user you added to the ACL of your Widget Catalog and gave the admin role to.
8. Click OK to close the dialog.
9. Save and close the Security settings document.
10. Back in the Organizational policy document, click the drop down next to the Security field and select the name of the Security policy document you just saved from the selector dialog.
Create A Mail Setting Document
For the Desktop settings to take effect in iNotes you need a Mail settings document as well.
1. Open the Organizational policy document.
2. Click the New button next to the Mail field.
3. On the Basics tab give the settings document a name.
4. Click the Save & Close button.
5. In the Organizational policy document click the down arrow button next to the Mail field.
6. Select the Mail settings document you just created in the selection dialog and click OK.
7. Save the the Organizational policy document.
8. Mail policies will be applied to iNotes users every 12 hours, so in order to have the policies apply immediately you need to run a command in the Domino servers console.
Go to the console and enter: tell adminp process mailpolicy
Configuration Settings
In the configuration settings document for your server we need to make some changes to configure the gadget rendering server. Some of the changes we make in this section can have security implications if untrusted 3rd party gadgets are going to be rendered in Notes or iNotes. However for a development environment, where you are only rendering gadgets you built, these settings should be fine.
1. Open your Domino Administrator client.
2. Go to the Configuration tab for your server.
3. Under the Server tree select the Configurations view
4. Click the Add Configuration button at the top of the view.
5. Select the Basics tab of the Configuration Settings document.
6. Select Yes in the Use these settings as the default settings for all servers field.
7. If you are using Domino 9.0.1 or later you will also need to select Enabled in the Configuration for Domino Server with Shindig field.
This will enable the Social Edition tab in the Configuration document.
8. Go to the Social Edition tab of the Configuration document and click the Basics tab.
9. In the Domain name for unlocked gadgets and content fetching field put the host name of your server (for example: myserver.mydomain.com).
10. In the Shindig server(s) host name field put the host name of your server (for example: myserver.mydomain.com).
11. If you are using a Domino 9.0.1 server or later select Disabled for the Locked domains field.
By selecting disabled you will not be able to enter anything in the Locked domain suffix field.
If you are using a Domino 9.0 server there will be no Locked domains field for you to disable; therefore in Domino 9.0 you can leave the Locked domain suffix field blank.
12. At this point the Locked domain suffix field should be blank and the Domain name for unlocked gadgets and content fetching field as well as the Shindig server(s) host name field should have the same value.
13. If you are using a Domino 9.0.1 server or later select Disabled for the Use HTTPS for OAuth redirect URLs field.
If you are using a Domino 9.0 server you will disable this in the next section.
If you are using a Domino 9.0 server, you should also follow the steps below to further configure the Social Edition tab of the Configuration document. If you are using a Domino 9.0.1 server or later you can save and close the Configuration document and skip to the next section.
1. Click the Advanced tab in the Social Edition tab of the Configuration document.
2. Click the shindig.properties tab.
3. Click the Set/Modify Parameters button.
4. In the Shindig Configuration Parameters dialog click the drop down arrow at the end of the Item field.
5. In the Select A Parameter dialog, select shindig.locked-domain.enabled and click OK.
6. In the Value field enter false.
7. Click the Add/Update button to add the configuration parameter.
8. In the Shindig Configuration Parameters dialog click the drop down arrow at the end of the Item field.
9. In the Select A Parameter dialog, select shindig.signing.global-callback-url and click OK.
10. In the Value field enter http://<Domino Server’s host name
/fiesta/gadgets/oauthcallback. For example, http://myserver.mydomain.com/fiesta/gadgets/oauthcallback.
11. Click the Add/Update button.
12. In the Shindig Configuration Parameters dialog click the drop down arrow at the end of the Item field.
13. In the Select A Parameter dialog, select shindig.oauth2.global-redirect-uri and click OK.
14. In the Value field enter http://
/fiesta/gadgets/oauth2callback. For example, http://myserver.mydomain.com/fiesta/gadgets/oauth2callback.
You should now have three configuration parameters set, one to disable locked domains, one to set the OAuth 1.0 callback URL, and one to set the OAuth 2.0 callback URL.
15. Click OK to close the dialog.
17. Save and close the configuration document.
Testing Your Environment
After the configuration is finished you should restart your Domino server to make sure all the configuration takes effect. To verify your configuration you can use the test gadget from the verification page in the cookbook. Follow the steps in the cookbook and the steps in the documentation linked from the cookbook to import the gadget into your widget catalog. Once imported you can go to your Notes or iNotes clients open the Widget Catalog and drag and drop to install it. After installed into the client right click to open it. Not all the tests will pass since your environment is not 100% secure but it proves that you can render a gadget.
Troubleshooting
If you are running into a problem after following the steps in this article please visit the troubleshooting section of the Cookbook. There you can search for numerous symptoms and corresponding solutions to the problem. Before visiting the troubleshooting section make sure you check the logs of your Notes or iNotes client and the Domino server. The troubleshooting guide will often times key off of errors in the logs.
Celebrate
You have finished configuring the OpenSocial Component for Notes and iNotes, take a break and celebrate your awesome accomplishment!