OLE 0.6 User Documentation

Owned by Nora Roggeveen-Sams (Unlicensed)
Last updated: Mar 21, 2014Version comment

Information on this page applies to Kuali OLE, Release 0.6.

Contents
 

Test-driving OLE 0.6

  1. Log into KIS

  2. Use the Driver's Manual and other documentation available on this wiki to test functionality or go directly to

    Unknown macro: {html}

    <A href="http://demo.ole.kuali.org/ole-demo/portal.jsp" mce_href="http://demo.ole.kuali.org/ole-demo/portal.jsp" target="_Blank">OLE DEMO Drive</A>

  3. Give us your feedback

KIS Login

To guarantee access to all OLE materials and attached files, it is recommended you be logged into KIS.

  1. Current KIS user? Check that you are logged in via the top right corner of this screen. If you see your name, you are logged in. If not, click the "log in" link.
  2. New to Kuali? Setup your account - it's easy and fast, and only requires your name and email address to get started immediately. You can then access information on other Kuali projects thru this wiki, Google Docs or even Jira. Create a KIS Account
  3. KIS credentials are NOT required to access our Wiki Pages or the DEMO drive of OLE.

Driver's Manual

(info) If you have any trouble accessing the Driver's Manual, please check your browser settings for PDF handling, or simply right click on any of the links to save locally and review. Opening the main Driver's Manual document locally in Adobe Acrobat also provides all PDF bookmarks for easy document navigation.

OLE 0.6 Driver's Manual Functional Document (PDF - 10 MB)

Demo and Installation

(info) The help icons, that appear next to some fields (see image on right), are not functioning for OLE 0.6. If selected, you will only receive an error message at this time.

Appendices, References and Resources

Appendices & Reference:

Kuali Linked Resources:

Release Notes

Introduction

The Kuali OLE 0.6 Milestone Release focuses on enhancing the infrastructure that was available in the OLE 0.3 Milestone Release.

  • New schemas have been introduced:
    • The OLE Instance schema is loosely based on the MARC Format for Holdings Data (MFHD). OLE Instance documents are used to identify and describe library resources locally owned/licensed by libraries and as such contain unique information that can not be captured in Bibliographic documents that may be used/shared by multiple libraries.
    • ONIX-PL, a standard used to describe and transmit licensing information for electronic resources, will be utilized as the central schema for storing data within Kuali OLE’s licensing module.
  • KFS has been upgraded.
  • With the onset of Rice 2.0, KRAD and KRMS features have been incorporated into part of OLE.
    • KRAD provides the user interface OLE needs for inquiries and lookups, transactional and maintenance documents.
    • KRMS provides OLE the opportunity to build its own flexible and easily managed business rule system.
  • Code refactoring corrects the mistakes made during the 0.3 Milestone Release and keeps the OLE system better maintained.
    The Service Registry contains information about all services that have been registered from OLE to the services bus (KSB), designed to allow developers to quickly develop and deploy services for remote and local consumption.
  • KFS PURAP upgrade has been postponed.

Schemas

Instance Schema

OLE Instance documents are used to identify and describe library resources locally owned/licensed by libraries and as such contain unique information that can not be captured in Bibliographic documents that may be used/shared by multiple libraries.

OLE Terms and Definitions
  1. Instance. This document type includes information traditionally known as holdings and item information. It is a single document type with 2 categories of information (holdings and item).
  2. Holdings. Describes the extent of a resource available to the user. In the case of continuing resources holdings data may record the pattern of issuance of a resource and/or a summary statement of volumes held.
  3. Item. Describes the smallest unit of a resource that is managed and/or circulated individually.  It provides specific information regarding the physical location when pertinent.

The OLE Instance schema is loosely based on the MARC Format for Holdings Data (MFHD) and represents core elements that must be included when describing holdings and items.  The schema does not support every MFHD field/subfield but does include additional pieces of information not supported by MFHD. Additionally, the OLE Instance schema has taken some elements traditionally captured with holdings data and moved those to item descriptions.   These include elements for describing the location of items (MFHD 852 field and subfields) as well as information relating to how users may access electronic resources (MFHD 856 field and subfields).  Because the current schema only represents “core” elements, it does allow for the addition of “local” pieces of data via the <extension> element. 

