1. Introduction

CUD provides a number of interfaces for CUD registered users to access the data. These act as gateways to retrieve data from and provide data to CUD. Besides, users can choose the format in which data retrieved must appear. For example using the Simple Matching and Query interface, users may choose to download results in a comma delimited (CSV) file or in rich meta data with values of each attributes.

Users may choose the format to suit the purpose they are using the data for. It is similarly possible to generate a query, save it and reuse it in more than one interface.

2. CUD Interfaces

The following are brief descriptions of available CUD interfaces intended to assist with selection is the most appropriate for a given requirement. Details of now to request access are also provided, and additional details of how to use the interface will be provided once that request has been fulfilled. A summary of available interfaces, their purpose and what can be obtained from them is:

Table 1. Available CUD Interfaces
Interface Personal access Server/ service use AuthN method preferred Attributes available
CUD UI Y N Webauth CAS plus special release
REST N Y Kerberos CAS plus special release
SOAP query N Y Kerberos CAS plus special release
SOAP push N Y Various CAS plus special release
SQL Push N Y As required for JDBC connection CAS plus special release
LDAP push N Y LDAP simple bind over SSL/TLS CAS plus special release
  • CAS is the Cud Attribute Set as defined below

2.1. CUD UI

Typical use cases: ad-hoc lookups of data in CUD; preparation and testing of query to be used by server/service

The CUD UI is a web application which enables registered users to perform the following:

  • Searching using a query builder
  • Matching
  • Manage affiliations

All users are encouraged to use the CUD UI to familiarise themselves with the documented features

2.2. REST

Typical use-case: retrieve data for a college or department, saving to file for local processing

Representational State Transfer (REST) is the preferred method of querying CUD from a server or service. It allows data to be requested using a simple GET query communicated over HTTPS. The client is then able to save the data received from CUD to a local file for processing, or store it in memory. Client requirements are:

  • Can make GET requests over HTTPS and process the data returned
  • Can use HTTP-Negotiate + Kerberos for authentication using credentials stored in a keytab

On many Linux/Unix servers Curl can be used for this purpose. For other cases the Cud Client is available which:

  • Is full self-contained, and requires no additional Kerberos libraries on a system
  • Uses Java, with a requirement for Java 7
  • Can be invoked unattended in a script

2.3. SOAP

Typical use-case: send data to/accept data from packaged application which supports SOAP for this purpose.

SOAP is currently supported as a means of pushing data to remote webservices. Requirements are specific to each service.

2.4. LDAP

Typical use case: provision accounts to local Active Directory, with account lifecycle managed by CUD

CUD can push data to an external LDAP directory, such as Microsoft Active Directory. Requirements of the directory are:

  • Supports SSL/TLS
  • Enables CUD to authenticate with a simple bind
  • Is accessible for connections initiated from CUD server

2.5. SQL

Typical use case: maintain data on a set of people in a table in a database for use locally

CUD can push data into a SQL database. Normally this involves storing data in a table or tables in the remote database which is dedicated to this task. This data is then processed by local procedures to update other data tables, or referenced as appropriate in queries. CUD can update the log table either incrementally, or by dropping existing data and repopulating the table(s). Requirements for the SQL database are:

  • Addressable remotely on a network port (note: Microsoft Access and OpenOffice Base are not networked databases and so are not supported) with connections initiated from the CUD servers
  • Has a supported Java Database Connection (JDBC) driver
  • Username and password for use by CUD

3. Requesting use of a CUD interface

A request must be made for access to CUD via an interface. The procedure is to request personal access to the CUD Web User Interface, plus service access to other interfaces as requested initially or subsequently. The initial request for access must be supported by a signed terms and conditions of CUD access form returned to: Identity and Access Management Team, Systems Development and Support, University of Oxford IT Services, 13 Banbury Road, Oxford. You may also scan the form in and send it as an attachment to you request.

For people who have no access to CUD UI use the following email template replacing elements in <> with your details:

