Data Ingestion with OneRoster API

  • Article

OneRoster API (Application Programming Interfaces) is an Industry Standard format, from 1EdTech (formerly IMS Global), for exchange of Student Information System (SIS) / Student Management Systems (SMS) data. Using this sync method, you can connect directly to your SIS/SMS using the REST-based OneRoster 1.1 APIs developed by your SIS/SMS provider. The API support allows you to synchronize data directly instead of using CSV (Comma Separated Value) files.

Data Accessed by School Data Sync

Important

By connecting and making institution data available with School Data Sync, you acknowledge that you are authorized to share this data with Microsoft and commit to adhere to your organization’s data governance standards.

Action URL Required Filter Properties Optional / Recommended Filter Examples
GetAllAcademicSessions /academicSessions status dateLastModified /academicSessions?offset=0&limit=5000&filter=status=’active’/academicSessions?filter=dateLastModified>’{deltaDateTime}'

Set up SDS for Microsoft 365 Education Tenant

  • Microsoft 365 Education tenant
  • Need Global Administrator Permissions

SDS Access and First Time sign-in

To access the SDS Admin Portal launch your web browser, navigate to sds.microsoft.com, and then sign in using your Microsoft 365 Global Admin account.

  1. Select Get started.

    Screenshot showing welcome message.

  2. Select Continue.

    Screenshot showing overview of SDS.

    Allow a few moments for services to provision to tenant before next step.

    Screenshot showing pending while waiting for service provisioning to complete.

  3. Select Create new inbound flow. Select Next to continue.

    Screenshot showing prompt to create new inbound flow.

  4. Choose your data source. For OneRoster API, you select the option Connect to my data.

  5. Select the format. For OneRoster API, you select the option API. Select Next to continue.

    Screenshot of selecting API.

    Screenshot showing process request to obtain list of API providers.

  6. You need to select your SIS / SMS provider from the provider list. Once you've selected, select Next to continue.

    Screenshot showing list of API providers for selection.

    Note

    If your SIS / SMS Provider is not in the list, see OneRoster Provider Overview for instructions to participate in pilot testing or information to send to your provider for them to participate to be added as a OneRoster provider.

  7. To enable the connection to your SIS / SMS, you need to provide the connection credentials.

    • Web access URL: URL where your OneRoster API is accessible for your SIS / SMS

    • Client ID that is used to connect to your SIS / SMS OneRoster API

    • Client Secret that is used to connect to your SIS / SMS OneRoster API

    • Access Token URL, if your SIS / SMS OneRoster API is configured for authentication using OAuth2, you'll also need to provide the Access Token URL endpoint that will be used to connect. The endpoint is different from the Web access URL.

    • Select Next to continue.

    Screenshot showing prompts for API credentials.

  8. Next, we test the connection to your SIS / SMS based on the information entered in the last screen.

    Screenshot showing validation of API credentials.

    • If there are no issues, you're notified, and can select Next to continue.

    • If we're unable to establish a connection, you're notified, and will be able to select Back to review and update the information provided.

    Screenshot showing successful validation of API credentials.

  9. Choose your current academic year and provide a friendly name, such as 2023 or 2022 – 2023. (Characters must be utf8 or will be automatically stripped out).

    Important

    Academic year is used to associate incoming data to help build year over year historical data. The approach is aligned to an academic year versus calendar year. If your academic year spans across a calendar year, for example, start 8/15/2022 and ends 6/15/2023, the academic year value to be selected is the ending year, 2023. For more information, see Academic Year handling

    Enter the dates for when your academic year starts and ends.

    Based on the supported optional data capabilities from your provider, you see the toggle selected On (default) to include other data. You can select the toggle to turn off if you wish. If the toggle is off and unavailable to turn on, this means that the provider’s profile doesn't currently support providing the optional data. For more information if your provider supports sending optional data, see OneRoster API Provider Overview.

    Enter the date when SDS should stop syncing data based on the defined academic year for this source. It's most common to stop syncing data on the academic year end date you just entered.

    Select Next to continue.

    Screenshot prompting for Academic Year and stop sync date.

  10. Select the user identity rule options. Make your selections for both staff and student roles.

    Note

    User matching is performed with the inbound flow and does not write or update the user objects in Microsoft Entra ID. The matching is performed and stored in the Education data lake. For more information, see Microsoft 365 Manage Users on the writing of the match link forward with the outbound flow.

    • Attribute from source: user attribute based on data that is coming from your SIS / SMS.
      • Available source options are Username and Email.
    • Attribute to match to: user property in Microsoft Entra ID to match to.
      • Available Microsoft Entra ID match options are UserPrincipalName and Mail.
    • (OPTIONAL) If your user data doesn't include the @domain value, select a domain from the list.

    Warning

    Selecting a domain is optional and should only be used if the incoming data based on the selected Attribute from source does not include the @domain value. SDS doesn't check and append if the value is missing on a record. SDS will append the domain selection to all records which could result in @domain@domain and not find matches in those instances for existing user mapping with users in Microsoft Entra ID.

    Caution

    If the SIS / SMS users, for example users in the staff role group, could be associated to @domain1 or @domain2 or @domain3 you must have a @domain included in the source data, based on the selected Attribute from source selection (example: prefix@domain). This is needed for your Attribute to match to: UserPrincipalName or Mail to find the correct Microsoft Entra user to match with.

    OneRoster API v1.1 specification only allows passing one role per user. If associated with multiple organizations, it can only pass in the same role for a user to multiple organizations. Since one role per organization then records are marked as isPrimary ‘True’.

    Important

    When configuring Microsoft 365 Manage Users flow, these rules are used if the option is activated to Create unmatched users, to define the construct for the Microsoft Entra UserPrincipalName property.

    After you're satisfied with your selections, select Next to continue.

    Screenshot showing User Identity Rules prompts.]

  11. Review information presented on Review and create. If everything looks correct, select the Next button. If not, you're able to navigate back to correct.

    Screenshot of Review and create.]

    Screenshot of processing after selecting create.]

  12. Your inbound data flow has been created and the first run is pending, select Done button. Check back to see the status of your first run.

    Screenshot that the inbound flow has been created.]

    Screenshot that shows Home Dashboard and Manage data action.

    Tip

    You can set up your Manage data configuration immediately after defining your Connect data configuration, during the active first run, or later after the first run has finished.

  13. To check on the status of the run, navigate back to the Home dashboard page.

    If there are no issues with your data, the Home dashboard will state, "No Data Errors or Warnings Found" and "We did not encounter any data errors or warnings during your last run. Keep up the great work!"

    If there are issues found with your data, the Home dashboard informs that ‘We found some issues with your data’ and encourage you to Investigate sync health.