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

Ed-Admin Integration with ADAM

The Ed-Admin module is not enabled by default and it will need to be enabled before it can be used. To enable the integration, please navigate to Administration → Site Administration → Edit site settings and click on the Custom Modules tab. Enter the module name edadminsync 

If there are existing custom modules enabled, leave a space between existing modules and this module name. The order of the custom modules, if there is more than one, does not matter. Click on Save Settings to save these settings.

Configuring the Integration

Navigate back to the Site Settings: Administration → Site Administration → Edit site settings and click on the Custom Modules tab. A set of settings will appear beneath the Ed-Admin Sync header:

The settings are discussed below:

Once done, click on Save Settings.

Setting Up Grade Definitions

Grade definitions are an important step that allows ADAM to understand which grades the pupils belong to. This is not always obvious to tell because Ed-Admin allows grades to include campus definitions and more which can be confusing to ADAM.

Navigate to Administration → Import & Export → Perform Ed-Admin Sync.

Click on the option to “Perform synchronisation check for Grades”.

ADAM will query the Ed-Admin database to find a list of all grades that are in use. It will then show these grades with corresponding drop-down options next to each. Please choose the grade that ADAM should apply to those descriptors.

Note: The order that the grades appear in will vary from server to server. Please be careful in case the order is not sequential.

Once done, click on the Save button at the bottom of the page.

It is recommended to check your Grade settings before doing a synchronisation.

Running a Manual Synchronisation

Navigate to Administration → Import & Export → Perform Ed-Admin Sync.

Choose whether to import Staff or Pupils by clicking on the appropriate button to begin the process:

If you do not see these buttons, and rather only see the option to “Perform a synchronisation check for Grades”, then you must complete this step first. Instructions are above.

A list of pupils or staff will appear. Use the options at the top of the list to select which pupils or staff should be synchronised. If no pupils or staff can be retrieved from Ed-Admin, a warning will appear:

If this happens, check your settings and try again.

In spite of the tick boxes at the top, pupils/staff can be individually selected/deselected from the list for synchronisation.

Click on Synchronise Information to begin the process of pulling the information into ADAM.

Changes in the Change Log

ADAM stores all changes to pupil and staff information in the change log. By conducting a synchronisation with Ed-Admin, the changes will be logged against the current user who will appear, in terms of that log, to be the user who made the changes.

Google Integration with ADAM

@todo

Moodle Integration with ADAM

Please see the separate section on Moodle Integration.

Papyrus Integration with ADAM

ADAM is able to integrate with the cloud-based library management system, Papyrus.

ADAM first needs to be configured to allow Papyrus access to the data in its database.

Create an API Key

Follow the instructions for creating a new API Key.

The API Key will need access to all the following end-points. Use the “Ctrl” button on your keyboard while you click on each of them.

Create Data Query Secrets

Two DataQuery Secrets need to be created: one for staff, and one for pupils. The secrets must all be associated with the API Key that you created in the first step.

The fields required by Papyrus are:

Configuring Papyrus

Before you can configure Papyrus, please make sure you have completed the steps above. You will need your ADAM server’s URL address, the API token you generated, and the two secrets generated above. With this information in hand, contact Papyrus for instructions on how and where to enter this information.

Wonde Integration with ADAM

Wonde provides a go-between platform to synchronise information from ADAM to a variety of other service providers. In order to achieve this, Wonde needs to be given permissions to view and access the data in your ADAM database. Wonde needs access to the ADAM API in order to retrieve information from the database.

Create an API Key

Navigate to Administration → Security Administration → Manage API Tokens. Click on the option to Add new API Token:

The API Key will need access to all the following Resources. Use the “Ctrl” button on your keyboard while you click on each of them.

In the Notes field, put the text “Wonde Integration”.

Click on the Save Token button.

Once saved, your API Token list should include and entry like this. The most important part is to ensure that the list of resources is identical as shown:

Create Data Query Secrets

You must add the API Token (above) before you can proceed.

Three Data Query Secrets need to be created: one for staff, one for pupils and one for families. These allow access to specific fields. Navigate to Administration → Security Administration → Manage Data Query API Fields.

The following steps need to be repeated three times.

Click on Add a new set of fields.

Ensure that the API Token shows the same “Wonde Integration token that you created in the first step.

Each of the three secrets that you create will use a different data source. The first will be Current Pupils, the second will be Current Families and the third will be Current Staff.

Put “Wonde Integration” as your Comment and then click on Add Record.

You will then see all the fields related to the data source that you chose. Here, we have fields relating to families:

At the bottom of this list, click on “Show additional fields”. Some greyed fields will appear in the list.

Tick all the fields so that Wonde has access to all the information (NB: for family information, don’t tick the pupil fields that appear at the bottom - this is unneeded - and similarly, for pupils, don’t tick family information that appears at the bottom):

Click on Save Details at the bottom of the list.

The data source and secret now appear in the list. Repeat these steps for the other two data sources.

Information to Share with Wonde

You need to give Wonde the following information:

People who have access to this information will have access to all personal and private information that is stored about your pupils, families and staff members. It is therefore strongly recommended that you transmit this information to Wonde using secure means and, specifically, we strongly recommend that you do not share this information by email.

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.

SportCap Integration with ADAM

SportsCap is a sports and fixture management system for schools with direct integration to the SA Rugby “BokSmart” system. SportsCap can pull information directly from ADAM to populate its database.

Requirements: