Frequently Asked Questions

Metadata & Catalog

  1. What is the recommended frequency for calling AssetMetadataRequest in order to keep the catalog up to date without overloading it (daily, every 6 hours, other)?

    1-4 times per day

  2. The initial catalog dump: in what exact format is it provided (XML, TSV/CSV, ZIP)? Is there any specific documentation available?

    XML, TSV, or CSV – your choice. There's no documentation specific to the initial dump. The XML is the exact same format as the metadata API response. The TSV/CSV basically splits each "collection" XML element into separate TSV/CSV files, which all get zipped together. You can request the full catalog using the Vendor Admin https://haldms.halleonard.com/vendoradmin.

  3. Are asset deletions or deactivations flagged in the metadata or simply removed?

    These come through in the metadata with: delete

  4. Do reference lists (classifications, instruments, series, etc.) change regularly? If so, how are you notified?

    These rarely change, but since they are included with every metadata response, you are not notified.

Rights, Territories & Restrictions

  1. Is the sellable countries field guaranteed to be kept up to date at all times? What is the update policy in the event of a change in rights?

    Yes, it's always up to date. If it changes, the asset will come through as a metadata update... if any part of the asset changes, it comes through as a metadata update.

  2. Are the URLs returned via AssetAccessRequest pre-signed (time-limited) or permanent? How long are they valid for?

    The only URL returned in the AssetAccessResponse is to the Scorch file – it is permanent. URLs in the Transaction[Open|Retry]Response (ViewURL, DownloadURL) are valid for 30 minutes.

  3. Are there any specific restrictions regarding local storage (internal cache, PIM database) of metadata or previews?

    No.

  4. For international sales: how do you manage tax rules and billing implications?

    We apply the appropriate tax when you are billed. The country of sale is required in the TransactionOpenRequest.

Transactions, Sales & Billing

  1. Does triggering a TransactionOpenRequest generate immediate invoicing, or is there a consolidated reporting system?

    It is not immediate. You are billed monthly.

  2. What is the expected procedure for cancelled transactions (TransactionCancelRequest): financial management, end customer access rights, etc.?

    You handle voiding the customer's payment if necessary. You call the cancel request whenever a customer should no longer have access to the asset.

  3. Is there a maximum expected delay between the sale on our site and the sending of a transaction to the DAM?

    If I understand the question right, this would be up to you. The customer wouldn't have access to the content until you open the transaction on the DAM System.

  4. For TransactionRetryRequests, is there a maximum number of attempts or a time limit?

    No.

Formats, Files & Previews

  1. Are the available formats (PDF, SCORCH, audio demo, play-along, etc.) the same for all countries or subject to geographical restrictions?

    They are the same. Territorial restrictions are applicable to the asset as a whole.

  2. Does the DAM provide previews (preview pages, audio clips) that can be used on the website? Is there a recommended workflow for these uses?

    Yes, DAM provides a 1st-page preview image for sheets, a preview version for interactive assets, and a preview clip for audio assets. Preview URLs for audio assets are provided in the asset metadata (non-expiring). Previews for all sheets (interactive and non) can be handled with an iframe with src="//haldms.halleonard.com/nf/preview//" see: Preview page

  3. Does the AutoPrint operation generate a temporary or permanent URL for the PDF? How long is the link provided valid for?

    Temporary URL, valid for 5 minutes. AutoPrint is useful for ensemble orders. Ensembles have parts as separate transactions, each with its own PDF. AutoPrint will combine all the PDFs from the transactions of a single order into one, large PDF, making it easy for customers to save and/or print.

Security, Authentication & Compliance

  1. Do you have any specific requirements regarding TLS (supported versions, cipher suites, specific certificates, mutual TLS if applicable)?

    • TLS 1.2 or 1.3 are supported.
    • The following ciphers are supported:
      • TLS_AES_128_GCM_SHA256
      • TLS_AES_256_GCM_SHA384
      • TLS_CHACHA20_POLY1305_SHA256
      • ECDHE-ECDSA-AES128-GCM-SHA256
      • ECDHE-RSA-AES128-GCM-SHA256
      • ECDHE-ECDSA-AES128-SHA256
      • ECDHE-RSA-AES128-SHA256
      • ECDHE-ECDSA-AES256-GCM-SHA384
      • ECDHE-RSA-AES256-GCM-SHA384
      • ECDHE-ECDSA-AES256-SHA384
      • ECDHE-RSA-AES256-SHA384

  2. What are the usage limits (rate limiting) per VendorId/VendorKey:

    • 100 requests per minute (this is subject to change)
    • 1 metadata request at a time, no simultaneous request limit on other request types
    • no daily quota limit

  3. Is it possible to use multiple environments (test/sandbox/production) with separate credentials?

    Separate DAM credentials can and should be used for test/sandbox and production environments.

Performance & Volume

  1. For high volumes (e.g. complete catalog with tens of thousands of assets), do you recommend a specific breakdown of requests?

    Use the Vendor Admin https://haldms.halleonard.com/vendoradmin for large metadata requests. This will submit the requests in the background and email you when it's done with a link to download the metadata. The API limits date range requests to 3 months, but the Vendor Admin does not.

  2. What is the expected average response time for large requests (AssetMetadataRequest on several thousand assets)?

    It can range from a few seconds to several minutes, depending on the request (number of assets in a by-asset-ID request or number of assets included in the date range of a by-date-range request)

  3. Do you offer optimization mechanisms (compression, pagination, server cache, etc.)?

    Gzip compression is used on the response, if the client can accept it.

Multi-system Integration & Best Practices

  1. In a multi-store/multi-brand context, can we use a single VendorId/VendorKey or do we need an identifier for each store?

    If all of the stores/brands represent the same Hal Leonard dealer account, you can use a single vendor ID/key. If you have multiple Hal Leonard dealer accounts, each one will need its own DAM vendor.

  2. Can you confirm that we can store metadata (internal PIM, catalog database) on a long-term basis? Are there any retention rules?

    Yes, you can store the metadata long-term. There are no retention rules.

  3. Do file URLs (PDF, SCORCH, audio) link to a public CDN, or do they require specific client-side authentication?

    No authentication is required. Authentication is built into the URLs that expire.

  4. Do you have a recommended UML diagram or sequence diagram for implementing your API?

    We don't have any such diagram documented, but it's fairly straightforward if you use the XML metadata response structure as a guide.

Maintenance, Support & Development

  1. Do you provide a changelog, roadmap or notification mechanism in the event of changes to DTDs or XML structures?

    We never introduce breaking changes in the existing DTDs/XML structure. If breaking changes are required, a new API version would be released, and you would be notified via email.

  2. Are you planning to migrate to REST/JSON or a more modern version of the API?

    Yes, however there is no ETA yet.

  3. Is there dedicated support (N2 or N3) in the event of a blockage or repeated ‘ErrorResponse’ responses?

    It is recommended that you contact your Sales/Account Representative. However, we do have monitoring in place so our engineers can look into errors affecting multiple vendors without requiring you to notify us.

  4. Do you offer a webhook system to notify: asset modifications, deletions, changes to territorial rights?

    Not at this time.

Logging, auditing & Technical Support

  1. Do you provide logs that can be consulted by VendorId (file access, transactions, errors) to facilitate auditing and support?

    Though we have our own internal logs, we do not provide any to you. It is up to you to log any/all responses from the DAM System API for later auditing/troubleshooting.

  2. Do you have an SLA on response times and availability of the /dam service?

    We have no response time or availability SLAs, but about 95% of response times are under 800ms and 99% are under 1500ms.

  3. In the event of your service being unavailable, is there a protocol or procedure in place to ensure transaction continuity?

    Yes, however there is nothing for you to do as a vendor other than handle errors from the DAM API and display an appropriate message to your customers.