Transaction Open

An XML TransactionOpenRequest allows a vendor to open one or more transactions on digital assets. It can be used to open transactions on individual digital assets, where a vendor sells each digital asset separately. Such a transaction request for a single digital asset is also called a Sheet TransactionOpenRequest in this document. A TransactionOpenRequest can also be used to open transactions on a collection of digital assets (also called a package). A package is comprised of a group of digital assets sold as one entity to customers on the vendor site. A TransactionOpenRequest for a package is called a Package TransactionOpenRequest in this document.

Sheets

For a Sheet TransactionOpenRequest, a VendorLineItem element is included in the request document, specifying a digital asset (identified by asset ID), a vendor OrderNumber, a CountryCode (identifying the country of sale for customer), a UnitPrice and/or LineItemPrice (one or both are required), an optional Quantity, and an OrderLineId. The OrderNumber is an alpha-numeric field that uniquely identifies the order within the vendor's system. The UnitPrice and LineItemPrice must be real numbers without currency symbols (e.g. 3.95).

The OrderLineId element denotes the order line number for each order line item in an order. The OrderLineId must be an integer. The combination of VendorId, OrderNumber and OrderLineId must be unique for each transaction in DAM System, thus allowing the same asset to be sold multiple times within the same order.

The XML request document may include requests to open multiple transactions on different items. Each transaction requested is handled separately and may succeed or fail independently of the others. However, if a system error (also called fatal error) occurs that renders the system incapable of handling the XML request document, then an ErrorResponse will be sent out instead of the TransactionOpenResponse, thus causing all transactions from the request to fail.

The DAM System will reply with a TransactionOpenResponse XML document containing a TransactionItem element for each VendorLineItem element in the request. The TransactionItem element will include a StatusCode element from the list of status codes. If the StatusCode is 1, the response will also include a TransactionId from the DAM System identifying the transaction, the file name, the file type, the file's mime type, the file's URL, footer text strings, and view/download URLs. You may or may not need to use all of the response elements on your site depending on how you have implemented this system.

If the StatusCode is not 1, then the TransactionItem element will not include any elements following the StatusCode and StatusDescription.

In addition, the ParentTransactionId element will not be included in the TransactionOpenResponse. This element is only relevant for a TransactionRetryResponse and is explained on the Transaction Retry page.

Packages

As mentioned earlier, a package is simply a collection of digital assets sold as a single entity to customers on the vendor site. The type and content of packages that can be sold via the DAM system are pre-defined by Hal Leonard Corporation. The list of valid packages available on the DAM system is sent as part of each AssetMetadata response you receive. Currently the DAM system contains both Folio and Ensemble type packages.

The DAM system treats a package as a single entity and opens all transactions for the digital assets in the package through a single Package TransactionOpenRequest. For a Package TransactionOpenRequest, the VendorLineItem element will be comprised of child VendorLineItem elements. For example, a Folio-type Package called "FolioABC" consists of three digital assets SheetA, SheetB and SheetC. The Package TransactionOpenRequest will have a parent VendorLineItem element that will describe the Folio Package "FolioABC" and inside this parent VendorLineItem element (that describes the folio package), there will be three children VendorLineItem elements, with each child VendorLineItem element describing each of the three sheets /digital assets (i.e., a child VendorLineItem element for SheetA, a child VendorLineItem element for SheetB and a child VendorLineItem element for SheetC).

Folio Packages

For each child VendorLineItem element in a Folio package TransactionOpenRequest, a quantity must not be specified. Instead the quantity will be taken from the parent VendorLineItem element. Therefore, the quantity of children VendorLineItem elements will always be the same as that of the parent VendorLineItem element in a Folio package TransactionOpenRequest. Even if a quantity is specified in the child VendorLineItem element, the system will ignore it.

Ensemble Packages

Quantity elements are optional on each child VendorLineItem in an Ensemble package TransactionOpenRequest. If you do not specify a Quantity element on a child VendorLineItem, the system will use the default quantity for the child asset as defined by its "part count". For example, a "Violin 1" part is one of the child assets that makes up a string ensemble package. The partCount for that asset, when part of the string ensemble package, is four (4). If you do not specify a quantity on the VendorLineItem for the "Violin 1" child asset, the system will use its default value of 4. See the description of the "partCount" attribute in the Package Metadata section. If you wish to open transactions with the default (standard) instrumentation for the ensemble, the easiest thing to do is not to send Quantity elements on child VendorLineItem elements.

