ORCA-Registry v2.4.1 Documentation

Transcription

1 ORCA-Registry v2.4.1 Documentation Document History James Blanden 26 May 2008 Version 1.0 Initial document. James Blanden 19 June 2008 Version 1.1 Updates for ORCA-Registry v2.0. James Blanden 8 January 2009 Version 1.2 Updates for ANDS and ORCA-Registry v2.3. Minor corrections. James Blanden 19 February 2009 Version 1.3 Updates for ORCA-Registry v Minor corrections. Table of Contents Background...2 Document Scope...2 Requirements...3 Overview...4 Functional Specification...6 Public Access...6 Search...6 Browse...7 Index...9 View Registry Object...10 Web Services...12 Administration...14 List Data Sources...14 Add Data Source...15 View Data Source...16 Edit Data Source...20 Delete Data Source...21 Add Registry Object...22 Edit Registry Object...25 Delete Registry Object...26 Brief Technical Overview...27 System Requirements...27 File Structure...27 Database...28 ORCA-Registry v2.4.1 Documentation 19 February 2008 Page 1 of 28

2 Background The Online Research Collections Australia (ORCA)-Registry software is a product of the Australian Partnership for Sustainable Repositories (APSR) Collection Services and Infrastructures (COSI) initiatives of ORCA-Registry software is now being utilised and further developed by the Utilities Program of the Australian National Data Service (ANDS). The ORCA-Registry is a PHP/PostgreSQL web application designed to be housed within an instance of the COSI-Framework. Document Scope This document describes the ORCA-Registry software only. It does not describe specifics of the software framework that is required to house it (see the COSI-Framework documentation for more information); issues relating to governance of an instance of the software; or provide guidelines or information for those who wish to provide data to an instance of the software. Installation instructions are provided in the software download, and so are not repeated here. A general knowledge of web application design and technologies is assumed. ORCA-Registry v2.4.1 Documentation 19 February 2008 Page 2 of 28

3 Requirements Requirements to be met by the ORCA-Registry web application software were defined at a high level in background and project documentation. As the development progressed, understanding and definition of the requirements became clearer these are summarised below. The registry data structures are to be based on those described in (and the schema provided by) ISO Registry Services for Libraries and Related Organisations (ISO TC46 SC4 Working Draft, 13 December 2005). Available as a Microsoft Word document at Define an XML schema (based on the above) for the import, export, and interchange of data into, out of, and between instances of the software. Provide for the import of conforming XML data over HTTP. Provide for the export of conforming XML over HTTP thus enabling the aggregation/federation of registries, and providing data for utilisation by external services. Provide public access to a web-based user interface for searching and browsing (discovery) of data in the registry. Provide restricted access to a web-based user interface for complete administration of the registry for the owners of the registry to manage the sources of data that the registry will be populated from. Provide restricted access to a web-based user interface for partial administration of a defined set of records in the registry for the owners of the sources of data that the registry will be populated from to manage some aspects of registry interaction with their data. For version 2, additional requirements were identified. Profile ISO 2146 to derive a new schema that is better suited for the collections registry application. This schema is known as Registry Interchange Format Collections and Services (RIF CS). Base the registry on this new schema. OAI-PMH data provision. Support for an external harvester to enable scheduled recurring harvests, and harvest from OAI-PMH data providers. Version 2.4 provides for the requirements of manual input, edit and deletion of Registry Objects (with version adding suggested vocabularies to certain fields on the input and edit forms). ORCA-Registry v2.4.1 Documentation 19 February 2008 Page 3 of 28

4 Overview The ORCA-Registry is a PHP/PostgreSQL web application designed to be housed in an instance of the COSI-Framework (see the COSI-Framework documentation for more information). Figure 1 (below) provides a conceptual overview of the application design. Figure 1: Overview of the ORCA-Registry. The registry is a database containing Registry Object records along with some information to support the gathering of this data from data providers via their Data Sources. Registry Object records are one of four classes describing a Collection, Service, Party, or Activity. These records are defined using the Registry Interchange Format Collections and Services (RIF-CS, an XML schema based on that provided in the ISO 2146 draft standard). ORCA-Registry v2.4.1 Documentation 19 February 2008 Page 4 of 28

