Document Summary

This document serves as a guide for vendors accessing digital assets maintained in the Hal Leonard Digital Asset Management (DAM) System. References to earlier versions of the DAM System are given to assist vendors who are upgrading from previous releases.

Overview

The Digital Asset Management (DAM) system is a B2B warehouse of digital media assets, controlled and managed by Hal Leonard Corporation. The DAM system maintains information (metadata) about each asset and provides it to approved vendors via a published API. The vendor then offers the digital media assets for sale through their own web site and records any sales in the form of transaction requests to the DAM system. For example, when a vendor sells a "print" of a digital media file, the sale is recorded through an "open transaction" request to the DAM system.

Vendors interact with the DAM system via XML documents sent as HTTPS (SSL) POST requests to the DAM API. Each of these interactions is described more detail throughout this document. During development, vendors are given test account credentials that can be used to send test requests to the DAM System, without incurring any billing activity. All credentials to the DAM API are supplied by Hal Leonard.

Roles & Responsibilities

The diagram below provides a high-level view of the roles and processes each party is responsible for when setting up a web site to sell digital content from the DAM system.

Hal Leonard Responsibilities Digital Retailer Responsibilities
Create/publish digital content and metadata to the DAM System. Periodically request information (metadata) from the DAM API for new, updated, and deleted assets. Load this data to your own database.
Capture sales activity, including cancellations and retries. Create an ecommerce site, including search, shopping cart and credit card processing to sell digital assets.
Create and distribute periodic invoices for sales activity. Report all sales in real-time to the DAM System via the API.

DAM-Digital Retailer Diagram

DAM System Integration Road Map

  1. Review the API documentation.
  2. Request a DAM API test account from your Hal Leonard sales representative.
  3. Create the processes to retrieve and process asset metadata from the DAM API. Load this into your database, taking care to handle "new", "updated", and "deleted" assets properly (as noted in the metadata).
  4. Build an ecommerce web site, including search, shopping cart, and credit card processes using the asset metadata. Note that some assets may not be sold into all countries. Therefore, some type of IP/Location checking must be part of your site. An asset's sellable territory is described in its metadata.
  5. Create the processes to report sales transactions to the DAM API. The DAM system will assign a unique transaction ID to each sale. You will need to save this in your database and use it whenever communicating with the DAM API about that particular sale, for example to do a retry or cancellation.
  6. Create the processes to issue retry and cancellation transactions. Retry transactions are never billed. Cancellation transactions will issue credit for a previous sale on your next monthly sales invoice.
  7. Once your site is tested, contact your sales representation and ask that they test the site. You must provide some means to purchase an asset from your test site (e.g. test account credentials, test credit card number, etc.). We must experience it just like your customer would.
  8. Once your site is approved, you will be provided an extract of the entire asset database from DAM. This will be provided as a very large XML file (in the exact same format as the AssetMetadata Response), or as a set of related CVS or Tab-Delimited files, all in a ZIP archive. You will need to do the initial load of your database from this information. Please note that these files are large and may not work with the processes you created to handle the smaller XML metadata responses returned by the DAM API, so please plan accordingly. Once the initial load is complete, subsequent asset data may be retrieved using the DAM API, since these will be much smaller in size. We recommend requesting new metadata from DAM at least once a day.
  9. Change your DAM test account credentials to your DAM production account credentials. These will be provided by your Hal Leonard sales representative.

Naming Conventions

Important words or points are bolded or italicized.

Links are in blue.

Some code examples are in a fixed-width font.

Other code examples are in a separate block.