Promotional events: A primer on using EDItEUR's documentation

The release this spring of the ONIX 3.0 new Block 7, Promotional Events, leads to questions like “How does it work?” and “How do I remove entries from retailers once the event is past?” which further might lead someone to wonder “How do I handle an empty Block 7 anyway?” Although this is brand new metadata and no one is using it yet, we expect this to change. For instance, BNC CataList plans to display event metadata, at least one major retailer supports an API dedicated to trading it, and Germany made the original request to EDItEUR and plans to use event promotion as part of their national metadata support. The need is real so the use will happen.

So, how does it work?

The first step you should take in this journey is getting the most recent documentation from EDItEUR, their resources are superb and comprehensive. For this specific scenario, you can download the zip folder of the documentation package Version 3.0.7 here or you can find this folder and more resources in this section of their website, please note that this documentation is updated regularly, the best way to stay up to date is to get your downloads from the EDItEUR site directly.

ONIX for Books (these three documents plus the code lists) is a complete system for metadata and all the parts that need to be used. In the folder you will find multiple HTML documents that can be easily accessed from your browser, be sure to fully expand the contents of each one of them.

In the Product Information Format Specification document, you can scroll down to the table of contents, which will help you navigate your way through this sea of information and get to the section we will be working on today, Block 7: Promotion detail.

You should see a section starting like this:

Once you're there, you'll notice that some of the tags cite code lists, click on the list number to open the list. Here we have included the first two:

ONIX Code Lists Issue 49, March 2020

List 244: Event identifier type

Value	Description	Notes

Value	Description	Notes
01	Proprietary

ONIX Code Lists Issue 49, March 2020

List 245: Event type

Value	Description	Notes

Value	Description	Notes
00	Unspecified – see description
01	Book signing
02	Book reading

Feeling confused?

List 244 tells you very little, but you know by looking at List 245 that Promotional Events supports book signings and book readings — and there’s a default alternative that allows you to use a description. But you might be feeling confused because the specification document is a technical manual that shows how the parts interrelate as XML, and what you want is an explanation about how EDItEUR intends their system to work. Don’t panic, we’ve got you. What you're looking for is found in the Implementation and Best Practice Guide document that was also part of the zip folder. But before we go there, let’s explore this a little more.

Your first discovery should be that scanning code lists tells you a lot.

Even though it might not be evident at first, there’s navigation built into the Specification document. Click on a light blue bar describing an “element” and you will get pulled up to it’s XML source — the dark blue bar for its composite. Click on it and you pull yourself further up the ONIX XML tree alternating dark and light bars until you get the Block 7 bar — which takes you to its source — the product record itself. A click there delivers you to the table of contents. Now you know how to navigate the document, so head back down to Block 7.

Navigation in the specification is just the XML visualized. (Tangent: It’s helpful to know that ONIX is very structured XML and the order is controlled. An ONIX file is in the same order as the specification — you can “read” an ONIX file and follow along in the specification. A better way to put it is that the XML schema is the source for both. It’s the set of rules read by software and that controls the XML processing.)

Here’s some of that tree visualized where the dots note a change of XML root. Note that the composite “Event identifier” and the element “Event type” both are children of the top level working composite of “Promotional Event.”

<Product>
. <PromotionDetail> 
. . <PromotionalEvent>
. . . <EventIdentifier>
. . . <EventType>

First note that a “block” is just one big composite — an XML container. So any XML path to Promotional Events goes through <Product>/<PromotionalDetail>/ first. The fact that XML groups it as a unit allows rules about its processing to be unique.

Now, note that the specification tells us something very important — so important that it’s in the first line of the description:

Event identifier: An optional group of data elements which together define an identifier for an event.
Event type: A mandatory ONIX code which specifies the type of promotional event.

What’s optional and what’s mandatory is very important — the things that “must be there” and things you might include. Also note that Event type is the first mandatory code list in Promotional Events and its root is the primary container, so you know it’s important to the use of that composite.

