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

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

 

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

  1. Connect to our Secure FTP Instructions using the instructions found here: Secure FTP Instructions
  2. Navigate to the Secure FTP folder of Hardware → Public → OE117-Customer-DVD → Windows
  3. Download the file 11.7 – SMS 2.0 – Role – API Server Install.exe.
  4. Save the downloaded file to the ?:\skyward\install folder on the Skyward Web server
  5. 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.

  1. Double click 11.7 – SMS 2.0 – Role – API Server Install.exe file located in the ?:\skyward\install
    folder.
  2. The Welcome screen displays → Next.
  3. 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.
  4. The Skyward Suites Selection window will display → Select Student Management or School
    Management Suite (Student and Business Combined Database) → Next.
  5. The Training Database Setup window will display → Choose No Training Database or Only a
    Training Database. → OK.
  6. Production Student/School Management Programs Location window will display → Choose the
    Student Management or School Management program folder → Next
  7. 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.
  8. 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.
  9. API for a Training Database only, the Training Programs Location window will display → Choose the Student Management or School Management training programs folder → Next.
  10. 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.
  11. 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
  12. The Ready to Install windows displays → Next to start the installation.
  13. The Installing API Server window displays → The information that scrolls across the screen can be viewed in the installer log file when Installer completes.
  14. 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.

  1. Create a Secured User account within your database for each 3rd Party Organization that will connect to the API Server.
  2. 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.
  3. 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.
  4. 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

  1. 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.
  2. 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.

  1. 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.
  2. 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.
  3. 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

<appSettings>
  <add key=”DistrictOneAPI_NSHost” value=”myserver” />
  <add key=”DistrictOneAPI_NSPort” value=”5162″ />
  <add key=”DistrictOneAPI_ASName” value=”asAppserverDistrictOne” />

  <add key=”DistrictOneAPI_NSHost” value=”myserver” />
  <add key=”DistrictOneAPI_NSPort” value=”5162″ />
  <add key=”DistrictOneAPI_ASName” value=”asAppserverDistrictOne” />
<appSettings>

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.

  1. 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.
  2. Expand the IIS Server → Expand Sites → Expand the Skyward Web Site → Select the API
    Application → Click on the Machine Key icon.
  3. 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.
  4. On the right-hand side → Click Generate Key → Click Apply
  5. 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.
  6. Copy the MachineKey.config file noted above to each Web Server {Skyward program
    path}\ocx\skywardapi\ folder that has the API Server installed.
Scroll to Top