8 Apr 2008
Running Alfresco web scripts as Liferay portlets
I’ve seen a lot of Liferay and Alfresco forum posts from people having trouble getting Alfresco running within a Liferay portal. Once that’s done, people usually want to invoke Alfresco web scripts as portlets without requiring a separate single sign-on (SSO) infrastructure. Some people have pointed to the Alfresco wiki (Deploying 2.1 WAR Liferay 4.3). That is a helpful reference but it isn’t the full story. Here are some notes that may help.
1. Download the Liferay 4.3.6 + Tomcat 5.5 JDK5 bundle. I had mixed results with the latest release 4.4.2. You may be tempted to try to download the WAR-only distribution and configure it in your existing Tomcat instance. In this case, save yourself the time and headache and get the bundle. Fool with the WAR distribution later.
2. Unpack the Liferay distribution and fire it up. Make sure you can log in as the email@example.com (password: test) user to validate that all is well with the Liferay install.
2a. Create a test user. (“Create Account” on the Liferay login screen). Remember the email address. This will matter shortly. For this discussion I’ll assume Foo User with a screen name of fuser and an email address of firstname.lastname@example.org. Make sure you create a home directory. In this example, we’ll call it “fuser”.
2b. Verify that you can log in as your test user.
3. Shut down the server.
4. Download Alfresco 2.1.2 Enterprise, WAR only. Alfresco 2.1.1 has a known issue (AWC-1686) with the way authentication is handled for web scripts in the context of Liferay so make sure you are using 2.1.2.
5. Expand the Alfresco 2.1.2 WAR into the Tomcat webapps/alfresco directory (which you’ll have to create the first time). If you are tweaking the install (such as pointing to a specific MySQL database, using something other than MySQL, pointing to a different data directory, etc.) make sure you have copied your good set of extensions into Tomcat’s shared/classes/alfresco/extension directory.
6. Copy the MySQL connector into Tomcat’s common/lib directory.
7. Start Tomcat. When it comes up, you’ll have Liferay running and you’ll have Alfresco running, but Liferay doesn’t yet know about Alfresco. Verify that you can log in to Alfresco as admin.
7a. While you are here, create a test user account. You need to create a user account that has an email address that matches the test user account you created in Liferay. In this example you created Foo User with a screen name of fuser and an email address of email@example.com so you need to create an Alfresco user with the same settings. You’ll log in to Alfresco as fuser. You’ll log in to Liferay as firstname.lastname@example.org.
7b. Verify that you can log in to Alfresco as fuser.
8. Shut down Tomcat.
9. Now you need to configure Alfresco as a Liferay plug-in. This involves adding four files to Alfresco’s WEB-INF directory: liferay-display.xml, liferay-plugin-package.xml, liferay-portlet.xml, and portlet.xml. Why aren’t these available in the Alfresco source or on the wiki? Apparently someone tried to address this at some point because there is a link on the wiki but it is broken. Until that’s addressed, I’ve put them here.
10. Remove the portlet-api-lib.jar file from Alfresco’s WEB-INF/lib directory.
11. Re-package alfresco.war. It is now ready to hand over to Liferay.
12. Start Tomcat.
13. Find your Liferay deploy directory. If you are running out-of-the-box on Linux, Liferay’s “deploy” directory is called liferay/deploy and it resides in the home directory of the user who started Tomcat. I’m running it as root so my Liferay deploy directory is /root/liferay/deploy.
14. Copy the alfresco.war you just created into the deploy directory. Watch the log. You should see Liferay working on the WAR. He’s finding the plug-in config files and essentially deploying the Alfresco portlets.
15. Now log in to Liferay using the Liferay admin account (email@example.com). Go to a page, then use the global navigation dropdown to select “Add Content”. The list of portlets should appear and you should see the “Alfresco” category. If you don’t, look at the log because something is amiss. Add the My Spaces portlet to the page. You may see an error at this point but ignore it. The problem is you probably don’t have a user in Alfresco that has an email address of “firstname.lastname@example.org”, which is the currently-logged in user.
16. Log out.
17. Log in as your test user that exists in both Alfresco and Liferay (email@example.com).
18. Go to the page. You should see the “My Spaces” portlet. You should be able to upload content, create spaces, etc.
Exposing your own web scripts as portlets
All Alfresco web scripts are automatically exposed as JSR-168 portlets, including the ones you create. To add your web scripts as portlets, first make sure you have authentication set to “user” and transaction set to “required” in your web script’s descriptor. Then, update portlet.xml, liferay-portlet.xml, and liferay-display.xml. Follow the pattern that’s in those files already and you’ll be fine. For example, if you deploy the Hello World web script from my web script tutorial, you need to add a new portlet to portlet.xml with a “scriptUrl” like: /alfresco/168s/someco/helloworld?name=jeff. Then you update liferay-portlet.xml and liferay-display.xml with the new portlet name or portlet ID.
Single sign-on with no single sign-on?
The web script runtime has a JSR-168 authenticator. So when your web scripts get invoked by the portlet, the current credentials are passed in. That’s why your web script can run without requiring an additional sign in. Prior to this being put in place, people had to implement Yale CAS (or an equivalent) to get SSO between Liferay and Alfresco web scripts.
What’s not covered in these instructions is that you’ll probably want to (1) configure both Alfresco and Liferay to authenticate against LDAP and (2) change the configuration of either Alfresco or Liferay to use the same credential (either username or email address) for both systems so that if you do have users logging in to both, they don’t have to remember that one requires the full email address but the other doesn’t.
If you see one of the Alfresco portlets displaying “Data is not currently available” or somesuch, try hitting
Alfresco in another tab. Log in, then log out. Then go back to the
portal and open the page again. It should work now. I’m not sure what’s going on there. I think it may have to do with me switching back-and-forth between Liferay instances (4.3.2 versus 4.4.2) so maybe you won’t see it.
You may see an error like this:
21:22:15,965 WARN [BaseDeployer:1038] Unable to format /usr/local/bin/liferay-4.3.6/temp/20080408212212978/WEB-INF/faces-config-jbpm.xml: Error on line 5 of document file:///usr/local/bin/liferay-4.3.6/temp/20080408212212978/WEB-INF/faces-config-jbpm.xml : A ‘)’ is required in the declaration of element type “application”. Nested exception: A ‘)’ is required in the declaration of element type “application”.
I haven’t chased that down yet. I’ll update this post with a comment when I find out. I’m sure fixing that will also fix the problem that you’ll see if you try to start an advanced workflow from a piece of content displayed in the My Spaces portlet.
I was also seeing an error when trying to use the “Add Content” link in the straight Alfresco client. I think it is JSF-related. Again, I’ll update this post with a comment when it is resolved (or when I find a Jira ticket).