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.

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