Salamander for Apple School Manager Support

The Salamander for Apple School Manager Utility is a Windows Application designed to collect data from school MIS/SIS systems, process it into CSVs suitable for use with the Apple School Manager service and send those files to the Apple School Manager service for processing.


Current Version 1.5.0.0
Version Date 17th October 2019
Supported MIS/SIS Systems This version supports the following MIS/SIS systems:

SIMS.Net
Facility CMIS
Progresso
WCBS Pass
Engage by DoubleFirst
iSAMs
Bromcom
Arbor
SchoolBase
ScholarPack
RM Integris

Others added on request

Download Please contact asm@salamandersoft.co.uk to get a copy of the utility.

Apple, Apple School Manager, iCloud, iTunes U, iPad, Apple ID are trademarks of Apple Inc., registered in the U.S. and other countries.

v1.5.0.0 adds the following:

Support for defining the Password Policy
Previous versions output the Password_Policy field for students as ‘4’. The new release supports, ‘4’, ‘6’ and ‘8’.
The default remains at ‘4’

Changes the encoding of the output CSV files to UTF-8
The CSV Files outputted are now encoded using UTF-8

v1.4.0.0 was released on 30th July 2019

Location name prefix option
The ability to add a prefix to the ‘location_name’ pushed to ASM has been added. This is to allow the user to set a location which is more easily differentiated from the main location applied by ASM by default. The ‘location_id’ is unchanged.

Fix for issue with Bromcom support where a student had more than 1 nationality
Previously a student record was being provided per nationality. This has been rectified.

Fix for an issue with Bromcom detecting multiple ‘schools’
Improvements have been made to the way schools are detected and loaded from Bromcom.

Support for RM Integris
This version adds support for RM Integris via their REST API.

Support for ScholarPack
This version adds support for ScholarPack.

 

v1.3.0.0 was released on 1st March 2019 and added the following:

SchoolBase Support
Support for extracting data from locally hosted instances of SchoolBase has been added.

Support for reading the ‘Home’ Email address from SIMS
Previous versions could only read the ‘Work’ Email address from SIMS. This feature adds the ability to pull the ‘Home’ Email address instead.

Support for Progresso REST API
This version adds support for Progresso’s REST API

Bug Fixes
A couple of minor fixes have been applied

v1.2.0.0 was released on 19th October 2018 and added the following:

Improved support for iSAMS
iSAMS is now connected to using a single API Key which allows for easier installation.
Updated instructions on using iSAMS with this utility are provided below.

Bug Fixes
Issues with some Unicode characters not being accepted by Apple School Manage have been addressed.
An issue preventing the successful use of the Registration Groups feature has been addressed.

v1.1.0.0 was the first release and has the following features:

Support for extracting data from 6 MIS/SIS Systems

SIMS.Net
Facility CMIS
Progresso
WCBS Pass
Engage by DoubleFirst
iSAMs
Bromcom
Arbor

The ability to provide data in XML format to the utility for conversion to the appropriate data type for Apple School Manager(Pre release versions only)

The ability to map CSV files for matching email addresses

As Apple School Manager uses email addresses to manage the link from the data provided to Apple School Manager it is important that this information is provided.
As this data is not available by default in many MIS/SIS systems the utility will allow users to provide details as where to get this information from.

MIS/SIS
If supported for chosen MIS/SIS system (more details in the MIS/SIS Configuration notes section), this will use the data from the MIS/SIS to provide the email addresses outputted in the data.

CSV
In this mode, you will be able to input a CSV file which contains the users’ email addresses and a unique ID link to their MIS/SIS Record.

None
This will simply not attempt to get the email address information for users.

Note. In this configuration, the outputted CSV files will not be complete and will fail validation by the Apple School Manager service.

Pull data from Registration/Form Groups
You can now choose to have Apple School Manager courses derived from Registration Groups rather than timetabled class data.

Update function
The ability to update the utility when new versions are available.

Effective Date
Effective Date is a process which allows the user to define the date on which the export processes run. During Holiday period’s it may be useful to set this to look at the student, teacher and class information at a particular date rather than the date of running the application.

This allows the utility to help the provisioning of Apple School Manager for new Academic Years and/or Terms before they start.

Toggle output CSV with missing details
By default the utility will output, to the CSV files, the details of every user it finds in the data from the MIS. This will include those without complete details which could cause sync issues with Apple School Manager . This version now adds the ability to, optionally, remove the details for any missing students/staff.

Overall
In order for the utility to run, it must be run on a Windows Machine running .Net 4.6 or higher.

