Noteflight Viewer

This section is intended for those vendors who already have a functioning web site and are currently selling Scorch content via the DAM System API. Its purpose is to provide the minimum set of tasks a vendor must complete to integrate Noteflight assets into their web site.

Conceptual Differences - Noteflight & Scorch

• There is no plug-in to install with Noteflight. All Noteflight Viewer code is encapsulated in Hal Leonard's DAM System. Accessing the Noteflight Viewer is as simple as embedding an iframe URL in your web page.
• When registering a sale to the DAM API (via a TransactionOpen request), you will be given one or more URLs to access the Noteflight or Print Edition (PDF) asset in the XML response. These URLs are short-lived and expire after only a few seconds. Therefore, anytime you want to display a customer's purchase, you will need to issue a TransactionRetry request against the original sales transaction ID to get a fresh set of URLs.
• A single asset may now be available in multiple renderings, for example as a PDF file (Print Edition), or MusicXML (Noteflight) file. It's important to understand this in order to display the available formats to a customer before they purchase. Note that you cannot mix Noteflight/PDF assets with Scorch assets on your site.

Task Checklist

The following list of tasks is the minimum required to convert your site from Scorch to Noteflight. These tasks can be done in any order, but it is recommended that you follow this sequence. A full description of each task immediately follows this list. It's also recommended that you include the Minimum System Requirements for Noteflght somewhere on your site. They can be found at: http://haldms.halleonard.com/nf/minreq.jsp. Your DAM vendor account must be enabled for Noteflight access before you can begin testing your changes. Contact us when you're ready to begin your transition and we will make the necessary adjustments.

1. Update the DAMVersion element and DTD URL in all XML Requests.
2. Handle New DAM Metadata.
3. Add Personalization String.
4. Handle New Transaction Response Elements.
5. Replace Scorch Preview-Mode Code.
6. Replace Scorch Purchase-Mode Code.
7. Load Rendering Data.

Detail Task Descriptions

Update DAMVersion and DTD URL in all XML Requests

All requests to the DAM API should use DAMVersion 5.0 in the XML request.

Handle New DAM Metadata

Add processing to handle the new <Renderings> element in the AssetMetadata response.

This will tell you what type of renderings are available for the given asset.

Note that for some MusicXML assets, Noteflight Viewer functionality may be altered. For example, due to the nature of the following notational formats, transposition functionality is disabled:

Format	Format Name
EDPNO	Educational Piano
EGTB	Easy Guitar with TAB
TAB	Guitar TAB
GTRENS	Guitar Ensemble
UKEENS	Ukulele Ensemble

In addition, if there is no lead line (vocal or instrument) in the music, the Top Staff Instrument functionality is disabled.

Add Personalization String

Add the personalization element to TransactionOpen & TransactionRetry requests. Personalization values are inserted into watermarks (footers) at the bottom of each page within the Noteflight viewer and at the bottom of each printed page. This element is optional, but highly recommended to help discourage sharing of the printed file. If you want to personalize the footer with the customer's name, you must supply the value with the initial TransactionOpen request, and each subsequent TransactionRetry request. Currently, the only personalization value supported is the "customer name", denoted by the "custname:" keyword in the <Personalization> element.

With customer name:

Order 4137058 | 1 copy purchased by John Customer on Jun 10, 2015 at 3:55pm CDT

Without customer name:

Order 4137058 | 1 copy purchased on Jun 10, 2015 at 3:55pm CDT

Handle New Transaction Response Elements

Two new elements <ViewURL> and <DownloadURL> are being added to the TransactionOpen and TransactionRetry responses. These are the URLs you will use in the source parameter of the iframe tag in your web pages following a customer purchase. Note that these are very short-lived URLs; therefore, you will need to issue TransactionRetry requests every time a customer wishes to view or download a prior purchase.

Replace Scorch Preview-Mode Code

Remove the existing Scorch plug-in code (the <OBJECT> and <EMBED> tags) and replace with an iframe, using your vendor ID and the ID of the asset you wish to preview in the iframe src parameter:

You must also specify the allowfullscreen="true" parameter on the iframe tag for "full screen" functionality to work correctly.

Note that this is for previewing assets only (prior to purchase). The DAM system will verify that you have permission to access the asset id in the URL before displaying it. If your vendor account does not have permission to the asset an error page will be displayed.

Replace Scorch Purchase-Mode Code

Remove the existing Scorch plug-in code (the <OBJECT> and <EMBED> tags) and replace with an iframe, using the ViewURL or DownloadURL as the value of the src parameter. The ViewURL, if present in the Transaction Open or Retry response, will display the fully interactive Noteflight file. The DownloadURL will cause a watermarked PDF to be downloaded to the user's computer. If you wish to force the PDF to be displayed in the browser window using the built-in PDF viewer instead of having the user save the file to their computer, you can append "/inline" to the DownloadURL that was provided. In the case of a touch device, the DownloadURL will always display the file in a browser window.

Note that these are very short-lived URLs; therefore, you will need to issue TransactionRetry requests every time a customer wishes to view or download a prior purchase.

Load Rendering Data

We will provide a CSV extract from DAM that you can use to initialize "rendering" data on all existing assets in your system. It is best to do this after you have your changes in place to handle the new <Renderings> element in the metadata XML.

ASSET_ID,RENDERING_TYPE
3656,musicxml
3656,pdf
3657,pdf
3658,musicxml
3658,pdf
...