So, why the big deal about Quantity elements on child VendorLineItem elements if leaving them off gives you the standard instrumentation for the package? Well, by specifying Quantity elements, you now have the ability to sell a customized set of parts for the ensemble. This is especially useful in situations where band/orchestra directors have more of one instrument than another in their groups.

If you specify a Quantity element on a child VendorLineItem, you must specify them on all of the child VendorLineItem elements for the package, even if it's a zero (0) quantity. A zero quantity is valid and is used to denote that no prints are allowed for that child. The DAM system will validate that the sum of all the child Quantity elements on the package equals the sum of the "standard" set of parts for the package. An error will be returned if this fails. If everything validates correctly, transactions will be opened for each of the child VendorLineItem elements, including those with zero quantities. The only type of child VendorLineItem that you are not allow to change the quantity on are those that are classified as "scores". These assets always default to a quantity of one (1). See the description of the "score" attribute in the Package Metadata section. Note that all child quantities will be multiplied by the value of the parent VendorLineItem's Quantity element when the transactions are opened in the DAM system.

Also, it is important to note that package asset ID should be specified in the parent VendorLineItem element's AssetId element for all types of package requests.

Three additional attributes, AssetType, Format, and Type, were added to the VendorLineItem element for future development. They can be ignored at this time.

The DAM System will reply with a TransactionOpenResponse XML document containing a TransactionItem element for each VendorLineItem element in the request. Hence, for a Package TransactionOpenResponse, a TransactionItem element may be comprised of multiple TransactionItem elements embedded within it. For our earlier "FolioABC" example, in the TransactionOpenResponse, the parent TransactionItem element for "FolioABC" will contain three child TransactionItem elements in it respectively for SheetA, SheetB and SheetC.

The parent TransactionItem element for each package request will include a StatusCode element from the list of status codes. If the StatusCode is 1 for the parent TransactionItem element, then the status code of all the child TransactionItem elements is 1 and the response in each of the child TransactionItem elements will include a valid TransactionId from the DAM System identifying the transaction, the file name, the file type, the file's mime type, the file's URL, footer text strings, view/download URLs as well as status code and status description (for that particular asset in the package). An example of a request and response without errors is shown in Package Example 1 below.

If the StatusCode is not 1 for the parent TransactionItem element of the Package Request, then each of the child TransactionItem elements will not contain the TransactionId value. In such a case, a new Package TransactionOpenRequest will need to be sent to the DAM system once the error is corrected. Also, if a particular digital asset in the package caused the problem, the child TransactionItem element corresponding to that digital asset will contain a status code that is not 1 and the status description will contain the error description. The rest of the child elements will contain a status code of 1, thus helping you identify the exact asset in the package that caused the problem. Such an example is shown in Package Example 2. Remember, if any part of the Package TransactionOpenRequest fails, no transactions will be opened for the child TransactionItem elements.

Noteflight Vendors

Due to Noteflight vendors no longer using the Scorch plug-in, the FileName, FileType, MimeType, FileURL, Footer1, and Footer2 elements are not used/needed, however they are still included in the response for backwards compatibility.

Vendors using Noteflight will see a ViewURL and/or DownloadURL in the TransactionOpenResponse for each TransactionItem that represents a single asset. A "View" and "Download" URL for packages will only exist on the child assets within a package. This is because there is no "view" or "rendering" of the entire package as a self-contained asset.

The ViewURL is a URL on the DAM System that represents the Noteflight view of an asset.
The DownloadURL is a URL on the DAM System that represents a PDF view of an asset.

Both URLs expire 30 minutes after the TransactionOpenResponse is sent back to the vendor from the DAM System.

Request / Response Examples

Sheet Example

Sheet TransactionOpenRequest Example:

<?xml version="1.0"?>
<!DOCTYPE DAMRequest SYSTEM "https://haldms.halleonard.com/dam_dtd/DAMRequestVersion5.dtd">
<DAMRequest>
    <RequestHdr>
        <DAMVersion>5.0</DAMVersion>
        <VendorId>123</VendorId>
        <VendorKey>theKey123</VendorKey>
    </RequestHdr>
    <TransactionOpenRequest>
        <VendorLineItem>
            <AssetId>4000</AssetId>
            <OrderNumber>12345</OrderNumber>
            <CountryCode>US</CountryCode>
            <UnitPrice>3.99</UnitPrice>
            <LineItemPrice>7.98</LineItemPrice>
            <Quantity>2</Quantity>
            <OrderLineId>56789</OrderLineId>
            <Personalization>custname:John Customer</Personalization>
        </VendorLineItem>
    </TransactionOpenRequest>
</DAMRequest>

Sheet TransactionOpenResponse Example:

<?xml version="1.0"?>
<!DOCTYPE DAMResponse SYSTEM "https://haldms.halleonard.com/dam_dtd/DAMResponseVersion5.dtd">
<DAMResponse>
    <ResponseHdr>
        <DAMVersion>5.0</DAMVersion>
        <VendorId>123</VendorId>
    </ResponseHdr>
    <TransactionOpenResponse>
        <TransactionItem>
            <AssetId>4000</AssetId>
            <OrderNumber>12345</OrderNumber>
            <OrderLineId>56789</OrderLineId>
            <TransactionId>1122333</TransactionId>
            <FileName>A_B_004000.sco</FileName>
            <FileType>SCORCH</FileType>
            <MimeType>application/x-sibelius-score</MimeType>
            <FileURL>http://haldms.halleonard.com/sf/A_B_004000.sco</FileURL>
            <Footer1>This is the first page footer.</Footer1>
            <Footer2>This is the second page footer.</Footer2>
            <ViewURL mimeType="text/xml">haldms.halleonard.com/nf/viewer/A39NVEXG5TPJ2TNUQ12DRJ8JX27X5WF6</ViewURL>
            <DownloadURL mimeType="application/pdf">haldms.halleonard.com/nf/download/F1U8PFF8RL2F5L2FHHQC8WJ65A7KK9YW</DownloadURL>
            <StatusCode>1</StatusCode>
            <StatusDescription>OK.</StatusDescription>
        </TransactionItem>
    </TransactionOpenResponse>
</DAMResponse>

Package Example 1

Package TransactionOpenRequest #1

<?xml version="1.0"?>
<!DOCTYPE DAMRequest SYSTEM "https://haldms.halleonard.com/dam_dtd/DAMRequestVersion5.dtd">
<DAMRequest>
    <RequestHdr>
        <DAMVersion>5.0</DAMVersion>
        <VendorId>123</VendorId>
        <VendorKey>theKey123</VendorKey>
    </RequestHdr>
    <TransactionOpenRequest>
        <VendorLineItem>
            <AssetId>25199</AssetId>
            <OrderNumber>230797</OrderNumber>
            <CountryCode>US</CountryCode>
            <UnitPrice>9.99</UnitPrice>
            <LineItemPrice>9.99</LineItemPrice>
            <Quantity>1</Quantity>
            <OrderLineId>0</OrderLineId>
            <VendorLineItem>
                <AssetId>1884</AssetId>
                <OrderNumber>230797</OrderNumber>
                <CountryCode>US</CountryCode>
                <OrderLineId>370831</OrderLineId>
                <Personalization>custname:John Customer</Personalization>
            </VendorLineItem>
            <VendorLineItem>
                <AssetId>4072</AssetId>
                <OrderNumber>230797</OrderNumber>
                <CountryCode>US</CountryCode>
                <OrderLineId>370832</OrderLineId>
                <Personalization>custname:John Customer</Personalization>
            </VendorLineItem>
            <VendorLineItem>
                <AssetId>7590</AssetId>
                <OrderNumber>230797</OrderNumber>
                <CountryCode>US</CountryCode>
                <OrderLineId>370833</OrderLineId>
                <Personalization>custname:John Customer</Personalization>
            </VendorLineItem>
            <VendorLineItem>
                <AssetId>15275</AssetId>
                <OrderNumber>230797</OrderNumber>
                <CountryCode>US</CountryCode>
                <OrderLineId>370834</OrderLineId>
                <Personalization>custname:John Customer</Personalization>
            </VendorLineItem>
            <VendorLineItem>
                <AssetId>18442</AssetId>
                <OrderNumber>230797</OrderNumber>
                <CountryCode>US</CountryCode>
                <OrderLineId>370835</OrderLineId>
                <Personalization>custname:John Customer</Personalization>
            </VendorLineItem>
        </VendorLineItem>
    </TransactionOpenRequest>
