MDE-EdFi-Documentation

Sandbox Certification Testing

When certification begins, vendors will be required to generate a key and secret to a “Minimal” sandbox Operational Data Store (ODS) with no sample data pre-loaded. This ODS will contain the Minnesota Education School and District records synchronized with MDE ORG, MN specific descriptors, District Programs, and the State Course Catalog and Staff records required for the MCCC data collection. When submitting data for each of the Certification scenarios, we ask that you use a district you have access to, and schools within the district.

Accessing the Sandbox

Please note: In school years ending 2020 though 2022, sandbox environments were given sbYY_ in the base paths for the API, affecting sandbox and Swagger URLs. For school year 2022-2023, the base sandbox URL was merely https://test.edfi5.education.mn.gov/swagger/ - note the “edfi5” portion of the URL, but no sbYY_ portion. For the 2023-2024 school year, a sandbox identifier returned without an underscore: https://test.edfi5.education.mn.gov/sb24/api/. For the 2024-25 school year, given minimal changes, we have merely added a 2024-25 profile to that same sandbox environment.

Sandbox Admin Website

As part of Sandbox certification, you will need access to the Sandbox Admin Site. To request an account, contact MDE by email. In the Sandbox Admin Site, you will be able to create ODS instances to use for development and testing of your integrations. (The Ed-Fi TechDocs have more detailed instructions on setting up sandboxes.)

Swagger UI

We continue to use the Swagger UI tool to visualize and interact with the ODS API. Developers can access this UI for MDE’s Sandbox to test-drive Create, Read, Update, and Delete (CRUD) actions before building integrations as necessary.

Please note: When using Swagger, always double-check the “API Section” listed in the upper right drop-down, and note:

Once inside the Swagger UI, click the “Authorize” button to enter in the client id (key) and client secret you created in the Sandbox Admin site. This will allow you to test GET, PUT, and other API request via the Swagger UI. Do not use the “populated” credentials provided by default for anything other than general exploration.

Sandbox Base and OAuth URLs

Developers can further test their code integrations at the URLs in this section.

Extension vs. Core Resources

Note that Ed-Fi URLs vary based on whether or not core Ed-Fi standard or MN extensions are being accessed:

Important Note: the school year must be included after “/v3/” and before the core/extension namespace in Stage and Production, but not in Sandbox. For example:

```…/api/data/v3/2024/MN/studentSection504PlanProgramAssociations```

The Sandbox ODS/API oauth URL is: ```https://test.edfi5.education.mn.gov/sb24/api/oauth/```

Authentication In Ed-Fi 3.x ODS/API uses two-legged OAuth 2.0 Client Credentials Grant Flow. More information and sample API calls are located in [the Ed-Fi tech docs](https://techdocs.ed-fi.org/display/ODSAPIS3V520/Authorization).

## Sandbox Tips
- In the staging and production environments, SIS vendor API keys will be associated with a claim set limiting access to only the API resources included in this documentation. This claim set has been enabled in the Sandbox environment. When you access a resource not included in the claim set you will receive the following message in the response: ```Access to the resource could not be authorized. Are you missing a claim?```
- In the sandbox, multiple SIS Vendor profiles have been created, limiting access to specific properties on each of the resources required in the referenced school year. These appear in the upper right "API Section" drop-down and are named as above.
    - These profiles are tied to your key and secret, and are auto-enabled in Staging and Production - meaning you will not have to include the profile in the "accept" or "content-type" headers of the request for the profile to take effect. (See more details in the [Staging Environment Load and Quality Check section](/MDE-EdFi-Documentation/sis_test_plan_d_staging.html#staging-environment-load-and-quality-check))
- When creating a sandbox, you have the option of including a set of sample data in the sandbox. The sample data used, is associated with St. Paul Public School District (LocalEducationAgencyId = 10625000). When you do not select the option to include sample data, your sandbox database will be loaded with an essentially empty ODS, except that it will include MN Schools and Districts, and other preliminary seed data such as MDE-customized Descriptors, State Course Codes, and District Programs. _Please note: if you do not see this "seed" data in a sandbox, it means MDE has not yet completed this process for the sandbox environment. You may need to destroy your current sandbox and create a new one once the synching process is conducted._
- The actual certification test will be conducted in a sandbox with no sample data loaded and you will reference your own data in the Scenarios, relating elements to MDE Schools, Districts and Descriptors as needed.
- The Sandbox environment ignores the School Year included in the API base URL. When prepping for submissions to Staging and Production, remember to include the year, i.e. "20##". 
- The School IDs and District IDs used for the ODS/API resources are the MDE State Organization IDs (stateOrganizationID). See the section below for details.
- MN custom descriptor codes have been loaded under the namespace ```uri://education.mn.gov/```
- StaffUniqueId will be loaded using the FFN in the Educator Licensing System.
- Post-Secondary Institution IDs will be pre-loaded by MDE; these college identifiers will come from the MDE-ORG system.
- All Descriptor references require namespaces, and do not rely on the concept of a default operational context. Descriptor references must be formatted as follows: ```uri://[organization indicator]/[name of descriptor]#[code value]``` For example: ```uri://education.mn.gov/ProgramTypeDescriptor#Special Education```
  - This can be seen when updating a studentSchoolAssociation record. For example, within the MN extension part of the record (shown below), the code value for ```membershipAttendanceUnitDescriptor``` is not merely "Days", but **"MembershipAttendanceUnitDescriptor#Days"**:
  ```javascript
  "_ext": {
    "MN": {
      "homeboundServiceIndicator": true,
      "specialPupilIndicator": true,
      "residentLocalEducationAgencyReference": {
        "localEducationAgencyId": 10625000
      },
      "membership": {
        "membershipAttendanceUnitDescriptor": "uri://education.mn.gov/MembershipAttendanceUnitDescriptor#Days",
        "attendance": 180,
        "membership": 180,
        "percentEnrolled": 100
      },
      "transportation": {
        "transportationCategoryDescriptor": "uri://education.mn.gov/TransportationCategoryDescriptor#01",
        "transportingLocalEducationAgencyReference": {
          "localEducationAgencyId": 10625000
        }
      }
    }
  }

Minnesota District and School IDs

The MDE stateOrganizationID (assigned in MDE ORG) is formatted as follows: ttddddsssmmm, where:

The MDE stateOrganizationID value is stored in Ed-Fi on the Ed-Fi EducationOrganizationIdentificationCodes collection and is surfaced via the Ed-Fi LocalEducationAgencies, Schools, and PostSecondaryEducation resource endpoints.

The Ed-Fi LocalEducationAgencyId and SchoolId are derived as follows: ttddddsss. The final three digits in sss are always zero filled (000) for the LocalEducationAgencyId. Do not use a leading zero in the LEA type portion.

Examples:

More information is available in MDE ORG, including this reference on LEA (organization) types.

Identifiers: Schools vs. Buildings

MDE’s system for identifying individual schools is independent of building or physical address. Therefore, a district may have multiple school identifiers assigned for the same building, especially if that building houses several different school classifications.

For example, the Comfrey Public School District (0081-01, or 10081000000) houses its district office, elementary, and secondary schools (along with several other programs) at 305 Ochre Street West in Comfrey (as of December 2020). However, each program gets an individual identifier, such as:

Navigation