ColdFusion and LiveCycle ES: Rights Management

Friday, May 22, 2009

This is the final part of a planned 3-part series on getting started with LiveCycle ES for ColdFusion developers. With this post, I aim to:

  1. walk through the steps for Configuring LiveCycle Rights Management
  2. show how to invoke the RightsManagementService webservice
  3. address some additional issues I hit which stakeholders should understand

Big Caveat: I’m just learning this stuff. I have not worked with an Adobe salesman or tech support, so it’s highly probable that the stuff I’m talking about in configuration is complete crap. This post is a diary of what I went through to merely get it all working, and by “working”, I mean “I was able to create a rights-managed PDF that communicates with the LC server”.

Configuring LiveCycle

Make sure the service is enabled in LC Admin: Services, Applications and Services, Services Management, Filter on “Rights Management”, and ensure “RightsManagementService” is running. Click on that link and ensure the default soap endpoint is enabled.

Create a new group

I’m not sure if I needed to do this, but I did it, so I’m documenting it.

  1. Settings – User management – Users and Groups
  2. Click “New Group” button. Created group named “Rights Management”
  3. Clicked through and gave the group permissions associated with Rights Management stuff. You do this when you get to Step 4 and then click “Find Roles”, then select the stuff that looks rights-management-ish. Again… consult a professional, not me.

Create a new user

For the purposes of this post, I’m going to skip anything related to creating new domains. Instead, when we invoke the webservice, we’ll just invoke with the default domain that ships with LC. It goes without saying that when you do this in the real world, you’ll need to a) know your sh*t and b) probably consult with a company to help you get all this set up. Again, this is just to get up and running for a POC.

Now, then:

  1. Settings – User Management – Users and Groups
  2. Click “New User”. Give this user a name, username, password, blah blah blah. For this POC, select “DefaultDom” as the domain. Click next
  3. Click “Find Groups”, and select the new Rights Management group that you created above
  4. At step 3, I ignored Find Roles and went to Finish.

Create a new Policy Set

  1. Services – Live Cycle Rights Management ES – Policies -- Policy Sets.
  2. Click “New”. Give it a name. Click next
  3. Search for a domain. I selected “Default Domain”. Click through and accept the addition.
  4. Click Next, then search for the User you just created. Click Next and give that user permissions to monkey with policies in documents
  5. I added that user to Document Publishers, too. Click through to finish

Create a new Policy

  1. Services – LiveCycle Rights Management ES – Policies
  2. Click the link for the Policy Set you just created
  3. Click the Policies tab, then click “New”
  4. Give your policy a name
  5. Apply whatever settings you want. Click Save
  6. Check its checkbox, then click the Enable Button. Click through to finish.
  7. In your webservice call, you’ll use the policy set name and the policy name, along with the user and domain you associated with the policy set

Grrrrrrr

If you do all the stuff I’ve just talked about, you might be thinking “Gee, the LC Administrator is a bit tough to get around”. I’d respond with “ya think, Beav?”. I have come to despise the administrator. I’m assuming that Adobe wants you to use Workbench for most of this stuff. That, to me, is the only possible explanation for creating an admin that is so user-unfriendly. It’s a navigational nightmare.

Configuring SSL

Set the Rights Management Server URL

Services – LiveCycle RightsManagement ES – Configuration – Server Configuration

Set the Base URL to an SSL URL. For my POC, I used https://localhost:8443

Enable SSL in JBoss

I followed Duane Nickull’s excellent instructions. A few gotchas though:

First, in a “note” in the middle of the page, he writes: “Note: If you installed the Adobe LiveCycle 7.2 release using the turnkey installers, the path to this will be different. It should be: $JBOSS_HOME/server/all/deploy/jbossweb-tomcat50.sar”.

Pay attention to that note. Don’t gloss over it.

Second, a very very important point that is not addressed (well… I believe it’s just plain wrong, at least as of this writing): when you create the keystore, you need to set the “first and last name” as the name of the server on which you intend to deploy this. For my POC, I used “localhost”. In fact, I used “localhost” for every damn answer. Note that this is just if you’re using a self-signed keystore; if you used a real one (i.e. you buy a cert), you won’t have to go through this rigamarole.

Finally, Duane shows how to get the cert installed via FireFox. On my Vista machine, this didn’t work. I had to use Internet Explorer, and I had to follow the steps below.

Now, if you haven’t done so already, restart JBoss.

Making your cert a “trusted” cert on your machine

  1. In Internet Explorer, navigate to the URL you specified in the Server Config above. For example, I navigated to https://localhost:8443
  2. It’ll give you a red error address bar, so you’ll need to install the certificate. Right click and hit “install” or whatever the options are.
  3. This will launch IE’s certificate install wizard. Start the process, and when you get to the certificate store page, do not accept the default. Instead, select “Place all certificates in the following store”, click “browse”, and select “Trusted Root Certificate Authorities”.
  4. Click through to the end and you should be all set up.

Invoking the RightsManagementService with ColdFusion

<cfscript>
creds = {username='administrator',password='password'};
serviceRoot = "http://localhost:8080/soap/services/RightsManagementService";
wsdl = "#serviceRoot#?wsdl";
ws = createObject("webservice",wsdl,creds);
ws._setProperty("javax.xml.rpc.service.endpoint.address","#serviceRoot#?blob=base64");

filePath = expandPath("readme.pdf");
theFile = fileReadBinary(filePath);

inPDFDoc = {contentType="application/pdf",binaryData=theFile};
documentName="readme.pdf";
policySetName="Marc Policy set";
policyName="loose2";

response = ws.applyPolicy(inPDFDoc,documentName,policySetName,policyName,"cf","DefaultDom");

outputData = toBinary(response.getBinaryData());
</cfscript>

<cfset newfile = expandPath("readme_withrights.pdf")>
<cffile action="write" file="#newFile#" output="#outputData#">

Additional Issues and Considerations

As of this writing, whenever I open a rights-managed PDF created using the above steps, the PDF still prompts me twice: Once telling me that the PDF has to connect to the LC server, and once asking me for a username/password. I am 99% certain this is a configuration problem on my end. I just haven’t dug enough to figure it out yet. If you know how, please let me know. When I get back to my LC proof of concept, I’ll get the answers and update this post.

I believe it’s important for stakeholders deciding whether Rights Management is right for them to get solid answers – with proof – regarding the user experience with RM-managed PDFs. In my specific case, the PDFs wouldn’t be for internal consumption; rather, they’d be sent out to the masses, whose technical savvy could range from “My grandmother” to “my boss”. Bottom line: know your users.

No comments: