About the Author

Jon Machtynger - CTO, IBM Collaborations Solutions, UK and Ireland As CTO for IBM's Collaboration Solutions brand in the UK and Ireland, Jon helps define IBM's strategy to to support successful and innovative collaboration and social solutions. These cover a broad range of technologies and enable him to collaborate with many clients, business partners and internal communities across multiple industries. One particular interest area focuses on building novel solutions with our Research and Development labs. With a background in Commerce, Computer Science and Psychology, he has a keen interest in the balance between the requirements of business and the opportunities presented by the dynamics of people and technology.

Download PDF   

Introduction

In January 2013 some colleagues, providers of education services, and I were discussing the advantages and disadvantages of running both a Moodle and a SmartCloud experience in parallel. Moodle is an open-source platform widely used in the education space to support curriculum design, course structure and it promotes interaction with students in the context of their formal class membership. Although SmartCloud has been used to support education processes, including remote teaching, file sharing, and collaborate learning, the adoption of Moodle is already in place. Education establishments are therefore already focused on running their teaching processes through Moodle and decision has impeded the adoption of SmartCloud in some education contexts.

There are, of course, many benefits of SmartCloud over Moodle, for example:

• Cross-faculty and cross-school access of content
• Enterprise authentication (no VPN required)
• An ability to offer web-based lessons and meetings, and cross-platform application chat
• Seamless integration across tools and platforms such as Microsoft OfficeTM, Microsoft OutlookTM, and IBM NotesTM.

One approach to getting the best of both worlds is to combine aspects of Moodle’s and IBM’s open source approaches. That is, education establishments can still primarily interact through Moodle, but have access to SmartCloud content and functionality.

IBM is active in the open-source arena, and you can download IBM’s Social Business Toolkit SDK (SBTK), as well as a number of other open-source projects from www.openntf.org. The SDK is intended for web and Java developers and is continually expanded to accommodate feedback from testers and users. This has resulted in an ever-evolving set of APIs accessible from Java, Javascript, or straight HTML. This SDK makes it possible to provide access to Connections and SmartCloud from many environments. In this particular instance a fairly pervasive tool used by staff and students worldwide. Because the SDK toolkit can be hosted from many environments (Tomcat, WebSphere, Portal, for example), adopters of this approach have access to a very wide choice of architectural patterns and authentication approaches. As of June 2013, Moodle has a user base of over 83,000 registered and verified sites and almost 71 million users. With minimal effort, there could potentially be an additional 71 million users of Connections/SmartCloud.

While many universities see value in social or collaborative platforms, for proper adoption of these, ideas need to support their existing educational processes such as creation and delivery of course material, as well as processes used by students such as accessing and sharing content from very different platforms (Microsoft Office, Microsoft Windows ExplorerTM, and publically available social networks). This is where the potential conflict lies. With only so much time at one’s disposal, how can I as a user embed access to complementary services through a platform that is already part of my ‘day job’?

The approach taken in this article

I will start with an empty un-themed Moodle environment, and walk through the integration approach. I will then outline some code in Moodle, some code in the SBTK, and how we integrate the two. I will then describe how to customise the look and feel of the Connections content to suit the Educator's local environment.

There are a couple of ways to provide access to “Connections” content. I will also show how this can be configured to use both (even simultaneously). For demonstration purposes, I will use two publically-available Connections environments. The first is Greenhouse, which is the equivalent of an on-premises Connections environment but accessible in the cloud. Access to this is free and could be considered a testing area for many IBM Collaboration offerings. The second is the commercially available IBM SmartCloud for Social Business with guest and trial options. Links to both of these can be found in the references section at the end of the article.

You will be shown how to:
1) Create a Moodle block to access Connections files.
2) Create user-defined Moodle profile fields to customise your experience.
3) Connect to both Connections on premises and Connections in the cloud.
4) Theme your SBTK blocks (using CSS).

Assumptions

This is an introduction to integration options between Moodle and Connections, so I will only cover the basics. In summary:

• I will use Moodle 2.x , however you can use any Moodle version, subject to Moodle coding constraints.
• I will use the included SBTK ‘Playground’ to host our SBTK snippet code with the included Tomcat server. You could also deploy this against another Application server, but this is beyond the scope of this article.
• I will not focus on scalability, resilience, or high availability. While these are important topics for a deployment involving many thousands of students it is also beyond the scope of this article.
• Both Greenhouse and SmartCloud provide a Connections environment, so unless I refer to a specific instance or particular functionality, I will use Connections to refer to what is generally available in both. Otherwise, I will refer specifically to Connections on-premises or SmartCloud for Social Business.
• You will need accounts for Greenhouse and SmartCloud for Social Business. These are easy to get so if you do not have them, get them now and come back to this part in the article when you have access.

