Sony DADC User Rights Management Solution

Common Gateway Platform Back Office

Introduction

The CGP backoffice is used to protect content. A detailed description of the API can be found in the section CGP Back Office API V3.

The high level workflow for protecting a book is:

  1. Open a packaging session:
  2. Upload the file
  3. Mark the upload as finished
  4. Wait for the packager to finish
  5. Download protected file
  6. Close packaging session
  7. Distribute the ccid to your stores

After your book has successfully been protected you can update the metadata of the product. This can be useful if, for example, you want to change the URL where you host the protected file, change DRM details, or correct an error. See Update Metadata for more details.

Open packaging session

Opening a session is done with the API call Open Packaging Session. With this call all metadata for the book is passed the the CGP server, as well as some information specific to the protection process.

  • The number of file fragments. See Upload File (below) for details on fragmented upload.
  • The hash sum of the book. The hash sum is used to check integrity after uploading (and the possible fragment assembly).
  • An exclusion list. This can be used when protecting book in epub format. Usually all files inside an epub container will be encrypted by the protection process. The exclusion list allows the exclude some of the files from encryption. As an example the first chapter could be unencrypted as a preview while all others get encrypted. The Back Office API documentation gives an example on what this list should look like.

Any packaging session older than a week will be closed automatically. See Close Packaging Session.

Upload File

In this step the actual content is uploaded. The CGP server have a limit of 100MB for a single request. If your books are larger than this or you want to upload the file in smaller parts you can split the file. Cut the binary content into fragments of any size smaller than the 100 MB and upload them one by one. The fragments can be uploaded in any order and also the size of the fragments do not need to be the same for all fragments. With the data, the fragment index is one of the parameters to the call. This index will then be used to assemble the fragments in the correct order. CGP checks the hash of the uploaded fragment and gives immediate response if the upload succeeds, or if a fragment needs to be uploaded again. In that event simply complete another upload request with the same fragment Index.

Finish Upload

After you finish uploading the content, whether as a single file or as file fragments, execute this request. CGP will check if all parts have been received successfully and if yes, enqueue the workload at the packager.

Wait for the packager to finish

You can actively pull the packager status for your workload. Or you can register a callback, which will notify you when the book has been successfully packaged or if there was an error while processing the workload.

Pulling the status

To pull the status use the getPackagingStatus call. Pass the packaging session ID and get the status in return. See Packaging Status for the description of the different statuses. If the packaging is already complete you also get additional information. This includes the CCID, used later on to reference the protected content, the URL where you can download the protected book, and the hash value of the protected book, which can be used to check the integrity after download.

Get status via callback

Callbacks are registered globally for your store. You need to provide us an URL where we can send the callback to. Every time a workload reaches a final state we will then send a callback to this URL. The payload of the callback is the same information as you get in the pull request (see above).

Download the file

CGP does not host the encrypted file. You need to download the file and host it on your end. If you have passed a contentUrl with the open packaging session call, you need to place the file at this location.

Close Packaging Session

Once you are finished with the session, either because you have already downloaded the protected file and checked the integrity or you want to abort the session for any reason, you should close the session. Closing the session will make CGP delete all files (plain files, encrypted files, intermediate files) belonging to this session from our servers.

Distribute the CCID to your stores

The last step is to distribute the CCID codes (most likely together with other metadata of the product) to the stores which are going to sell the content. The CCID is the only thing the stores need to interact with CGP. If you did not provide the content url in the open packaging session call, then you also need to take care that the protected book gets delivered to the client/store.

Implementation Prerequisites

Customers that want to evaluate our packaging API are supplied with a dedicated sample store as well as credentials for store and API access. This sample store is a test platform, often used to evaluate the product, and it runs on the CGP Server.

Packaging a book involves taking an unprotected eBook and encrypting it for Digital Rights Management so that it can be distributed using URMS.

Datalogics will provide you with the information you need.  Make sure you have these values available:

  • Sample Store Link (it should look like “http://<sample-store>/#/login”)
  • Sample Store Credentials, for both the regular user and the administrator
  • Back Office API endpoint
  • API Access Key, or the Store Secret, an encrypted character string that serves as a password to authenticate a store to the CGP Server
  • Store ID, a unique code used to identify the store or library to URMS

Verifying the uploaded content with the URMS Sample Application

Books that have been packaged using the Back Office API can be tested with the sample mobile apps (for iOS and Android) that are provided with the sample store. To upload encrypted books to the sample store follow these steps:

  • The sample store and app currently rely on CGP providing them with the correct links where encrypted books and thumbnails can be downloaded. For this reason when making the Back Office API “Upload Package File” call, provide the following additional parameters:

contentUrl: http://<sample_store_endpoint>/sample-store-a/content/<filename>.MNB with .MNB extension

thumbnailUrl: http://<sample_store_endpoint>/sample-store-b/thumbnail/<filename> without extension

  • After the packaging is complete and the “Get Status” call provides the downloadUrl to the encrypted book, download that book. Find and write down the CCID.
  • Log on to the store’s back office as administrator and select Books/Upload. “Upload” is for books that have already been encrypted, while “New” applies to non-encrypted titles.
  • Provide the CCID code for the eBook, the file name, and any other required information. Note that the file name must match the name provided in the “Upload Package File” call, and enter it without the file extension.

Optional Features

Distributor Managed Content

Content can be marked as distributor managed content. This is done with the flag distributorManaged in the openPackagingSession call. If this flag is set to 1, buy and lend transactions cannot be done directly via the URMS API, but only using the distributor’s API. In this case the distributor is responsible to register the operation at URMS. Therefore the distributor needs to make use of the web service calls Buy Book On Behalf and Lend Store Book On Behalf. These calls allow to make the buy and lend operation on behalf of the retailer as the names already suggest. To be able to use these calls the distributor needs to be authorized to do on behalf calls for a specific retailer. Adding an authorization is an operative task done by the local system administrator.

Callbacks

There are two options for retrieving the status of your packaging workload, pulling the status via the operation Get Packaging Status, or requesting a callback. Both options provide the same information, so if you built your system using a polling mechanism you won’t miss any data by not requesting a callback and vice versa. Callbacks usually will not cause more than a one minute delay on the status change.

If you would like to use callbacks, they need to be globally activated for your store. If callbacks are enabled, you can still actively pull the status and receive a callback every time a workload has reached a final state. Final states are when a file is successfully packaged, or when the packager runs into an error and the workload can not be completed. In case of an error you will receive additional information on the cause of the error. If the process completes properly, the response will include metadata, including the CCID of the book.

The callback is sent to the endpoint specified for your store (see Store Setup). The payload of the callback looks very much like the response of the get packaging status operation, except that it does not contain the status and the message of the operation. The payload is either encoded as JSON message or as a XML document.

The response to the callback needs to be a HTTP 200 in case of success. The content of the response is discarded. You do not need to provide any other information. Any other message will also be OK if this better fits the framework you are using. If we can not deliver the callback or do not receive a HTTP 200 response we will retry the callback 10 times with increasing timeout. After that, the callback is discarded, and you will need to call the get packaging status operation to get the status of the workload.

Download Resources

Code Snippets for Back Office API (v3) Sample Implementation (Java)

Code Snippets for Back Office API (v2) Sample Implementation (Java)