IT Services

CUD Interfaces

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

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:

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:

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

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:

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:

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: 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):

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

To: 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:

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: 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:

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:

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:

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

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

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:

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

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

Table 5. Interface Data Formats
Interface Data format Flat Structured