EMMA Help Topics
Signing in to EMMA
Searching EMMA may be performed by anyone, but downloading, uploading, and other operations that affect the state of EMMA will require you to identify yourself by signing in.
Sign in with Bookshare
Pressing thebutton 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 presson 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 (email@example.com).
Searching in EMMA
A search term is required to begin. You may search for matches on the basis of:
- Keyword (default choice)
- 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.
Enter one or more search terms in the search input box, then press thebutton. (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.
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.
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.
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.
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:
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.
These are drop-down menus which can only be set to a single value.
Use this filter to limit results to just those from a specific member repository.
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.
Limit results to items that have at least one of the selected file formats.
Limit results to items that have at least one of the selected remediation properties.
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.
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).
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.
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).
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 "
to the URL).
Downloading from EMMA
Activation of item download links require you to be signed in to EMMA (although certain non-restricted items may be freely downloadable, depending on the originating member repository). After performing a search, scroll to the item of interest, and click on the download link to initiate a download.
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".
Uploading to EMMA
You must be signed in in order to submit a new remediated item, or to make changes to an existing repository entry.
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.
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.
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 thebutton 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 firstname.lastname@example.org.)
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.
Metadata field filters
EMMA defines a significant number of metadata fields, so there are three radio buttons to provide different views of the data entered so far:
The initial selection is unfiltered, showing form fields for all of the metadata types defined by EMMA.
Select this option to see only the fields that have been filled, either with data extracted from the file, or with values that have been entered manually.
This filter option also shows required fields that have not been supplied.
Select this option to see only required fields that have not been supplied and/or optional fields which do not have acceptable values.
If this filter option shows no fields, then the entry should be ready to be submitted.
Step 5: Complete the submission
When all required fields have been supplied, and all fields with data are valid, then thebutton will be enabled. Press it to complete the submission.
If you decide that you do not want to submit the item, you may click(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.
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 Select a file to upload" above for a description of the remainder of this process.button. Refer to "
When the changes have been validated, thebutton will be enabled.
If you decide that you do not want to commit to the changes, you may click(which will attempt to return you to the previous page), or simply go to any other page in EMMA.
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(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. This will removes the remediated content file and the associated entry from the EMMA Unified Index.
EMMA Bulk Upload Manifests
You must be signed in in order to create, modify, or submit bulk uploads.
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.
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.
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:
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 thebutton which will open a "file chooser" for CSV files.
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.
Once your changes, additions, and deletions are as you like them, click thebutton to commit them. Uncommitted manifest items will be visible on the submission page but they aren't eligible for submission.
After saving your manifest, you might be ready to submit the items it contains. In this case you may click thebutton on that page to submit that manifest. Once your changes, additions, and deletions are as you like them, click the button to commit them. Uncommitted manifest items will be visible on the submission page but they aren't eligible for submission.
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.
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(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. This will removes the manifest and its contents from your list.
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.
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, thebutton 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, clickto 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.
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.
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.
EMMA Bibliographic Lookup Tool
Although the target application will generate these queries from fields in the submission form, this interface allows you to create that query manually and receive the results (in JSON format) that the target code would receive.
A query can be a simple identifier like "isbn:9780521454285", or it can a search including multiple search terms. Single identifier queries return the least ambiguous results. General searches may return many items that might not be what you had in mind. Caveat emptor.
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:
- author:”Stephen King”
- author:”King” title:"The Shining"