• Diff for "JSSAPI"
Last updated at 2016-10-18 15:15:02 by ouit0354
Differences between revisions 2 and 3
⇤ ← Revision 2 as of 2016-04-07 14:49:43 →
Size: 4740
Editor: ouit0354
Comment:
← Revision 3 as of 2016-04-07 16:11:37 → ⇥
Size: 2895
Editor: ouit0354
Comment:
Deletions are marked like this. Additions are marked like this.
Line 20: Line 20:
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! 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.
Line 22: Line 22:
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. 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.
Line 24: Line 24:
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:

{{{#!highlight bash start=1
# Variables
JSS_URL="jss.orchard.ox.ac.uk"
API_URL="https://${JSS_URL}/JSSResource"
READ_USER="apireadonly"
READ_PASS="xxxxxxxxxxx"
WRITE_USER="apiwriteonly"
WRITE_PASS="xxxxxxxxxxx"
VMWARE_SN="XXXXX-XXXXX-XXXXX-XXXXX-XXXXX"
VMWARE_VERS="9.x"
GROUP_ID="503"
SN_EA_ID="19"
SN_EA_NAME="VMware Fusion Serial Number"
#VERS_EA_ID=""
#VERS_EA_NAME=""
}}}
{{{#!highlight sh start=16
# XML blob to put
read -r -d '' XML_BLOB <<EOF		  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:
 {{{#!highlight xml numbers=off
Line 48: Line 29:
<computer>
  <extension_attributes>
    <extension_attribute>
      <id>${SN_EA_ID}</id>
      <name>${SN_EA_NAME}</name>
      <type>String</type>
      <value>${VMWARE_SN}</value>
    </extension_attribute>
  </extension_attributes>
</computer>
EOF
}}}
{{{#!highlight sh start=30
# curl_get takes one argument:
# $1: the api resource to get
curl_get() {
  /usr/bin/curl --silent \
                "${API_URL}/${1}" \
                --user "${READ_USER}:${READ_PASS}"
}
# curl_put takes two arguments:
# $1: the api resource to put
# $2: the data to put
curl_put() {
  /usr/bin/curl --silent \
                -H "Content-Type:text/xml" \
                -X PUT \
                -d "${1}" \
                "${API_URL}/${2}" \
                --user "${WRITE_USER}:${WRITE_PASS}"
}
# xmllint_cmd takes one argument:
# $1: the xml to lint
xmllint_cmd() {
  echo "${1}" | /usr/bin/xmllint --format --recover - 2> /dev/null
}
# xpath_cmd takes two arguments:
# $1: the xml to lint
# $2: the xpath expression
xpath_cmd() {
  echo "${1}" | /usr/bin/xmllint --format --recover --xpath "${2}" -
}
}}}
{{{#!highlight sh start=59
# GET the XML representation of the group
group_xml=$(curl_get "computergroups/id/${GROUP_ID}")
# Retrieve the computer ids as a string
computer_ids=$(xpath_cmd "${group_xml}" "//computers/computer/id")
}}}
{{{#!highlight sh start=63
# Parse the id numbers out of the string and attempt to PUT the data to each computer record
for i in $(echo "${computer_ids}" | sed -e 's!<id>!!g' -e 's!</id>! !g') ; do
  result=$(curl_put "${XML_BLOB}" "computers/id/${i}")
  [[ $? -eq 0 ]] || { echo "ERROR: curl returned nonzero exit code $? after attempting to PUT data with REST API."; exit 1; }
  [[ $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; }

  echo "SUCCESS: Computer record with id ${i} updated"
done
}}}		 <computer_group>
  <id>478</id>
  ...
  <computers>
     <computer>
         <id>000</id>
         <name>Test Computer</name>
         ...
     </computer>
     ...
   </computers>
   ...
</computer_group>}}}

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:

You may also view the official resource documentation for the Orchard JSS at:

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>
Orchard is a close co-operation of
JOIN US