SMS 2.0 API Server Launch Kit Instructions

The SMS 2.0 REST API and what it means to you

API is short for Application Program Interface and can best be defined as s a set of routines, protocols, and tools for building software applications. An API specifies how software components should interact, either internally or externally with applications from different vendors. The Secure (https) SMS 2.0 REST API is available to 3rd party vendors that wish to interact with the SMS 2.0 Student Management or School Management (Combined Database) Suite. The 3rd party vendor works with Skyward to consume the API and integrate the API into their products.

The SMS 2.0 REST API has 2 endpoints, the LMS API endpoint and the OneRoster API endpoint. Note: The OneRoster API is new and was made available in the February 2019 Release Addendum 6 or newer. The SMS 2.0 REST API endpoints are Read Only, unless you purchase the LMS/OneRoster API license. If the license is purchased both the OneRoster API and LMS API allow pass back of select Student Management Data.

This Launch Kit is intended for Self-Hosted Customers with On Premises servers. If your district is Cloud Hosted, your hosting provider will perform the API Server Install. If your district uses Managed Services, IT Services will perform the API Server Install. Cloud Hosted and Managed Services customers should create an IT Services Service Call to request the API Install by calling 1-800-236-0001 or visiting the Skyward Support Center.

API Installation

API Server Pre-Install Checklist

LMS API Minimum Version: 2016 June Release + Addendum 10

LMS API requires Skyward Version: 05.16.06.00.10 (or later)

OneRoster API Minimum Version: 2019 February Release + Addendum 6

OneRoster requires Skyward Version: 05.19.02.00.06 (or later)

System Requirements:

Windows 2019 / 2016 / 2012 / 2012 R2 Server
Windows 2012 Requires Windows Service Pack 2
.NET 4.6.1 or Newer
1GB of Free RAM, 200 MB of Free Disk Space on the Skyward Drive
VMWare/Hyper-V Citrix XEN Virtual Servers are supported
The Skyward API Server can be installed on any Skyward Web IIS Server with Progress OpenEdge already installed.
Skyward API Server Install takes about 15 minutes to install
Skyward API Server can be installed while users are in Skyward.
Occasionally the .NET install will require a reboot before the API works.

API Server Components to be installed:

.NET 4.6.1
IIS API Application
API Config File Settings

API Server Firewall Requirements

If your districts Skyward IIS Web Server(s) have a firewall between the Web Server and the database, please ensure the following ports are open. Districts may define custom ports when they were installed so all ports should be verified using the OpenEdge Explorer / Management tool.

Default ports used by the API Server

From Web Server(s) to Database Server →NameServer UDP Port 5162
From Web Server(s) to Database Server → TCP Port for the Stateless AppServer
- Student Management default → TCP 3095
- School Management (Combined Database) default → TCP 3099
- Student Management Training default → TCP 4001
- School Management Training (Combined Database) default → TCP 4005
Both Directions Web Server(s) / Database Server -> TCP Port Range for the Stateless AppServer
Default → TCP range 2002 – 2202

Note: The Stateless AppServer for Student Management is called asStuMon and for School Management
(Combined Database) it is called asSkyMon. For Training systems, the Stateless AppServer for Student Management is called asStuMonTrn and for School Management (Combined Database) it is called asSkyMonTrn.

Choosing a Skyward Server for the API Server

If you have one Skyward Student / School Management Server, then this is where the API Server will be
installed. Verify the server meets the minimum requirements before installing the API Server.

The API Server Install typically takes about 15 minutes to install per Web Server.

The API Server can be installed while users are in Skyward. A reboot is suggested but not always necessary.

In some situations, the server must be rebooted before the API will work correctly.
If you have multiple Skyward Servers, then you must install the API Server on every Skyward Student /
School Management Web Server and you must complete the additional configuration to setup a Machine
Key for load balanced servers.

API Server Install Summary

Ensure your software is at the June 2016 Release + Addendum 10 or later
Download the API Server Installer
Run the API Server Installer (~15 minutes)
Create a Key and Secret (~5 minutes)
If using multiple Load Balanced Web Servers configure the Machine Key
Test your API Server (~5 minutes)
If the API Server Test fails reboot the Web Server(s)
Provide the API URL, Key, and Secret to the 3rd party vendor.

Download the API Server Installer file from the Secure FTP site.

