Data Map

The data returned from Vendor Admin and the AssetMetadataRequest conforms to the following conceptual data model. Not all data is provided to all vendors. Data entities noted in red below are only provided to vendors with access to Hal Leonard's recording assets. Data entities noted in green below are only provided to vendors with access to Hal Leonard's UserGen assets.

Preview Mode HTML Code

When you request DAM asset metadata in CSV (comma separated) or TAB (tab-delimited) format, several files will be returned to you within a single archive file. If you use only the XML data format, you can the use the file organization to set up your own database. Note that some data is only provided to vendors with access to Hal Leonard's recording assets.

The files returned in the archive are:

File Name Description
ASSET A digital sellable good. An asset may be a physical asset, which may be sold individually, or a collection of assets, which may be sold as a group, such as a digital folio. See ASSET_PACKAGE.
ALBUMS Recording Vendors Only - The catalog albums to which an asset may belong.
ASSET_ALBUM Recording Vendors Only - The albums to which an asset belongs.
ASSET_CATEGORY The categories to which an asset belongs.
ASSET_CONTRIBUTOR The person(s) or group associated with the asset, including the "role" played, for example "Artist", "Composer", "Author", etc.
ASSET_HARDGOOD The Hal Leonard SKU of related hard good products, such as folios or individual sheets, that contain the asset. The ASSET_HARDGOOD file has been deprecated and replaced with the ASSET_RELATEDGOOD file. The ASSET_HARDGOOD file is, however, still provided for backwards compatibility.
ASSET_IMAGES The file names of static images related to an asset. This includes preview pages, and cover images of varying sizes. See IMAGE_TYPES
ASSET_INSTRUMENT The instrument(s) most closely associated with an asset.
ASSET_KEYWORD Specialized keywords to make an asset more searchable. These keywords are not intrinsic to an asset's title, sub-title, description, or any other natural data that describes the asset.
ASSET_PACKAGE This file describes the combinations of assets, in parent-child relationships, that may be sold collectively as a single asset, for example as a digital folio.
ASSET_PRICE This file identifies the price of the asset. Price is split out into its own file to accommodate the possibility of assets with multiple prices. For now, all assets only have a single price. The asset's retail price is also included in the ASSET file for backwards compatability.
ASSET_RECORDING Recording Vendors Only - The recordings to which an asset belongs, including the available quality levels.
ASSET_RELATEDGOOD Identifies any sellable goods that are related to the asset. Includes both hardgoods and digital goods.
ASSET_RENDERING This file lists the available renderings for an asset. This information allows you to show customers what type of content is available for a given asset – available in PDF or Scorch, for example.
ASSET_SERIES The Series to which an asset belongs. See SERIES file.
ASSET_SKILL Recording Vendors Only - The list of assets required to achieve a defined proficiency.
ASSET_USERGEN_MEDLEY_ASSET Usergen Vendors Only - The recordings to which an asset belongs, including the available quality levels.
ASSET_USERGEN_PART Usergen Vendors Only - The recordings to which an asset belongs, including the available quality levels.
ASSET_WRITER The writer(s) associated with an asset. Note: The ASSET_WRITER file has been deprecated and replaced with the ASSET_CONTRIBUTOR file. The ASSET_WRITER file is, however, still provided for backwards compatibility.
CATEGORY The catalog of "classifications" to which an asset may belong, for example "Pop", "Rock", etc. These can be used to set up browsing hierarchies in your system.
CONTRIBUTOR_BIOGRAPHIES Recording Vendors Only - A short description of a contributor's background, along with a still image or video clip URL.
CONTRIBUTOR_ROLES The list of allowed roles a person or group may play when associated with an asset, for example "Artist", "Arranger", "Editor", etc.
COUNTRY The current DAM System ISO country list.
FORMAT The catalog of notation formats an asset can have.
GROUP_TYPES The different type of product associations in the system. There are currently three group types: "Hardgood", "Voicing", and "Digital". Each group type is uniquely identified by a "group type" identifier. Group types help define the relationships between items, for example, item "A" may have a "hardgood" relationship to item "B". Item "A" may also have a "voicing" relationship to items "C", "D", and "E". Voicing relationships are typically defined between similar choral products where the only difference is the voicing of the arrangement (SATB, SSA, TTB, etc.)
IMAGE_TYPES The catalog and URL location of the various types of images available for an asset. This data is used in conjunction with the ASSET_IMAGES data.
INSTRUMENT The catalog of all instruments.
INSTRUMENTATION_PARTS The "catalog" of all instrumental parts defined in the DAM system, each uniquely identified by a "part code" identifier. This can be used to determine the instrument part name, for example "Trumpet 1", associated with an asset.
KEY_SIGNATURES The catalog of musical key signatures an asset may have. Only one key signature exists per asset and represents the most common tonal/modal center of the musical work.
QUALITY_TYPES Recording Vendors Only - The list of available bandwidth levels, such as "low", "medium", and "high" in which an asset may be provided.
RECORDINGS Recording Vendors Only - The catalog of recordings to which an asset may belong.
RECORDING_STUDIOS Recording Vendors Only - The catalog of studios at which a recording was made.
SELLABLE_COUNTRY The countries into which a digital asset may be sold. Note that assets that have "world" rights will have no entries in this file.
SERIES "Series" is specific to choral format assets and provides a finer level of product classification for each asset. Each series name is uniquely identified by a series id. Series can be used to facilitate searching and browsing choral products.
SKILLS Recording Vendors Only - A proficiency desired, such as "Finger Picking", or "Slap Bass".