</DAMRequest>

Package TransactionOpenResponse #1 - Response without Errors

<?xml version="1.0"?>
<!DOCTYPE DAMResponse SYSTEM "https://haldms.halleonard.com/dam_dtd/DAMResponseVersion5.dtd">
<DAMResponse>
    <ResponseHdr>
        <DAMVersion>5.0</DAMVersion>
        <VendorId>123</VendorId>
    </ResponseHdr>
    <TransactionOpenResponse>
        <TransactionItem AssetType="SCORCH" Format="PVG" Type="F">
            <AssetId>25199</AssetId>
            <OrderNumber>230797</OrderNumber>
            <OrderLineId>0</OrderLineId>
<!-- The parent TransactionItem is OK (1), therefore all the child TransactionItems are OK. -->
            <StatusCode>1</StatusCode>
            <StatusDescription>OK.</StatusDescription>
            <TransactionItem>
                <AssetId>1884</AssetId>
                <OrderNumber>230797</OrderNumber>
                <OrderLineId>370831</OrderLineId>
                <TransactionId>20533035</TransactionId>
                <FileName>HL_DDS_00375378.sco</FileName>
                <FileType>SCORCH</FileType>
                <MimeType>application/x-sibelius-score</MimeType>
                <FileURL>http://haldms.halleonard.com/scorch_files/HL_DDS_00375493.sco</FileURL>
                <Footer1>This is the first page footer.</Footer1>
                <Footer2>This is the second page footer.</Footer2>
                <DownloadURL>haldms.halleonard.com/nf/download/4WHEX696YEPD2FR9DYBYGQF2KT7F1TSA</DownloadURL>
                <StatusCode>1</StatusCode>
                <StatusDescription>OK.</StatusDescription>
            </TransactionItem>
            <TransactionItem>
                <AssetId>4072</AssetId>
                <OrderNumber>230797</OrderNumber>
                <OrderLineId>370832</OrderLineId>
                <TransactionId>20533042</TransactionId>
                <FileName>HL_DDS_0000000000090175.sco</FileName>
                <FileType>SCORCH</FileType>
                <MimeType>application/x-sibelius-score</MimeType>
                <FileURL>http://haldms.halleonard.com/scorch_files/HL_DDS_00375574.sco</FileURL>
                <Footer1>This is the first page footer.</Footer1>
                <Footer2>This is the second page footer.</Footer2>
                <DownloadURL>haldms.halleonard.com/nf/download/4JW63BAHT687KXBJKD7WDYFGA3N1EVLF</DownloadURL>
                <StatusCode>1</StatusCode>
                <StatusDescription>OK.</StatusDescription>
            </TransactionItem>
            <TransactionItem>
                <AssetId>7590</AssetId>
                <OrderNumber>230797</OrderNumber>
                <OrderLineId>370833</OrderLineId>
                <TransactionId>20533049</TransactionId>
                <FileName>HL_DDS_0000000000103892.sco</FileName>
                <FileType>SCORCH</FileType>
                <MimeType>application/x-sibelius-score</MimeType>
                <FileURL>http://haldms.halleonard.com/scorch_files/HL_DDS_0000000000102637.sco</FileURL>
                <Footer1>This is the first page footer.</Footer1>
                <Footer2>This is the second page footer.</Footer2>
                <DownloadURL>haldms.halleonard.com/nf/download/1U82H3G34UH7RGRUAH1T6Y9KTETFPGJ4</DownloadURL>
                <StatusCode>1</StatusCode>
                <StatusDescription>OK.</StatusDescription>
            </TransactionItem>
            <TransactionItem>
                <AssetId>15275</AssetId>
                <OrderNumber>230797</OrderNumber>
                <OrderLineId>370834</OrderLineId>
                <TransactionId>20533056</TransactionId>
                <FileName>HL_DDS_0000000000120801.sco</FileName>
                <FileType>SCORCH</FileType>
                <MimeType>application/x-sibelius-score</MimeType>
                <FileURL>http://haldms.halleonard.com/scorch_files/HL_DDS_00375570.sco</FileURL>
                <Footer1>This is the first page footer.</Footer1>
                <Footer2>This is the second page footer.</Footer2>
                <DownloadURL>haldms.halleonard.com/nf/download/9GUZ4HT9PA277JNEHRBLPXVTV267BVEQ</DownloadURL>
                <StatusCode>1</StatusCode>
                <StatusDescription>OK.</StatusDescription>
            </TransactionItem>
            <TransactionItem>
                <AssetId>18442</AssetId>
                <OrderNumber>230797</OrderNumber>
                <OrderLineId>370835</OrderLineId>
                <TransactionId>20533063</TransactionId>
                <FileName>HL_DDS_0000000000123509.sco</FileName>
                <FileType>SCORCH</FileType>
                <MimeType>application/x-sibelius-score</MimeType>
                <FileURL>http://haldms.halleonard.com/scorch_files/HL_DDS_0000000000090069.sco</FileURL>
                <Footer1>This is the first page footer.</Footer1>
                <Footer2>This is the second page footer.</Footer2>
                <DownloadURL>haldms.halleonard.com/nf/download/2VD883U52M4AEG9K44ADTCUU74HXFMMZ</DownloadURL>
                <StatusCode>1</StatusCode>
                <StatusDescription>OK.</StatusDescription>
            </TransactionItem>
        </TransactionItem>
    </TransactionOpenResponse>