5 The basic operation of the registry software can be described as follows. An organisation has data (usually housed in a repository of some description, though not necessarily) that they wish to be discoverable by users of the registry. They (the data providers) request that the owners of the registry configure their organisation s repository as a Data Source in the registry. The registry owners configure the Data Source; issuing a key (which is unique within the registry, and taking an agreed form); setting a URI for where to find the data that the data providers will expose; and creating roles to allow the data providers to manage and test their Data Source against the registry. The data providers now need to provide XML conforming to the RIF CS at the URI set for their Data Source (forming a Repository Interface for the Metadata Export box in Figure 1). The data can now be imported into the registry, where it will be discoverable by search and browse, and exposed by web services. Version 2 of the registry extends this functionality by providing support for Harvester 1.0. If a harvester is configured, then the registry can use it to schedule recurring harvests, and to harvest data from OAI-PMH data providers that support the RIF CS (which includes other instances of the ORCA-Registry v2.x software). Version 2.4 extends the functionality of the registry to the manual input, edit and deletion of Registry Objects. ORCA-Registry v2.4.1 Documentation 19 February 2008 Page 5 of 28

6 Functional Specification Public Access The ORCA-Registry provides public access to functionality that supports discovery, exchange, and further utilisation of the data that it contains, by users and external software. Search The Search activity provides a simple form for searching the registry. The Search provides filtering by Registry Object class (using checkboxes); restriction to a data source and/or group; and a text field for entering a search term or phrase. The Search will query the registry with the entered text across Registry Object identifiers, names, subjects, and descriptions. Any resulting matches will be filtered according to which classes (Collections, Services, Parties, and Activities) have been included the search. A checked checkbox next to a class indicates that objects of that class will be included in the results. The default setting has all of the checkboxes checked, and so will include objects of all classes in the results. Results can also be filtered by source and group, where source is the data source from which the data was obtained, and group is a set used to support the definition of an institutional portfolio. The search is implemented using the PostgreSQL full text search functionality. The entered text is converted to a query using plainto_tsquery; compared to indexed ts_vectors for identifiers, names, subjects, and descriptions; and ordered by rank with weightings (from highest to lowest) for identifiers, names, subjects, and descriptions. Further information about this technology is available at Matches in the results are highlighted with a yellow background. Figure 2 (below) shows an example of the Search activity displaying results for a search. Figure 2: ORCA-Registry, Search example. ORCA-Registry v2.4.1 Documentation 19 February 2008 Page 6 of 28

7 If more results than can reasonably be displayed on one page are returned, then the bottom of the page will provide navigation between pages of results, as shown in Figure 3 (below). Figure 3: ORCA-Registry results pagination example. Any search results will consist of a list of records including the following information for each record (where available): Names. A list of all recorded names for the record. Consisting of all name values for the record, delimited by a middle dot character, not including name part type, and hyperlinked to the View Registry Object activity for that record. Class Type. Registry Object class key. Class Key. Registry Object class key. Source. The title of the Data Source from which the data was collected. Group. The top-level group to which this object belongs. Identifiers. A list of all recorded globally recognised identifiers for the record delimited by a middle dot character. Relations. A list of all recorded relations that the Registry Object has to other Registry Objects collected from the same Data Source. Consisting of relation description relatedobject-name pairs, delimited by a semi colon ;, and hyperlinked to the View Registry Object activities for the related records. Subjects. A list of all recorded subjects for the record. Consisting of subject type: value pairs delimited by a middle dot character. Description. All of the recorded descriptions for the record, truncated to less than 300 characters. Consisting of description type: value pairs. In addition, identifiers and subjects are hyperlinked (in green) such that clicking on them will execute another search, passing the identifier or subject as the query text. Browse The Browse activity provides an alternative means of finding information within the registry. Browse provides a mechanism for filtering the contents of the registry by data source and group along with Registry Object type and subject. Groups are displayed for all selected data sources. Registry Object types are displayed for all selected data sources and groups. Subjects (if any) are displayed for all selected data sources, groups, and Registry Object types. Browse results contain Registry Objects with attributes that fall entirely within the selected set. All data sources and groups are selected on initial rendering of the Browse activity. Browse results are displayed in the same manner as the Search results (with the obvious exception of any match highlighting). ORCA-Registry v2.4.1 Documentation 19 February 2008 Page 7 of 28

8 Figures 4a and 4b (below) show examples of the Browse activity. Figure 4a: ORCA-Registry, Browse example. Figure 4b: ORCA-Registry, Browse example. ORCA-Registry v2.4.1 Documentation 19 February 2008 Page 8 of 28

9 Index The Index activity provides an alphabetised (per Registry Object class and by name) listing of the objects within the registry. Names with leading non-alpha characters, a s, and the s are included in the listings for names beginning with the character following as well as the listing for names beginning with those characters. Figure 5 (below) shows an example of the Index activity. Figure 5: ORCA-Registry, Index example. ORCA-Registry v2.4.1 Documentation 19 February 2008 Page 9 of 28

