Interacting with the JSS API

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.

Background

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.

Example

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 can make this much easier. The below example uses curl to do this, but you can and should do this any way you are most comfortable.

N.B. 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.

1. First find out the ids and names of the extension attributes you wish to modify. To do this, pull down the list of computer extension attributes using e.g. curl --user "$USER:$PASS" https://jss.orchard.ox.ac.uk/JSSResource/computerextensionattributes | xmllint -format - which will give you a list like:

   <?xml version="1.0" encoding="UTF-8"?>
   <computer_extension_attributes>
     <size>80</size>
     <computer_extension_attribute>
       <id>44</id>
       <name>Asset number</name>
     </computer_extension_attribute>
     ...
   </computer_extension_attributes>
   

2. Find the extension attributes you wish to change. In this example it would be the extension attributes with id 19 and name "Software: VMware Fusion Serial Number"

3. Load the xml you wish to modify into a variable e.g. with bash:

   read -r -d '' XMLBLOB <<EOF
   <?xml version="1.0" encoding="UTF-8"?>
   <computer>
     <extension_attributes>
       <extension_attribute>
         <id>19</id>
         <name>Software: VMware Fusion Serial Number</name>
         <value>XXXXX-XXXXX-XXXXX-XXXXX-XXXXX</value>
       </extension_attribute>
     </extension_attributes>
   </computer>
   EOF
   

4. If you have a group containing the computers you wish to modify, you can get the ids for all the computers it contains by doing a curl GET on the group id. You can find the group id by accessing the group in the JSS and the URL will have an id number in it e.g. https://jss.orchard.ox.ac.uk/smartComputerGroups.html?id=478&o=r&nav=c the group id is 478. The following command would get the group represented as XML from the API: curl --user "$USER":"$PASS" https://jss.orchard.ox.ac.uk/JSSResource/computergroups/id/478 which will return something like this:

   <?xml version="1.0" encoding="UTF-8"?>
   <computer_group>
     <id>478</id>
     ...
     <computers>
        <computer>
            <id>000</id>
            <name>Test Computer</name>
            ...
        </computer>
        ...
      </computers>
      ...
   </computer_group>
   

5. Extract the computer ids by whatever means you like (manually, xpath, sed etc.) and then run a for loop through the list of ids updating the record with your XMLBLOB e.g.

    for computer_id in $COMPUTER_IDS do
      echo XMLBLOB | curl --user "$USER:$PASS" -T - --request PUT "https://jss.orchard.ox.ac.uk/JSSResource/computers/id/$computer_id"
    done
   

   Note the JSS should return a tiny xml blob with just the computer's id in it if successful (which you could use for error checking if you so desired)