To: sysdev@it.ox.ac.uk Subject: Request for access to CUD UI Please supply access to CUD as follows: Name: <your name> SSO username: <your username> Unit: <Unit of the University with which you are affiliated> ITSS: Y/N Reason for access (required if not ITSS):
  • ITSS should be answered Y/N depending on whether you appear in the ITSS register
  • If you are not on the ITSS register you must provide a Reason for access - why you are requesting access, including the purpose CUD data will be put to

Once you have access to the CUD UI you can request access to an additional service interface using the following email template:

To: sysdev@it.ox.ac.uk Subject: Request for access to CUD interface Please supply service access to CUD as follows: Name: <your name> ITSS: Y/N Reason for access (required if not ITSS): ITSS Managers: Machine FQDN: Interface requested:
  • ITSS should be answered Y/N depending on whether you appear in the ITSS register
  • If you are not on the ITSS register you must provide a Reason for access - why you are requesting access, including the purpose CUD data will be put to
  • ITSS Managers is a list of members of ITSS with /itss principals (e.g. unit0001/itss) who should be given access to download kerberos principals or other credentials generated as a result of this request. At least one must be provided
  • Machine FQDN is the fully qualified network name of the server or service which will be using the interface, e.g. host.oucs.ox.ac.uk
  • Interface requested should be one or more of:
    • REST
    • SOAP query
    • SOAP push
    • SQL Push
    • LDAP query
    • LDAP push
  • If your request if for REST, SOAP query or LDAP query and GSSAPI+Kerberos authentication is not supported by the software which will be used to access CUD, please include this information in Interface requested

4. Data attributes available

4.1. CUD attribute set

The CUD attribute set (CAS) comprises a list of attributes which are available by default to all registered users of CUD for all person records in CUD. Some attributes in the CAS are consolidated values from multiple sources, others are single values taken from a single source

Table 2. CUD Attribute Set
Name Source/owner Consolidated from
cud:cas:cudid CUD
cud:cas:barcode Card office
cud:cas:barcode7 Card office
cud:cas:external_tel Telecoms
cud:cas:firstname cud:derived:uas_universitycard:firstname
cud:cas:fullname cud:derived:uas_universitycard:fullname
cud:cas:internal_tel Telecoms
cud:cas:known_as cud:derived:oucs_registration_email:preferredname
cud:cas:lastname cud:uas_universitycard:famnam
cud:cas:middlenames cud:uas_oss:middlename
cud:cas:olis_number Libraries
cud:cas:oxford_email OUCS Registration
cud:cas:sso_username OUCS Registration
cud:cas:suffix OSS cud:uas_oss:suffix
cud:cas:title cud:uas_university_card:title
cud:cas:university_card_status Card office
cud:cas:university_card_type Card office
cud:fk:bodleian_record_number Libraries
cud:fk:hris_staff_number HRIS
cud:fk:oak_person_id Oak LDAP
cud:fk:oak_primary_person_id Oak LDAP
cud:fk:opendoor_staff_number HR
cud:fk:oss_student_number OSS
cud:fk:oucs_pcode OUCS Registration
cud:fk:telecom_id Telecoms
cud:fk:university_card_sysis Card office

4.2. Complete list of attributes

Additional attributes, not included in the CAS are available on application. You must have a good reason for using additional attributes, access to which will be considered in consultation with the data owner.

The following table shows additional consolidated attributes:

Table 3. Additional Attributes
Name Consolidated from
cud:consolidated:external_email cud:uas_oss:alternativeEmail
cud:consolidated:dob cud:uas_universitycard:dob
cud:consolidated:universitycard_sub_category cud:uas:universitycard_sub_category
cud:consolidated:universitycard_sub_category_expanded cud:uas:universitycard_sub_category_expanded

The following table shows all attributes, their source and whether they are included in the CAS.

