CUD Ui User Guide

2. Introduction

The Core User Directory User Interface (CUD UI) can be found at https://ui.cud.ox.ac.uk and is accessible to registered users. It provides functionality in three areas:

1. Searching
2. Matching
3. Affiliations Manager

Login through Webauth is needed to access any functionality.

3. Simple Searching

The interface for simple searching provides a list of queries which have been previously run and saved (none in the screenshot below), and a button to create a new query.

A new query is built in a query builder screen which offers tools to set criteria for a commonly used subset of data stored in CUD.

Criteria can be set on attributes selected from a drop-down list (see Appendix A below for an explanation of these attributes), and an “equals” or “not equals” operator selected. Click the Add button every time a criteria is completed.

Criteria can be combined using the “AND” or “OR” operator (please note that you should also use parentheses when using the “OR” operator. You need to click the “Add” button to include such an operator in your search.

When all criteria are set, click the “Search” button to execute the search, which is run in the security context of the logged-in user. Results are displayed further down the page. We will save this query as “Demo query” so that we can run it again. A saved query is also assigned a reference which enables you and others to reference this query when using the web services interface.

We can now Edit/run the query to explore that formats in which data is available:

CSV:

XML in flat format:

XML in structured format:

See Appendix B for more information on data structures and formats.

More sophisticated queries can be built to provide result sets similar to those provided from the Registration database (until August 2012). Date fields can be search using the NOW function, to which days can be added or subtracted. When setting a criteria for University Card Expiry Date and Registration Expiry Date ranges of dates can be searched using the [<from> TO <end>] syntax, which can include wildcards. Combining these with [NOW TO *] will match all date fields with a date greater than or equals to today. Dates can be added to and subtracted from NOW in a way similar to the following examples:

NOW-1DAY

NOW+1DAY

NOW-1MONTH

NOW-2MONTHS

NOW-1YEAR

NOW+1YEAR

NOW-1YEAR+1MONTH

Further examples can be found at <http://lucene.apache.org/solr/api/org/apache/solr/util/DateMathParser.html>

Specific dates can be used, but these must be formatted correctly as ISO8601 yyyy-MM-ddThh:mm:ssZ such as 2012-01-31T12:00:00Z

The NOW function can only be used in date fields, of which the only two queryable in this interface are:

• University Card Expiry Date
• Username Expiry Date

Ranges without the NOW function can be used on other fields.

Solr/Lucene query syntax is used, to find out more about how criteria can be described http://wiki.apache.org/solr/SolrQuerySyntax is a good (if technical) starting point. Please note that not all filters and processors are enabled on CUD, so not everything will work as expected. You are encouraged to use the CUD UI interface to build and test queries.

Here is a query demonstrating the use of parentheses and the “OR” operator:

4. Simple Matching

The simple matching interface is intended to allow locally held lists of people to be matched against CUD data. This could provide the following benefits:

• Discover whether a record for a person exists in a central data source
• Discover the affiliations recorded for a person
• Enrich locally held data with additional attributes

• Aid with lifecycle management by exposing when affiliations are no longer valid

The Simple Matching display a list of matching operations previously executed (none in the screen shot below), and a button to create a new matching list.

Here we create one called “Training Demo”

and click to manage it from the list

A blank matching list is now displayed.

To start we upload a file for matching

The column headings must be left as they are in the sample. Add as much data as you are able. Please note that the fields that can be provided are limited, but this is likely to be extended during the early adopter phase.

We are asked to wait while the file is processed

Returning to the matching list we can see which rows matched data in CUD, the number of matches made for each of these, and which rows did not match any data.

Where a match has been made it (or they) can be reviewed by clicking the icon on the row in question.

At which point it is possible to see on what basis that match was made, and the level of confidence that has been assigned to the matching strategy.

Multiple matches can be reviewed and false matches removed

The resulting list can be downloaded as a csv file containing the data you uploaded and data matched from CUD

The matching list will remain in CUD for up to one year, but the matching data is a snapshot of what CUD contains when the match is made and so is not updated as data changes in CUD.

5. Affiliations Manager

Affiliations Manager is intended to enable units of the University to assert an affiliation with a unit. These affiliations supplement those asserted by central data systems such as University card and HR. Affiliations suitable for adding to CUD in this way must be:

• Of interest to more than one unit within the University
• Actively managed by the Unit which asserts the affiliation (unmanaged affiliations will expire automatically)
• Suitable to be available as part of the CUD attribute set to all authorised users of CUD

The benefits of using Affiliations Manager include:

• The affiliations asserted can be used as criteria in searches of CUD
• Affiliations are added to person records in CUD, as these records are constantly updated management of the life cycle of an affiliation is made easier
• Affiliations can be shared between multiple units

Affiliations Manager displays Affiliation lists which have been asserted over which you have administration rights (the creator of an Affiliation list automatically has administration rights over it). No such lists are shown in the example below. A button is provided to enable a new Affiliation list to be created.

Affiliations in CUD take the form <status>@<unit> both parts of this must be selected from the drop-down lists provided. Additional statuses can be requested (a process for this is being developed at the moment). Units are defined by PRAC, and only those over which you have administrative rights are available for you to choose from.

Once the Affiliations list has been created it appears on the Affiliations Manager front page and can be managed.

A blank affiliations manager contains the following sections:

Actions

• Upload a file for matching (using a similar process to that used for Simple Matching)
• Download a file containing exact matches that have been made
• Upload a file containing exact matches, including a CUD ID for each record. This file can be obtained from Simple Matching, or using the matching functionality provided by Affiliations Manager

Confirmed Members

• People who are asserted to have the affiliation and on whose CUD records the affiliation is included
• A button to use in order search for individual people and add them to the affiliation list

Matched records requiring checking

• The results of a matching upload once processed by CUD, these should be checked and manipulated such that each record uploaded is matched to a single record in CUD

Un-matched records requiring checking

• Records contained a matching upload which could not be matched against CUD. You are encouraged to check carefully whether these people exist but have not been found for any reason
• If you are sure that a person does not currently exist in CUD (e.g. people external to the University), but you wish to assert an affiliation for the person, you may add them to CUD as a special case

Here a file is uploaded for matching. Please note that each time a file is uploaded for matching all records which have previously been uploaded for matching are deleted before the upload is processed. Confirmed members of this affiliation are not affected.

The column headings must be left as they are in the sample. Add as much data as you are able. Please note that the fields that can be provided are limited, but this is likely to be extended during the early adopter phase.

We are asked to wait while the file is processed

When matching in the Affiliations Manager CUD infers an affiliation of the unit for which the affiliation list is being created, so results may differ slightly from Simple Matching.

The matches can be inspected and manipulated as necessary. See the Simple Matching Documentation for details on how to do this.

Here we have removed one of the matches, as a match had already been made for that object. We then download a file of exact matches, so ignoring the record with multiple matches. This example this consists of a single record, complete with the CudID.

That file can then be uploaded to confirm membership of the affiliation list. At this point the affiliation is added to person documents in the CUD data store and so can be used in search terms and retrieved by authorised CUD users. The lists of matched records awaiting checking and unmatched records are cleared at this point. New lists may then be uploaded for matching.

If you are absolutely sure that the an un-matched person does not exist in CUD or in any of the primary data sources that supply data to CUD, you may add the person as a special case. The affiliations list, it's owner and administrators will be recorded as the source of data for this person.

6. Appendix A: Attributes available in searches

The following attributes are available for searching:

7. Appendix B: Data formats

The CUD UI provides data in two structures and 3 formats

The “Flat” data structure is used to provide data in delimited (CSV) format. It has the following characteristics:

• Multiple values are concatenated
• Metadata is not includes except in the column headers
• Encoding is not declared

It can also optionally be used for XML and JSON format.

Attribute formatted as XML using “Flat” structure

<cudSubjects>

<cudSubject>

<attributes>

<cudAttribute>

<name>solr:id</name>

<value class="string">cud:AFD01CAABED1-41BF-94DE-0EE7A42A9262</value>

</cudAttribute>

...

</attributes>

</cudSubject>

</cudSubjects>

Multi-valued attribute formatted as XML using “Flat” structure

<cudSubjects>

<cudSubject>

<attributes>

<cudAttribute>

<name>cud:cas:scoped_affiliation</name>

<value class="list">

<string>MC@EN</string>

<string>MC@EN;20090106;20120630;UAS_UniversityCard</string>

<string>MC@oucs</string>

<string>MC@oucs;20090106;20120630;cud:derived:UAS_UniversityCard:OUCS</string>

<string>MC@Computing Services</string>

<string>MC@Computing Services;20090106;20120630;cud:derived:UAS_UniversityCard:OUCS</string>

<string>Unknown@oucs</string>

<string>Unknown@oucs;;;OUCS_Registration_Affiliations</string>

<string>Unknown@Computing Services</string>

<string>Unknown@Computing Services;;;OUCS_Registration_Affiliations</string>

<string>Staff@EN</string>

<string>Staff@EN;20110110;20120630;UAS_OpenDoor</string>

<string>Staff@oucs</string>

<string>Staff@oucs;20110110;20120630;cud:derived:UAS_OpenDoor:OUCS</string>

<string>Staff@Computing Services</string>

<string>Staff@Computing Services;20110110;20120630;cud:derived:UAS_OpenDoor:OUCS</string>

</value>

</cudAttribute>

...

</attributes>

</cudSubject>

</cudSubjects>

The “Structured” data structure provides more detail as well as metadata. If you are able to consume data in this format then you are strongly encouraged to do so.

Attribute formatted as XML using “Structured” structure

<cudSubjects>

<cudSubject>

<cudId>AFD01CAA-BED1-41BF-94DE-0EE7A42A9262</cudId>

<attributes>

<cudAttribute>

<name>cud:cas:barcode7</name>

<source>cud:derived:uas_universitycard</source>

<lastUpdated>2012-04-05 08:29:00.0 UTC</lastUpdated>

<description>Barcode7 derived from barcode</description>

<value class="string">2761086</value>

<primaryKey>false</primaryKey>

</cudAttribute>

</attributes>

...

</cudSubject>

</cudSubjects>

Affiliation formatted as XML using “Structured” structure

<cudSubjects>

<cudSubject>

<cudId>AFD01CAA-BED1-41BF-94DE-0EE7A42A9262</cudId>

<affiliations>

<cudAffiliation>

<source>UAS_UniversityCard</source>

<affiliation>EN</affiliation>

<status>MC</status>

<startDate>2009-01-06 00:00:00.0 UTC</startDate>

<endDate>2012-06-29 23:00:00.0 UTC</endDate>

<lastUpdated>2012-04-05 08:27:49.0 UTC</lastUpdated>

<dateAdded>2011-12-07 09:11:25.0 UTC</dateAdded>

</cudAffiliation>

...

</affiliations>

</cudSubject>

</cudSubjects>

8. Appendix C: Other Documentation

CUD Client – for server-to-server retrieval of data in automated processes

CUD Webservice client user guide

CUD Attribute Set and release policies

CUD CAS usage and signoff