In order to run in Extract Mode you must also have the appropriate permissions to the folder where the Apple School Manager CSV files are to be written to and the connection information for the chosen MIS/SIS.

In order to use the Send Mode the utility must have an internet connection for https traffic and SFTP traffic (port 22).
You must also supply the details of the Apple School Manager SFTP service you have configured to receive the data.

You must also have the appropriate permissions to the folder where the Apple School Manager CSV files are to be read/written.

Note. Separate prerequisites exist for each MIS/SIS system. Please refer to the ‘MIS/SIS Connection notes’ section for more details.
Each of the supported MIS/SIS Systems have different prerequisites.

SIMS.net
In order to connect to SIMS.net the utility must be ran on a machine running SIMS.net workstation running the appropriate version for the database you wish to get data from.
For most sites, this will be the latest SIMS version.

You will also need the following:

Details of a SIMS user with a permission role of ‘Class Teacher’ and ‘Third Party Reporting’ as a minimum
To know where SIMS Workstation is installed on the machine running the tool (usually C:\Program Files (x86)\SIMS\SIMS .net or C:\Program Files\SIMS \SIMS .net)
The Name of the SIMS Server SQL Instance (can be found in the SIMS connect.ini)
The name of the SIMS Database (can be found in the SIMS connect.ini)

Note. For sites using hosted SIMS, the utility will need to be installed on the machine running the SIMS connector and VPN
Progresso
To connect to progresso the utility will need access to the internet on ports 80 and 443.
You will need to know the Progresso School ID and the Access must be granted in the Progresso API.

To Grant access for this utility in progresso users must:

    1. Login to progresso as user who is a ‘School Administrator’
    1. Goto SYSTEM > API Licenses
    1. Click ‘Provide Access’
    1. From the dropdown box select “Salamander Soft”
    1. Select the areas of the system you wish to allow access for and provide Read access.
  1. Click Save

Facility CMIS
The data from Facility CMIS is collected directly from the SQL database using a standard SQL Protocol.

In order to connect, you will need to have a SQL Server connection string for the database.
This connecting string must include the authentication method and any required credentials.

Examples and help regarding SQL Server connection strings can be found HERE

WCBS Pass
The data from WCBS Pass is collected directly from the SQL database using a standard SQL Protocol.

In order to connect, you will need to have a SQL Server connection string for the database.
This connecting string must include the authentication method and any required credentials.

Examples and help regarding SQL Server connection strings can be found HERE

XML
Primarily for testing purposes, the ability to pass XML data through the tool has been added. The supported XML files are:

school.xml – This file contains the basic school information including the name and DfE Local Authority and Establishment numbers.
pupil.xml – A list of the pupils
staff.xml – A list of the staff
class.xml – A list of each class, with their membership

Sample files with demo data can be downloaded from HERE

Note. It is not expected that this function will be provided in the final release versions and should only be used for testing where access to a supported MIS/SIS is not possible.

Engage by DoubleFirst
The data from Engage by DoubleFirst is collected directly from the SQL database using a standard SQL Protocol.

In order to connect, you will need to have a SQL Server connection string for the database.
This connecting string must include the authentication method and any required credentials.

Examples and help regarding SQL Server connection strings can be found HERE

iSAMs
To connect to the data in iSAMs you will need access to generate a single API Keys for use in the tool for:


