EMMA Help Topics

Sign in with Bookshare

Pressing the Sign in button at the upper-right corner of the EMMA screen take you to a page of sign-in options. Currently the only option is via Bookshare authentication, which is engaged when you click on the "Sign in with Bookshare" link.

(You must have an active account with Bookshare in order to use EMMA.)

When you click on the "Sign in with Bookshare" link, EMMA redirects you to the Bookshare page (above) which prompts you for your Bookshare credentials.

When you press Sign in on that page, Bookshare redirects your browser back to the original EMMA page along with a hidden "bearer token". (This token will be attached to your requests to indicate your confirmed identity.)

EMMA local sign-in

Test accounts are available for EMMA testers. Please contact project managers or developers at the University of Virginia if you would like credentials for one of these accounts (emmahelp@virginia.edu).

OVERVIEW

A search term is required to begin. You may search for matches on the basis of:

• Keyword (default choice)
• Title
• Creator (e.g., Author)
• Identifier (e.g., ISBN)

The Sort By default selection is Relevancy, and this should be appropriate for most searches.

The remaining filters are all optional:

• Repository: pick one, or default to all repositories
• Page Size: not currently implemented
• Format, Feature, and Accessibility: you may make multiple selections for each control. These will generate matches when ANY of the selected choices matches an item. Note that selections of filters tend to reduce the number of matches.

Search Types

Enter one or more search terms in the search input box, then press the Search button. (A search term can be a single word or phrase, title, identifier or author name.)

To clear the current search input, click on the "✖" that will appear on the right side of the search input box. This does not result in a new search — it simply clears characters that have been input to help begin a new search.

Keyword search is best for "discovery" of items that you hadn't considered before, but can lead to a large number of results — especially if you give only a single search term, or if your search terms contain many common words.

If you already know that you are looking for a title, or are looking for a specific ISBN, then you can help reduce the number of "false positive" matches by specifying the appropriate search input type.

Keyword Search

This search type looks for items matching your search term(s) across a combination of metadata fields (title, author, description, etc).

As a convenience, if a search term appears to be a standard identifier, your keyword search will automatically converted to an identifier search.

Title Search

Find items whose title matches the search term(s).

For example, a Title search for "King" will return results with the word "King" somewhere in the title, but won't return items by Stephen King.

Creator Search

Find items whose author/creator matches the search term(s).

For example, a Creator search for "King" will return results by an author, editor or composer with "King" somewhere in their name, but won't return items that simply have "King" somewhere in the title.

Identifier Search

Find items whose ISBN, ISSN, OCLC, LCCN, DOI, or UPC matches the search term(s).

Just giving an identifier number alone should be sufficient — however, there are some cases (depending on the numbering scheme) where it may be necessary to prefix the identifier with its type:

Filters

The menu selections below the search input bar either filter out results that are not of interest or control the way that results are presented. (Press Less ▲ to reduce the number of filters shown; press More ▼ to see all filter selections.)

Filters (also known as "limiters") reduce the result set by eliminating all of the result items that don't meet the filter criteria. For example, setting "Repository" to "EMMA" discards all results from the current search except for items that originate from the EMMA repository.

Simple Filters

These are drop-down menus which can only be set to a single value.

Repository

Use this filter to limit results to just those from a specific member repository.

Multi-select Filters

These are drop-down menus which can be set to multiple values.

Click to drop down the menu selections, then click on a filter value to select it.

This has the immediate effect of eliminating all search results that don't meet the condition imposed by the selection.

After the drop-down menu closes, your selection will appear as a marker with a leading "✖".

Click on the "✖" to remove the filter value. (This has the immediate effect of re-running the current search without that filter condition.)

Click in the area outside the marker to cause the menu to drop down again. Select a different filter value, and that will be added to the previous facet selection value.

This may cause some additional results to appear, because the multi-select facets use "inclusive-OR" logic — meaning that they allow through items that match at least one of the filter values.