File Columns and Data Types

The names, data types, and descriptions of the columns in each file are listed below. Note that each file will contain a comma, or tab separated list of column headings as the first record in the file. Be sure to delete this if you do not need it. Columns in bold represent the uniquely identifying attribute(s) for the record.

File: ALBUMS

Column Data Type Comments
ALBUM_ID Number(9,0) The unique identifier of an album
ALBUM_NAME VarChar(320) The album name.
ALBUM_IMAGE_FILE VarChar(2000) The file name and URL of an album cover image.

File: ASSET_ALBUM

Column Data Type Comments
ASSET_ID Number(10,0) The unique identifier of an asset.
ALBUM_ID Number(9,0) The unique identifier of an album.

File: ASSET

Column Data Type Comments
ASSET_ID Number (10,0) A number that uniquely identifies each asset.
ASSET_TYPE VarChar(40) The type of asset, for example: SCORCH, FOLIO, et.
FORMAT VarChar(40) The short-name format ID. See FORMAT.
ASSET_TITLE VarChar(100) The title of the song or package.
DESCRIPTION VarChar(4000) Only non-sheet assets will have a description. See PACKAGE_TYPE column.
DATE_ADDED Char(10) Format = mm/dd/yyyy. The date that the asset was added to the DAM system.
DATE_DELETED Char(10) Format = mm/dd/yyyy. The date that the asset was removed from the DAM system. Note that no sales are permitted beyond the date the asset was deleted.
PAGE_COUNT Number(5,0) The number of pages in the song.
RETAIL_PRICE Number(5,2) Hal Leonard's suggested retail price for the asset.
FILENAME VarChar(80) The asset's physical file name.
FILETYPE VarChar(40) The asset's file type, for example SCORCH. Note that Package assets do not have a file type, since they are simply a collection of other assets.
FILESOURCE VarChar(25) Indicates whether the asset was created from a "native" notation file, such as a Sibelius or Finale file, or "pdf", if the asset was created from a PDF source. Currently, "native" and "pdf" are the only two possible values. Note that assets created from "pdf" sources require a minimum of Scorch v5 to view the asset.
MIME_TYPE VarChar(80) The internet media type associated with the asset, for example: "application/x-sibelius-score".
FILEURL VarChar(230) The URL path and file name to the physical asset.
WORLD_RIGHTS Char(5) Values = "TRUE" or "FALSE". If "FALSE", the SELLABLE_COUNTRY file will list all the allowed countries in which this asset may be sold.
SONG_NUMBER Number(6,0) Hal Leonard's internal song identifier.
PUBLIC_DOMAIN Char(5) Values = "TRUE" or "FALSE". Indicates whether the song represented by this asset exists in the public domain.
PACKAGE_TYPE VarChar(100) Values = "SHEET" or "PACKAGE". See ASSET_TYPE.
ASSET_ACTION Char(6) Values = "new", "update", or "delete". Indicates whether this record should be added, updated, or deleted. For "update" assets, all data will be provided, not just the "changed" data. It is up to the receiving system to determine which fields and files need to be updated.
ASSET_VOICING VarChar(50) Typically, the voicing configuration of a Choral format asset, for example SATB, SSA, TTB.
PERFORMANCE_TIME Number(10,0) The performance duration of the asset in seconds.
EXTERNAL_REF VarChar(80) The identifier of the company providing the asset. Do not use.
DIFFICULTY_LEVEL_LOW Number(3,2) The relative performance difficulty of the asset. (low end of the range).
DIFFICULTY_LEVEL_HIGH Number(3,2) The relative performance difficulty of the asset. (high end of the range).
TEMPO Number(5,0) The beats per minute of the asset.
MINIMUM_QUANTITY Number(9,0) The minimum allowed purchase quantity, typically enforced on Choral format assets.
IMAGE_URL VarChar(2000) The URL of a thumbnail image of the asset, typically used for audio and video assets only.
TITLE_SORT VarChar(100) The title against which sorts should be preformed. Articles, such as "A", "An", and "The" will have been removed from titles to facilitate proper sorting.
SUBTITLE VarChar(100) Text which further claifies the musical work, such as "from the musical Annie"
KEY_SIGNATURE_ID Number(9,0) The ID of the Key Signature and Modality most closely associated with the musical work.
MUSIC_BRAINZ_ID VarChar(80) The musical work's identifier in the MusicBrainz open content music database.
EXPLICIT VarChar(1) A Y/N indicator that denotes whether an asset contains graphic material, such as profanity in lyrics.
PARTABLE VarChar(1) A Y/N indicator that denotes whether an Ensemble's parts may be sold individually. This information is only available on Ensemble assets. See ASSET_PACKAGE.
SMD_ID VarChar(80) Not currently used.
USERGEN_BLACK_BOX VarChar(1) A Y/N indicator that denotes if copyright holder is unknown at the time the arrangement is created.
USERGEN_ARRANGABLE VarChar(1) A Y/N indicator that denotes if the work is arrangable through the Usergen program
USERGEN_VENDOR_PRODUCT_TYPE VarChar(50) The type of Usergen content: usergen_original is original composition, not based on the work of some other party. usergen_arrangement_of_copyright for arrangements of copywritten work, usergen_pd for public domain arrangements usergen_arrangement_of_usergen_song for arrangements of other usergen songs
USERGEN_SELLER_ID Number(38,0) The seller Id of the arranger on ArrangeMe
USERGEN_AUTHORIZED_PERFORMERS Number(38,0) Maximumn number of performers of a given asset, 0 if unlimited.
USERGEN_CONTENT_PROVIDER VarChar(50) Which of the UserGen creation sites this asset came from
USERGEN_ADAPTATION_PRODUCT_ID VarChar(100) The product id of the Usergen asset that this asset was arranged from
USERGEN_ADAPTATION_VENDOR VarChar(10) The Usergen provider that the the adapation product id was from.
USERGEN_VENDOR_SONG_ID VarChar(40) The Usergen provider's song id
USERGEN_COMMISSION_OVERRIDE_RATE NUMBER(7,6) The Usergen arranger's comission override rate
USERGEN_PUBLISHER_NAME VarChar(100) The arranger's publisher name