Proposed architecture

Figure 1 shows a simplified view of the proposed architecture. In summary, you add a custom Moodle block to your existing Moodle environment that exposes content contained in Connections. To access this content, I use the Social Business toolkit, which includes a standard Tomcat server.



Figure 1: A simplified architecture showing Moodle and Connections

The primary interface to Connections content is the Tomcat server, not Moodle. Therefore I use a Moodle block that points to routines contained within the Social Business Toolkit, which is hosted inside Tomcat. I do however, have some flexibility around how this content will be displayed even though Moodle manages the display interface.

Installation procedure(s)

Moodle installation

I assume that Moodle is already installed in your environment. If you do not have Moodle installed, there are a number of good guides on how to do this. This article assumes that you are adding capabilities to your Moodle installation without affecting anything you already have installed.

Make a note of your Moodle install directory ($MOODLE_HOME).

Installing the Social Business SDK

Download the SBTK zip file from http://ibmsbt.openntf.org. Extract the zip file and make a note of its location ($SBTK_HOME).

The SBTK already contains a Tomcat server, which requires a working Java Runtime Environment (JRE). Ensure you have one installed.

Change directory to $SBTK_HOME/tomcat, which contains a zip file of the tomcat server. The file will be called something like apache-tomcat-7.0.30-sbt.zip. Unzip that file. You will see a list of directories like this:


Figure 2: The contents of the apache-tomcat directory

The three directories of most interest are:

Point the SBTK at Connections

Use Greenhouse to point the SBTK at an IBM Connections repository:

Beneath the conf directory, edit the sbt.properties file.

Underneath the section headed Connections Basic Endpoint Parameters modify the connections.url parameter to point to the Greenhouse server.

Change:

which will result in output like this:


Figure 3: Configuring the Connections Endpoint to point at Greenhouse

Start Tomcat

Start the Tomcat server. The shell scripts within bin are not executable by default, so change their mode to 755, and start Tomcat by running startup.sh as follows:


Figure 4: Making the shell scripts executable and starting Tomcat

You will see the environment variables being set, and if your Java process is running, you will be able to go to http://localhost:8080 and see the Samples application page (Figure 5).

Working with the Samples Application

Figure 5: The Samples application available from Tomcat.

Click on the Toolkit Samples button. You will see the "playground", which allows you to look at, and play with SBTK snippets in either JavaScript or Java.


Figure 6: The Toolkit Samples entry point.

Click on the word ‘Javascript’, to enter the playground. Open the Authentication entry in the tree on the left hand side and choose ‘Connections Basic Auth’, where you can now test connectivity to Greenhouse.



Figure 7: The layout of the SBTK playground

The three areas to highlight are:
(1)The snippet tree on the left hand side, which lets you choose snippets to play with.
(2)The actual snippet code in the top right half of the screen
(3)The output of the snippet code.

Choose ’Connections Basic Auth’, and then click on Login Popup, which will prompt for Greenhouse credentials.


Figure 8: Testing Greenhouse connectivity.


You will see the status in the snippet code output section change to a message showing that you are now authenticated (Figure 9).

Figure 9: A successful authentication.

Lastly, test that you can get a list of the files stored in Greenhouse. Choose the ‘Connections’ main section on the left, and then beneath ‘Files’, choose ‘Get My Files’.


Figure 10: Testing that we can see our Connections Files.

The output is not well formatted but it does provide real data. The SBTK simply provides sample snippet code to show you how to access the APIs in the context of your Connections content, but in practice you would probably customise it to suit your own requirements, with your own style sheets. With this in mind, I have written my own snippet code, which I will add to the Sample snippet directory accessed directly from Moodle.

Adding additional SBTK snippets

As you have seen, the SBTK comes with a number of sample snippets. Now add a couple more to give you something better to customise.

Extract the file MoodleSnippets.zip into the $SBTK_HOME/tomcat/apache-tomcat-7.0.30/webapps/sbt.sample.web/samples/js directory.
If you go back to http://localhost:8080/sbt.sample.web/javascript.jsp, it will now have a Moodle sub-directory, and a number of useful routines. I have taken the sample snippets and made them a little prettier. Each snippet has a Javascript routine as well as an optional HTML file, which I discuss in more detail later.


Figure 11: The contents of the Moodle snippets directory.

Building a Moodle block to call our SBTK routines

There are a number of ways of adding functionality into Moodle and we will use Blocks for the following reasons:

• Existing Moodle environments do not need any customisation. A Block can simply be copied into the Moodle’s blocks directory and the administrator can enable it.
• Individual Blocks can be added/enabled or removed/disabled in parallel, so the combination of Connections functionality you use is flexible.
• Each Block can be customised in isolation. You may want Blocks that do very specific things for different users, or that look differently for different communities. For example, Blocks that access external (e.g. SmartCloud) content might obviously highlight this, say with a particular theme to let people know that this content is not ‘internal’.