To clear all facet selections, click on the "✖" on the right side of the menu control.

Format (multi-select)

Limit results to items that have at least one of the selected file formats.

Feature (multi-select)

Limit results to items that have at least one of the selected remediation properties.

Accessibility (multi-select)

Limit results to items that have at least one of the selected accessibility features.

Search Result Controls

The following menus do not limit the potential set of results you receive; they just control the order and presentation of results.

Sort By

The default sort shows the result set in decreasing order of relevance, starting with the entries that most closely match the search terms.

NOTE: If search criteria are very broad, then alternate sort orders may bring items to the top that are only marginally useful. Selecting a sort order is most useful when items of a result set are highly correlated by fairly specific search criteria (search terms plus filter selections).

Page Size

For "Results By File":
Select the number of results per page. While some search terms may be so specific that the index can eliminate all but the exactly right entry, more general terms may result in dozens (or thousands) of results. This filter gives you control over how large result sets are broken into easier-to-handle chunks.

For "Results By Title":
This menu is disabled; the number of records acquired from the index is set to the largest value that can be accommodated.

Search Display Modes

The search index underlying EMMA deals in low-level quantities that correspond to individual files (one entry for every copy of every format for a given title). The default EMMA search display mode takes these raw results and reshapes into a hierarchical view of title-level entries.

Results By Title

