It is sometimes necessary to use the JSS's RESTful API in order to automate changes to computer records. This page will help you to understand how this works, using an example.
The JSS at https://jss.orchard.ox.ac.uk features a full-featured RESTful API to allow programmatic interaction with the database. A good primer on how you can make use of it with Bash or Python can be found at:
The JSS API for Everyone
You may also view the official resource documentation for the Orchard JSS at:
JSS REST API Resource Documentation
What follows is an example in Bash of how one might use the API to GET and PUT computer records.
The Department of Computer Science have two labs of 20 computers each which all run VMWare Fusion with a single key, which is changed every year as they upgrade to a new major version. The installer for VMware Fusion in the Orchard Software Centre has a postinstall_script which reads the key from the computer's record in the JSS and serialises it accordingly. One could simply go through each computer record via the web GUI and update the key each time a new major version is released, but this is quite tiresome, and so the JSS API comes to the rescue!
You will need an account with at least read permissions for the objects you wish to access in the JSS in order to use HTTP GET commands, and one with at least write permissions to use HTTP POST, and update permissions to do HTTP PUT. The Orchard model is to have two separate accounts, one for reading and one for writing, to ensure that scripts that are only supposed to read do not accidentally write data. The Orchard team will be happy to create these accounts for you on request.
N.B. For the sake of this example I will assume you are using a Mac, obviously if you wish to use a different platform you may need to modify things such as the paths to your binaries.
First we need to set some variables:
1 # Variables 2 JSS_URL="jss.orchard.ox.ac.uk" 3 API_URL="https://${JSS_URL}/JSSResource" 4 READ_USER="apireadonly" 5 READ_PASS="xxxxxxxxxxx" 6 WRITE_USER="apiwriteonly" 7 WRITE_PASS="xxxxxxxxxxx" 8 VMWARE_SN="XXXXX-XXXXX-XXXXX-XXXXX-XXXXX" 9 VMWARE_VERS="9.x" 10 GROUP_ID="503" 11 SN_EA_ID="19" 12 SN_EA_NAME="VMware Fusion Serial Number" 13 #VERS_EA_ID="" 14 #VERS_EA_NAME="" 15
16 # XML blob to put 17 read -r -d '' XML_BLOB <<EOF 18 <?xml version="1.0" encoding="UTF-8"?> 19 <computer> 20 <extension_attributes> 21 <extension_attribute> 22 <id>${SN_EA_ID}</id> 23 <name>${SN_EA_NAME}</name> 24 <type>String</type> 25 <value>${VMWARE_SN}</value> 26 </extension_attribute> 27 </extension_attributes> 28 </computer> 29 EOF
30 # curl_get takes one argument: 31 # $1: the api resource to get 32 curl_get() { 33 /usr/bin/curl --silent \ 34 "${API_URL}/${1}" \ 35 --user "${READ_USER}:${READ_PASS}" 36 } 37 # curl_put takes two arguments: 38 # $1: the api resource to put 39 # $2: the data to put 40 curl_put() { 41 /usr/bin/curl --silent \ 42 -H "Content-Type:text/xml" \ 43 -X PUT \ 44 -d "${1}" \ 45 "${API_URL}/${2}" \ 46 --user "${WRITE_USER}:${WRITE_PASS}" 47 } 48 # xmllint_cmd takes one argument: 49 # $1: the xml to lint 50 xmllint_cmd() { 51 echo "${1}" | /usr/bin/xmllint --format --recover - 2> /dev/null 52 } 53 # xpath_cmd takes two arguments: 54 # $1: the xml to lint 55 # $2: the xpath expression 56 xpath_cmd() { 57 echo "${1}" | /usr/bin/xmllint --format --recover --xpath "${2}" - 58 }
59 # GET the XML representation of the group 60 group_xml=$(curl_get "computergroups/id/${GROUP_ID}") 61 # Retrieve the computer ids as a string 62 computer_ids=$(xpath_cmd "${group_xml}" "//computers/computer/id")
63 # Parse the id numbers out of the string and attempt to PUT the data to each computer record 64 for i in $(echo "${computer_ids}" | sed -e 's!<id>!!g' -e 's!</id>! !g') ; do 65 result=$(curl_put "${XML_BLOB}" "computers/id/${i}") 66 [[ $? -eq 0 ]] || { echo "ERROR: curl returned nonzero exit code $? after attempting to PUT data with REST API."; exit 1; } 67 [[ $result =~ ^\<\?'xml version'\=.+\<computer\>\<id\>[[:digit:]]+\</id\>\</computer\>$ ]] || { echo "ERROR: Unexpected response from JSS after attempting to PUT data with REST API: ${result}"; exit 1; } 68 69 echo "SUCCESS: Computer record with id ${i} updated" 70 done