</DAMResponse>

Package Example 2

Package TransactionOpenRequest #2

<?xml version="1.0"?>
<!DOCTYPE DAMRequest SYSTEM "https://haldms.halleonard.com/dam_dtd/DAMRequestVersion5.dtd">
<DAMRequest>
    <RequestHdr>
        <DAMVersion>5.0</DAMVersion>
        <VendorId>123</VendorId>
        <VendorKey>theKey123</VendorKey>
    </RequestHdr>
    <TransactionOpenRequest>
        <VendorLineItem>
            <AssetId>26799</AssetId>
            <OrderNumber>230797</OrderNumber>
            <CountryCode>US</CountryCode>
            <UnitPrice>9.99</UnitPrice>
            <LineItemPrice>9.99</LineItemPrice>
            <Quantity>1</Quantity>
            <OrderLineId>0</OrderLineId>
            <VendorLineItem>
                <AssetId>1934</AssetId>
                <OrderNumber>230797</OrderNumber>
                <CountryCode>US</CountryCode>
                <OrderLineId>370831</OrderLineId>
                <Personalization>custname:John Customer</Personalization>
            </VendorLineItem>
            <VendorLineItem>
                <AssetId>1975</AssetId>
                <OrderNumber>230797</OrderNumber>
                <CountryCode>US</CountryCode>
                <OrderLineId>370832</OrderLineId>
                <Personalization>custname:John Customer</Personalization>
            </VendorLineItem>
            <VendorLineItem>
                <AssetId>8407</AssetId>
                <OrderNumber>230797</OrderNumber>
                <CountryCode>US</CountryCode>
                <OrderLineId>370833</OrderLineId>
                <Personalization>custname:John Customer</Personalization>
            </VendorLineItem>
            <VendorLineItem>
                <AssetId>1973</AssetId>
                <OrderNumber>230797</OrderNumber>
                <CountryCode>US</CountryCode>
                <OrderLineId>370834</OrderLineId>
                <Personalization>custname:John Customer</Personalization>
            </VendorLineItem>
            <VendorLineItem>
                <AssetId>3952</AssetId>
                <OrderNumber>230797</OrderNumber>
                <CountryCode>US</CountryCode>
                <OrderLineId>370835</OrderLineId>
                <Personalization>custname:John Customer</Personalization>
            </VendorLineItem>
        </VendorLineItem>
    </TransactionOpenRequest>
</DAMRequest>

Package TransactionOpenResponse #2 - Error Response