Mandatory does NOT mean Event type must appear in an ONIX record — it only means that within its root composite it's mandatory. Similarly Event identifier is “optional” but its type and value are mandatory. If you provide the identifier composite you need to use a code to define it and provide a value to be the identifier. But the composite is not mandatory. Event type’s root is <PromotionalDetail> /<PromotionalEvent> which are “optional” in an ONIX file. There are not many truly mandatory data points in ONIX but many are mandatory if an optional composite is used.

It’s normal for an optional identifier section to lead or be close to the top of many ONIX sections and it’s there to support computers and their cross referencing needs. For instance within Promotional Events there’s a special reference composite that matches a contributor in the product record. Similarly, an identifier might be needed to provide a solid way to differentiate or group multiple promotional events either within this record or across many records. Useful not mandatory.

On to EDItEUR’s best practices

Hopefully by now you’re feeling less intimidated by the specification document and the code lists. We start there because you can’t use the best practices document without them as it assumes you can refer to this mechanical detail as needed while the best practices can focus on the whys of the structure and the use of that structure for communication.

When I’m figuring things out I like to have both documents open, they're designed to be used together. In addition to the navigation tools mentioned earlier, and assuming you’ve fully extract the zip above, by holding the alt key and clicking on a composite’s bar (any of them) you will be toggled over the supplementary document — from the best practices document to the specification and vice versa. Again, it’s in “ONIX order.”

Either way, navigate to Best Practice’s section.

Block 7: Promotion detail / Promotion detail composite

Here you’ll find the basics:

a note explaining why Block 7 appears between Block 2 and 3
that Block 7 — the <PromotionDetail> composite contains one or more repeats of the <PromotionalEvent> composite
that it’s intended to be used for describing author signings, readings, or other events arranged to promote sales of the product:
- these are frequently arranged in ‘tours’, so an author might visit a dozen bookstores in a region, with the activity in each store more or less identical
  - in ONIX, such a tour is described in a single promotional event composite and each individual stop on the tour is an ‘occurrence’ of that event
- if the activity at each store is significantly different — for example a different celebrity guest participates alongside the author — then the ‘tour’ should be described as multiple individual events

The information above has been taken from the best practices document, I have only broken it down into bullet points and added emphasis. Now we know that this can be used either as one “event” with multiple occurrences OR as multiple events, we can also clearly differentiate who's at the event as necessary.

Immediately below the description is a big blue box. These are your friends — EDItEUR provides them to highlight the bits you really need to know. Normally you’d also find a white box as well, in which common mistakes are listed, but since this is a completely new addition, no one has made any mistake to comment on.

The big blue box repeats a shorter version of the above and provides details about how to handle it as block — including that it’s OK to provide an empty <PromotionalDetail> composite to remove all previously supported entries.

There’s also a small diagram — these are visual summaries.

The down arrows on the right going around show that <PromotionalEvents> is optional. That would be the empty block message explained in the blue box, but a note in the yellow box also clarifies it.
The up arrows on the left going up around show that <PromotionalEvents> can repeat. If Promotional Events are used, there can be more than one.

Now you have almost all the tools you need to read the best practices document and can go onto the “meat” of Block 7, the actual Promotional Events composite to learn how to use it.

P.27 Promotional Events

This is what you'll find within the first blue box of this section.

The intent of the composite is to describe in detail events such as author appearances, signings, readings, and so on. These are an increasingly important part of the marketing mix for many publishers and types of book. Each <PromotionalEvent> composite:

must specify the type of event and its target audience
must specify a name for the event (and by extension, for each occurrence of the event)
should list each of the participants in the event
- event participants who are Product contributors or are listed in <NameAsSubject> should be listed using <ContributorReference>, and must therefore have a matching ID in <Contributor> (in Groups P.5, P.7, or P.18) or <NameAsSubject> (in Groups P.12 or P.18) and in <ContributorReference> — even if this is a proprietary ID
- other participants should be listed using a full <Contributor> composite
- participants’ sequence numbers and role codes relate to their participation in the event, and are likely to be different from their roles and sequence numbers that relate to the product (as given in Groups P.5 or P.7)
must list the details for at least one occurrence of the event in <EventOccurrence>. Each occurrence of the event must include a status and a date and time
for physical events, must list the venue details — country or region and city (in <LocationName>), plus the venue
for virtual events, must provide the necessary details of the website or URL (N.B. code list entries for this are yet to be defined)

