iSAMS API

The existing iSAMS Batch API key is also used as the Batch OAuth client ID. You do not need to replace the existing key for this change.

Before configuring the connector, obtain:

• School Data Endpoint Host
• Batch OAuth Client ID — your existing Batch API key
• Batch OAuth Client Secret — a school-specific secret provisioned with the apiv1 scope

The Batch OAuth credentials are separate from the optional iSAMS REST API credentials used to import high-resolution profile photos. Do not enter the REST API client ID or secret in the Batch authentication fields.

1. Log in to your iSAMS account.

2. Go to Control Panel Home > External Web Services > API Services Manager.

3. Select 'Request Batch API Key'.

4. Enter the following details:

• Integrator Name: Schoolbox Pty Ltd
• Product Name: Schoolbox

If the details are accurate, you should receive a support email from iSAMS via Zendesk.

6. Follow the link in the email.

7. Request your API key. Provide iSAMS with the following list of nodes required:

• Estate Manager Datasets
  • All Buildings & Rooms
• HR Manager Datasets
  • Current Staff
  • Current Staff - Photos
• Pupil Manager Datasets
  • Current Students
  • Current Students - Health
  • Contacts
  • Current Students - Photos
• School Manager Datasets
  • Academic Houses
  • School Divisions
  • School Forms
• SEN Manager Datasets
  • SEN Register
  • SEN Types
• Teaching Manager Datasets
  • Teaching Sets
  • Teaching Set Lists
• Timetable Manager Datasets
  • Published Timetable Schedule
  • Timetable Week Allocations
  • Weeks, Days & Periods

You can manage the iSAMS API connector.

To do this, as a Superuser:

1. Go to Administration > School Data Import > Home.
2. In Data Source, select iSAMS.
3. In School Data Endpoint Host, enter your school data endpoint host.

   Note: The address is usually in the format {your_school}.isams.cloud/api/batch/1.0. Do not include https://, as this will cause the importer to fail.

4. In Import Frequency, select how often Schoolbox should import data.

   Note: This should match the cache timeout in iSAMS. The default cache timeout is 24 hours. Until the cache expires, iSAMS will continue sending the previously cached data to Schoolbox.

   It is recommended that an import runs after midnight and finishes before the scheduled User Provisioning System run. You can run another import before the school day starts to retrieve timetable changes, and another after working hours to retrieve changes made by SIS administrators.

5. In Import Timeout, enter the import timeout.

6. Under iSAMS Configuration, configure the following sections:

   1. Batch API Authentication

      • In Batch OAuth Client ID (previously Batch API Key), enter your existing Batch API key.
      • In Batch OAuth Client Secret, enter the school-specific client secret provisioned with the apiv1 scope.

   2. REST API Profile Photos

      Optionally enter the REST API Host, REST OAuth Client ID, and REST OAuth Client Secret to import higher-quality profile images.

      These credentials are separate from the Batch API credentials.

   3. Import Settings

      • Use Day Number Offset to correct the displayed iSAMS day where necessary. Select 0 when no adjustment is required.
      • In Parent, enter the contact types that Schoolbox should identify as parents, separated by commas. Leave the field blank to identify all contact types as parents.
7. Select Save.

You have now managed the iSAMS API connector.

Schoolbox gives you more control over how you import data using School User Data Store (SUDS) from an API connector into Schoolbox. You can now import specific groups of data - like user profile data, timetable data - separately, instead of all at once.

This will help you when you want to make small updates or test new data without affecting everything in your system.

To perform an update of your SUDS data from an API connector:

1. First, ensure you have enabled school data import for your school. See Managing the School User Data Store (SUDS). 
    
2. Next, go to Administration > School Data Import > Home.
   This opens the school data import home page for you. 
    
3. Then, select the 3-dot menu iconand select one of the following:
   • Update user data and timetables
   • Update user data only
   • Update timetable only
4. For each, select Save to proceed with the import.
    
5. Next, in Daily Org Import Time, enter the specific time of day when you want your school’s timetable data to be automatically imported into Schoolbox from your external system.
   Note: This runs every day of the week.
   This scheduled import ensures that any timetable updates made in your source system are reflected in Schoolbox each day.
   Timetable data updates are not immediate. They typically take around 15–20 minutes to appear in Schoolbox, though in some cases, it may take longer.
   Note: This field only affects the import of timetable data.
    
6. To view your current endpoint status and the status of previous imports, scroll beyond the API configuration:
    
7. Select 'current endpoint status' for a detailed view of the status of each endpoint and node as required.
   Note: The 'Previous Imports' section will vary based on the SIS and API configuration used. 

Before you begin, ensure that you have access to create SSO clients within iSAMS Authentication.

To configure an iSAMS SSO client for Schoolbox:

1. Create a new SSO client in iSAMS:
   1. Go to Authentication.
   2. Select Manage SSO Clients.
   3. Select Create SSO Client.
       
2. Configure the client details:
   1. Select the Details tab.

   2. Enter the following values:

      Client ID	schoolbox.isams
      Client Name	Schoolbox Auth Client
      Client URL	<Your Schoolbox domain>
      Login Screen	iSAMS Parent Portal
      Backchannel Logout URI	blank
      Access Token Type	Reference

      
      Note: Replace Your Schoolbox domain with the URL used to access your Schoolbox site.
       

3. Configure the scopes:
   1. Select the Scopes tab.
   2. Add the following scopes:
      • openid
      • email
      • profile
         
4. Configure the redirect URIs:
   1. Select the Whitelist URIs tab.

   2. Add the following values:

      Allowed Post Login Redirect URI	<Your Schoolbox domain>/login/oidc
      Allowed Post Logout Redirect URI	<Your Schoolbox domain>

       

5. Save the client:
   1. Select Save & Close.
   2. Record the generated Client ID and Client Secret.

Important: The Client Secret is only displayed when the client is first created and cannot be viewed again later. Record it before closing the window.

You've now created an iSAMS SSO client for Schoolbox. Use the generated Client ID and Client Secret when configuring the iSAMS authentication provider in Schoolbox.