10 View Registry Object The View Registry Object activity displays all of the data held in the registry for a Registry Object. The data is displayed as follows: Class. The heading for the record is the class of Registry Object. Type. The type of Registry Object. Key. The Registry Object key. Source. The title of the Data Source from which the data was collected. Group. The group of the Registry Object. Date Created. The date the Data Source says that the Registry Object was created. Date Modified. The date the Data Source says that the Registry Object was last modified. Names. The names of the Registry Object. Identifiers. A list of all recorded globally recognised identifiers for the record. Physical Addresses. A list of all recorded physical addresses for the record. Electronic Addresses. A list of all recorded electronic addresses for the record. Relations. A list of all recorded relations that the Registry Object has to other Registry Objects. Subjects. A list of all recorded subjects for the record. Description. All of the recorded descriptions for the record. In addition, names, identifiers, and subjects are hyperlinked (in green) such that clicking on them will execute another search, passing the name, identifier, or subject as the query text. Figure 6 (below) shows an example of the View Registry Object activity. Figure 6: ORCA-Registry, View Registry Object example. ORCA-Registry v2.4.1 Documentation 19 February 2008 Page 10 of 28

11 If the user is an authenticated ORCA Data Source Administrator and a (direct or inherited) member of the organisation that is the record owner of the Data Source of the Registry Object (or an ORCA Administrator) then they will also see Created When and Created Who data along with button for Edit and Delete of this Registry Object. Figure 6.1 (below) shows this view. See the section on administration for more information. Figure 6.1: ORCA-Registry, View Registry Object example. The View Registry Object activity provides a hyperlink that will return RIF-CS for the currently displayed Registry Object. ORCA-Registry v2.4.1 Documentation 19 February 2008 Page 11 of 28