Because there are many publically available guides to show how to create a Moodle Block, I will only explain what you need to know to get the basics of the Block working.

In Figure 12 , you can see the constituent files from a block that I have called icfiles. The db/access.php file dictates what your block is allowed to do, and the lang/en/block_icfiles.php provides English specific descriptions for your Block that is visible in your Moodle installation. Here also is where you customise how the names of your blocks are referenced in a user-friendly manner.


Figure 12: The Connections 'Files' block code (blocks/icfiles)


Listing 1: Access rights provided for the Connections Files Block (db/access.php):

Listing 2: Language specific descriptions for your Block (lang/en/block_icfiles.php):







Let us look at the PHP block code and then I will summarise what it does.

Listing 3: A very simple Moodle block:



Table 1: Notes to describe the main Block's source code.

4	A Javascript function that forces a refresh when the drop-down value changes.
34	The Block header description is pulled from lang/en/block_icfiles.php
64	This variable allows you to selectively retrieve content from either a Connections or SmartCloud environment. I describe later how to create a user profile field.
68	The beginning of the HTML form containing my drop-down selector and the ordered list containing my files.
72	The drop-down with a call to the refresh routine on a change of value
74	The first or each of the available options. Note the following: The value is the URL of the SBTK routine that needs to be called to populate the file list. The URL contains a reference to the environment (&env=…) containing the files. Namely, Greenhouse or SmartCloud for Social Business.
86	The content is shown as the output of an iFrame. This has a number of implications. Firstly, any theming/skinning that Moodle controls is not passed to the iFrame content. Secondly, the Moodle HTTP session and the iFrame’s Tomcat HTTP session are different, so even if you are logged into your Connections environment on a different Browser session, you need to provide a log in via Tomcat as well. We can remedy this using a single-sign-on approach via OAuth or a SAML login, but this is beyond the scope of this article.
88	This is the default output for the block (i.e., show My Files).

This is what the block does:

• By default, show files I have stored in my Connections repository.
• Provide a drop-down selector where I can choose whether I see ‘My Files’, ‘Files Shared with Me’, or ‘Files Shared by Me’.
• Get me the content from my preferred Connections environment (on-premises Connections or SmartCloud for Social Business).

Analysing the SBTK Snippet

The Moodle Block selectively exposes the Connections capability to a Moodle user. However, the hard work of getting the content is done by the SBTK snippet. Let us walk through the snippet that gets My Files.

Listing 4: The SBTK Snipper to get 'My Files':



Table 2: Notes to describe the snippet's source code:

2	Load pre-requisite libraries for FileService
4	Define a variable to call those capabilities
6	Execute the getMyFiles routine returning at most 100 entries.
10	If there are no values, you do not have any files
16	Create an ordered list in HTML
20	For each valid file, create a child entry to contain the ordered item
34	The display name is the first 25 characters of a file name with a ‘…’ suffix if it is long
42	Build up an HTML tag so if a user clicks on the file they are prompted to download it
56	Provide a place to show an error message

Loading the Moodle Block Code into your Environment

Copy and Configure the Moodle Block Code

Extract the contents of the MoodleBlocks.zip file and copy the icfiles directory into $MOODLE_HOME/blocks. As a Moodle administrator you will see the following:


Figure 13: Moodle is now aware of the new Block.

Click on the Upgrade Moodle database now button. If you now go to Site Administration -> Plugins -> Blocks -> Manage Blocks, you will see a new Connections Files Block available.


Figure 14: And the new Block is now available to be used.

To make the block accessible in your environment, as the administrator go into Front page settings -> Turn editing on. In the lower left hand side of the screen, you will see a block containing a drop down titled Add a block. It provides a list of available blocks, and the Connections Files Block is one of them (Figure 15 ).


Figure 15: Making your new block visible.

Add it, and you will probably see a Certificate security error (Figure 17).


Figure 16: Your Tomcat host is untrusted.


Right click within the block and open that frame in a new Tab or browser window. You will then see the whole block and can provide an exception to the security warning.


Figure 17: Adding a security exception.

You will then see the Connections Files block half hidden by the block format. Enter your login credentials and click on the Log in button. In the block (Figure 19 ) you can now see an ordered list of My Files.


Figure 18: You now have a login prompt.


Figure 19: Once logged in, files are visible.

You can now add additional blocks for Communities, since this source is also available in the code from this article. You will now customise your experience.

Customising your blocks and Moodle