The OLE Instance schema does not dictate how libraries combine items to comprise holdings data.  As with MFHD, libraries may choose to describe multiple copies of a single resource in one OLE Instance or provide separate OLE Instance documents for each copy.  The OLE Instance <separateOrCompositeReport> element will allow libraries to indicate for each OLE Instance document whether or not it is for only one copy or for a consolidation of information about more than one copy of the bibliographic item.

High Level Business Rules
  1. 1 Bibliographic Description must have at least 1 OLE Instance Description.
  2. 1 Bibliographic Description may have more than 1 OLE Instance Description.
  3. 1 Instance may have more than 1 related Bibliographic Description (to account for ‘bound-withs’/analytics).
    1. An Instance document will contain references to each parent system-generated Bibliographic Universally Unique Identifier (UUID).
    2. An Instance document will have a system-generated UUID.  
    3. Instance documents may be moved from one Bibliographic description to another Bibliographic description.
    4. An Instance must have 1 Holdings description and only 1 Holdings description.
      1. A Holdings description will have a system-generated UUID.
        1. Identifiers from legacy systems will be stored/managed in <formerIdentifiers>  within the holdingsGroup which allows for the capture of the former identifier and the type of the former identifier).
        2. An Instance must have 1 Item description and may have many Item descriptions.
          1. Each Item description will have a system generated aka UUID - distinct from the item barcode or URL/URN).
            1. Identifiers from legacy systems (former barcodes, former system identifiers) will be stored/managed in <formerIdentifiers> within the itemGroup which allows for the capture of the former identifier and the type of the former identifier.
            2. Within an Instance document, Holdings information is shared by all Items, but is not physically inherited by the Items.  If Holdings specific data is changed, it is therefore changed for all Items within the same Instance document.
              1. Data captured for Items, (e.g. Location information) can be changed globally across Items, but via parameters and not by just simply changing it at the "holdings" level.
              2. Requisition Line Item references 1 Item description within an Instance document.  This relationship is captured in the OLE rdbms.
              3. Purchase Order (PO) Line Item references 1 Item description within an Instance document.  This relationship is captured in the OLE rdbms.
                1. The PO Line Item UUID  will also be captured in the Item description for auditing purposes.
                2. Receiving Line Item references 1 to Many Item descriptions within an Instance document.  This relationship is captured in the OLE rdbms.
                3. When a new Item description (within an Instance document) is created during Receiving – or during any other library process that occurs subsequently to the ordering process - the related PO Line Item primary key/identifier will need to be populated in the newly created Item description.
                4. Item descriptions may be moved from one Instance document to another Instance document.
                5. References to the PO Line Item primary key/identifier must be retained within the Item descriptions for auditing purposes.

Both the schema and the schema documentation (with an internal OLE version number of 8.1) may be found in Google docs:

OLE Meta- Metadata

The following are NOT part of the Instance Schema or even other Docstore Document schemas, but are instead stored on Dosctore nodes in the architecture .....including Bibliographic documents.

  • Date Entered 
  • Created By
  • Last Updated
  • Last Updated By
  • Harvestable?
  • Status 
  • Suppress From Public
  • Fast Add Flag

