Salamander SDS Support

The Salamander SDS Utility is a Windows Application designed to collect data from school MIS/SIS systems, process it into CSVs suitable for use with Microsoft’s School Data Sync Service and send those files to the School Data Sync service for provisioning Office 365.


Current Version1.4.0.0
Version Date2nd March 2018
Release NotesAdded support for outputting Non UK schema files
Improved reporting of issues connecting to Office 365 when getting SDS Profiles
Supported MIS/SIS SystemsThis version supports the following MIS/SIS systems:

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

DownloadPlease contact sds@salamandersoft.co.uk to get a copy of the utility.
v1.4.0.0 adds the following:

Support for non UK CSV Headings
The utility can now output the CSV files using either the US or UK Schema headings.

Arbor Support
Support for extracting data from Arbor has been added.

SIMS.Net support for reading connect.ini
SIMS.Net users can now load a Connect.ini to gather the Database and Server details

Bug fixes
A couple of bugs have been fixed.

v1.3.0.0 was released on 29th December 2017 and added the following:

Pull data from Registration/Form Groups
You can now choose to have SDS sections derived from Registration Groups rather than timetabled class data.

Select SDS Profiles
The utility will now pull a list of your SDS profiles to use when sending the data.

Bug fixes
A couple of bugs have been fixed.

Pre release 4 (v1.2.5.0) was released on 26th September 2017 and added the following:

Term Start and End Dates
The CSV files outputted now contain the ‘term’ start and end dates for the Sections. This is based on the Academic Year as defined in the MIS system.

Bromcom support
Support for Bromcom has been added.

Update function
This release fixes an issue updating from previous versions of the tool.

Pre release 3 (v.1.2.0.0) was released 7th August 2017 adding the following:

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 SDS 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 SDS. This version now adds the ability to, optionally, remove the details for any missing students/staff.

Pre release 2 (v1.1.0.0) was released 11th May 2017 and added the following features:

Support for Engage by Double First
Support for iSAMS

Some minor bug fixes

Pre release 1 (v1.0.0.0) was released on 4th May 2017 and was the first release of this utility bringing the following:

Support for extracting data from 6 MIS/SIS Systems

SIMS.net

Progresso

Facility CMIS

WCBS Pass

Engage by DoubleFirst

iSAMs

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

The ability to map CSV files for matching username and email addresses

As SDS uses usernames and email addresses to manage the link from the data provided to SDS 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 usernames and 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, usernames and a unique ID link to their MIS/SIS Record.

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

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

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

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

Note. Separate prerequisites exist for each MIS/SIS system. Please refer to the ‘MIS/SIS Connection notes’ section for more details.

In order to use the Send Mode the utility must have an internet connection for https traffic.
You must also supply the Username and Password of a user with rights to upload data to SDS.

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

Azure Enterprise App
In order to automatically get the list of available SDS Profiles the utility uses an Azure Enterprise app for which consent must be given.

To authorise our Office 365 App, all you need to do is follow the link below.

https://login.microsoftonline.com/common/oauth2/authorize?client_id=af2b5caa-fb61-496b-8e3d-f264b8e6a27c&prompt=admin_consent&state=12345&redirect_uri=https://azure.salamandersoft.co.uk&response_type=code+id_token&nonce=SalamanderSoft

You need to login as an Administrator for your Office 365 Tenant. Once logged in, you will be presented a page detailing our App and the permissions required. If you accept these permissions, the app will be added to your tenant and the utility will be able to read the list of SDS Profiles in your tenancy.

If you prefer not to give this app consent, we can supply a version of the utility which doesn’t have this feature.
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’
  2. Goto SYSTEM > API Licenses
  3. Click ‘Provide Access’
  4. From the dropdown box select “Salamander Soft”
  5. Select the areas of the system you wish to allow access for and provide Read access.
  6. 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 3 API Keys for use in the tool for:


Recommend Key NameBatch Methods required in the key
SalamanderSoft_PupilStudent Manager Datasets > Current Students
SalamanderSoft_StaffHR Manager Datasets > Current Staff
SalamanderSoft_ClassTeaching Manager Datasets > Departments
Teaching Sets
Teaching Set Lists
School Manager Datasets > Years

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.

The configuration of the SDS Profile you wish to work with is very important and should be considered before working with the utility.

The utility is designed to work only in situations where users already exist. It is possible to use the outputted files to create new users via SDS by adding the column Password to the outputted files ‘student.csv’ and ‘teacher.csv’.

It is recommended that a new, dedicated, SDS Profile be configured for the utility.

The following fields are extracted by the utility and should be those configured when creating a profile:

School Properties – school.csv


Field NameDescription
DfE NumberThe Local Authority name and Establishment number from the MIS with a hyphen separator.
This is used a the link value between all the User and Section objects passed to SDS.
NameThe Name of the school. This is used in the SDS School profile and dashboard.

Student Properties – student.csv


Field NameDescription
IDThe ID of the Student from the MIS
School DfE NumberThe School Number as produced in the ‘DfE Number’ field in school.csv
Student NumberThe Admission Number of the student. For some systems this is the same as ID.
GradeThe Grade/Year of the student
StatusThe Enrolment Status of the student.
UsernameThe username of the student if available. Where this data is from is configurable.

Teachers Properties – teacher.csv


Field NameDescription
IDThe ID of the teacher from the MIS
School DfE NumberThe School Number as produced in the ‘DfE Number’ field in school.csv
TitleThe Title/Salutation of the teacher.
UsernameThe username of the teacher if available. Where this data is from is configurable.

Section Properties – section.csv


Field NameDescription
IDThe ID of the class/section as used by SDS. As some MIS/SIS Systems do not store a separate ID for the class/section, the utility uses the name.
School DfE NumberThe School Number as produced in the ‘DfE Number’ field in school.csv
Section NameThe Name of the class/section as in the MIS/SIS.
Course IDThe ID of the course.
Course NameThe full name of the course.
Course NumberWhere a course number is available this is used. For Those MIS/SISs where a number is not available, the Course Name is used.
Course SubjectThe Full Name of the course’s subject.

StudentEnrollment Properies – studentEnrollment.csv


Field NameDescription
Section IDThe ID of the Section the Student is a member of
IDThe MIS/SIS ID of the Student.

TeacherRoster Properties – teacherRoster.csv


Field NameDescription
Section IDThe ID of the Section the Teacher is a member of
IDThe MIS/SIS ID of the Teacher.

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 SalamanderSDS.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 by SDS. See the ‘Configuring SDS’ section for more information about how to configure your SDS Profile.

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 Username and Email Addresses
As SDS uses usernames and email addresses to manage the link from the data provided to SDS 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 usernames and 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, usernames and a unique ID link to their MIS/SIS Record.

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

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

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 SDS.

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 configured in your SDS Profile.

Send Mode
The Send mode will upload the specified set of CSV files to the Microsoft School Data Sync API.

Before proceeding you will need to have the following information:

Username and Password for an account in your Office 365 with access to manage School Data Sync.

To have granted access to the Azure Enterpise app as covered HERE

The location of the CSV files you need to upload.

Note. It is highly recommended that you read the ‘Configuring SDS’ section and check it against your extracted data before using the utility in this mode.

Once you have entered the user, profile and folder settings you can run the send process.
This will connect to your chosen School Data Sync Profile, which will validate the files that have been sent.
In the event that the files fail the validation by School Data Sync, the validation messages will be displayed in the utility. These can then be copied to the clipboard.

Once all the files have been successfully updated, SDS 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 SDS before the data is processed in your tenant.


For support please contact sds@salamandersoft.co.uk