12 Web Services The Web Services activity displays information and links to the data export services provided by an instance of the registry. As well as supporting the transfer and aggregation of data between and among multiple instances of the ORCA-Registry software, these services also provide a means for external (or downstream ) services to utilise the data (as per the overview diagram in Figure 1). The services provided are listed below. An OpenSearch service ( An OAI Data Provider service ( The service supports resumption tokens (returning 100 records at a time for the ListRecords and ListIdentifiers verbs), and the oai_dc and rif metadata prefixes. Get Registry Object Groups. This service retrieves a list of distinct Groups from the registry. Get Data Source List retrieves a list of the Data Sources that the registry is configured to gather data from. The response (described by the ORCA-Registry Data Source List Schema) provides the key for each Data Source, the Provider Type of the source, and the URI that the data was retrieved from. The Get Registry Objects service retrieves RIF CS according to the parameters passed to it. The search string is treated as per the public Search activity. Put Harvest Data is a service that is not publicly visible. It accepts a package of RIF CS data, checks that it originated from the configured Harvester and runs the import process on the data. The Search Engine Index Seed provides a visible hyperlink to the registry search for search engine crawlers from which the registry contents in its entirety can be reached by following hyperlinks (via the pagination of the results). ORCA-Registry v2.4.1 Documentation 19 February 2008 Page 12 of 28

13 Figure 7 (below) shows an example of the Web Services activity. Figure 7: ORCA-Registry, Web Services example. ORCA-Registry v2.4.1 Documentation 19 February 2008 Page 13 of 28

14 Administration The ORCA-Registry installation creates two functional roles in the COSI-Framework, ORCA Administrator and ORCA Data Source Administrator. Members of the ORCA Administrator functional role will have access to all administrative activities, and all Data Source records. Members of the ORCA Data Source Administrator functional role will not be able to add or delete data source records, and will only have access to Data Source records (and their associated Registry Objects) that are owned by organisational roles that they are a member of. List Data Sources The List Data Sources activity displays a list of the all of the Data Sources that the registry is configured to collect data from. ORCA Data Source Administrators will only see Data Sources that are owned by organisational roles that they are a member of. The Data Source list can be filtered by title using the form at the top of the page. If the List Data Sources list contains only one record, then the user will be taken to the View Data Source activity for that record. Figure 8 (below) shows an example of the List Data Sources activity. Figure 8: ORCA-Registry, List Data Sources example. ORCA-Registry v2.4.1 Documentation 19 February 2008 Page 14 of 28

15 Add Data Source The Add Data Source activity (only accessible by ORCA Administrators) displays a form for adding a new Data Source to the registry. The form indicates that key, title, URI, Provider Type, and Harvest Method are mandatory. Key must be unique for an instance of the framework. URI is the location at which the data (conforming to the ORCA-Registry Data Interchange Schema) is located. If the URI is not yet known, just enter as a placeholder. OAI Set and Harvest Date are shown or hidden conditionally depending on the value set for Harvest Method. Figure 9 (below) shows an example of the Add Data Source activity. Figure 9: ORCA-Registry, Add Data Source example. ORCA-Registry v2.4.1 Documentation 19 February 2008 Page 15 of 28

16 View Data Source The View Data Source activity displays detailed information for a Data Source. Figure 10 (below) shows an example of the View Data Source activity. Figure 10: ORCA-Registry, View Data Source example. Clicking the Edit button will take the user to the Edit Data Source activity for this record. Clicking the Delete button (only available to ORCA Administrators) will take the user to the Delete Data Source activity for this record. The Test and Import buttons control interaction between the registry and the Data Source (or Harvester). The Clear button removes all records collected from this Data Source from the registry. ORCA-Registry v2.4.1 Documentation 19 February 2008 Page 16 of 28

17 Clicking the Test button will cause the registry to either attempt a connection to the Data Source at its configured URI, or submit a test harvest request to the Harvester. The results of this test will be recorded in the Activity Log. No data will be imported or modified. This provides a test of the Data Source that can be used by ORCA Data Source Administrators to assist in the development of their interfaces, or to assist in troubleshooting a Data Source without risk of modifying data in the registry. Figure 11 (below) shows an example of the View Data Source activity displaying the results of running a test import against the Data Source. Figure 11: ORCA-Registry, View Data Source, Test example. ORCA-Registry v2.4.1 Documentation 19 February 2008 Page 17 of 28

18 Clicking the Import button will cause the registry to either attempt a connection to the Data Source at its configured URI, or submit a harvest request to the Harvester. If a direct connection is made, then the response is processed for import as soon as it is received. If a request was sent to the Harvester then the status of the request is displayed. Figure 12 (below) shows an example of the View Data Source activity displaying the results of running an import. Figure 12: ORCA-Registry, View Data Source, Import example. ORCA-Registry v2.4.1 Documentation 19 February 2008 Page 18 of 28

19 Clicking the Clear button will remove all Registry Objects collected from the Data Source from the registry. Figure 13 (below) shows an example of the View Data Source activity displaying the results of clearing the registry of objects collected from the Data Source. Figure 13: ORCA-Registry, View Data Source, Clear example. ORCA-Registry v2.4.1 Documentation 19 February 2008 Page 19 of 28

20 Edit Data Source The Edit Data Source activity provides a form for modifying a Data Source. Only ORCA Administrators will be able to modify the Record Owner attribute. The key cannot be changed if there is an error with the key, then the record must be deleted and a new one with the correct key created using the Add Data Source activity. After successfully saving the changes, the user will be taken to the View Data Source activity for that record. Clicking the Cancel button will take the user back to the View Data Source activity for this record (without saving any changes). Figure 14 (below) shows an example of the Edit Data Source activity. Figure 14: ORCA-Registry, Edit Data Source example. ORCA-Registry v2.4.1 Documentation 19 February 2008 Page 20 of 28

21 Delete Data Source The Delete Data Source activity prompts for confirmation that a Data Source is to be deleted. Clicking the Delete button will remove all Registry Objects collected from the Data Source from the registry, and then delete the Data Source from the registry. Clicking the Cancel button will take the user to the View Data Source activity for that record (without deleting any records). Figure 15 (below) shows an example of the Delete Data Source activity. Figure 15: ORCA-Registry, Delete Data Source example. ORCA-Registry v2.4.1 Documentation 19 February 2008 Page 21 of 28

22 Add Registry Object The Add Registry Object activity enables the manual input of a Registry Object into the registry. Clicking the Save button will check that a Data Source has been set; if so then generate RIF-CS from the form data; validate it; and if validation is successful insert the object into the registry then take the user to the View Registry Object activity for that record. If the RIF-CS doesn t validate the user will see an error message indicating the cause of the error. Changes to the registry resulting from the use of this activity are logged against the Data Source set. Note that this activity will allow the user to set a Data Source for the object from a list of any for which the user has authorisations (via membership of organisational roles that are record owners of the Data Sources). This activity checks that the user is an authenticated ORCA Data Source Administrator and a (direct or inherited) member of the organisational role that is the record owner of the Data Source of the Registry Object (or an ORCA Administrator). Figure 16 (below) shows the initial state of the Add Registry Object activity. Figure 16: ORCA-Registry, Add Registry Object initial state. The form provided by this activity uses add and remove buttons to add and remove elements and so enable the input of any valid RIF-CS structures. ORCA-Registry v2.4.1 Documentation 19 February 2008 Page 22 of 28

23 Figure 16.1 (below) shows how the add and remove buttons provide the mechanism by which the Add Registry Object form can accommodate any valid RIF-CS structure in its entirety. Figure 16.1: ORCA-Registry, Add Registry Object example expanded state. The form also provides calendar and vocabulary controls to assist with the input of data. The vocabulary control attached to a field can be used to enter a term into that field from a list of suggested terms (it will not override or prevent the input of another term). The terms displayed by the vocabulary tool are retrieved from either the vocabulary XML provided with the software, or from an external service (as configured in the orca_init.php). The use of an external service is at the time of writing only at an experimental stage. ORCA-Registry v2.4.1 Documentation 19 February 2008 Page 23 of 28

24 Figure 16.2 (below) shows an example of the vocabulary control showing a suggested vocabulary for the RIF-CS Relation Type. Figure 16.2: ORCA-Registry, vocabulary control. Figure 16.3 (below) shows the vocabulary control highlighting a previously entered term in the list. Note that the identifier for the vocabulary term is inserted into the field, but the names are displayed by the tool. The identifier for a term can be revealed in the list by holding the cursor over the term. Also note that the identifier and name of a term may be the same. Figure 16.3: ORCA-Registry, vocabulary control with selected value. ORCA-Registry v2.4.1 Documentation 19 February 2008 Page 24 of 28

25 Edit Registry Object The Edit Registry Object activity enables the modification of a Registry Object in the registry. This activity functions in the same way as the Add Registry Object activity other than being initially populated with data and not allowing editing of the Key. Changes to the registry resulting from the use of this activity are logged against the Data Source set. Note that this activity will allow the user to set a Data Source for the object from a list of any for which the user has authorisations (via membership of organisational roles that are record owners of the Data Sources). Clicking the Cancel button will take the user to the View Registry Object activity for that record (without modifying any records). This activity checks that the user is an authenticated ORCA Data Source Administrator and a (direct or inherited) member of the organisational role that is the record owner of the Data Source of the Registry Object (or an ORCA Administrator). Figure 17 (below) shows an example of the Edit Registry Object activity. Figure 17: ORCA-Registry, Edit Registry Object example. ORCA-Registry v2.4.1 Documentation 19 February 2008 Page 25 of 28

26 Delete Registry Object The Delete Registry Object activity enables the removal of a Registry Object from the registry. Clicking the Delete button will remove the Registry Object from the registry. Clicking the Cancel button will take the user to the View Registry Object activity for that record (without deleting any records). Note that the Registry Object may re-created with the next harvest from the originating Data Source. Also note that any relation that the object has with other objects in the registry may be broken by its removal. The record deletion will be logged against the record s Data Source. This activity checks that the user is an authenticated ORCA Data Source Administrator and a (direct or inherited) member of the organisation that is the record owner of the Data Source of the Registry Object (or an ORCA Administrator). Figure 18 (below) shows an example of the Delete Data Source activity. Figure 18: ORCA-Registry, Delete Data Source example. ORCA-Registry v2.4.1 Documentation 19 February 2008 Page 26 of 28

27 Brief Technical Overview System Requirements The ORCA-Registry is a PHP/PostgreSQL web application built to utilise the COSI-Framework (an install of which is a prerequisite). System and web browser requirements are the same as those for the COSI-Framework (see the COSI-Framework documentation for more information). File Structure The ORCA-Registry file structure is similar to that of the COSI-Framework within which it is housed. Activities are defined in files at the application root, and within folders that are not prefixed with an underscore ( _ ). Folders that are prefixed with an underscore are used to hold function libraries, help content etc. Function library files are prefixed with orca to prevent name clashes with other files included in the COSI-Framework. Figure 19 (below) shows the ORCA-Registry file structure. Figure 19: ORCA-Registry file structure. ORCA-Registry v2.4.1 Documentation 19 February 2008 Page 27 of 28

28 The file orca_init.php at the root of the application contains the environment settings for an installed instance of the ORCA-Registry. The ORCA-Registry defines some Cascading Stylesheet (CSS) styles for its own use in orca.css. These are included into the response in orca_init.php via the COSI-Framework API. The installation process makes changes to the application_config.php and database_env.php files in the housing COSI-Framework. Database The accompanying document ORCA-Registry DatabaseSchema.pdf shows the database structure used by the application. ORCA-Registry v2.4.1 Documentation 19 February 2008 Page 28 of 28