In Figure 20, you can see that the file list is returned in a green font. Moodle is responsible for its own theming, but it has no control over the SBTK snippet experience. Remember that the content is returned within an iFrame and is therefore not really running within Moodle, but remotely within Tomcat. This is however, easy to resolve. Each snippet is written in Javascript, but you can also provide a corresponding HTML file. This file can be used for example, to build a form or table to contain content, but I have used it to embed some CSS theming. Because my default theme is the Moodle Boxxie theme, I borrowed values from its CSS files. Now my Moodle theme and the Connections content look and feel the same.

Listing 5: The associated HTML file can also be used to host CSS styling:



Here is a screen shot of my (empty) Moodle environment containing properly themed Files and Communities blocks.


Figure 20: Themed blocks seamlessly blend into your Moodle experience.

Adding Moodle Profile Fields

Every Moodle user has a profile, which allows them to provide information such as full name, Skype ID, Mobile number, and photo. As an administrator, you can also include additional profile fields; this gives you much flexibility around how you exploit the capabilities in SmartCloud or Connections. For example, I have yet another SmartCloud Block where users can open SmartCloud meetings, or join regular class webinars. I have set these values up as Profile fields. These are user specific, so a lecturer or student can host his or her own meeting without having to remember their value, or even go to the SmartCloud home page.

Here, I use a Profile Field to set the default Connections repository. In this case, we are using Greenhouse, or SmartCloud for Social Business.

Guidance on how to add user-defined fields can be found here: http://docs.moodle.org/20/en/User_profile_fields. In summary however, you add user-defined fields as the administrator by going to Settings -> Site Administration -> Users -> Accounts -> User Profile Fields -> Create new Profile Field.

First create a new Profile Category called IBM Connections.
Then create a new Profile Field of type Menu of Choices.
The short name will be IBMICSC
The Name will be Connections Repository
Set your category to be the IBM Connections category you just created
Your menu options will be:

Set your default environment to be defaultEnvironment

Go into My profile settings -> Edit profile where you will see an option to define your Connections point as either Connections (on-premises) or Connections (SmartCloud). The variable IBMICSC is referenced in the block code shown in Listing 4 (note 4 from Table 2 ).


Figure 21: You can now choose your default Connections environment.

The configuration required to access this has already been included in
$SBTK_HOME/tomcat/apache-tomcat-7.0.30/webapps/sbt.sample.web/WEB-INF/managed-beans.xml. We will now examine the default managed-bean.

Listing 6: The default managed-bean:

This is your default Basic authentication environment to an on-premises Connections site. There is also another environment set up to allow Basic authentication to SmartCloud. Note that this is different from the OAuth and OAuth2 approaches you might want to consider. Here you’re using basic authentication with a user name and password.

Listing 7: The SmartCloud basic environment allowing basic authentication.




To use the smartCloudBasicEnvironment, append &env=smartcloudBasicEnvironment to URLs calling your snippets. You can also see this in Listing 3 (note 74 from Table ). where the $ICSCEnv variable is referenced. Now when you change your Connections Repository to SmartCloud, you will be prompted again for a login, but the content will come from your SmartCloud account (Figure 22 ).


Figure 22: My Moodle site now returns my SmartCloud files and communities.

You are not just restricted to using a single repository since you can use multiple blocks at the same time. Just copy an existing block and modify the name. Then you can show information from multiple Connections repositories simultaneously.

Conclusion

People are creatures of habit, and while Connections and SmartCloud for Social Business offer excellent capabilities, embedding these capabilities into existing day-to-day activities is key to helping them be used. In this article, I showed how simple it is to add these capabilities from multiple repositories and theme them to fit into your existing environment. In principle, users of Moodle need not be aware that the content is not part of an existing University infrastructure.

References and Links

Moodle description on Wikipedia:
https://en.wikipedia.org/wiki/Moodle

Get the Social Business Toolkit:
http://ibmsbt.openntf.org/

A step by step guide to creating a Moodle Block:
http://docs.moodle.org/dev/Blocks

Social Business Toolkit Documentation:
https://www.ibmdw.net/social/documentation/

Social Business Toolkit Playground:

https://greenhouse.lotus.com/sbt/SBTPlayground.nsf/Home.xsp

Register for a Greenhouse account:
http://greenhouse.lotus.com and then choose ‘Sign Up’ in the top right corner.

Register for a Trial SmartCloud for Social Business Account:
https://www.ibm.com/cloud-computing/social/us/en/startatrial/

Download the code for the blocks and snippets used in this article here:
Moodle Blocks
Moodle Snippets

 

Thanks/Credits

Getting to this solution wasn't as intuitive as it could have been and the SBTK has evolved during the period of this article. I'd like to recognise the help of the following in the Dublin Development Lab.

• Andrew Penrose
• Fred Raguillat
• Mark Wallace
• Michael Bowler