Table 4. All Attributes
Name Source/owner In CAS
cud:fk:universitycard_sysis Card Office Y
cud:uas_universitycard:student_id Card Office
cud:uas_universitycard:staff_id Card Office
cud:uas_universitycard:title Card Office Y (consolidated)
cud:uas_universitycard:fullpernam Card Office Y (consolidated)
cud:derived:uas_universitycard:firstname Card Office Y (consolidated)
cud:derived:uas_universitycard:fullname Card Office Y (consolidated)
cud:derived:uas_universitycard:middlenames Card Office Y (consolidated)
cud:uas_universitycard:famnam Card Office Y (consolidated)
cud:uas_universitycard:known_as Card Office Y (consolidated)
cud:uas_universitycard:dob Card Office
cud:cas:universitycard_status Card Office Y
cud:cas:universitycard_type Card Office Y
cud:uas:universitycard_sub_category Card Office
cud:uas:universitycard_sub_category_mapped Card Office
cud:cas:barcode Card Office Y
cud:derived:uas_universitycard:barcode7 Card Office Y
cud:uas:universitycard_comp_date Card Office
cud:uas:universitycard_start_date Card Office
cud:uas:universitycard_college_expanded Card Office
cud:uas:universitycard_college_expanded_name Card Office
cud:uas:universitycard_last_printed_date Card Office
cud:uas:universitycard_mifare_id Card Office N but available to ITSS
cud:uas:universitycard_paxton_id Card Office
cud:uas:universitycard_sub_category_expanded Card Office
cud:uas:universitycard_sub_category_expanded_name Card Office
cud:uas:universitycard_college_expanded Card Office
cud:uas:universitycard_college_expanded_name Card Office
cud:uas:universitycard_card_type_expanded Card Office
cud:fk:oss_student_number OSS Y
cud:uas_oss:prefix OSS
cud:uas_oss:suffix OSS Y(consolidated )
cud:uas_oss:middlename OSS Y(consolidated )
cud:uas_oss:lastname OSS Y(consolidated)
cud:uas_oss:firstname OSS Y(consolidated)
cud:uas_oss:preferred_given_name OSS
cud:derived:uas_oss:fullname OSS
cud:uas_oss:alternativeEmail OSS
cud:uas_oss:dateofbirth OSS
cud:uas_oss:gender OSS
cud:uas_oss:ucasid OSS
cud:uas_oss:college_offer_status OSS
cud:uas_oss:fee_status_code OSS
cud:uas_oss:fee_category OSS
cud:uas_oss:hesa_dom OSS
cud:uas_oss:prog_attmpt_status OSS
cud:uas_oss:divcode OSS
cud:uas_oss:divdesc OSS
cud:uas_oss:deptcode OSS
cud:uas_oss:deptdesc OSS
cud:uas_oss:prog_start_date OSS
cud:uas_oss:caltype OSS
cud:uas_oss:attendance_type OSS
cud:uas_oss:attendance_mode OSS
cud:uas_oss:clsstnding OSS
cud:uas_oss:progcode OSS
cud:uas_oss:progtitle OSS
cud:uas_oss:progshorttitle OSS
cud:uas_oss:year_of_student OSS
cud:uas_oss:unitsetcd OSS
cud:uas_oss:addressline1 OSS
cud:uas_oss:addressline2 OSS
cud:uas_oss:addressline3 OSS
cud:uas_oss:addressline4 OSS
cud:uas_oss:city OSS
cud:uas_oss:county OSS
cud:uas_oss:postcode OSS
cud:uas_oss:countrycode OSS
cud:uas_oss:countrydesc OSS
cud:uas_oss:mobile_phone_number OSS
cud:uas_oss:contact_phone_number OSS
cud:uas_oss:deptdesc_mapped OSS
cud:uas_oss:progtype OSS
cud:fk:bodleian_record_number Libraries Y
cud:bodleian_readers:title Libraries
cud:bodleian_readers:given_names Libraries
cud:bodleian_readers:family_name Libraries
cud:cas:olis_number Libraries Y
cud:bodleian_readers:dateofbirth Libraries
cud:bodleian_readers:email Libraries
cud:derived:bodleian_readers:firstname Libraries
cud:derived:bodleian_readers:fullname Libraries
cud:derived:bodleian_readers:middlenames Libraries
cud:bodleian_readers:mifare_id Libraries
cud:bodleian_readers:start_date Libraries
cud:bodleian_readers:expiry_date Libraries
cud:bodleian_readers:bodleian_category Libraries
cud:bodleian_readers:subject_of_study Libraries
cud:bodleian_readers:friends Libraries
cud:bodleian_readers:contact Libraries
cud:bodleian_readers:address1_line1 Libraries
cud:bodleian_readers:address1_line2 Libraries
cud:bodleian_readers:address1_line3 Libraries
cud:bodleian_readers:address1_line4 Libraries
cud:bodleian_readers:address1_line5 Libraries
cud:bodleian_readers:address1_type Libraries
cud:bodleian_readers:address1_default Libraries
cud:bodleian_readers:address1_expiry Libraries
cud:bodleian_readers:address2_line1 Libraries
cud:bodleian_readers:address2_line2 Libraries
cud:bodleian_readers:address2_line3 Libraries
cud:bodleian_readers:address2_line4 Libraries
cud:bodleian_readers:address2_line5 Libraries
cud:bodleian_readers:address2_type Libraries
cud:bodleian_readers:address2_default Libraries
cud:bodleian_readers:address2_expiry Libraries
cud:bodleian_readers:address3_line1 Libraries
cud:bodleian_readers:address3_line2 Libraries
cud:bodleian_readers:address3_line3 Libraries
cud:bodleian_readers:address3_line4 Libraries
cud:bodleian_readers:address3_line5 Libraries
cud:bodleian_readers:address3_type Libraries
cud:bodleian_readers:address3_default Libraries
cud:bodleian_readers:address3_expiry Libraries
cud:bodleian_readers:address4_line1 Libraries
cud:bodleian_readers:address4_line2 Libraries
cud:bodleian_readers:address4_line3 Libraries
cud:bodleian_readers:address4_line4 Libraries
cud:bodleian_readers:address4_line5 Libraries
cud:bodleian_readers:address4_type Libraries
cud:bodleian_readers:address4_default Libraries
cud:bodleian_readers:address4_expiry Libraries
cud:bodleian_readers:address5_line1 Libraries
cud:bodleian_readers:address5_line2 Libraries
cud:bodleian_readers:address5_line3 Libraries
cud:bodleian_readers:address5_line4 Libraries
cud:bodleian_readers:address5_line5 Libraries
cud:bodleian_readers:address5_type Libraries
cud:bodleian_readers:address5_default Libraries
cud:bodleian_readers:address5_expiry Libraries
cud:fk:opendoor_staff_number HR Y
cud:uas_opendoor:title HR Y(consolidated)
cud:uas_opendoor:initia HR Y(consolidated)
cud:uas_opendoor:middle_name HR Y(consolidated)
cud:uas_opendoor:surname HR Y(consolidated)
cud:uas_opendoor:forename HR Y(consolidated)
cud:uas_opendoor:preferred_name HR Y(consolidated)
cud:uas_opendoor:person_birth_date HR
cud:derived:uas_opendoor:fullname HR
cud:uas_opendoor:dept_acronym HR
cud:uas_opendoor:dept_name HR
cud:cas:oxford_email OUCS Registration Y
cud:cas:sso_username OUCS Registration Y
cud:fk:oucs_pcode OUCS Registration Y
cud:oucs:reg_comp_date OUCS Registration
cud:oucs:reg_displayname_first OUCS Registration
cud:oucs:reg_displayname_last OUCS Registration
cud:derived:oucs_registration_email:preferredname OUCS Registration
cud:fk:telecom_id Telecoms Y
cud:cas:external_tel Telecoms Y
cud:cas:internal_tel Telecoms Y
cud:dars:constituent_id DARS
cud:dars:constituent_lookup_id DARS
cud:fk:hris_staff_number HRIS Y
cud:uas_hris:title HRIS
cud:uas_hris:firstname HRIS
cud:uas_hris:middlename HRIS
cud:uas_hris:lastname HRIS
cud:uas_hris:known_as HRIS
cud:uas_hris:dob HRIS
cud:uas_hris:originalStart HRIS
cud:uas_hris:gender HRIS
cud:uas_hris:email HRIS
cud:uas_hris:academic_flag HRIS
cud:uas_hris:primary_post_appointment_id HRIS
cud:uas_hris:primary_post_appointment_type HRIS
cud:uas_hris:primary_post_post_start HRIS
cud:uas_hris:primary_post_department_name HRIS
cud:uas_hris:primary_post_department_code HRIS
cud:uas_hris:primary_post_category_code HRIS
cud:fk:oak_primary_person_id Oak LDAP Y
cud:fk:oak_person_id Oak LDAP Y

