Code Corner: Adventures in DPS Entitlement

Here at Storycode, we’ve been in the process of implementing some neat things that take advantage of Adobe’s DPS Direct Entitlement Server.  The first step of this was to set up the Direct Entitlement Server in the first place, which can be a pretty drawn-out ordeal if you don’t understand what to expect at each stage of the process. I’m documenting everything I went through here in hopes that someone else may have an easier time getting up and running than I did.

Here’s a very brief list of steps:

  1. ensure you have a place on the internet to host your server
  2. ensure that you have a working SSL certificate
  3. install the DPS Direct Entitlement Server
  4. create a test subscriber and entitle a folio to it
  5. test the DPS Direct Entitlement Server
  6. apply for whitelisting

 
Adobe provides some easy-to-follow instructions for getting up and running with their Entitlement Server, but, unfortunately, they’re kind of buried alongside a number of less-helpful, outdated documents that are no longer accurate. Trying to figure out on your own which instructions you should follow can be a very frustrating exercise.

To successfully install the DPS Entitlement Server, there are a number of documents to look at, but this is the only DPS Entitlement installation document you should look at.

If, like I didn’t, you don’t fully understand the entitlement process, it’s also worth reading about how to use the DPS Entitlement server once you’ve got it installed. This document does a pretty good job of explaining DPS Entitlement.

Those documents are both very well written and will get you through the process of getting the server up and running, but they don’t really cover the process of getting your server whitelisted on Adobe’s end, which is required if you want to actually see it functioning.

For whitelisting, you’ll need to to provide two things to an Adobe support representative via email:

  1. 1. Your Adobe Integrator ID
  2. 2. Your shiny new Direct Entitlement Server’s “Service URL”

 
The Adobe Integrator ID is a string that you make up, and I recommend naming it after your company so that it’s easy to remember.  For example, ours is “storycode_integrator_id”, which is something we’re unlikely to ever have to look up.

The Service URL for your Direct Entitlement Server is dependent on where and how you installed it. The actual URL is conveniently displayed inside the UI of your Direct Entitlement Server, so it’s easy to look up. You can find it immediately under the Adobe Digital Publishing Suite banner, pictured below.

service_url

Now that you’ve got an Adobe Integrator ID and a Direct Entitlement Service url, you need to communicate them to an Adobe representative.  You do this by downloading and filling out a DPS Direct Entitlement Request Form PDF.

One thing to keep in mind: that form is two years old and references things that are no longer correct.  Where it says ‘URL for verifyEntitlement’, put in your Direct Entitlement Service URL.  The API version should be ’2′.

You may notice that the form field may not be long enough to hold your entire Service URL. Because of this, you’ll want to also include all the information from the form in the body of your email to the Adobe representative. (They still want the form filled out, though.)

Once you’ve filled out the form, email it to cresupp@adobe.com, including the following info in the body of the message:

  1. a friendly request for Direct Entitlement whitelisting
  2. your Service URL
  3. your Integrator ID
  4. that your Direct Entitlement Server is API version 2
  5. your test username and password

 
It will likely take a day or so before you’ll get a reply.  Once they receive the request, they’ll test your installation.  If it passes all the tests, they’ll whitelist you, and you’ll be good to go. However, in my experience, this involved several rounds of back and forth emails because certain requests failed for one reason or another.  Each of these back-and-forth emails took a full day to complete. With that in mind, I strongly recommend that you test things yourself before submitting your PDF in order to minimize the turnaround time.

At the link below, I’m providing the actual URLs, methods and payloads for each of the requests the Adobe representative will test.  You can use Postman or curlto interact with them on your own Entitlement Server.

Good luck on your adventures with DPS Direct Entitlement!

Direct Entitlement API testing information available here.