To access a remote web service instead of a local one in your code you need to add a file called webserviceclient.properties to the classpath

webserviceclient.properties

If you're accessing the web service from your own web application then you need to place webserviceclient.properties in WEB-INF/classes/alfresco/webserviceclient.properties for it to be picked up properly.

Create a java class called AlfrescoCreateUser with a main method public static void main(String[] args) throws Exception { AlfrescoCreateUser alfTest = new AlfrescoCreateUser(); alfTest.createUser(); }

Copy the createPersonProperties method from the AdministrationServiceSystemTest in the web service client code /** * Taken from AdministrationServiceSystemTest in the web service client. */ private NamedValue[] createPersonProperties(String homeFolder, String firstName, String middleName, String lastName, String email, String orgId) { // Create the new user objects return new NamedValue[] { new NamedValue(Constants.PROP_USER_HOMEFOLDER, false, homeFolder, null), new NamedValue(Constants.PROP_USER_FIRSTNAME, false, firstName, null), new NamedValue(Constants.PROP_USER_MIDDLENAME, false, middleName, null), new NamedValue(Constants.PROP_USER_LASTNAME, false, lastName, null), new NamedValue(Constants.PROP_USER_EMAIL, false, email, null), new NamedValue(Constants.PROP_USER_ORGID, false, orgId, null)}; }

You need to set the user properties and get an authentication token using the admin access details. The code below creates a user called test with a home space also called test under Company Home -> User Homes /** * Creates the user test with a home space in Company Home. */ public void createUser() { String login = "test"; String password = "password"; String homeFolder = "://app:company_home/cm:" + login; String userName = "test"; String userMiddlename = ""; String userSurname = "Test"; String userEmail = "test"; String userOrg = ""; try { AuthenticationUtils.startSession("admin", "admin"); AdministrationServiceSoapBindingStub administrationService = WebServiceFactory.getAdministrationService(); NewUserDetails newUser = new NewUserDetails(login, password, createPersonProperties(homeFolder, userName, userMiddlename, userSurname, userEmail, userOrg)); administrationService.createUsers(new NewUserDetails[] { newUser }); } catch (AuthenticationFault f) { System.out.println("Administration Fault"); f.printStackTrace(); } catch (RemoteException e) { System.out.println("RemoteException"); e.printStackTrace(); } finally { AuthenticationUtils.endSession();> } System.out.println("User created successfully"); }

Run the class and check that the user has been created successfully.

Whoops, you’ve inadvertently done something Very Bad to your Alfresco install and the application throws a fit about the indexes when you try to start it up.  There’s a problem with the database data and the lucene indexes being out of synch.

To solve this error you need to rebuild the lucene indexes.  To do this:
1.  Stop Alfresco.
2.  Delete everything under /alf_data/lucene-indexes
3.  Edit C:/Alfresco/tomcat/shared/classes/alfresco/extension/custom-repository.properties or
alfresco.war/WEB-INF/classes/alfresco/extension/customer-repository.properties to set the property index mode to AUTO instead of validate
4. Start Alfresco again.

customer-repository.properties:
Now instead of validating the indexes and failing, the indexes will be rebuilt if a problem is found.

java.lang.UnsatisfiedLinkError: no Win32NetBIOS in java.library.path:

You need to add the folder containing the Win32NetBIOS.dll and Win32Utils.dll to the java.library.path of your application server.  For JBoss make an entry in run.bat

The server should now be able to find the files.

We want to access the node 066a443a-a43f-4911-9ef2-56cd96a3392e in this example which is the reference for the space we created. The url is

http://localhost:8080/alfresco/n/browse/workspace/SpacesStore/066a443a-a43f-4911-9ef2-56cd96a3392e

We will be using the browse outcome of the ExternalAccessServlet which takes a node reference of the folder to display.

First we get an authentication ticket: String userName = "admin"; String password = "admin"; String ticket = ""; // Start the session and get a ticket try { AuthenticationServiceSoapBindingStub authenticationService = (AuthenticationServiceSoapBindingStub) new AuthenticationServiceLocator().getAuthenticationService(); AuthenticationResult result = authenticationService.startSession(userName, password); ticket = result.getTicket(); } catch (ServiceException serviceEx) { System.out.println("javax.xml.rpc.ServiceException: " + serviceEx); } catch (RemoteException remoteEx) { System.out.println("java.rmi.RemoteException: " + remoteEx); } System.out.println("Ticket is: " + ticket);

Now we append the ticket to the url: String BROWSE_SPACE = "http://localhost:8080/alfresco/n/browse/workspace/SpacesStore/"; String nodeReference = "066a443a-a43f-4911-9ef2-56cd96a3392e"; String APPEND_TICKET = "?ticket="; String url = BROWSE_SPACE + nodeReference + APPEND_TICKET + ticket;

You can then access the workspace page directly by opening up a url similar to this:

http://localhost:8080/alfresco/n/browse/workspace/SpacesStore/066a443a-a43f-4911-9ef2-56cd96a3392e?ticket=TICKET_c02f49a5cb8db3f59e4b538d25deaa202f4de493

You can get more information about accessing the web client using urls here.

The structure of the Alfresco repository is similar to that of nested folders or nodes. You start with a root folder and then add sub folders that can contain content or more folders. In Alfresco these folders are called spaces. Each space or piece of content has its own node reference.

In our scenario you have a standalone web application and want to be able to link to Alfresco’s Web Client from it. Alfresco will then handle all the content management functionality. You have objects in your web application for which you want a corresponding workspace in Alfresco to contain any content for that object. The functionality you need to add to your web application is:

1. When an object is created, create a corresponding workspace for that object in Alfresoc and retrieve the node reference for that workspace.
2. Store the objects and matching node references (you will need to do this yourself).
3. Select an object in your web application, get the node reference for the workspace in Alfresco, and open a new tab/window to view/update that workspace in Alfresco.
4. You also want to bypass the Alfresco login page / authentication in all these scenarios so the user doesn’t have to enter login details.

At a minimum you will need the following jars in your web application:

alfresco-web-service-client.jar
axis-1.4.jar
commons-discovery-0.2.jar
wsdl4j-1.6.2.jar
(jaxrpc.jar should already be available in a jboss application)
commons-logging-1.1.jar
wss4j.jar
opensaml-1.0.1.jar
xmlsec-1.4.1.jar

Depending on the jar files already included in your application you may need to add some more jars.

We’ll start with authenticating a web service call that will create a new space. To use a web service api you need to authenticate your session.

Authentication for web service API:

// Start the session
AuthenticationUtils.startSession(“admin”, “admin”);

try {
// Make your web service call in here
}
catch (Throwable e) {
System.out.println(e.toString());
e.printStackTrace();
}
finally {
// End the session
AuthenticationUtils.endSession();
}

To create a workspace called “child” in the “parent” workspace using a web service call:

// The default workspace store is SpacesStore
Store storeRefence = new Store(Constants.WORKSPACE_STORE, “SpacesStore”);

// We want to create a new folder or workspace called child in the parent folder under company home
// Create parent reference to the parent space in company home
ParentReference parentReference = new ParentReference(storeReference, null, “/app:company_home/cm:parent”,
Constants.ASSOC_CONTAINS, Constants.createQNameString(Constants.NAMESPACE_CONTENT_MODEL, “sample_folder”));

// Create the child folder
NamedValue[] properties = new NamedValue[] { Utils.createNamedValue(Constants.PROP_NAME, “Child Folder”) };
CMLCreate create = new CMLCreate(“1″, parentReference, null, null, null, Constants.TYPE_FOLDER, properties);
CML cml = new CML();
cml.setCreate(new CMLCreate[] { create });
UpdateResult[] results = WebServiceFactory.getRepositoryService().update(cml);

// From the result of the web service call we want to retrieve the node reference for the child folder so we can access it later
String childReference = results[0].getDestination().getUuid();
System.out.println(“Created a new workspace, node is: ” + childReference);

In Part Four we will handle generating a url to access the space we have just created and bypassing the login page when accessing the url.

The next step is to set up the database.  If you’ve already installed the default version of Alfresco you’ll need to drop the database and recreate it.  Either way, you’ll find mysql scripts in extra/databases/mysql for setting up or dropping the schema.   See Using Alfresco for document management Part One for details on how to do a default install of Alfresco and for configuring Open Office.

You now need to extract alfresco.war to edit the contents. I expanded it into exploded/alfresco.war so I can copy the alfresco.war folder directly into my jboss application when I’m ready to deploy.

We need to configure the war for deployment in JBoss. You’ll find the config files needed in the extensions/extension folder. The ones we want are:
custom-hibernate-dialect.properties
custom-repository.properties
custom-repository-context.xml

Copy these to exploded/alfresco.war/WEB-INF/classes/alfresco/extension

In custom-repository.properties you need to set the dir.root to point to where you want to store your alfresco data. Also uncomment and set the database values – don’t forget to disable the derby settings also.

Finally you need to set the external executable locations. What I did here was copy the ImageMagick and bin folders from the default Alfresco install into my root folder containing alf_data.  Otherwise you will need to install missing executables yourself.

custom-repository.properties: dir.root=C:/Alfresco/alf_data db.username=alfresco db.password=alfresco db.pool.initial=10 db.pool.max=100 ooo.exe=C:/Program Files/OpenOffice.org 3/program/soffice ooo.user=${dir.root}/oouser img.root=C:/Alfresco/ImageMagick swf.exe=C:/Alfresco/bin/pdf2swf db.driver=org.gjt.mm.mysql.Driver db.url=jdbc:mysql://localhost/alfresco

Now update the hibernate dialect in custom-hibernate-dialect.properties

I used JBoss 4.2.2 as my application server.  Before deploying you should edit jboss-4.2.2.GA/server/default/deploy/ejb3.deployer/META-INF/persistence.properties to change hibernate.bytecode.provider from javassist to cglib.

To avoid getting permgen out of memory errors you will probably need to configure your JBOSS_HOME/bin/run.bat to increase the memory size.

You can now try coping alfresco.war into your jboss application. Assuming this doesn't cause a spectacular display of stack traces, when the server finally starts up you can try accessing the application at http://localhost:8080/alfresco.

You're now ready to start figuring out how to use alfresco as it is, or integrate it with other applications.

Next - Creating a workspace using a web service API

The first step was to install Alfresco… but which version?  The easiest thing to do is install the fully featured Alfresco Labs 3 and run that initially to investigate what Alfresco can do.  Eventually I would need to deploy it in JBoss, but first things first… This also gives you the option of cheating later and using some of the programs installed by default when they’re missing in a more customised deployment.

The installation:
Prior to installation I already had a local mysql database installed.  I downloaded Alfresco Labs 3 and ran the setup file.  I chose a custom install.  I deselected the jdk and open office and installed the remainder into C:/Alfresco.  I set my data to be stored in C:/Alfresco/alf_data and part of the installation included setting up the alfresco database using the mysql details I provided.

The configuration:
On the default install, extension files are stored in C:/Alfresco/tomcat/shared/classes/alfresco/extension.   Most of the settings will have been set correctly in the default install.

To configure my open office installation I edited custom-repository.properties which overrides the default values.
You start the server by accessing Start -> Programs -> Alfresco Labs -> Start Alfresco Server.  Unfortunately if there are any problems at all the window closes leaving you to search the logs or run the batch scripts manually to see what's going on.

Exploring the application:
Assuming your server starts up successfully, open up the Alfresco Explorer in the same menu location.  You can log in here as admin/admin.  This is the web client program which you can use to create users, assign spaces and edit content.  There's also Alfresco Share as an alternative which is more geared towards setting up collaborative sites.  It takes a bit of time to get familiar with the interface, but there's nothing too difficult to figure out.

You can explore the database schema.  The main tables to note are:
alf_authority which lists the user details
alf_node which gives you the node ids for the documents
avm_modes gives more details about the document nodes

The real fun and games start when you try to deploy a version other than the default install or access the repository or web client remotely.  Details on those to follow later...

Next - Deploying Alfresco Web Client in JBoss