ADAM

Third Party Integration

API Integration with ADAM

ADAM provides a RESTful JSON API which technical users can make use of. For more information, please see the dedicated section discussing the API.

Clever Integration with ADAM

@todo

Google Integration with ADAM

@todo

Moodle Integration with ADAM

Please see the separate section on Moodle Integration.

SOCS Integration with ADAM

SOCS is an online co-curriculum and calendar management system that many schools use to manage sports fixtures and programmes. ADAM is able to make information available to SOCS in their required format.

SOCS Export

To get the exports working, you will need to do the following:

  1. In “Site Settings”, under the “Third Party Integration” settings, look for the “SOCS” section.
  2. For the secret key, set a long random string of characters. We recommend at least 20 characters. This does not need to be memorable since you will never need to type this in. Here is a website that can help you generate a string of random characters.
  3. If you have sports houses captured as classes in ADAM, configure the subject as needed. If you don’t, and if your pupils’ houses are not important, you can leave this as your default registration class.
  4. Save these changes.
  5. Send the URL to your SOCS export to your SOCS contact. The URL is described in more detail below.

The SOCS URL

You need three components to make up the URL:

  1. Your server’s ADAM address. For example:

http://demo.adam.co.za

  1. Next you add the following text to the URL, exactly as it appears:

/api/socs/socs.xml.php?k=

  1. Finally you add your secret key (please don’t add this one!):

abcdefghijklmnopqrst

Your final URL will look like this:

http://demo.adam.co.za/api/socs/socs.xml.php?k=abcdefghijklmnopqrst

Test your link by copying and pasting it into the address bar of your web browser. You should see output that looks similar to this:

<Pupils>
 <Pupil>
   <Firstname>John</Firstname>
   <Middlenames>James</Middlenames>
   <Knownname>John</Knownname>
   <Surname>Doe</Surname>
   <Initials>JJ</Initials>
   <Gender>M</Gender>
   <YearGroup>10</YearGroup>
   <Formname>Grade 10</Formname>
   <Housename>Blue House</Housename>
   <EmailAddress>pupil_1754@adam.co.za</EmailAddress>
   <UniquePupilIdentifier>55012</UniquePupilIdentifier>
 </Pupil>
 <Pupil>
   ...

If, however, you simply see this:

<Pupils/>

… it indicates that your secret key has not been recognised.

If you get any other error (notably, a “404 – Not Found” error), that will indicate that your URL is incorrect.

Once you have verified that your URL works, send this to your SOCS representative and they will provide further information on how to perform synchronisations from within the SOCS portal.

Pupil Identification to SOCS

ADAM will use the pupil’s “administration number” as configured in their profiles to uniquely identify a pupil to SOCS. If the administration number changes, then SOCS will treat this as a new pupil having entered the school and the previous one of having left.

Notably, if you’ve been using SOCS before, the admin numbers that were in use must match otherwise the pupils won’t match and historical information will be lost! The synchronisation process will assume that the pupils are new pupils and will delete the pupils it can’t match.