As much as I love working with Alfresco (and I do, really), there are some things about it that still make me scratch my head and say "huh?".  One of these things is the way Alfresco Share handles adding users to sites.  Typically, a site manager simply invites a user to a Share site via the invite mechanism.  95% of the time this is exactly how I want it to work.  Sometimes, however, I need to add a user directly without going through the invite process.  Strangely, Alfresco admin users cannot simply add users to an arbitrary site.  Under older versions of Alfresco (3.1), there was a simple workaround.  A user could be added directly to a site group, and thus the site, through the Alfresco Explorer admin interface.  In newer versions of Alfresco (3.3.3, in my case), this no longer works.  The site manager, collaborator, contributor and consumer groups no longer show up in the admin interface's group search.  Aaaaarrrrgh!!!

Thankfully, there is another way.  It takes a little more work.  I have written a few articles before about the Alfresco Javascript API, and we're going to dive into it again to accomplish the task at hand.  

So, let's get started!  To add a user directly to a Share site using the Javascript API, two things are required:

1. Valid Alfresco user credentials.  The account needs to either have SiteManager access to the site to which the user will be added, or it need to be an admin account.
2. A good REST client.  There are quite a few to choose from.  Depending on the task, I either use the WizTools.org RESTClient, or the Eclipse restclient-tool.  Either one will work just fine.

The first step is to fire up your REST client or a browser and get an Alfresco authentication ticket.  This is done via a simple HTTP GET operation.  Just hit the following URL:

http://<your_alfresco_host>/alfresco/service/api/login?u=username&pw=password

This will return an authentication ticket that can be appended to all of your future requests.  The exact response will look something like this:

1

<ticket>TICKET_ce2ffccb238802825af8ae7632160dd87aa234e7b</ticket>

The part of the ticket that should be appended to the URL is the content of the <ticket> element.  Make a note of the ticket, it will be required in a moment.  Now, fire up your REST client if you haven't already.  The client will be used to send a POST to the site membership web service.  This web service is used by Alfresco Share internally to (duh) add a user to a site with a specified role.  You can browse all of the available web scripts on your system at this URL:

http://<your_alfresco_host>/alfresco/service/index

The script we're looking for is in the package /org/alfresco/repository/site/membership, and is called the "Add Site Membership" script.  A full description of the script and its parameters can be found here:

http://<your_alfresco_host>

/alfresco/service/script/org/alfresco/repository/site/membership/memberships.post

The script itself is pretty simple.  Take a moment to read the description, go over the associated Javascript and get a feel for what it is going to do.  I'll wait.  Done?  Good.  If you look at the URL that will accept the POST, you'll see it has a pretty simple signature.  Only one part of the URL needs to be changed.  You'll need the short name of the site to which you want to add a user.  The short name is the "URL name" that you used when you created the site.  It's a part of every URL in the site.  For this example we'll assume I have created a site called My Test Site with a URL name (short name) of "mytestsite".  The URL specified by the script looks like this:

http://<your_alfresco_host>/alfresco/service/api/sites/{shortname}/memberships

Looking at the URL template above, it's pretty clear what to do.  Substitute the shortname of your site for {shortname}.  The last part of the URL is the Alfresco authentication ticket created earlier.  Simply append it as a URL parameter named "alf_ticket".  

http://<your_alfresco_host>/alfresco/service/api/sites/mytestsite/memberships?alf_ticket=TICKET_dc233f7e8212825ef8fa8f945762ee24df53bcd7b

When I first started working on this I tried to use the authentication built into my REST client, but Alfresco constantly complained about HTTP authentication.  Appending the ticket in this manner seems to work nicely with every web script I have tried.  The last step in this process is to create a JSON object that will go into the body of the POST request.  A quick look at the Javascript for the memberships script shows that it expects a JSON object that contains a role (SiteManager, SiteCollaborator, SiteContributor or SiteConsumer, corresponding to the Share site roles), and a person object with a username property.  Here's what such a request looks like:

1
2
3
4
5
6
7

{
"role":"SiteManager",	
"person":
	{
		"userName" : "username"
	}
}

Note that this isn't everything that Alfresco includes in a person object, but it's enough to get the job done in this case.  Once you have entered this JSON into the body of your POST request, there is one more task and we're ready to send the request.  Alfresco is expecting a certain content type for JSON requests.  A proper REST client will let you set any additional HTTP headers that the request requires.  Add a header called "Content-type" and set its value to "application/json".  Once the header is set and your request body is ready go ahead and send the request.  You should get back an HTTP OK response, with a body that contains another JSON object with a bit of detail about what was done.  For the request and test site in this example, the response should look something like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
	"role" : "SiteManager",
 
	"authority":
	{
		"authorityType" : "USER",
		"fullName" : "User Name",
		"userName" : "username",
		"firstName" : "User",
		"lastName" : "Name",
		"url" : "\/alfresco\/service\/api\/people\/username"
	},
	"url" : "\/alfresco\/service\/api\/sites\/mytestsite\/memberships\/username"
 
}

It's entirely possible that there was an easier way to do this that I completely missed.  Even if there is, it never hurts to get more familiar with the Javascript API.  The Alfresco Javascript API is a powerful tool for Alfresco users.  It doesn't matter if you are a developer or admin, learning the Javascript API is essential.

Happy coding!