File: ASSET_ARTIST

Column Data Type Comments
ASSET_ID Number (10,0) The related asset for this artist.
ARTIST_NAME VarChar(80) The name of the artist.
ARTIST_NAME_REV VarChar(80) The reversed name of the artist in the form "last, first".
PRIMARY Char(1) Values = "Y" or "N". Denotes the most significant artist associated with this asset. Only one primary artist may exist per asset.

File: ASSET_CATEGORY

Column Data Type Comments
ASSET_ID Number (10,0) The related asset for this category.
CATEGORY_ID Number (10,0) The id of the asset's related category (See the CATEGORY file.)

File: ASSET_CONTRIBUTOR

Column Data Type Comments
ASSET_ID Number (10,0) The related asset for this contributor.
CONTRIBUTOR_TYPE VarChar(50) The role the contributor plays when associated with the asset, for example "ARTIST", "ARRANGER", "EDITOR", etc.
CONTRIBUTOR_NAME VarChar(80) The name of the contributor.
CONTRIBUTOR_NAME_REV VarChar(80) The reversed name of the contributor in the form "last, first".
PRIMARY Char(1) Values = "Y" or "N". Denotes the most significant contributor associated with this asset. Only one primary contributor may exist per asset.
CONTRIBUTOR_NAME_SORT VarChar(80) The name against which the contributor should be presented in an ordered list. For example, "The Beatles" will have a value of "Beatles" for this field.
MUSICBRAINZ_ID VarChar(80) The contributor's identifier in the MusicBrainz open content music database.