Connect to our Secure FTP Instructions using the instructions found here: Secure FTP Instructions
Navigate to the Secure FTP folder of Hardware → Public → OE117-Customer-DVD → Windows
Download the file 11.7 – SMS 2.0 – Role – API Server Install.exe.
Save the downloaded file to the ?:\skyward\install folder on the Skyward Web server
Continue to the API Server Install section.

Notes:

The 11.7 – SMS 2.0 – Role – API Server Install.exe needs to be installed on one Windows SMS
Student or School Management server that runs the IIS Web Server.

Double click 11.7 – SMS 2.0 – Role – API Server Install.exe file located in the ?:\skyward\install
folder.
The Welcome screen displays → Next.
The Installation Folder window displays → The Install will automatically detect the current
OpenEdge Installation path. If the path is not correct change to the Drive and folder path where Skyward
was installed → Next.
The Skyward Suites Selection window will display → Select Student Management or School
Management Suite (Student and Business Combined Database) → Next.
The Training Database Setup window will display → Choose No Training Database or Only a
Training Database. → OK.
Production Student/School Management Programs Location window will display → Choose the
Student Management or School Management program folder → Next
The Database Location window will display → Select Yes if this server is the Student Management or School Management Database Server and proceed to step 10. → Select No if this server is not the Student Management or School Management Database Server and proceed to step 8 → Next.
Not the Production database server → Enter the IP Address and NameServer Port of the Student Management or School Management Database Server → Next.
Note: The standard Student / School NameServer Port is 5162.
API for a Training Database only, the Training Programs Location window will display → Choose the Student Management or School Management training programs folder → Next.
The Training Database Location window will display → Select Yes if this server is the Student Management or School Management Database Training Server and proceed to step 10. → Select No if this server is not the Student Management or School Management Database Training Server and proceed to step 11 → Next.
Not the Production database server → Enter the IP Address and NameServer Port of the Student Management or School Management Training Database → Next.
Note: The standard Training Student / School NameServer Port is 5162
The Ready to Install windows displays → Next to start the installation.
The Installing API Server window displays → The information that scrolls across the screen can be viewed in the installer log file when Installer completes.
The Installation is Complete window displays → Choose View Installer Log to review → Choose Finish to exit the installer.

API Configuration

Generating a Key and Secret

A Key and Secret will need to be created and given to 3rd parties that want to read data from the API Server. A Key and Secret is synonymous with a username and password. It is recommended that a unique Key and Secret be created for each 3rd party vendor that will be connecting the API Server.

Create a Secured User account within your database for each 3rd Party Organization that will connect to the API Server.
Browse to Product Setup → Skyward Contact Access → Secured User → Click Add → Click the
Organization button → Enter Organization (Vendor) Name → Click Add Entered name to Secure
Users → Enter Address Info and Save (optional) → Enter Demographic Info and Continue (optional) → Enter Security Info desired and Save →
Note: The user must remain active, other settings can remain at the default.
Highlight the New Organization User in the Secured User list → Click the API button in the lower
right corner of the screen → Click Generate New key
Note: If the API button is not available please make sure you are running the June 2016 Release +
Addendum 10 or later.
The Key and Secret displayed on the API access screen will be used by 3rd party vendors making the connection to the API Server.

Test the LMS API Server using Swagger

From the any web browser → browse to the Student/School URL
https://{DNSNAME}/api/swagger/ui/index → Enter a valid Key and Secret → Choose Get Token → Click on District → Choose Get District Information → Choose Try it out!
Notes:
• Do not run this test from the Skyward Server using Internet Explorer.
• The swagger Try it Out! Test page button queries data from your Skyward database just like a 3rd
party application would do. This test validates that your Key and Secret are correct, and that the API
Server is working correctly.
A successful test will display data retrieved from the Skyward database like the “DistrictCode” or
“DistrictName” in the Response Body like the example shown below.

Send your API Information to your 3rd Party Vendor

The API URL, Key, and Secret are the 3 pieces of information needed to complete your API configuration.
These pieces of information will be given to the 3rd party vendor by you so they can successfully use the
API.

Determine which API the vendor uses, it will either be the LMS API, or the OneRoster API.
The vendor will be able to tell you which API they use.
Once you know which API is used, determine your API URL based on the examples below.
You will need to give the vendor your API URL.

LMS API URL is:
On Premises hosted customers: https://school.k12.state.us/api
ISCorp hosted customer: https://skyward.iscorp.com/APIdistrictnameSTU
Note: Be sure to change the sample URLs above to use your districts URL settings.

