Using External Repositories

Adding repositories in Documents and Media is a new feature in Liferay 6.1. Content Management Interoperability Services (CMIS) is a specification for improving interoperability between Enterprise Content Management systems. Documents and Media allows users to connect to multiple third-party repositories that support CMIS 1.0 with AtomPub and Web Services protocols.

Some of the features supported with third-party repositories include:

• Reading/writing documents and folders
• Document check-in, check-out, and undo check-out
• Downloading documents
• Moving folders and documents within the repository
• Getting revision history
• Reverting to revision

There are some subtle differences in setting up the different kinds of third-party repositories for use in Documents and Media. But there are plenty of similarities too.

Common Liferay configuration steps:

• Adjust the portal properties.
• Add any user accounts required by the repository.
• Add the repository.

Lastly, keep in mind your third-party repository may require installation and deployment of an appropriate Liferay plugin. Plugins for SharePoint and Documentum are available through Liferay’s Marketplace.

Let’s go through those steps, starting with setting our portal properties.

Adjusting Portal Properties

The admin must ensure that the same credentials and authentication are being used in Liferay and in the external repository. This is normally synchronized using a mechanism like LDAP. If you don’t have LDAP, you need to ensure manually that the credentials and authentication are the same. In order to authenticate with the third-party repository, you need to store passwords for the user sessions. Set the following portal property in your portal-ext.properties:

session.store.password=true

Next, we need to make sure the login and password for Liferay are the same as the external repository. This is easily accomplished by using identical screen names, so in portal-ext.properties add the following:

company.security.auth.type=screenName

Alternatively, configure these properties in the Control Panel under Portal Settings → Authentication.

Adding Required Repository Users

Once these properties are set, you must create a user in Liferay with a screen name and password matching the administrative user of your external repository. Be sure to assign appropriate roles (e.g. Administrator) to that user. Sign out of Liferay and sign in again as that new user. See sections of the Management chapter on adding and managing users.

Adding the Repository

You can add new repositories from the UI by clicking the Add button from the Home folder. Repositories can only be mounted in the Home folder.

Figure 4.7: Adding a new repository

All fields in this form are required, except for Repository ID. Leave this field blank, and a repository ID is automatically generated by the system.

When finished, the repository is displayed in the left side of the window in the Home folder.

Figure 4.8: Viewing a repository

Using this information, we can now add an example repository. As noted previously, there are several repositories that work well with Liferay using CMIS. One that is familiar to many users is SharePoint. In the exercise below, we’ll set up SharePoint as a Documents and Media repository.

Example Repository Setup: SharePoint

With Liferay Portal you can connect to an external SharePoint server and add it as a Documents and Media repository. This lets users collaborate and share documents more easily between both environments. We will mount a SharePoint repository via CMIS AtomPub and SharePoint SOAP web services.

Liferay uses a combination of SOAP and Representational State Transfer (REST), based on the Atom convention, to connect to the SharePoint repository. SharePoint provides various SOAP services for modifying and querying data from its document library. Liferay uses Axis2 to generate SOAP calls to the SharePoint server.

To use SharePoint as a Liferay Documents and Media repository, we’ll do the following:

• Configure the CMIS Connector on SharePoint.
• Activate a SharePoint site as a CMIS Producer.
• Acquire your SharePoint document library’s repository ID.
• Enable Basic Authentication on the SharePoint host.
• Add SharePoint as a Liferay Documents and Media repository.

Note that this section is geared towards portal system administrators and SharePoint system administrators.

Before you can use SharePoint as an external repository with Liferay portal, you must verify that SharePoint is properly configured. Several services must be set up on the SharePoint server before synchronizing with Liferay.

Configuring the CMIS Connector on SharePoint

SharePoint utilizes a CMIS Connector and a CMIS Producer to interface with Liferay Portal. The Connector is installed with the SharePoint Administrator Toolkit using a solution package called a Windows SharePoint file (.wsp). If you don’t have it already, install the SharePoint Administrator Toolkit for its CMIS Connector. Install and deploy the CMIS Connector as a Farm Solution on SharePoint.

The folder Content Management Interoperability Services (CMIS) Connectors contains the spscmis.wsp file. Choose the appropriate deployment settings and deploy that file. When deployment completes, Solution Properties shows the solution is successfully deployed to all target sites. Now it’s time to configure the CMIS Producer.

