– For Spanish version, please read this same blog from the translated page . –
One of our customers asked me a few questions on how to set up multiple bookstores with Adobe Content Server (ACS). It is quite common for ACS hosts to support multiple stores or libraries, called distributors in ACS. I hope you will find info here helpful if you are thinking about working with more than one distributor, as this customer of ours is doing.
There are actually two types of “distributors” that are relevant when setting up your ACS server.
- Content Distributors (aka your distribution channel)
These are companies you have partnered with to provide your content to their user communities. An obvious example would be a bookstore or bookstores that you partnered with. Very commonly, you can be your own content distributor.
- ACS Distributors
There is a Distributor resource type that you set up and configure in ACS which defines a distinct set of properties and permissions for your published content. You will see the term “distributor” referenced in ACS applications and ACS documentations.
An ACS distributor you configure in ACS does not necessarily map one-to-one with your content distributor. For clarity, we will use these two phrases to distinguish between the two in this post.
Every ACS installation has to set up at least one ACS distributor, but you can also set up multiple. If you have multiple content distributors, you can create individual ACS distributors for each one of them, but you don’t have to.
How do I decide when to set up additional ACS distributors?
There are a few things to consider:
- Access properties – Is it ok to share the distributor key (sharedsecret) that authorizes ebook downloads?
- EBook permissions – Will a book have different set of permissions for each content distributor?
- Content distribution – Do you rely on ACS web API to retrieve the resource IDs for a content distributor or do you generate your own list of resources depending on some other criteria?
- Billing – Do you need to generate separate billings?
If the answer to any of these questions is “Yes,” then you most likely will need to set up separate ACS distributors. These are the basic deciding factors, in addition to other business related reasons that may be relevant.
What data do I need to send to my content distributors?
If you are working with multiple distributors, you will need to send them some data so they can properly generate download links for ebooks that are stored and managed on your server.
Minimally, you will need to send the distributors:
- the resource IDs for ebooks;
- the distributor name (ordersource as called in many places in ACS);
- the sharedsecret; and
- the URL (linkURL) for the download link.
For ebook resources, you can optionally provide other metadata, such as titles and thumbnail links. The only key piece of data you need is the resource ID (resid).
The other three required properties come from the ACS distributor. The following is exported from ACS Admin Console for a distributor. The distributor UUID is not needed for generating download links but it is useful to generate other web API calls for a distributor. So you may need to provide this to your content distributor as well.
[sourcecode language=”text” autolinks=”false”]
How do I bill different distributors?
If you structure your billing with each distributor so that billings are based on the actual transactions, there is a little bit of extra work that you need to do in order to generate separate billings for each distributor. Adobe issues a monthly summary of the total number of transactions. In order to break this down to each individual distributor, run queries on your ACS database to get a more detailed report. A sample query (provided with ACS software with a couple of tweaks) looks like this:
[sourcecode language=”text” autolinks=”false”]
SELECT distributor.name, fulfillment.transid, fulfillment.transtime, resourceitem.title, resourceitem.creator, resourceitem.publisher FROM fulfillment
INNER JOIN fulfillmentitem ON (fulfillment.fulfillmentid = fulfillmentitem.fulfillmentid)
INNER JOIN resourceitem ON (resourceitem.resourceid = fulfillmentitem.resourceid)
INNER JOIN distributor ON (distributor.distid = fulfillment.distid )
WHERE fulfillment.transtime BETWEEN '2012-04-01 00:00:00' AND '2012-04-30 23:59:59'
ORDER BY distributor.name;
And a snippet of the report generated with this query looks like:
name transid transtime title creator publisher Bookstore ABC ABC-167332520427 2012-04-10 15:45:15 Title Author Publisher Bookstore ABC ABC-405271779476 2012-04-02 14:45:06 Title Author Publisher Bookstore ABC ABC-529341818957 2012-04-10 15:16:24 Title Author Publisher Bookstore ABC ABC-129946313394 2012-04-10 14:32:31 Title Author Publisher Bookstore ABC ABC-181057724353 2012-04-10 15:20:23 Title Author Publisher Bookstore ABC ABC-404886166440 2012-04-10 15:07:35 Title Author Publisher
From this report, you can generate your own billings to each content distributor.
This concludes the main considerations in setting up a distributor. I hope you will find the info here useful. If you have questions or feedback, please feel free to add comments, or email us directly at email@example.com.