File: ASSET_HARDGOOD

Column Data Type Comments
ASSET_ID Number(10,0) The ASSET_ID associated with this hardgood.
HAL_LEONARD_SKU Number(8,0) The Hal Leonard hardgood SKU.
SHEET Char(5) Values = "TRUE" or "FALSE". Indicates whether this SKU is a single song sheet hardgood.

File: ASSET_IMAGES

Column Data Type Comments
ASSET_ID Number(10,0) The ASSET_ID associated with this image.
IMAGE_TYPE Number(3,0) The type and location of the image. (See the IMAGE_TYPES file).
IMAGE_FILENAME Char(200) The image file name.

File: ASSET_INSTRUMENT

Column Data Type Comments
ASSET_ID Number (10,0) The related asset for this instrument.
INSTRUMENT_ID Number (9,0) The id of the asset's related instrument. (See the INSTRUMENTS file.)

File: ASSET_KEYWORD

Column Data Type Comments
ASSET_ID Number (10,0) The related asset for this keyword.
KEYWORD VarChar(320) The keyword value.

File: ASSET_PACKAGE

Column Data Type Comments
PARENT_ASSET_ID Number (10,0) The parent asset of the collection.
CHILD_ASSET_ID Number (10,0) The constituents (children) of the collection.
PART_COUNT Number (3,0) The number of copies to be included when the constituent is sold as a single unit.
PART_CODE VarChar(10) The id of the related instrument name. See INSTRUMENTATION_PARTS file.
PART_SEQUENCE Number (3,0) The order in which to sort the package in score sequence.
SCORE Char(1) Values = "Y" or "N". A "Y" denotes that the asset is the "score" part of the package.

File: ASSET_PRICE

Column Data Type Comments
ASSET_ID Number (10,0) The related asset for this price.
PRICE_TYPE_ID Number (9,0)
PRICE_TYPE_USAGE VarChar(40) "full", "audio-only", or "upgrade"
PRICE_VALUE Number (7,2) The price value for the given usage.

File: ASSET_RECORDING

Column Data Type Comments
ASSET_ID Number (10,0) The related asset for this recording.
RECORDING_ID Number (9,0) The unique id of the recording for this asset.
QUALITY_TYPE VarChar(200) The recording quality level available for this asset.

File: ASSET_RELATEDGOOD