Activating a SharePoint Site as a CMIS Producer

The Producer makes SharePoint repositories available through the CMIS Connector. Choose the SharePoint site containing the document libraries to be used as document repositories. Every document library in this site is made available as a repository through the CMIS connector.

Go to Site Actions → Site Settings → Manage Site Features. Enable the Content Management Interoperability Services (CMIS) Producer by clicking Activate.

Now any document library created under this site is CMIS enabled. Before we leave our SharePoint console, let’s take note of our SharePoint document library’s repository ID.

Acquiring the SharePoint Document Library’s Repository ID

Acquiring your SharePoint document library’s repository ID, or list ID, is important as it must be specified in the AtomPub URL Liferay uses to connect with the external repository. Finding it, however, can be a little confusing. The easiest way to find the repository ID is by accessing the SharePoint repository using a browser such as Mozilla Firefox.

Follow these steps to get the repository ID:

1. In SharePoint, open the desired library.

2. Under Library Tools select Library.

3. Click on Library Settings, located to the far right.

4. The browser window refreshes displaying the repository ID between curly braces ‘{’ and ‘}’ in the browser’s address bar.

   

   Figure 4.9: The repository ID can be found by displaying the repository's URL in a Firefox browser.

   The repository ID is highlighted in the figure above. For this example, the repository ID is 6DFDA9-B547-4D1D-BF85-976863CDF533. Therefore, the AtomPub URL you’d use when adding this repository in Documents and Media would resemble this:

    http://liferay-20jf4ic/CMIS/_vti_bin/cmis/rest/6DFDA9-B547-4D1D-BF85-976863CDF533?getRepositoryInfo.
   

Be sure to copy down this URL so you can use it to configure SharePoint as a repository in Documents and Media. Next, let’s enable Basic Authentication on the SharePoint host.

Enabling Basic Authentication on the SharePoint Host

For the CMIS connector and producer to work, Basic Authentication on IIS must be enabled. This lets Liferay’s SharePoint hook authenticate against the SharePoint web services. Enable Basic Authentication on your SharePoint host.

You are now prepared to mount SharePoint as an external repository.

Adding SharePoint as a Liferay Documents and Media Repository

With the SharePoint server configured, we now turn our attention to Liferay. As mentioned in the common steps for adding an external repository, be sure to adjust the portal properties and add any user accounts required by the repository.

Here are the steps specific to configuring Liferay to use SharePoint:

1. Download and install the SharePoint hook from Marketplace. See the Downloading and Installing Apps section of the Leveraging the Liferay Marketplace chapter of this document for more information.

2. Add the Documents and Media portlet to a page, if you haven’t done so already.

3. In the Documents and Media portlet click Add Repository and enter the following information:

   Name: Enter an arbitrary name for the repository.

   Description: Describe the repository.

   Repository Type: Select SharePoint (AtomPub).

   AtomPub URL: Enter the applicable URL using the format below, substituting the SharePoint server’s host name for [host] and the SharePoint document library’s repository ID for [repository ID]:

    http://[host]/CMIS/_vti_bin/cmis/rest/[repository ID]?getRepositoryInfo
   

   Repository ID: Leave this field empty. Liferay searches for the first repository using the given parameters and sets this value to that repository’s ID.

   Site Path: Enter data using the format below, the SharePoint server’s host information for [host] and the SharePoint document library’s repository name for [repository path]:

    http://[host]/[repository path]
   

4. Click Save.

The left navigation panel of your Documents and Media portlet now lists your new repository.

Tip: In the site path example below, notice how the repository path has a folder Shared Documents consisting of two words.

http://liferay-20jf4ic/CMIS/Shared Documents/Forms/AllItems.aspx

The space between the words in the repository name must be accounted for when setting the site path in Liferay. Replace the empty space with the string %20 so the site path value now looks like this:

http://liferay-20jf4ic/CMIS/Shared%20Documents/Forms/AllItems.aspx

This should be done for any multi-word repository name.

Remember that connecting to an external SharePoint server and adding it as a Documents and Media repository is a great way to give users flexibility for sharing and collaborating on Microsoft Office documents.

To further enhance your use of Microsoft Office documents with Documents and Media, Liferay provides integration directly with Microsoft Office. Let’s look at that next.