<?xml version="1.0"?>
<!DOCTYPE DAMResponse SYSTEM "https://haldms.halleonard.com/dam_dtd/DAMResponseVersion5.dtd">
<DAMResponse>
    <ResponseHdr>
        <DAMVersion>5.0</DAMVersion>
        <VendorId>123</VendorId>
    </ResponseHdr>
    <TransactionOpenResponse>
        <TransactionItem AssetType="PART" Format="ePak" Type="E">
            <AssetId>10344</AssetId>
            <OrderNumber>230797</OrderNumber>
            <OrderLineId>0</OrderLineId>
            <StatusCode>30</StatusCode> The parent TransactionItem error.
            <StatusDescription>Invalid Folio item in request</StatusDescription>
            <TransactionItem>
                <AssetId>1934</AssetId>
                <OrderNumber>230797</OrderNumber>
                <OrderLineId>370831</OrderLineId>
                <FileName>HL_DDS_00375493.sco</FileName>
                <FileType>SCORCH</FileType>
                <MimeType>application/x-sibelius-score</MimeType>
                <FileURL>http://haldms.halleonard.com/scorch_files/HL_DDS_00375493.sco</FileURL>
                <Footer1>This is the first page footer.</Footer1>
                <Footer2>This is the second page footer.</Footer2>
                <DownloadURL>haldms.halleonard.com/nf/download/4WHEX696YEPD2FR9DYBYGQF2KT7F1TSA</DownloadURL>
                <StatusCode>1</StatusCode>
                <StatusDescription>OK.</StatusDescription>
            </TransactionItem>
            <TransactionItem>
                <AssetId>1975</AssetId>
                <OrderNumber>230797</OrderNumber>
                <OrderLineId>370832</OrderLineId>
<!-- The specific child TransactionItem in error. -->
                <StatusCode>2</StatusCode>
                <StatusDescription>File does not exist or bad path.</StatusDescription>
            </TransactionItem>
            <TransactionItem>
                <AssetId>8407</AssetId>
                <OrderNumber>230797</OrderNumber>
                <OrderLineId>370833</OrderLineId>
                <FileName>HL_DDS_0000000000102637.sco</FileName>
                <FileType>SCORCH</FileType>
                <MimeType>application/x-sibelius-score</MimeType>
                <FileURL>http://haldms.halleonard.com/scorch_files/HL_DDS_0000000000102637.sco</FileURL>
                <Footer1>This is the first page footer.</Footer1>
                <Footer2>This is the second page footer.</Footer2>
                <DownloadURL>haldms.halleonard.com/nf/download/2VD883U52M4AEG9K44ADTCUU74HXFMMZ</DownloadURL>
                <StatusCode>1</StatusCode>
                <StatusDescription>OK.</StatusDescription>
            </TransactionItem>
            <TransactionItem>
                <AssetId>1973</AssetId>
                <OrderNumber>230797</OrderNumber>
                <OrderLineId>370834</OrderLineId>
                <FileName>HL_DDS_00375570.sco</FileName>
                <FileType>SCORCH</FileType>
                <MimeType>application/x-sibelius-score</MimeType>
                <FileURL>http://haldms.halleonard.com/scorch_files/HL_DDS_00375570.sco</FileURL>
                <Footer1>This is the first page footer.</Footer1>
                <Footer2>This is the second page footer.</Footer2>
                <DownloadURL>haldms.halleonard.com/nf/download/9GUZ4HT9PA277JNEHRBLPXVTV267BVEQ</DownloadURL>
                <StatusCode>1</StatusCode>
                <StatusDescription>OK.</StatusDescription>
            </TransactionItem>
            <TransactionItem>
                <AssetId>3952</AssetId>
                <OrderNumber>230797</OrderNumber>
                <OrderLineId>370835</OrderLineId>
                <FileName>HL_DDS_0000000000090069.sco</FileName>
                <FileType>SCORCH</FileType>
                <MimeType>application/x-sibelius-score</MimeType>
                <FileURL>http://haldms.halleonard.com/scorch_files/HL_DDS_0000000000090069.sco</FileURL>
                <Footer1>This is the first page footer.</Footer1>
                <Footer2>This is the second page footer.</Footer2>
                <DownloadURL>haldms.halleonard.com/nf/download/1U82H3G34UH7RGRUAH1T6Y9KTETFPGJ4</DownloadURL>
                <StatusCode>1</StatusCode>
                <StatusDescription>OK.</StatusDescription>
            </TransactionItem>
        </TransactionItem>
    </TransactionOpenResponse>
</DAMResponse>

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search