Column Data Type Comments
ASSET_ID Number (10,0) The asset associated with this related good.
RELATED_PRODUCT Number (10,0) The unique identifier of the related good.
HL_SKU_OR_ASSET_ID VarChar(25) Indicates whether the value of the RELATED_PRODUCT field is a Hal Leonard SKU (a hardgood) or an Asset ID (a digital good).
GROUP_TYPE_ID Number (10,0) Denotes the type of relationship: 1 = hardgood; 2 = Voicing.
SHEET Char(5) Values = "TRUE" or "FALSE". Indicates whether the Hal Leonard SKU is a single song sheet hardgood.
PRIMARY_SOURCE Char(1) A Y/N indicator that denotes whether the main item that is related to this asset.
FEATURED Char(1) A Y/N indicator that denotes whether the item is closely related.

File: ASSET_RENDERING

Column Data Type Comments
ASSET_ID Number (10,0) The related asset for this keyword.
RENDERING_TYPE VarChar(20) The type of rendering available for this asset. Possible values could be: “pdf”, “musicxml”, “scorch”, etc.
RENDERING_FILENAME VarChar(80) The filename value. Currently this field will only be populated for scorch rendering types.

File: ASSET_SERIES

Column Data Type Comments
ASSET_ID Number (10,0) The related ASSET for this series.
SERIES_ID Number (10,0) The related SERIES for this asset.

File: ASSET_SKILL

Column Data Type Comments
ASSET_ID Number (10,0) The related asset for this price.
SKILL_ID Number (9,0) The skill. (See the SKILLS file).
SEQUENCE Number (9,0) The relative order of this asset in the sequence of assets to achieve a skill.

File: ASSET_USERGEN_MEDLEY_ASSET

Column Data Type Comments
ASSET_ID Number (10,0) The medley Usergen asset
SONG_CATALOG_ID VarChar (11) The system generated id linking Usergen medley and HL song number
HL_SONG_ID Number (6,0) Hal Leonard's internal song identifier.
SEQUENCE Number (9,0) The relative order of the somgs in the medley
SONG_TITLE Number (9,0) The song's title

File: ASSET_USERGEN_PART

Column Data Type Comments
ASSET_ID Number (10,0) The parent asset id of this collection.
PART_ID Number (9,0) The asset id of this part.
PART_SEQ Number (3,0) The order in which to sort the package in score sequence.
PART_NAME Number (9,0) The name of the part asset.

File: ASSET_WRITER

Column Data Type Comments
ASSET_ID Number (10,0) The related asset for this writer.
WRITER_NAME VarChar(80) The name of the writer.
WRITER_NAME_REV VarChar(80) The reversed name of the writer in the form "last, first".
PRIMARY Char(1) Values = "Y" or "N". Denotes the most significant writer associated with this asset. Only one primary writer may exist per asset.

File: CATEGORY

Column Data Type Comments
CATEGORY_ID Number (10,0) A number that uniquely identifies each category.
CATEGORY_NAME VarChar(80) The classification to which an asset may belong, for example "Pop", "Rock", "Jazz", etc.

File: CONTRIBUTOR_BIOGRAPHY

Column Data Type Comments
BIOGRAPHY_ID Number (9,0) System generated unique id.
BIOGRPAHY VarChar(4000) The textual description of the biography. May contain HTML characters.
FILE_NAME VarChar(80) The file name of a static image or video clip.
FILE_PATH VarChar(200) The URL location of the image or video clip.
FILE_TYPE VarChar(10) The type of file, either JPG (static image) or FLV (Flash video clip).
CONTRIBUTOR_TYPE VarChar(50) The role the contributor plays when associated with the asset, for example "ARTIST", "ARRANGER", "EDITOR", etc.
CONTRIBUTOR_NAME VarChar(80) The name of the contributor.
CONTRIBUTOR_NAME_REV VarChar(80) The reversed name of the contributor in the form "last, first".
CONTRIBUTOR_NAME_SORT VarChar(80) The name against which the contributor should be presented in an ordered list. For example, "The Beatles" will have a value of "Beatles" for this field.
PRIMARY Char(1) Values = "Y" or "N". Denotes the most significant contributor associated with this asset. Only one primary contributor may exist per asset.
MUSICBRAINZ_ID VarChar(80) The contributor's identifier in the MusicBrainz open content music database.

