Search Google Appliance

Home >> Accounts >> Core User Directory >> CUD REST Query Examples

CUD REST Query Examples

The REST Interface user guide does also have some examples too, but some simple queries are shown here for starters.

Prerequisites

  • You have a CUD service principal
  • You've created a keytab
  • You have 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.

E.g.   Query used:cud\:cas\:current_affiliation:lady

Note the backslashes: they will be 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. 
 
 

Written by IT Services. Latest revision 20 February 2017