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:
- Enable Automatic Ed-Admin Sync: This will cause ADAM to syncrhonise data automatically from Ed-Admin at an interval determined by the Ed-Admin Sync Frequency interval. To start with, it is strongly recommended that schools leave this to “No” until they have conducted a few manual synchronisations are are happy that the process is working.
- Ed-Admin Server Hostname: ADAM needs to communicate with your Ed-Admin server and so it needs to know where it is. The host name is its address on the internet. Do not enter any “https://” prefix, or any trailing slashes.
- Ed-Admin Server API Key: Your Ed-Admin server will have a special password that can be used by APIs to communicate with your Ed-Admin database and get information. ADAM will need to know what that API Key is for it to communicate with Ed-Admin. It is a long string of random letters. Copy and paste it into this box.
- Ed-Admin Sync Frequency: If you’ve chosen automatic sync in the first setting, ADAM will use this setting to determine how often it should check for updates. This setting is ignored if automatic synchronisation is disabled.
- Ed-Admin Sync Threshold: Large and sudden changes to your database can often mean that something has been misconfigfured. As a security precaution, ADAM will check this threshold to ensure that it is not going to remove data in error. This number is treated as a percentage and ADAM must find at least 80% of its current students returned in the Ed-Admin data set. If there is fewer, it means the change is too large and ADAM ignores the update, thinking it is suspicious. The manual update ignores this setting on the understanding that you know what you’re doing!
- Ed-Admin Campuses: If you are limiting your synchronisation to one or more campuses, you can enter these here, comma separated. For staff, they must have one of these values either as their campus value, or as one of their “Areas of Work”. This allows staff to feature in multiple campuses, if required.
- Ed-Admin Match Method: Consult ADAM support for the best value that will work for your school. The default, Internal ID, is almost never a good idea if you only started synchronising data later, once the two databases ADAM and Ed-Admin were both fully established.
- Ed-Admin Grade Definitions: While there is a field here that can be manually edited, please rather see the section below on Setting up Grade Definitions.
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.
- APIRequests/test/get
- DataQuery/get/get
- Pupils/image/get
- Staff/image/get
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:
- Pupils
- Admin Number
- Last Name
- Preferred Name
- Date of Birth
- Age Group
- Grade
- Staff
- Admin Number
- Last Name
- First Name
- Full First Name
- Title
- Gender
- Initials
- Position
- Department
- Appointment Nature
- Teaching Subjects
- Email Address
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
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.
- DataQuery/get/get
- FamilyRelationships/gamily/get
- Pupils/image/get
- Staff/image/get
- XDevMan/currentpupils/get
Create Data Query Secrets
Three DataQuery Secrets need to be created: one for staff, one for pupils and one for families. The secrets must all be associated with the API Key that you created in the first step.
Tick all the fields so that Wonde has access to all the information.
Information to Share with Wonde
You need to give ADAM the following information:
- Your ADAM server URL where you log in (e.g. https://demo.adam.co.za/)
- The API Key that you created in the first step
- The three Data Query Secrets that you created in the second step.
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:
- In “Site Settings”, under the “Third Party Integration” settings, look for the “SOCS” section.
- 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.
- 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.
- Save these changes.
- 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:
- Your server’s ADAM address. For example:
http://demo.adam.co.za
- Next you add the following text to the URL, exactly as it appears:
/api/socs/socs.xml.php?k=
- 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:
- An API Token that allows access to the three DataQuery endpoints:
- DataQuery/get/get
- DataQuery/getone/get
- DataQuery/getsince/get
- Two DataQuery Secrets both linked to the API Token above, one for Pupils and the other for Staff. The fields required are:
- Pupils:
- ADAM Idenfitier (click “show additional fields”)
- Last Name
- Preferred Name
- Date of Birth
- Gender
- ID Number
- Population
- Staff:
- ADAM Identifier (click “show additional fields”)
- Last Name
- First Name (Preferred)
- Gender
- Population
- ID Number
- Birth