Generating MWN messages
The following articles are intended to help generating MusicalWorkClaimNotificationMessages
in response to a MusicalWorkClaimRequestMessage
. This guidance is based on an implementation by a music publisher and constitute a set of checks and actions for practical guidance and is not an exhaustive set of validation rules.
1. General rules
This guideline document describes how a music publisher that has received a MusicalWorkClaimRequestMessage
via a hub or directly from a record company should proceed when generating a MusicalWorkClaimNotificationMessage
as a response.
The overall structure of the MessageHeader
element will be retained and elements from the MessageHeader
of the request message will be re-used in the claim notification. For further details on the message header see below.
The PartyList
element from the request message will be re-used. The sender of the claim notification may make amendments to the party information, so that the Party
data may differ between request and notification.
The WorkList
, ReleaseList
and ResourceList
elements from the request message will be retained in the claim notification. Formatting and values will be the same as received.
Message Header
The MessageId
element from the claim request cannot be reused, as this identifier is unique per sender and two senders using the same identifier would cause the two claim notifications to have the same identifier. Also, multiple claim notifications in response to the same message need to have different identifiers. Therefore, an algorithm that creates a unique identifier for each claim notification has to be established.
The MessageSender
element of the claim notification message can be hardcoded for all messages.
A recipient of a MusicalWorkClaimRequestMessage
shall always reply to the sender of that message, whether it comes directly from a record company or whether it has been forwarded by a hub. Therefore, the data of the MessageSender
element is copied to the MessageRecipient
element.
If the request message has been forwarded by a hub, the SentOnBehalfOf
element in the request message contains the details of the record company which the request had been issued on behalf of. The party specified in this SentOnBehalfOf
element is not included in the response message.
The PartyId
(a DPID) and PartyName
elements can be taken from the claim request.
The MessageCreatedDateTime
element captures the time at which the message is created. This has to be in the ISO 8601:2004 format with a time zone designator.
Party List
If available, parties need to have an IPI name number included in PartyId
(in the IpiNameNumberelement
). The IPI name number should be provided for all controlled writers, original publishers, sub-publishers and administrators. Uncontrolled writers do not have this populated.
Any proprietary identifiers which are included on the claim request should be included for further associated parties in their response.
The PartyName
elements should not be taken from the claim request, but should be populated with the correct information from the internal systems of the message creator.
The NamesBeforeKeyName
and KeyName
elements should be added in the claim notification and populated with first and last name respectively.
Any additional writers not included in the original claim request need to be added to the PartyList
. They need to have a new PartyReference
identifier, the format for which is "P" followed by any number of characters (letters or numbers), which needs to be unique within the message. This PartyReference
is solely to allow the referencing of a party from the different parts of the claim notification; the PartyReference
has no applicability outside of the message.
The writers should then have their IpiNameNumber
, FullName
, NamesBeforeKeyName
and KeyName
elements populated from the internal systems of the message creator.
The IsOrganization
flag needs to be set, if the party is a writer, to false and, if the party is a publisher, administrator or sub-publisher, to true.
Work List
In the MusicalWorkId
element, the following data from the internal systems of the message creator is needed:
The
ISWC
of the work if available (for the ISWC element); andAny proprietary identifier (for the
ProprietaryId
element, where theNamespace
attribute is set to the DPID of the message creator).
In addition, each Work element needs to have a MusicalWorkReference
element, the format for which is "W" followed by any number of characters. This reference identifier needs to be unique within the MWN message. This MusicalWorkReference
is solely to allow the referencing of a work from the different parts of the claim notification; the MusicalWorkReference
has no applicability outside of the message.
The controlled parties with a MusicalWorkManuscriptShare
for the work need to be listed in the Writer
element. The writer reference identifiers and roles which are controlled are listed in WriterPartyReference
and Role
elements respectively. Multiple references can exist depending on the controlled writers with a MusicalWorkManuscriptShare
. The Writer
ties back to an entry in the PartyList
via the PartyReference
attribute.
The Role
element is populated for each party based on the CreativeMusicalWorkContributorRole
allowed value set and may use a proprietary value from the internal systems of the message creator (in which case the Namespace
attribute is set to the DPID of the message creator).
Titles in the claim request need to be matched against what is stored in the internal systems of the message creator. The data from the internal systems should be used to populate the TitleText
element.
Right Share List
The RightShareList
element with the claim information relevant to the response has to be created. Each right share in the list needs a RightShareReference
element, the format for which is "S" followed by any number of characters. The reference identifier only needs to be unique within the MWN message. This RightShareReference
is solely to allow the referencing of a right share from the different parts of the claim notification; the RightShareReference
has no applicability outside of the message.
The RightShareWorkReference
element includes the reference assigned to the work in the WorkList
(in the MusicalWorkReference
element).
Right Share Notification List
For each request that is responded to in the response message, a right share notification has to be added in the RightShareNotificationList
element.
The NotificationId
element is the identifier of the claim notification (not the identifier of the claim notification message). If an update to such a claim notification is issued, this identifier is put into the PreviousNotificationId
element of the update message.
The RequestId
element is the identifier of the request that the notification is responding to. This is a proprietary identifier specified by the sender of the request in the RequestId
element in the RequestList
and must be copied from there (including the Namespace
attribute).
The RightShare
element is the right share which is responded with in the claim notification and which is linked to the RightShareList
using the RequestRightShareReference
element. The value for this element is the RightShareReference
element of the entry in the RightShareList
.
The RightShareNotificationList
element may also include right shares marked as uncontrolled.
The RightsControllerRequestId
element shall be included against each entry in the RightShareNotificationList
if it is given in the request message (in the RightsControllerRequestId
element of the MusicalWorkShareRequest
). This proprietary identifier specified by the sender of the request helps to associate the response with a specific request.
2. Specifying different types of right shares
The Musical Work Right Share Notification (MWN) standard supports documenting different types of right shares:
MusicalWorkManuscriptShares
;OriginalPublisherShares
;MusicalWorkCollectionShares
; andLicensingShares
The decision which of these right shares should be generated is a business decision, and the next sections in this document describe what needs to be done for setting up a specific right share if this is applicable.
Details for each of these types are provided below.
MusicalWorkManuscriptShares
Writers shall be set out first in the claim notification so that the subsequent shares can be related to them.
For each claimed writer, a Party
element will need to be created in the PartyList
of the MusicalWorkClaimNotificationMessage
.
The writer will then need to be linked to the manuscript share via the RightsController
element in the RightShare
composite, where RightsController/RightsControllerPartyReference
must be set to the writer's PartyReference
. In addition, the writer shall be linked to the musical work that is related to that manuscript share (via the RightShareWorkReference
element) by setting the Writer
element in the MusicalWork
composite to the writer's PartyReference
.
The TerritoryCode
element for all manuscript shares shall be set to Worldwide
.
The RightShareType
element for manuscript shares must be set to MusicalWorkManuscriptShare
. To avoid confusion only one value shall be supplied for this element.
The RightsType
element shall be set to all values from the AVS that are applicable to the publisher sending the MusicalWorkClaimNotificationMessage
. The requested rights type from the MusicalWorkClaimRequestMessage
's Request/Condition/RightsType
should be included.
The RightShareNotClaimed
element may be used for writers that are not controlled and set to true.
The RightSharePercentage
element must be taken from the work's contribution percentage for the assigned writer. This will need to be denoted as a numeric value that can include a period to denote fractions of a percentage. Exact splits including as many decimal places as used in the internal systems of the message creator should be used for this element.
OriginalPublisherShares
The associated original publisher for each writer in the MusicalWorkClaimNotificationMessage
must be retrieved, and the message will have to be updated with correct publishers. For each original publisher, a Party
element must be created in the PartyList
of the MusicalWorkClaimNotificationMessage
.
The original publisher will then need to be linked to the original publisher share via the RightsController
element in the RightShare
composite, where RightsController/RightsControllerPartyReference
will have to be set to the publisher's PartyReference
.
The TerritoryCode
element for all original publisher shares will have to be set to the value from the original request (e.g. US
). When retrieving the ownership percentage, the territory value has to be considered (e.g. US splits).
The RightShareType
element shall have to be set to OriginalPublisherShare
. To avoid confusion only one value shall be supplied for this element.
The RightsType
element shall be set to the requested right type from the MusicalWorkClaimRequestMessage
's Request/Condition/RightsType
. The values may be restricted to values that are applicable to the publisher sending the MusicalWorkClaimNotificationMessage
.
The RightSharePercentage
element shall be defined as the share controlled by the original publisher. It shall link the original publisher manuscript percentage of the writer. This will have to be denoted as a numeric value that can include a period to denote fractions of a percentage. Exact splits including as many decimal places as used in the internal systems of the message creator should be used for this element.
The IsFollowerInTitleOf
element must link the original publisher share back to the manuscript share of the writer (using the BaseRightShare
and ManuscriptShare
elements). The next follower-in-title-of share must use this element to link back to the original publisher share. The IsFollowerInTitleOf/RightSharePercentage
should display the works contribution percentage for the assigned writer.
MusicalWorkCollectionShares
The associated administrative publisher/sub-publisher for each writer in the MusicalWorkClaimNotificationMessage
will need to be retrieved, and the message must be updated with correct publishers. For each publisher, a Party
element must be created in the PartyList
of the MusicalWorkClaimNotificationMessage
.
The publisher must then be linked to the musical work collection share via the RightsController
element in the RightShare
composite, where RightsController/RightsControllerPartyReference
will be set to the publisher's PartyReference
.
The TerritoryCode
element for all collection shares should be covered by the value from the original request (e.g. US
). When retrieving the collection percentage, the territory value has to be considered (e.g. US splits).
The RightShareType
element will need to be set to MusicalWorkCollectionShare
. To avoid confusion only one value shall be supplied for this element.
The RightsType
element must be set to the requested right type from the MusicalWorkClaimRequestMessage'sRequest/Condition/RightsType
. The values may be restricted to values that are applicable to the publisher sending the MusicalWorkClaimNotificationMessage
.
The LicensingAgent
element shall need to be specified for the collection share.
This LicensingAgent
element should also include an XML attribute IsAgent=false
. Its RightsControllerPartyReference
element will have denote the publisher in control of the license (which may be the original publisher). The PartyReference
element from the PartyList
must be used in RightsControllerPartyReference
element to identify the licensing agent.
The RightSharePercentage
element must be set as the percentage controlled by the collecting party. This shall be denoted as a numeric value that can include a period to denote fractions of a percentage. Exact splits including as many decimal places as used in the internal systems of the message creator should be used for this element.
HasOriginalPublisherShare/OriginalPublisherShare
shall be present on each collection share to link it back to an original publisher share. The value to be used in this element is the RightShareReference
element of the original publisher share.
The IsFollowerInTitleOf
element must link the collection share back to the original publisher share (using the BaseRightShare
element) and manuscript share of the writer (using the ManuscriptShareelement
). The next follower-in-title-of share will have use this element to link back to the original publisher share. The IsFollowerInTitleOf/RightSharePercentage
will have to contain the percentage controlled by the original publisher.
In IsFollowerInTitleOf/ManuscriptShare
, the BaseRightShare
element must contain the RightShareReference
element of the manuscript share and the RightSharePercentage
element will have to contain the contribution percentage from the manuscript share.
LicensingShares
The associated administrative publisher/sub-publisher for each writer in the MusicalWorkClaimNotificationMessage
will need to be retrieved, and the message shall be updated with correct publishers. For each publisher, a Party
element shall be created in the PartyList
of the MusicalWorkClaimNotificationMessage
.
The publisher can then be linked to the licensing share via the RightsController
element in the RightShare
composite, where RightsController/RightsControllerPartyReference
shall be set to the publisher's PartyReference
.
The TerritoryCode
element for all licensing shares is covered by the value from the original request (e.g. US
). When retrieving the percentage, the territory value has to be considered (e.g. US splits).
The RightShareType
element will have to be set to LicensingShare
. To avoid confusion only one value shall be supplied for this element.
The RightsType
element will have to be set to the requested right type from the MusicalWorkClaimRequestMessage
's Request/Condition/RightsType
. The values may be restricted to values that are applicable to the publisher sending the MusicalWorkClaimNotificationMessage
.
The LicensingAgent
element must be specified for the licensing share.
This LicensingAgent
element shall include an XML attribute IsAgent=true
. Its RightsControllerPartyReference
element shall denote the publisher in control of the license (which may be the original publisher). The PartyReference
element from the PartyList
is to be used in RightsControllerPartyReference
element to identify the licensing agent.
The RightSharePercentage
element shall be set as the percentage controlled by the licensing party. This will have to be denoted as a numeric value that can include a period to denote fractions of a percentage. Exact splits including as many decimal places as used in the internal systems of the message creator should be used for this element.
HasOriginalPublisherShare/OriginalPublisherShare
must be present on each licensing share to link it back to an original publisher share. The value to be used in this element is the RightShareReference
element of the original publisher share.
The IsFollowerInTitleOf
element shall link the licensing share back to the original publisher share (using the BaseRightShare
element) and manuscript share of the writer (using the ManuscriptShare
element). The next follower-in-title-of share will have to use this element to link back to the original publisher share. The IsFollowerInTitleOf/RightSharePercentage
shall contain the percentage controlled by the original publisher.
In IsFollowerInTitleOf/ManuscriptShare
, the BaseRightShare
element will have to contain the RightShareReference
element of the manuscript share and the RightSharePercentage
element shall contain the contribution percentage from the manuscript share.
3. Specifying uncontrolled writers
The Musical Work Right Share Notification (MWN) standard supports documenting different right share scenarios. Details of the data to be specified in the case of an uncontrolled claim are provided below.
In this case, a MusicalWorkClaimNotificationMessage
can still be issued in response to a MusicalWorkClaimRequestMessage
. In this message, the manuscript share will have a writer set to uncontrolled (via the RightShareNotClaimed
flag, see below), but no original publisher share will be provided that links to the manuscript share for the uncontrolled writer.
In the RightShare
element describing the manuscript share, the ValidityPeriod
element will be omitted as this is not relevant for uncontrolled shares.
A link will be made in the RightShareWorkReference
element between the manuscript share and the work and writer(s) it relates to.
The requested rights type from the MusicalWorkClaimRequestMessage
's Request/Condition/RightsType
shall be present in the claim notification's RightsType
element.
The only parties referenced will be the writer(s) (in RightsController
and via the MusicalWork
composite) and the publisher (in RightsController/RightsControllerPartyReference
). No LicensingAgent
element will be included in the claim notification as it is not required.
The RightShareNotClaimed
flag will be set to true when an uncontrolled writer is present.
The HasRightsInDispute
flag will be added to manuscript shares for uncontrolled writer shares and be set to false.
In the IsFollowerInTitleOf
element, the RightShareUnknown
element will be used instead of RightSharePercentage
element and will be set to true.
No further claim information will be provided for the uncontrolled writer.
4. Specifying pending responses
The Musical Work Right Share Notification (MWN) standard supports documenting different right share scenarios. Details of the data to be specified in the case of a pending claim, e.g. when the percentage of a contribution is not yet known or the full publishing information is not yet available, are provided below.
In this case, a MusicalWorkClaimNotificationMessage
can still be issued in response to a MusicalWorkClaimRequestMessage
. In this message, the RightShareList
element will include manuscript shares, original publisher shares and collection shares for pending writers.
In the RightShare
elements, the ValidityPeriod
element will be included as this will indicate when the pending response was issued to the record company.
A link will be made in the RightShareWorkReference
element between the pending manuscript share and the work and writer(s) it relates to. This is no different to the standard process of responding with a manuscript share as described on (2) above.
If a contribution percentage for the writer is known, it will be used in the RightSharePercentage
element. If this information is missing, the RightSharePercentage
will be replaced by a RightShareUnknown
flag set to true. This is applied to all right shares in the RightShareList
element (manuscript, original publisher and collection shares).
Any other information will be included as it has been defined in the General Response Rules described in (1) above and writer and publisher share rules discussed in (2) above.
The IPI name number, if it has been allocated, will be included in the Party
element (in PartyId/IpiNameNumber
) for the associated writer.
An entry in the PartyList
element needs to be included for the publisher, and this needs to be linked to the original publisher and collection shares via the RightsController
element in the RightShare
composite, where RightsController/RightsControllerPartyReference
will be set to the publisher's PartyReference
. If an entry has been included in the MusicalWorkClaimRequestMessage
, this will be used for the claim notification.