4.3. Requesting access to additional attributes

Please use the following email template to request access to additional attributes replacing elements in <> with your details:

To: sysdev@it.ox.ac.uk Subject: Request for additional CUD attributes Please supply access to additional CUD attributes as follows: Name: <your name> SSO username/service principal name: <username or principal> Additional attributes requested: ITSS: Y/N Reason for access:
  • SSO username/service principal name is the name of the login which requires access to the additional attributes. In the CUD UI this will be an SSO username. For other interfaces this will be the kerberos service principal name granted which has already been granted access to CUD, normally in the form cud/<host fqdn>@OX.AC.UK
  • Additional attributes requested is the list of name of the additional requested, taken from the complete list of attributes
  • ITSS should be answered Y/N depending on whether you appear in the ITSS register
  • Reason for access is required whether or not you are ITSS

4.4. Affiliations

In addition to attributes, CUD stores affiliations, which reflect the relationship of a person with the University.

CUD models an unlimited number of as affiliations with the following components:

  • Status (coarse grained)
  • Unit
  • Source
  • Start date
  • End date
  • Date last updated

Primary data systems have different status codes and different codes/acronyms for units

Status codes are stored “as-is” and not decoded, is there is no status it is stored as “unknown”

Unit codes are stored as received from the primary data system, but an attempt is also made to map them to a common acronym and name, so a single affiliation (from University Card) is stored in different forms:

  • MC@EN
  • MC@Computing Services

