Rostering Integration Considerations

DocsPublisher

You can configure your Instructure OneRoster integration options at each client connection level. 

During your integration alpha testing phase, Instructure will work with you to establish recommended default configuration settings for your institution.

Learn more about rostering service configurations and rostering integration best practices.

Note: Instructure is a OneRoster Consumer. For OneRoster Consumer and Provider definitions, view the Introduction to OneRoster.

Concurrency

Concurrency is the number of endpoints to be threaded at a single time. With a concurrency of three, configure up to three separate concurrent endpoints. For example, you could use the getTerms, getTeachers, getClasses endpoints concurrently.

Learn more about configuring school specific rostering endpoints to allow for concurrent enrollment data syncs.

Note: Instructure does not apply concurrency to pagination. As a result, the data load is as slow as the slowest endpoint response time combined with the pagination on a single thread.

Error Handling

Error handling relates to the configuration of displayed error codes. 

Follow the OneRoster error handling specifications. Additionally, it is recommended that you include your SIS name at the beginning of the imsx_description. This allows the integration to automatically display instructive error descriptions for end users.

Excluded Endpoints

Excluded endpoints are the endpoints not included in an API call. 

If two endpoints return identical datasets, exclude one dataset to reduce the number of API calls. For example, getAllAcademicSessions and getAllTerms may provide identical datasets, so include only one in your endpoint configuration.

During your integration alpha testing period, please notify Instructure of any excluded endpoints.

Learn more about OneRoster endpoint configurations.

Filter Queries

Filter the data included in a data sync using filter queries. You can configure filter queries on a per-job basis, allowing for both bulk and incremental data syncs.

During your integration alpha testing period, please notify Instructure of your configured filter queries for OneRoster.

Learn more about OneRoster filter queries. Additionally, learn more about incremental sync implementation requirements.

Pagination 

Because API calls to a SIS can request large amounts of data, pagination adds order to your API query results. To decrease HTTP traffic and improve synchronization timing, it is recommended that you configure pagination to support up to a limit of 1000 records at a time.

Learn more about the OneRoster pagination requirements.

Note: While not recommended, Instructure can support implementations where all requested data is included in a single API call if the number of timeouts does not become excessive. 

Retries

Retries are the number of times the integration attempts an API call. The Instructure OneRoster integration attempts an API call up to three times before erroring out. A delay period occurs between each attempt, and a delay multiplier increases the delay period between retries. 

With the below Example Configuration, an API call will attempt up to three times, waiting 5 seconds after the first error, then waiting 15 seconds for the second consecutive error. If the call fails a third time, the integration job fails.

Example Retry Configuration	Interpretation
“defaultRetries”: 2	3 attempts
“defaultDelay”: 5000	5 seconds
“defaultDelayMultiplier”: 3	15 seconds

Timeouts

Timeouts occur when an API request to the web server takes too much time compared to the website's server wait time. If necessary you can increase your website's server wait time (e.g. 2+ minutes). However, where possible, you should adjust your integration to make it more responsive (e.g. less than twenty seconds).