06 February 2009

Adobe Content Server 4 (ACS4) Setup Guide - Part 4

Packaging Books

The packaging tool is simple command line tool written in Java that makes the appropriate calls to the packaging services web-service API's.

The tool is provided as source code (as well as the pre-built jar file).
The input to the tool is an unencrypted book and, optionally, some metadata.

The result is the encrypted book is written to the place specified by the packaging configuration (the baseLocation) and the data about the book (its key, location, URL, etc.) are written to the Content Server database.

Included in the release zip is a set of (public domain) books, book-cover images and XML packaging files.

Unzip that file to some convenient location (e.g. C:\ACS4\srcbooks).

The packaging tool can be used to package individual books by themselves, but it is often more convenient to use a helper file that constitutes a packaging request, but we'll start out by packaging an individual file.

The inputs to the tool are the URL to the packaging service, the path to the book itself and the password used to log into the ACS4 admin console.

So if one navigates to the folder the books and tha packaging tool are in, and enter:

java –Xmx1024M –jar UploadTest-1_1.jar http://yourdomain.com:8080/packaging/Package srcbooks\MonteCristo.epub –pass password

The parameter –Xmx1024M tells the Java Virtual Machine (JVM) to allocate 1 GB for the process.

This isn't needed for small files, but large complex files may fail otherwise (and the JVM will often emit bizarre, misleading messages when it runs out of memory).
For very large files you may want to allocate even more memory.

Note that the tool needs to address the Package service inside the packaging WAR, hence the packaging/Package in the URL.

Although the above works, parameters can also be passed in an XML file that contains the packaging information.

So for example, the following command:

java –Xmx1024M –jar UploadTest-1_1.jar http://yourdomain.com:8080/packaging/Package srcbooks\theArtofWar.pdf –pass password -xml -jpg

will cause the file theArtofWar.epub to be packaged and the file theArtofWar.jpg to be placed in the same destination folder. It will also cause the tool to load the xml file from the same folder and read the metadata and permissions from it.

The following command will package all the books in a given folder:

java –Xmx1024M –jar UploadTest-1_1.jar http://yourdomain.com:8080/packaging/Package srcbooks –pass password -xml -jpg

The Admin Console (continued)

So now that there are packaged books, bring up the Admin Console again. Remember that the password is now the new one that you entered the first time you brought it up.

There are three panels in the Console:
  • Inventory,
  • Distributors,
  • and Licenses.
By default the Inventory panel is selected. The books that you just packaged should be shown.
If they do not, click on the All Items icon and you should see all the items you have packaged in the current database.

You can sort the items in the inventory by just clicking on the header of the column.
You can also search for specific book's text in the title, author etc.

To clear a search, click on the All Items icon again. Note that down at the bottom is an area titled Web Services APIs. This is just informational and primarily for developer's interest.

It shows what is happening under the covers. When you make some gesture in the Console (like clearing a search), the Console makes a web-service call to the Content Server fulfillment service and gets back some XML that represents the results of the search. This can be very useful information for developers investigating problems or as tutorials as they learn how to develop their own tools or integrate Content Server with their own systems.

On the right, you will see basic information about the book.
Select one of the books and you will see its information displayed (title, author, etc.) as well as the thumbnail of the book (assuming it was packaged with the thumbnail, i.e. –jpg was specified).

Below the basic information is the permissions info. These are the parameters that control what a user who downloads a book can do with it.

With Content Server you can control how many machines or devices a book can be downloaded to, whether and how much the user can print from the book, whether the user can copy to the clipboard and so on. (The User Manual and Technical Reference cover these elements in some depth).

There are two types of permissions:

Base Permissions:
These are the permissions you specified when the book was packaged (in the XML file, if specified). These are part of the packaged book. You can edit them in the Admin Console, essentially overriding the permissions that were specified when the book was packaged.
But note that this will change the base permissions associated with the packaged books and will affect any and all distributions of the book.

Distributor Permissions:
With Content Server you can also narrow the permissions on a per-distributor basis. In other words, you can make the permission more restrictive for any particular distributor or for all distributors. But you cannot make the permissions less restrictive.

If you check the Distribution Rights for the selected book, you will find it tells you:
“No Distributor Selected”
- naturally enough, since we haven't created one yet.

So what IS a distributor?
A Distributor is an entity such as a bookstore or library through which you, as the Content Server operator, distributes books.

Again, there is the Built-in Distributor, but this should be thought of as the Master or root.
It is not a Distributor in the normal sense and should not be used to distribute books.

Navigate to the Distributor panel by clicking on the Distributors link at the top of the console. This takes you to the Distributors panel. It is similar to the Inventory panel in that it lists all the Distributors, which can be sorted, searched, the properties examined and so on.

But at the moment there arent any, so click on the little + (plus) sign button on the bottom right to create a new Distributor. This will bring up a dialog prompting you to enter some properties for the new Distributor:
  • Name: Just the human readable label for the store
  • URL: The URL where the store will be located (more on this below)
  • Notify URL: The URL to which Content Server will instruct Digital Editions to send a notification when a transaction is verified complete and the user has the valid eBook. Digital Editions will also send a notification to this address when a loaned book is returned. This is an optional field.
  • Description: A human readable description of the site
  • Max Loan Count: The maximum number of loans a distributor can make of any given eBook. Many publishers restrict the number of copies of a given ebook that can be loaned at any one time to 1. After all, a library can only loan out the single copy of a real hardcover book at a time.
  • Link Expires: The length of time after which a generated link is no longer valid, in seconds.
  • Shared Secret: This is an automatically generated number which is known only to the Distributor and Content Server. Using this number, messages between the two can be digitally signed in such a way that each knows that only the other party could have sent the message.
Save the info. Now, you will see that you have distributor listed.
If you select it, then the properties are now editable on the right hand side. And the only books shown in the inventory will be those that have been assigned to that Distributor.

You're almost ready to enable a Distributor using the supplied Content Server sample store. But you need to actually assign some books to the distributor.

So go back to the Inventory panel. The new Distributor now appears on the left side. You can simply drag books from the inventory pane over and drop them on the Distributor.

Do that for some books then you're ready to install the Store.

If you made it to this point and opt not to install the sample store, congratulations, as you now have a working version of Adobe Content Server installed either way.

To complete this tutorial and set up the sample store, and deliver some ebooks, click here.


  1. Is packing of .PDF and .ePub files can be possible by calling ACS 4.0 webservice using php?

  2. Is it possible to automated whole workflow instead of manual packing of file, copying exported xml files into store.

  3. Packaging problems:

    I'm tring to package with this command:
    java.exe -Xmx1024M –jar C:\uploadtest\UploadTest-1_2.jar http://www.futurbook.com:8080/packaging/package c:\acs4\srcbooks\MonteCristo.epub –pass MYCONTENTSERVERPASSWORD

    But I get a error like: java.io.FileNotFoundException.

    Can any one help me?? sergi@futurbook.com

  4. Hi do you know how to scale out and ensure high availability of fufillment / packaging / admin services?

  5. Hi All,
    I am packaging new epub books with base permissions , but i want to replace permission existing packaged books on acs4 . What kind of xml tag will use??

  6. Hi Mangal Varshney,
    Yes you can create a php base app that will upload your epub books, set base permission and package finally. you will see packaged book in admin console.