CUD exposes affiliations in the form current_affiliations for convenience. It lists units with which a person has a current affiliation from any source

  • Status is not listed
  • Start, end and last updated dates not exposed
  • Easy to search
  • Easy to consume

CUD also exposes affiliations in the form scoped_affiliation where additional data is required. This includes all data held for an affiliation

  • For “flat” format (e.g. a CSV) the elements are concatenated with ; delimiters
  • Where there are multiple affiliations this can become difficult to process!
  • For “structured” formats elements are in a defined structure and so easier to process
  • Scoped_affiliation includes past, current, and (potentially) future affiliations

Affiliations can be considered part of the CAS, since all registered CUD users are able to view them. In many cases start and end dates not specifically included in the CAS are available as a component of an affiliation.

4.5. Data formats available

CUD supports the following data formats on interfaces:

  • XML
  • JSON
  • CSV
  • SQL
  • LDAP

Person records can be constructed with as “flat” or “structured”:

  • “Flat”: not very rich, lacks metadata, can be hard to interpret
  • “Structured”: rich, includes metadata, easier to interpret but requires processing on the client-side

The following table shows which data formats and structures are supported on which interfaces.

Table 5. Interface Data Formats
Interface Data format Flat Structured
  • You are encouraged to use the CUD UI to view the different data formats and structures in order to determine which is best for a specific purpose.