Followed by this diagram:

Event identifier is optional ↓, can repeat ↑

Event type is mandatory but can repeat ↑

Event status optional ↓ (one status only)

Target audience is mandatory, can repeat ↑

Event name is mandatory but can repeat ↑
(notes show it repeats to support multiple languages)

There’s a contributor section
- It’s optional ↓ and can be replaced by an optional NoContributor ↓
- contains three composites, see below.

Event description is optional ↓
(but can repeat to support multiple languages ↑)

Event occurrence mandatory but can repeat ↑
(see below for more)

Event sponsor is optional ↓, can repeat ↑

Event website is optional ↓, can repeat ↑

Below this diagram, EDItEUR provides a sample script for listing a two-stop interview tour.

Don’t forget that code lists can help you visually so going back to the specification document from time to time can help. It’s beyond the scope of a blog post to go over each in detail, but here’s each sketched in:

Event identifier (list 244) is discussed above.
Event type (list 245) must be defined but you can have more than one Type.
Event status (List 246) is optional but it would be “expected” because status can change.
Target audience (list 154) is mandatory and uses the Content audience composite so you can list “unrestricted,” “librarians,” “students,” and so on — as the Target Audience this event is for. (Default would be 00 “unrestricted”.)
Event name is mandatory. It’s listed as repeating but when you look at the specification the use case is multiple languages. That means by using attributes <EventName language=”eng”> and <EventName language=”fre”> you can repeat the Event Name. One tag entry per language.
Contributor block is optional but provides a means to list people or corporations associated with the event as two types:
- Contributor by reference: The book’s contributors go here! This exists because the event will usually share contributors with the book and there’s no need to repeat the information. So you provide a direct reference to the book’s metadata.
  - Sequence number (order matters, but this is “event presentation” order)
  - Contributor Role (it doesn’t have to match the book, it’s the event role)
  - Name Identifier (composite)
    Rather than provide the full Contributor you supply an Identifier that matches a contributor in the book record It could be a Product contributor (the author) OR Name as Subject entry (book about a person).
- Contributor: Non-book or other participants go here. This is a full contributor composite though you’re more likely to just provide PersonName or CorporateName for any who aren’t directly associated with the book. This is where you can list presenters, in-conversation-with participants, and anyone else appearing, so while a full Contributor composite is available, you’ll likely only need or want to provide a “basic” entry.
Contributor statement is an XHTML-enabled section where the contributors can be stated as you like them displayed for the event. The diagram (and specifications) warns that this can’t appear on its own and you must include at least one of the other two contributor block sections.
NoContributor is supported so you can be clear that there is no contributor information being supplied. It’s recommended for clarity as not supplying “people” information would be weird so it’s worth highlighting that it’s intentional. Optional for support so if you’ll be adding the people in a later update you don’t have to provide this.
Event description is optional and it’s XHTML enabled. It’s listed as repeating but when you look at the specification the use case is multiple languages (same as Event Name).
Event occurrence is mandatory and can be repeated so one event can have one or many occurrences, like an author book signing scheduled to happen at different bookstores. It’s considered a single Promotional event with multiple Event occurrences.
- Date (composite)
- Status
- Location — elements for country, region, location name (city)
- Venue
- Venue address
- Venue note (repeats on language)
- Event occurrence description (XHMTL enabled, repeats on language)
- Event occurrence sponsor
  - Name identifier (composite)
  - Person name or corporate name
- Event occurrence website (composite)
Event sponsor
- Name Identifier (composite)
- Person name or Corporate Name
Event website (composite)

I hope you’ve already discovered that reading EDItEUR’s Best Practice is more organized and complete than this blog post — there are excellent examples of the script in use in their documentation.

Bon data-voyage!

This originally appeared on the BNC Blog at https://www.booknetcanada.ca/blog/2020/5/12/promotional-events-a-primer-on-using-editeurs-documentation. Subscribe the the blog RSS at https://www.booknetcanada.ca/blog?format=rss.