CUD REST query examples

The REST interface user guide has some further examples, but some simple queries are provided below.

Prerequisites are that you have:

  • a CUD service principal
  • created a keytab
  • curl installed on your server. 

Example query

This example query searches for everyone that currently has an affiliation to your unit. 

If you run the query in the CUD UI (User Interface), below the results you will see some information text: Query Used.  This is always a very useful starting point when constructing any query that you might intend to use to query CUD via the REST interface, such as to query used:cud\:cas\:current_affiliation:lady (the backslashes are required for the REST query).

 

On your server, at the command line:

KRB5CCNAME=cudprincipalcache; kinit cud/<server>.<unit>.ox.ac.uk@OX.AC.UK -k -t <PathToKeytab>/<keytabFile>

Run an empty query:

curl --negotiate -u : 'https://ws.cud.ox.ac.uk/cudws/rest/search/person?q='

And the output is:

cud:cas:cudid,cud:cas:title,cud:cas:firstname,cud:cas:lastname,cud:cas:known_as,cud:cas:oxford_email,cud:cas:sso_username,cud:fk:university_card_sysis,cud:fk:opendoor_staff_number,cud:fk:oss_student_number,cud:cas:university_card_status,cud:cas:internal_tel,cud:cas:external_tel,cud:cas:scoped_affiliation

 

Now with an actual query:

curl --negotiate -u : 'https://ws.cud.ox.ac.uk/cudws/rest/search/person?q=cud\:cas\:current_affiliation:lady'

And, all being well, you should get the full results set written to the terminal window. Better to redirect to a file:

curl --negotiate -u : 'https://ws.cud.ox.ac.uk/cudws/rest/search/person?q=cud\:cas\:current_affiliation:lady' > results.csv

More options

Note that there are default fields included in the output (see the empty query, above) and that the default output is csv.  These can be changed,  but for now this page is just looking at some examples to get you started.

The AND and OR operators are available:

curl --negotiate -u : 'https://ws.cud.ox.ac.uk/cudws/rest/search/person?q=cud\:cas\:lastname:Bloggs AND cud\:cas\:firstname:Joe'  >  results.csv

Combine with brackets to limit your results further:

curl --negotiate -u : 'https://ws.cud.ox.ac.uk/cudws/rest/search/person?q=cud\:cas\:lastname:Bloggs AND (cud\:cas\:firstname:Joe OR cud\:cas\:firstname:Kate)' > results.csv

 

If you have access to the University Card end-date attribute, you can query for date ranges, but you will need to escape the square bracket range limiters.

curl --negotiate -u : 'https://ws.cud.ox.ac.uk/cudws/rest/search/person?q=cud\:uas\:universitycard_comp_date:\[NOW TO *\]'  >  results.csv

That query returns everyone with a current university card so you may not want to run that query! Not without some extra parameters, anyway, to cut down the number of results. 

Get support


Local IT support provide your first line of on-the-spot help

FIND MY LOCAL IT TEAM

 

Common requests and fault reports can be logged using self-service

   USE IT SELF-SERVICE    

   LOG A SUPPORT CALL    

VIEW MY SUPPORT CALLS  

The central Service Desk is available 24x7 on +44 1865 6 12345

 

If you do not have an SSO account you can use this form to contact the Service Desk