2. Parameters

As mentioned earlier, parameters are included in the query string. These should be URL-encoded (there are plenty of free URL-encoding utilities available both on and off the web).

Allowed parameters are as follows:

2.1. q

This is the parameter describing the Solr query, and is the only mandatory parameter.

Legal values are empty (no data will be returned), or a legal Solr query.

2.1.1. Example Request Parameters

An example of the Solr query "cud\:cas\:sso_username:unit1234", when encoded:

q=cud%5C:cas%5C:sso_username:unit1234

The Solr query "cud\:cas\:sso_username:unit1234 AND cud\:cas\:current_affiliation:oucs", when

encoded:

q=cud%5C:cas%5C:sso_username:unit1234%20AND%20cud%5C:cas%5C:current_affiliation:oucs

2.2. fields

The fields parameter allows the requestor to reduce the set of values returned for each record to only those attribute fields that are specified.

Legal values are a comma-separated list of attribute names.

2.2.1. Example Request Parameters

The fields parameter used to specify the Oxford email and CUD ID

("cud:cas:oxford_email,cud:cas:cudid"):

q=cud%5C:cas%5C:sso_username:oucs0098&fields=cud:cas:oxford_email%2Ccud:cas:cudid

2.3. format

The format parameter in CUD queries is optional, and specifies the format in which the requested data will be returned. It may be omitted, in which case the default 'csv' format will be used.

Legal values are 'csv' (the default), 'xml', 'json', or 'text'. If 'text' is chosen you can optionally set the 'delimiter' and 'qualifier' parameters to further customise the output (See below).

2.3.1. Example Request Parameters

The format parameter being used to specify data returned as XML:

q=cud%5C:cas%5C:sso_username:unit1234&format=xml

2.4. delimiter

The delimiter parameter in CUD is optional, and only relevant when the 'text' format is used. For other formats this parameter will be ignored. The first character of the value set for this parameter will be used as the field delimiter. If the text format is set, and this parameter is omitted, a comma will be used as the delimiter.

2.4.1. Example Request Parameters

The text format using a specific delimiter ("|"):

q=cud%5C:cas%5C:sso_username:unit1234&format=text&delimiter=%7C

2.5. qualifier

The qualifier parameter in CUD is optional, and only relevant when the 'text' format is used. For other formats this parameter will be ignored. The first character of the value set for this parameter will be used. The purpose of this parameter is generally to escape the field. If the text format is set, and this parameter is omitted, no additional qualifier will be used.

2.5.1. Example Request Parameters

The text format using a specific delimiter ("|") and qualifier ("@"):

q=cud%5C:cas%5C:sso_username:unit1234&format=text&delimiter=%7C&qualifier=@

2.6. history

The history parameter in CUD queries is optional, and indicates whether you wish the response to contain historical values for attributes and affiliations. You should only request this if it is required, and the default is not to include history. Include history if you wish are requesting data in XML or JSON format and wish it to be richly structured (see the CUD UI User Guide for further details).

Legal values are 'y', 'n' or omitted entirely.

2.6.1. Example Request Parameters

The history parameter used to request historical data in an XML format:

q=cud%5C:cas%5C:sso_username:unit1234&format=xml&history=y

Up: Contents Previous: 1. Introduction Next: 3. Prerequisites