In this display mode, search results from the index are aggregated into a set of entries which represent creative works at the title level (as they would be seen at the originating repository. Each entry starts in a collapsed state; click the ▶ toggle control to expand it.

Each title-level entry begins with bibliographic metadata that applies to the creative work, followed by one or more collapsible sections. Each section starts in an expanded state; click the ▼ toggle control to collapse it.

Each section represents a format in which a copy of the creative work is available (EPUB, DAISY, etc.) and contains remediation metadata and other information which is specific to the file itself.

It is not unusual for entries based on HathiTrust items to have a more complex structure, since these can be comprised of multiple copies of multiple volumes. Each volume will be its own "sub-tree" with potentially multiple formats (although, typically, just PDF), and each format having potentially multiple copies (unique scans from different universities).

Results By File

In this display mode there is a one-to-one correspondence between items returned by the index and the search result entries that are displayed on the page. All information for all (file-level) items are displayed fully expanded.

This mode might be useful if you are scanning for information that is not directly searchable by the index's defined search types. In this case, your browser's search-in-page facility can be used to find occurrences of the information directly on the page.

This mode may also be useful if you want search results in JSON format for automated processing (by appending "&results=file&format=json" to the URL).

Downloading a HathiTrust item

Because HathiTrust applies its own restrictions, item download links supplied to the EMMA Unified Index are actually links to the HathiTrust web page entry for the creative work associated with the item. Such pages may reference multiple copies of the same item — unique scans contributed by different academic partners.

The actual download is performed from the hathitrust.org web page; this constitutes a transaction between that web site and your web browser. Currently, the EMMA system is not a party to this transaction; future work may include enhancements to help reflect this information within EMMA. For now, however, the EMMA system will not be able to track your file download from HathiTrust, and therefore will not know the origin of this item.

Downloading an ACE / Scholars Portal item

Because these items are made available to EMMA users via Internet Archive, see Downloading an Internet Archive item below.

Downloading an Internet Archive item

EMMA manages downloads from Internet Archive in two ways, depending on the type of file:

For DAISY, Internet Archive currently only delivers encrypted content. In this case, the download link is a direct link to Internet Archive because the file itself is freely-available.

Use of the DAISY content, however, will require a key as described within the download itself. Refer to IA's article on Disability Access for details.

For other types (EPUB, PDF, etc.), EMMA intercedes by making a request to Internet Archive's facility for generating unencumbered sources "on-the-fly". Because these files are created dynamically, there may be some delay before the browser download dialog appears.

You may see an error message: This indicates that the current attempt to download was completed unsuccessfully. Retrying the download link after a few minutes, however, should result in the download without further delay.

Downloading a Bookshare item

Bookshare requires that downloads be performed by a "sponsor" on behalf of members with qualifying disabilities. Download links to Bookshare items are actually links to a Bookshare web page form through which the intended recipients can be indicated, and which performs the actual download.

The actual download is performed from the bookshare.org web page; this constitutes a transaction between that web site and your web browser. Currently, the EMMA system is not a party to this transaction; future work may include enhancements to help reflect this information within EMMA. For now, however, the EMMA system will not be able to track your file download from Bookshare, and therefore will not know the origin of this item.

Downloading an EMMA item

Items that are "native" to the EMMA repository (that is, items that have been uploaded by EMMA users and/or are otherwise not to be found in any of the other member repositories) come in two flavors (at least initially):

• Items uploaded directly to EMMA by EMMA users.
• Bookshare items that are part of their "EMMA Collection"

Items of the first type are delivered directly from the EMMA repository to a signed-in user.

Items of the second type were initially used to "prime" the collection of items associated with EMMA. These items are actually Bookshare items. When downloaded they behave like Bookshare items as described above, except that they are not "watermarked".

OVERVIEW

All of EMMA’s functionality related to working with submissions is available after selecting Uploads from the navigation menu. The Uploads main page displays all of the files that have been previously uploaded to EMMA under your account.

Upload Actions menu

The available functions are displayed at the top of each Uploads page as a set of buttons:

When you have completed remediation of a file and wish to share it with the EMMA community, this can be done by clicking the Create button. EMMA requires that you provide both the book’s content (a single file or multiple files contained within a single *.zip file) and metadata about the book that will benefit other EMMA users in determining if this volume will match their needs.

Action Short Cuts

Each item listed on the Uploads page is associated with controls to manage that item (to the left of the item details on desktop displays; at the top of the screen on mobile displays):

Clicking on △ will redirect your browser to a new screen that will allow you to modify the associated entry.

Clicking on ✖ will redirect your browser to a new screen that will prompt you to delete the associated entry.

List All Show your past and current uploads

This is a listing of your completed and pending EMMA submissions.

Each entry in the list is preceded by action short-cuts for working with that entry.

Create Submitting a new item to EMMA

EMMA requires that you provide both the book’s content (a single file or multiple files contained within a single *.zip file) and metadata about the book that will benefit other EMMA users in determining if this volume will match their needs.

Step 1: Prepare a file for upload

Currently remediated content must be submitted as a single file. If your content is comprised of multiple individual files, you will need to combine them into a single ZIP archive in order to submit them as a single EMMA entry.

Step 2: Select a file to upload

Press the Select file button to open your browser's file dialog. Navigate to find the file on your workstation, and select it to begin the provisional upload of the file.

As this is occurring, an orange progress bar will appear just above the buttons. When file processed successfully, EMMA will display the file name.

(If the progress bar completes but no file name is listed, then a problem encountered in processing the file. You may wish to contact emmahelp@virginia.edu.)

This step gives EMMA an opportunity to verify the integrity of the file. For certain file formats, metadata may be discovered that will be used to "pre-populate" the submission form.

Step 3: Indicate the Source Repository

Select "EMMA" if your file was an original scan, or is derived from a source other than one of EMMA's participating member repositories.

If your remediated file is based on a file from a participating member repository, you must indicate the EMMA entry associated with that original file.

When you select member repository source, you will be prompted for the identity of the original entry. For most items the standard identifier (ISBN, OCLC, etc.) is sufficient to locate the proper EMMA entry. (For items without a standard identifier, the full title should work.)

After the original item has been identified, you'll see that your submission has "inherited" the bibliographic metadata of the original item:

These fields appear differently as a reminder that the bibliographic metadata (title-level cataloging information) is not subject to change for items derived from EMMA entries supplied by member repositories.

Step 4: Provide metadata

In order to make your remediation efforts findable in EMMA, information must be supplied to identify the source material and the nature of the file being uploaded. These include:

• Bibliographic metadata, such as Title, Creator (Author), Language, Format, and Type.
• Remediation data, which will help other EMMA users know whether the entire volume was remediated, specify which chapters were remediated, and/or indicate whether the volume was born accessible.
• Source Repository, where you will indicate the source of the original file that was remediated. This may include the EMMA repository itself, one of the partner repositories (ACE, Bookshare, HathiTrust, Internet Archive), or one of the other choices in the dropdown list.

Step 5: Complete the submission

When all required fields have been supplied, and all fields with data are valid, then the Upload button will be enabled. Press it to complete the submission.

If you decide that you do not want to submit the item, you may click CANCEL (which will attempt to return you to the previous page), or simply go to any other page in EMMA.

EMMA-native versus member repository submissions

"EMMA-native" submissions (where "EMMA" is selected as the "Source Repository") will be entered into the EMMA index immediately after completion. This means that your submission can start appearing in EMMA search results almost immediately.

The remediation of a file derived from the holdings of a member repository must be submitted back to is submitted back to that repository for inclusion in their collection. Depending the policy of the specific member repository, there may be some delay (hours or days) before the new member repository item associated with your submission starts to appear in EMMA search results.

Change Updating an existing EMMA entry

If you arrive at this page through the Upload Actions Change button, you will be presented with a drop-down list of your previous submissions. Select an entry from the list to proceed.

The form for modifying an existing entry is very similar to the form for creating a new entry, except that the initial field filter is "Completed fields".

You may modify metadata associated with your submission by reviewing and modifying the metadata fields (refer to "Submitting a new item to EMMA" above for a description of how the fields are organized).

You may also replace the file that was originally submitted with a new file. To do this, select the Replacement file button. Refer to "Select a file to upload" above for a description of the remainder of this process.

When the changes have been validated, the Update button will be enabled.

If you decide that you do not want to commit to the changes, you may click CANCEL (which will attempt to return you to the previous page), or simply go to any other page in EMMA.

Remove Removing an existing EMMA entry

If you arrive at this page through the Upload Actions Remove button, you will be presented with a drop-down list of your previous submissions. Select an entry from the list to proceed.

To verify that this is really the item you want to delete, you may click on More ▼ to display the item's metadata.

If you decide that you do not want to delete the item, you may click CANCEL (which will attempt to return you to the previous page), or simply go to any other page in EMMA.

If you are certain that you want to delete the item, then click Delete. This will removes the remediated content file and the associated entry from the EMMA Unified Index.

OVERVIEW

The bulk upload feature, an alternative to the single-upload submission form, allows you to submit an unlimited number of items simultaneously. The information and requirements for each item to submit are no different, but the two-phase process supports workflows in which EMMA submissions can be more easily integrated into your organization's practices and accommodating your own schedule.

The first phase, creating and updating the manifest, supports the ability to assemble items for submission one at a time or in batches, in one sitting or in multiple sessions. In this phase the system validates your items as you enter them and will report on each item's readiness for submission.

The second phase, manifest submission, supports unattended operation after providing file location information. Submitting only pre-validated manifest items ensures that all submitted items have the potential to become valid EMMA entries.

All of EMMA’s functionality related to working with bulk upload manifests and bulk submissions is available after selecting Bulk Uploads from the navigation menu. The Bulk Uploads main page displays all of the manifest that have been previously created under your account.

Manifest Actions menu

The available functions are displayed at the top of each Bulk Uploads page as a set of buttons:

When you want to begin the process of sharing a large number of files all at once with the EMMA community, this can be done by clicking the Create button. Once the item(s) have been gathered into a manifest, items which have been validated and saved can be submitted all together.

Action Short Cuts

Each manifest listed on the Bulk Uploads page is associated with controls to manage that manifest (to the left of the manifest description on desktop displays; at the top of the screen on mobile displays):

Clicking on △ will redirect your browser to a new screen that will allow you to modify that manifest and its contents.

Clicking on ✖ will redirect your browser to a new screen that will prompt you to delete that manifest and its contents.

List All Show Your Bulk Upload Manifests

This is a listing of all EMMA bulk upload manifests you have created in descending time order, starting with the one most recently created or modified.

Each manifest in the list is preceded by action short-cuts for working with that manifest.

Create Creating a New Bulk Upload Manifest

The interface for creating a new manifest is identical to modifying an existing manifest. Continue to "Working With Bulk Upload Manifests" for help on adding and modifying manifest items.

Working With Bulk Upload Manifests

A bulk submission manifest is a collection of items that can be submitted together to create multiple EMMA entries. A manifest is presented as an interactive grid with a row for each distinct remediated item to be submitted to EMMA and where each column represents a metadata field for that item (including a reference to the remediated file).

Manifest items can be provided in several ways:

• CSV File Import
• Manual Item Creation

Manifest title

When a manifest is started, a unique title is generated as a way to distinguish it from others you may have created. You can choose to keep this title or replace it clicking the Edit button next to it, which copies it into to an edit control where some or all of the characters can be replaced.

If you're satisfied, the Change button (or Enter key) will update the title; otherwise the Cancel button (or ESC key) will keep the title as it was. The title can be changed whenever you like. (Take care to provide a name that will let you distinguish it from other manifests you may have created.)

CSV File Import

EMMA can fill manifest grid rows from the rows of an imported CSV ("comma-separated variable") file that has been exported from a spreadsheet (e.g. Microsoft Excel, or Google Sheets).

To begin, click the Import button which will open a "file chooser" for CSV files.

TODO...

Once rows have been imported, any missing or problematic values need to be resolved manually in order to ensure that the new items have sufficient information to allow them to be automatically submitted.

Manual Item Creation

To create a new row at any point in the grid click the + (plus sign) and a new empty row will be inserted after that row.

TODO...

Once your changes, additions, and deletions are as you like them, click the Save button to commit them. Uncommitted manifest items will be visible on the submission page but they aren't eligible for submission.

Next Steps

After saving your manifest, you might be ready to submit the items it contains. In this case you may click the Submit button on that page to submit that manifest. Once your changes, additions, and deletions are as you like them, click the Save button to commit them. Uncommitted manifest items will be visible on the submission page but they aren't eligible for submission.

Change Updating a Bulk Upload Manifest

If you arrive at this page through the Manifest Actions Change button, you will be presented with a drop-down list of your manifests in descending time order, starting with the one most recently created or modified. Select a manifest from the list to proceed.

The interface for editing an existing manifest is identical to creating a new manifest. Continue to "Working With Bulk Upload Manifests" for help on adding and modifying manifest items.

Remove Removing a Bulk Upload Manifest

If you arrive at this page through the Manifest Actions Remove button, you will be presented with a drop-down list of your manifests in descending time order, starting with the one most recently created or modified. Select a manifest from the list to proceed.

To verify that this is really the manifest you want to delete, you may click on More ▼ to display its details.

If you decide that you do not want to delete the manifest, you may click Cancel (which will attempt to return you to the previous page), or simply go to any other page in EMMA.

If you are certain that you want to delete the manifest, then click Delete. This will removes the manifest and its contents from your list.

Submit Submit a Bulk Upload Manifest

If you arrive at this page through the Manifest Actions Submit button, you will be presented with a drop-down list of your manifests in descending time order, starting with the one most recently created or modified. Select a manifest from the list to proceed.

Bulk Upload Submissions

On the bulk submission page you will see a table with a row for each item that could be submitted and columns for each of the submission steps for that item.

Any submission step that an item has not yet progress through will show in the associated column.

Correct and Save Items

The Validation column is the first "step" of bulk submission, and, generally, that step has already been performed in the creation of the manifest itself. Items that have been saved and validated will have in this column, and these items are ready for the next submission step.

Items that have not yet been saved will have in this column. Items that have been saved but are not valid will have in this column. Before these can be part of the submission, return to the manifest (via the Edit button on the status), make any changes required, verify that items are correct, and then save the manifest.

Identify Files

The File Status column is the next "step" of bulk submission. In general, all items will initially display in this column, meaning that the name of the remediated content file given in the manifest needs to be located.

Due to security constraints (enforced by all web browsers), files can only be accessed by explicit command of the user by way of the selection of file(s) through the native system's "file chooser". For the bulk submission page this is invoked by clicking the button.

Files are not uploaded at this point, only identified and given internal system "handles" that can be used to access the file for upload when the submission process is initiated.

The "file chooser" that is opened is "multi-select", meaning that you can specify more than one file before pressing "Open" to select them. To simplify the process, you can select "all files" (in whatever way your native system allows) and EMMA will locate all of the files whose names match manifest items. All other files will be ignored, so your remediated files can safely coexist with many other files in the same folder.

Because the automated submission process cannot begin without these file "handles" in place, the Start button is disabled until files

Identify items (optional)

If, for some reason, you would like to limit the set of items that will be part of the current bulk submission action, you can check the checkboxes of just those items.

If you want to exclude a few items, you can check the checkbox in the header to checkmark all items and then uncheck the items to exclude.

If you inadvertantly have checked items and want to restore the default behavior you can click the checkbox in the header to toggle the state of all items' checkboxes until all are unchecked. When all items are checked, the header checkbox is checked; when all items are unchecked, the header checkbox is unchecked; if only some items are checked, the header checkbox displays a dash (-) to indicate an intermediate state.

If no items are checked (which is the usual case), it is assumed that all eligible items should be included in the bulk submission.

Begin the bulk submission

Once file references have been resolved, click Start to begin the submission.

During or after the submission process you may click on the to see a text-based summary of submitted item successes (or failures).

At this point, the bulk submission interface does not require any interaction and will automatically process batches of manifest items through the remaining submission steps on their way to becoming EMMA entries.

File Uploading and Storage

There are actually two parts to this step, which is why you may see status values in the Storage Status column behave a little unexpectedly. The first part is handled by the EMMA client that runs in your web browser which performs the upload-to-cache part. The second part is managed by the EMMA server to

The first part is handled by the EMMA client that runs in your web browser which perform the actual "upload" in groups of five. As they are uploaded to cloud cache storage, their respective entry in the Storage Status column will change.

As files begin to arrive in cloud cache storage they will be "processed in" to be moved into permanent cloud storage, which is the second part of this step (handled by the EMMA server). Any entry whose file fails to be moved into permanent storage (possibly due to a network error or other transient problem) will not advanced.

Indexing Status

Metadata for items are submitted to the "index ingest API" to create the index entry associated with that item. As they are transmitted to the index, their respective entry in the Indexing Status column will change. Any entry whose metadata is not accepted by the index (possibly due to a network error or other transient problem) will not advance.

Entry Status

EMMA repository entries are created for manifest items. As associated EMMA database items are created, their respective entry in the Entry Status column will change. Any manifest item that has made it through this last step is now associated with an EMMA repository entry which is findable in EMMA search.

Search Terms

A query can have multiple space-separated terms. Each term must be of the form prefix:value, where prefix is either:

• An identifier type: isbn, issn, oclc, lccn, or doi.
• A search type: author, title, or keyword.

If the search value has a space in it, it must be surrounded by quotation marks -- either double-quotes (") or single-quotes (').

As an example, all of the following are valid searches:

• isbn:9780385528863
• title:Shining
• author:"King,Stephen"
• author:”Stephen King”
• author:”King” title:"The Shining"