OneRoster API URL is:
On Premises hosted customers: https://school.k12.state.us/api/ims/oneroster/v1p1/
ISCorp hosted customers: https://skyward.iscorp.com/APIdistrictnameSTU/ims/oneroster/v1p1/
Note: Be sure to change the sample URLs above to use your districts URL settings.
Share the API URL, Key, and Secret/Key with the 3rd party vendor, you are finished!

API Configuration in SMS

The API Configuration Options and API Logging can be found by browsing to Product Setup →
Contact Access → District Setup → Configuration → API Configuration.

These fields are not editable as the info is gathered when the third party connects to the API URL.

Congratulations the API Server Install and Configuration is Complete!

Advanced API Information

LMS API Data Objects

The following list of Data Objects have been made available to 3rd party vendors that consume the LMS API. Documentation on the supported endpoints are found using the Swagger Interface.

If the LMS/OneRoster API license is purchased the LMS API allows pass back for LMS API objects. If the
license is not purchased the LMS API allows read only access to all data objects listed below.

LMS API Version 1

AbsenceReasons
AbsenceTypes
Assignments
AssignmentScores
Courses
Departments
District
EmergencyContacts
Enrollments
Errors
GradingCategories
GradingCategoryCodes
GradingPeriods
Guardians
Names
Relationships
Schools
Sections
Settings
SpecialCodes
StaffMembers
StandardGrades
Standards
Students
Subjects

OneRoster API Data Objects

The following list of Data Objects have been made available to 3rd party vendors that consume the
OneRoster API. Documentation on the supported endpoints are found on the IMS Global website.
If the LMS/OneRoster API license is purchased the OneRoster API allows pass back for Categories,
LineItems (Assignments), and Results (Assignments Scores). If the license is not purchased the OneRoster
API allows read-only access to all data objects listed below.

OneRoster API Version 1.1

categories
results
lineitems
academicsessions
classes
courses
demographics
enrollments
gradingperiods
orgs
schools
students
teachers
termsusers

Advanced Configuration Options

The advanced configuration options are not necessary for most customers and are intended for special configurations where multiple environments are hosted on a shared set of web servers, or when a customer has multiple load-balanced web servers.

Configuring Multiple API Instances on a Shared Web Server

The template configuration file [skyward]\ocx\skywardapi\appsettings.config.template has examples to define multiple running instances of the API on servers that are set up with multiple Skyward environments, like a Cloud Hosted server.

To run multiple API instances each instance of the API must have a set of unique keys defined for each environment. The IIS Virtual Application must match the name of the unique keys. To configure multiple applications, copy the Multiple Applications appSettings section to the top of the appsettings.config.template file, overwriting the existing appSettings section, and then save the file as [skyward]\ocx\skywardapi\appsettings.config

For Example , set the key values to “DistrictOneAPI” and then set the configuration values for this customer within this configuration section. Once that is done,set the key values for “DistrictTwoAPI” and set the configuration values for District Two. You can support as many instances of the API on any one IIS Web Server as you wish by adding additional keys and setting the values.

In IIS you must create an API Virtual Application for each configuration section, for the example above you would need an API Virtual Application named “DistrictOneAPI” and another named “DistrictTwoAPI”. Your API URLs would be: https://{DNSNAME}/DistrictOneAPI and https://{DNSNAME}/DistrictTwoAPI

Additional IIS Setup for Load Balanced API Servers

If your district has more than one web server that is load balanced, please follow these steps to setup the API for load balancing. The API Server must be installed on all Skyward Web Servers that participate in the load balancing of the Skyward Web Applications.

Select one of your Skyward Web Servers that has the API Server Installed. Open the
Administrative Tools Control Panel → Open the Internet Information Services (IIS) Manager.
Expand the IIS Server → Expand Sites → Expand the Skyward Web Site → Select the API
Application → Click on the Machine Key icon.
Under Validation Key → Uncheck the option to automatically Generate at Run Time → Uncheck
the option to Generate a Unique Key for each application → Under Decryption Key → Uncheck the
option to automatically Generate at Run Time → Uncheck the option to Generate a Unique Key for each
application.
On the right-hand side → Click Generate Key → Click Apply
Open the {Skyward program path}\ocx\skywardapi\MachineKey.config file using Notepad and
you will notice it now has a Machine Key populated. → No changes are necessary → Close the file after
verifying the Machine Key is populated.
Copy the MachineKey.config file noted above to each Web Server {Skyward program
path}\ocx\skywardapi\ folder that has the API Server installed.