Tasks or Issues to be completed/addressed for OLE .8 or later releases

  1. For OLE Instance elements that parallel MFHD fields/subfields - update <documentation> tags that were copied from the Library of Congress MFHD website: http://www.loc.gov/marc/holdings/.
    1. Remove references to MFHD fields and subfields and instead refer to related OLE instance elements.
  2. Make structural changes: e.g., change some global elements to complexTypes or imbed them within the holdings / item sections so there are only 2 root elements (<instance> and <instanceCollection>.
  3. Where needed, re-sequence and/or regroup elements to better match the parallel MFHD structure.
  4. Remove <enumeration values> for a variety of elements and designate the “type” as “codeOrIdentifier” so local implementers can choose data values from locally controlled “maintenance documents”/“code lists”.
  5. Apply data lengths to some elements to better ensure that OLE Instance descriptions can be exported to the MFHD format as needed and stay within the character length limit of a MFHD record.
  6. Create separate schemas for individual modules of data to allow for easier updates and efficient maintainability, e.g., a separate schema for location that can be “included” within or “imported” to the OLE Instance schema.
  7. Determine usefulness of <linkage> and <fieldLinkAndSequenceNumber> and update schema appropriately.
  8. Determine usefulness of <alternateGraphicRepresentation> - if it is retained, will need to add a <linkage> subelement.
  9. Determine how to identify of “owners” of OLE Instance documents.
  10. Determine how to identify “circulation” locations.
  11. Final analysis and determination of status information – what types of statuses are needed – acquisitions, cataloging, circulation?  How are the statuses generated? What should status data values be?  Where should the status attributes be stored – the Docstore or OLE relational database management systems.

Note: Tasks/issues 1-5 have been completed in OLE Instance schema version 9.

Licenses Schema

From a blog post by Emily Lynema. The original post can be found at http://kualiole.tumblr.com/post/21389823477/kuali-ole-and-onix-pl

As of version 0.6, the Kuali OLE project has decided to collaborate closely with EdItEUR, the standards body responsible for the development and maintenance of ONIX-PL. ONIX-PL, a standard used to describe and transmit licensing information for electronic resources, will be utilized as the central schema for storing data within Kuali OLE’s licensing module. With a robust vocabulary for describing a license agreement and its terms, ONIX-PL enables staff to code license information in a format that can be re-purposed for both human and machine interaction. As an XML based standard, it also fits seamlessly into the existing Kuali OLE docstore architecture. Kuali OLE’s XML based document store is a key strategy to support storing and indexing records across a variety of metadata formats.

By taking advantage of years of effort on the part of EDItEUR, working with partners in the industry supply chain, to develop and maintain ONIX-PL, Kuali OLE is saving a significant investment of time and resources that would be required to design such a complex data standard from scratch. Kuali OLE has evaluated a matrix of over 60 data elements that partner libraries may want to interpret and/or record for licenses; the vast majority of that extensive list is already included in the ONIX-PL schema and vocabulary. For the handful of elements that did not map directly into ONIX-PL, Kuali OLE has been working directly with EDItEUR to define use cases for the development of new vocabulary entries. For example, we anticipate the creation of several new dictionary values that would allow staff to record when licensed content is accessible only via password, as opposed to the more common IP authentication or Shibboleth authentication. In addition, ONIX-PL allows staff to create an unlimited number of free-text notes about a given license.

Utilization of an XML based standard like ONIX-PL for storage of license terms also opens the door to future integration. Although libraries have not historically received ONIX-PL encoded licenses from publishers, utilizing this standard within the Kuali OLE docstore would make this level of integration simple. For this reason, licensing functionality currently scheduled for the first release of Kuali OLE includes the ability to import ONIX-PL encoded licenses. As another example, it might be possible to define a simple ERMI XML schema and a re-usable ERMI to ONIX-PL stylesheet for libraries that have existing ERMI based license data stores utilizing non-standardized formats. This would reduce the burden on libraries migrating license data into OLE to conversion of their ERMI data stores into a simple XML format for ingest.

In partnership with EDItEUR, the Kuali OLE project is excited about the prospect of a future where standardized license data can be efficiently stored, exchanged, and shared with users.

KFS Upgrade

A full KFS 5.0 code merge and upgrade is expected during the OLE project schedule for OLE 0.8 (spring 2013). OLE did prepare and edit some existing code and services to prepare for eventual upgrades, but partial upgrades during OLE 0.6 were postponed until KFS completes testing and debugging of KFS 5.0.

Rice 2 Server/POC

Recently, Rice 2.0 was released with the features we really need to improve our OLE system. The main features that Rice 2.0 has are:

KRAD

Kuali Rapid Application Development Module (KRAD). The user interface framework component (UIF) of KRAD is built upon a rich JQuery library, provides more UI (user interface) flexibility and improved configuration and tooling including messages and notifications, client side validation, AJAX enabled fields, ... KRAD provides the UI OLE needs for inquiries and lookups, transactional and maintenance documents. For example:

  • Perform lookups/inquiries within a lightbox/iframe that pops up over the document
  • Open documents or route log from action list or document search in a lightbox
  • Add support for some transactional document layouts without using JSPs.
    KRAD makes data dictionary change such as adding lookup constraints and custom constraints. Overall, KRAD will enhance OLE UI capabilities.

For more about KRAD, see Rice KRAD analysis

KRMS

The other important component in Rice 2.0 is Kuali Rule Management System (KRMS). KRMS is a rule engine for defining decision logic, commonly referred to as business rules. KRMS facilitates the creation and maintenance of rules outside of an application for rapid update and flexible implementation that can be shared across applications. KRMS provides OLE the opportunity to build its own flexible and easily managed business rule system.

For more about KRMS, see the KRMS and PeopleFlow Functional Overview

How OLE is affected

Based on the above Rice 2.0 features, obviously, moving OLE to Rice 2.0 framework is what we should go for. However, Kuali OLE's current version is bundled with KFS, which utilizes Rice 1.x. Since Rice 2.0 was formally released on Feb 24th, 2012, it was impossible for KFS (Kuali Financial System) to upgrade to Rice 2.0 before OLE 0.6 release. It is not realistic to abandon KFS and one-year's worth of implementation based on that and to rebuild our own financial system for OLE. So for the OLE 0.6 release we set up two servers, one for OLE with KFS/Rice1.x to keep our financial functions and one for OLE on Rice2.0 to try the new features and see what kind of benefits it can bring for OLE. Since Rice 1.x can not talk with Rice 2.0 through the KSB (Kuali Service Bus), therefore, the communication between two servers geso through SOAP services like this simple drawing for the architecture. 

As we discussed above, OLE 0.6 still keeps all the finance related functions, such as requisitions, on the OLE/Rice1.x server. On the OLE/Rice2.0 server, two important functions Ingest and Bibliographic Editor were implemented for OLE 0.6 by using KRAD and KRMS. Therefore, on OLE 0.6, Bib Editor will try some of the KRAD features such as client side validation. The actually data is checked in and checked out from the DocStore through web services.

For ingest functions on OLE 0.6, the business rules are not hard coded. Instead, users can define their ingest rules for each vendor in an XML profile, upload to OLE/Rice2, and through the KRMS interface, users can actually see those hierarchical rule structures. Through the ingest staff load interface, they can apply those rules to the data they want to load. Users can easily make changes to the rule profile and the actions they want to apply for those rules. When loading the data, the actual actions are executed on either the DocStore (such as create bib records), or OLE/Rice1.x (such as create PO) by calling the web services and passing the data.

Ingest and Bib Editor will be the good example to show you the benefits we can take from Rice 2.0.

Code Refactoring

Besides OLE/Rice 2.0 features, the other important piece for OLE 0.6 is the code refactoring. After the OLE 0.3 release, the OLE development team has better understanding of Rice and KFS. Code refactoring corrects the mistakes made before, and keeps the OLE system better maintained. OLE uses Fisheye as the bug tracking system, documenting all the problems found in the code review process. Jonathan Keller summarized clearly common mistakes the developers made in the previous codes in this PPT slides. By borrowing the experience from KFS and Rice, we have our coding standards for OLE from naming convention to Data Access Objects, service design and thread safety.
For lists of problems the developers may have in more detail, see:

Code refactoring also brings us other benefits, which will benefit the future OLE/KFS upgrades on Rice 2.0: It can reduce the problems that may occur during the upgrades.

Services Registries

The Service Registry contains information about all services that have been registered from OLE to the services bus (KSB). The Service Registry is available as a SOAP endpoint which allows for registering, removing, and querying on information about these service endpoints. It is important for OLE to make those services accessible remotely due to our OLE 0.6 two servers design since it allows OLE/Rice 2.0 applications to talk with OLE/Rice 1.x and the DocStore.

We have documented our OLE and DocStore services in the OLE service spread sheet, and the DocStore wiki. We realize that the documentation is not reader friendly but we will continue working on and improving the documentation for OLE version 0.8. The future wiki for services registry will borrow some from the Kuali Student services documentation, so that non-developers can also benefit from it.

More information about services registry in Rice can be found in the Rice Wiki.

KFS PURAP Upgrade

(postponed until KFS completes testing and debugging)

Give us your feedback!

Participate in the further improvement of the OLE application by providing some feedback on our release 0.6.

OLE 0.6 Feedback Survey

Operated as a Community Resource by the Open Library Foundation