Alfresco CMIS: Learn how to build applications that talk to content management servers in a standardized way using this superb course on getting the best from Alfresco CMIS. This is a highly practical, step-by-step guide.

Before we start, we are going to need a CMIS server to talk to. There are a number of ways to get access to a CMIS server. You can, for example, install your own or use one that is available on the Internet. Actually, it is best to install your own so that you can have some control over it and you have the confidence that there are not loads of other users doing stuff at the same time as you.

We will focus on the Alfresco content management server in this book, but all the exercises should work with any other CMIS-compliant server too. However, if you use another CMIS server, remember that it will have a different entry point URL than Alfresco's (different from, for example, http://localhost:8080/alfresco/cmisatom).

So we now have an Alfresco CMIS server that we can talk to. Next, we need a tool that can be used to make HTTP requests to the server. We are going to test the AtomPub and Browser CMIS bindings, which are based on the HTTP protocol and the back and forth sending of XML and JSON.

One really good tool that can be used for this is cURL; it is available for most platforms. On my Ubuntu laptop, I can just use the #sudo apt-get install curl command to install it. On Windows, you can download cURL from http://curl.haxx.se/download.html. If you are on a Mac, then Apple has a different version of cURL as part of the developer tools; it's also available through Homebrew using brew install curl.

Later on, in this chapter, we will also look at using the Chrome browser to view XML and JSON responses and some other command-line tools to parse and display XML and JSON.

When using the AtomPub binding or the Browser binding, authentication is delegated to the transport protocol, which is HTTP. All CMIS-compliant servers must, at the very least, support client authentication using the HTTP Basic authentication schema. We will use this in the following examples. If the server is Alfresco, the alternative is to use the Alfresco login service. As this is not supported by other servers, we will stick to the HTTP Basic authentication, which is portable.

The curl tool can handle Basic Auth for us automatically; we just have to pass the username and password, as follows, with the -u switch when we use curl:

$ curl -u admin:admin

If you are going to work only with Alfresco, you can log in and get a ticket that you can use in subsequent calls as follows:

$ curl "http://localhost:8080/alfresco/service/api/login?u=admin&pw=admin"
<?xml version="1.0" encoding="UTF-8"?>
<ticket>TICKET_39ea5e46e83a6d6e43845182f4254f9de50402fb...

To execute any other operation against a CMIS repository, we first need to find out its identifier, access points, and capabilities. The identifier is used when we want to connect and get a session to work within. It is also important to know the capabilities of a CMIS server, as not all requirements in the CMIS specification are mandatory, and the capabilities tell us what the repository supports and what it doesn't. The access points tell us how to, for example, get access to the top-level folders in the repository. All this information is accessible via the getRepositoryInfo service call.

Before we look at how to get repository information when using the AtomPub or the Browser binding, we will walk through the different properties that we will encounter and explain them. They are the same for all bindings, so it makes sense to describe them before looking at protocol-specific stuff.

The repository ID, identified by the repositoryId property, is usually needed...

After we have the information about the repository via the getRepositoryInfos service, we would typically want to access some folders and files in it. First, you would usually access the children of the top-level folder (also called root folder) in the repository, and this can be done via the getChildren service. This folder is called /Company Home in the Alfresco world.

The getChildren request returns a list of all the folders and files contained in a particular folder. This call has to be supported by the repository, but there are other navigation-related service calls too that might or might not be supported. The getDescendants call will return all the children of a folder to a specified depth. The getFolderTree call will return a complete folder tree to a specified depth (note that only folder objects are returned).

The repository information's call will return information on the navigation service calls that are supported besides the getChildren...

The getChildren service call allows us to specify a number of optional parameters at request time. To control the number of content items that are being returned, one can use the following parameters in the request URL:

These paging input parameters work in parallel with the following output parameters in the response:

When we are working with a repository, it is important to be able to find out what types are available so that we can classify documents and folders properly. One of the first things to do in a CMS project is to design a domain-specific content model so that content can be classified appropriately. A proper content model improves the search capabilities and enables specific behavior to be implemented based on the type of content.

The getTypeChildren service is used for listing types. This service call can also use the paging parameters that the getChildren service call uses, such as maxItems. The type listing will contain a type definition with information about each type. From the type definition, we can determine whether new objects can be created from this type (cmis:creatable), objects of this type are fileable (cmis:fileable) in a folder, you can search for the objects of this type by including the type in the FROM clause (cmis:queryable), and whether...

We now know how to list the contents of a folder. What we would want to do next is to probably download content files and list metadata (that is, properties) for individual content items.

<cmisra:uritemplate>
<cmisra:template>
http://localhost:8080/alfresco/cmisatom/f0ebcfb4-ca9f-4991-bda8-9465f4f11527/id?id={id}&filter={filter}&includeAllowableActions={includeAllowableActions}&includeACL={includeACL}&includePolicyIds={includePolicyIds}&includeRelationships={includeRelationships}&renditionFilter={renditionFilter}
</cmisra:template>
<cmisra:type>objectbyid</cmisra:type>
<cmisra:mediatype>application/atom+xml;type=entry...

After you have listed content (that is, CMIS objects) in the repository, you would probably want to be able to create, update, and delete content. This is handled via the CMIS object services.

The following table gives you an overview of the available object service calls that are related to creating the content of different types:

In this chapter, we have gone through most of the basic functionalities that are likely to be used on a day-to-day basis and learned how to use them with both the AtomPub protocol and the Browser binding protocol. We have seen how we can list the contents of a folder and navigate to the subfolders. The Browser binding has shown us that it is quite easy to work with CMIS via this binding as you can use HTML forms for almost all operations and it is easy to integrate with the UI this way.

In this chapter, we also looked into how to download the content types that the repository supports, which is important as you are likely to set custom types when uploading new content. We also covered how to create, read, update, and delete documents and folders for a specific domain. And finally, we went through how to download a document.

In the next chapter, we will look into more features supported by CMIS such as version management, access control, and searching for content.