File: CONTRIBUTOR_ROLES

Column Data Type Comments
ROLE_ID Number (10,0) A number that uniquely identifies each role.
CONTRIBUTOR_ROLE VarChar(50) The name of the role a contributor may play, for example "ARTIST", "COMPOSER", etc.

File: COUNTRY

Column Data Type Comments
COUNTRY_CODE VarChar(10) The ISO country code.
COUNTRY_NAME VarChar(100) The ISO country name.

File: FORMAT

Column Data Type Comments
FORMAT_SHORT_NAME VarChar(10) The unique identifier of the notational format.
FORMAT_NAME VarChar(80) The notational format an asset may have.

File: IMAGE_TYPES

Column Data Type Comments
IMAGE_TYPE_ID Number (3,0) System generated unique id.
IMAGE_TYPE VarChar(20) A short description of the type of image and its context.
IMAGE_TYPE_PATH VarChar(200) The URL location of the images of this type.

File: INTRUMENTATION_PARTS

Column Data Type Comments
PART_CODE VarChar(10) The unique identifier of the instrument part name.
PART_NAME VarChar(100) The instrument part name.

File: INSTRUMENTS

Column Data Type Comments
INSTRUMENT_ID Number(9,0) The unique identifier of the instrument.
INSTRUMENT_NAME VarChar(320) The instrument name.
INSTRUMENT_TYPE Char(1) An indicator "I" if this is a single instrument like guitar, or "P" if it a performance group like Cello Duet

File: KEY_SIGNATURES

Column Data Type Comments
KEY_SIGNATURE_ID Number (9,0) System generated unique id.
MODALITY VarChar(20) "MAJOR" or "MINOR".
KEY_SIGNATURE VarChar(320) The key signature description.

File: GROUP_TYPES

Column Data Type Comments
GROUP_TYPE_ID Number(10,0) The unique identifier of the group type (aka product association).
GROUP_TYPE VarChar(100) The name of the product association type, for example "Hardgood".

File: QUALITY_TYPES

Column Data Type Comments
QUALITY_TYPE_ID Number (9,0) System generated unique id.
QUALITY_TYPE_ABBR VarChar(20) A short caption of the quality.
QUALITY_TYPE VarChar(200) A long description of the quality.

File: RECORDINGS

Column Data Type Comments
RECORDING_ID Number (9,0) System generated unique id.
RECORDING_YEAR Number (4,0) The year in which the recording was made.
STUDIO_ID Number (9,0) The identifier of the studio where the recording was made. (See RECORDING_STUDIOS.)
SUP_FILE_NAME VarChar (80) The path to any supplemental content for the recording
SUP_LINK_NAME VarChar (80) The display name of the link
RECORDING_TITLE VarChar (100) The title of the recording
DESCRIPTION VarChar (4000) The description of the recording
VOICING VarChar (80) The voicing of the recording

File: RECORDING_STUDIOS

Column Data Type Comments
STUDIO_ID Number(9,0) The unique identifier of the recording studio.
STUDIO_NAME VarChar(320) The name of the recording studio.

File: SELLABLE_COUNTRY

Column Data Type Comments
ASSET_ID Number(10,0) The ASSET_ID associated with this ISO country code.
COUNTRY_CODE VarChar(10) The ISO country code.

File: SERIES

Column Data Type Comments
SERIES_ID Number(10,0) The unique identifier of the product series.
SERIES VarChar(100) The name of the product series, typically for Choral format assets.

File: SKILLS

Column Data Type Comments
SKILL_ID Number (9,0) System generated unique id.
SKILL VarChar(40) The skill name.
SKILL_PARENT_ID Number (9,0) The identifier of any skill that the given skill is a part of.