Recommend Key Name Batch Methods required in the key
SalamanderSoft_ASM Student Manager Datasets > Current Students
HR Manager Datasets > Current Staff
Teaching Manager Datasets > Departments
Teaching Sets
Teaching Set Lists
School Manager Datasets > Years
School Manager Datasets > Forms (only required if using the ‘Use Registration Group information’ feature

You can find some information on how to create iSAMs API Keys HERE

You will also need the hostname for your iSAMs instance.

Bromcom
To connect to the Bromcom API the following details are required:

Url for the bromcom cloud service
SchoolID (available from Bromcom)
Username*
Password*

*The user details should be new details created in the ‘system users’ section, with ‘Third Party’ Permissions enabled.

ScholarPack
The data from ScholarPack is collected from their API’s.In order to configure this you will need to grant access to your environment. SalamanderSoft is an approved provider, and access can be configured in ScholarPack.

Full details on how to configure this access can be found here:

https://support.scholarpack.com/hc/en-gb/articles/360001293911-API-Configuration

Once access is granted you will need to keep the ‘URL’ and ‘Scholar_School’ details from the ‘Access Details’ section once the approval is made to provide in the utility.

RM Integris
The data from RM Integris is collected via their API’s.
Each school can configure their own access to the API’s.In order to configure this you will need to grant access to your environment.

In order to do this, you must configure the ‘RM Integris Datashare’ in the ‘System Management‘ module. You should select the entry for your school, not SalamanderSoft.O
nce configured you will have 2 values which should be used in the utility:

Name in RM = ‘API Consumer Key’ > Name in Utility = ‘API Key’
Name in RM = ‘API Secret Key’ > Name in Utility = ‘API Secret’

These keys should only be used within your environment and must not be shared with our team or any other provider.

Arbor
The data from Arbor is collected via their API’s. In order to enable this access we must request access to the API via Arbor, which the school then needs to approve.
To request the approval, we need the name of the site as Arbor has it.

Once approved we are provided with the details, which we’ll arrange to pass on to you in a secure manner.

Please contact sds@salamandersoft.co.uk to request access to work with Arbor.

Installation
The utility is provided as a zip file which contains all the required files.
It can be run by unzipping all the files in the package to a folder on the machine you wish to use.

It is important that non of the files are blocked and so it is recommended that you check the zip file is not blocked by Windows before extracting it.

Note. The application must be run from a session on the machine it resides on and cannot be run accross a network share.

Once the application and associated files are extracted, it can be run by opening SalamanderASM.exe

Extract Mode
The Extract mode will connect to the chosen MIS/SIS system and pull data to generate the appropriate CSV files for SDS.

Settings Page
The first page ‘Settings’ allows you to prepare the MIS/SIS Connection.
Select the appropriate MIS/SIS Type and complete the text boxes. (more details in the MIS/SIS Configuration notes section)
Once this is done, you must test that the utility can successfully connect using the ‘Test Connection’ button.

If the connection is successful, the ‘School Name’ and ‘School ID’ are populated.
If the utility is not able to connect an error will be displayed and you will not be able to advance until the utility can successfully connect.

Note. It is important to note these values as they will be used as the location name and ID in the CSV files constructed to send to Apple School Manager .

Before proceeding you must also specify a folder where you wish to save the outputted CSV files. It is recommended that you choose a new, empty, folder for this purpose.

Once all the boxes on the ‘settings’ page are complete, you will be able to continue to the ‘Teacher Details’ and ‘Pupil Details’ pages.

Teacher/Pupil settings
Both the Teacher and Pupils details pages are the same and so will be covered in this single section.

Here you are presented with the option to use either Legal or Preferred names for the Teachers/Pupils pulled from your MIS. If you select the Preferred name and this is not available for user, the legal name will be used instead. If the setting is configured to not use a Preferred name and the Legal name does not exist in the MIS, no value will be returned.

Managing Email Addresses
As Apple School Manager uses email addresses to manage the link from the data provided to Apple School Manager it is important that this information is provided.
As this data is not available by default in many MIS/SIS systems the utility will allow users to provide details as where to get this information from.

MIS/SIS
If supported for chosen MIS/SIS system (more details in the MIS/SIS Configuration notes section), this will use the data from the MIS/SIS to provide the email addresses outputted in the data.

CSV
In this mode, you will be able to input a CSV file which contains the users’ email addresses and a unique ID link to their MIS/SIS Record.

None
This will simply not attempt to get the email address information for users.

Note. In this configuration, the outputted CSV files will not be complete and will fail to upload to Apple School Manager .

Once you have selected the appropriate setting, you may proceed.

Run
The run page will display some basic information regarding the configuration you have chosen before allowing you to Run the extract.

Once ran, if the extract is successful the View Extracts and ‘Proceed to Send mode’ buttons will appear:

View Extracts will open the folder the extracts have been written to so you can see the CSV files, and if needed make adjustments.

Proceed to Send Mode will set the application into the Send Mode ready to push the extracted files directly to Apple School Manager .

If the extract fails, you can copy the information on the screen to the clipboard to aid with troubleshooting.

Note. It is highly recommended that view any extracted CSV files to ensure all the details are correct and match those required by Apple School Manager .

Send Mode
The Send mode will upload the specified set of CSV files to the Apple School Manager SFTP service.

Before proceeding you will need to have configured the Apple School Manage SFTP service. The utility will need the following details:

SFTP Url
SFTP Username
SFTP Password

Information on configuring this can be found HERE

Once all the files have been successfully uploaded, Apple School Manager will be able to continue it’s sync process (if activated).
This will not be immediate. It can take a number of hours from the upload to Apple School Manager before the data is processed in your tenant.


For support please contact asm@salamandersoft.co.uk