A newer version of the Ed-Fi ODS / API is now available. See the Ed-Fi Technology Version Index for a link to the latest version.

Configuration Details

Owned by Ian Christopher (Deactivated)
Last updated: Apr 24, 2023 by Vinaya Mayya
6 min read

The Ed-Fi ODS / API is configurable in a number of ways. Since the source code is available to licensees, one could argue that everything is configurable. But, what we’re discussing in this section are things like settings and options that do not require a change to the compiled code.

Key configuration points include: OAuth endpoints, Instance type (e.g., Sandbox, Shared Instance), Token timeouts, Enabling / disabling features. See the following sections for more details on important configuration options: 


Developers' Guide Contents

Find out more about how to develop platforms based on the Ed-Fi ODS / API v5.3:

 

Required Configuration Settings

Some configuration must be done for every Ed-Fi ODS / API platform instance. Examples of required configurations include database connection strings, SMTP server locations, and similar.

To make it easier for developers to install and run the Ed-Fi ODS / API, the default download from source control is pre-configured with values appropriate for a developer or single-server test instance of the system. 


ApplicationLocationSetting NameValueDescription
EdFi.Ods.SandboxAdminappsettings.jsonOAuthUrlExample: http://site-address:port/oauthPoints to the root of the authorization API in the Ed-Fi ODS / API.
EdFi.Ods.WebApiappsettings.jsonApiSettings:ModeExample: Sandbox, SharedInstance, YearSpecific, DistrictSpecific
The component settings for the API. See the following section on Developers' Guide for more information on this setting.
EdFi.Ods.SwaggerUIappsettings.jsonWebApiVersionUrlExample: http://site-address:port/Points to the version endpoint in the Ed-Fi ODS / API.
A deployment to a staging or production instance is usually more involved, and requires additional configuration. Required configurations for a production instance can be found in the Deployment section of this documentation.

Optional Configuration Settings

Although this list of settings is not exhaustive, other important and useful optional configuration values include:
ApplicationLocationSetting NameValueDescription
EdFi.Ods.SwaggerUIappsettings.jsonSwaggerUIOptions:OAuthConfigObject:ClientIdExample:
rcKsguTICAaBm9PxyUW4i		Optionally provides the value to prefill in the "key" field of auth.
EdFi.Ods.SwaggerUIappsettings.jsonSwaggerUIOptions:OAuthConfigObject:ClientSecretExample:
t0CklTOfMBGZNPgVQDLHh		Optionally provides the value to prefill in the "secret" field of auth.
EdFi.Ods.SwaggerUIappsettings.jsonYears

Example: 

"Years": [
    {
      "Year": "2020"
    },
    {
      "Year": "2021",
      "IsDefault": true
    },
    {
      "Year": "2022"
    }
  ],
Optionally provides settings for years shown in swagger for School Year selection. This setting is applicable in a YearSpecific API.
EdFi.Ods.SandboxAdminappsettings.jsonUser
Example:
Contents on appsettings.json
 "User": {
        "Test Admin": {
            "Email": "test@ed-fi.org",
            "Admin": "true",
            "NamespacePrefixes": [
                "uri://ed-fi.org",
                "uri://gbisd.org"
            ],
            "Password": "zSKj8DdR4mQlPp3X2i1ra",
            "Sandboxes": {
                "Minimal Demonstration Sandbox": {
                    "Key": "FLqUvMPSoG4ryp7HiRBmX",
                    "Type": "Minimal",
                    "Secret": "bhJfA6qt7iNP3Xd5as9O0",
                    "Refresh": "false"
                },
                "Populated Demonstration Sandbox": {
                    "Key": "rcKsguTICAaBm9PxyUW4i",
                    "Type": "Sample",
                    "Secret": "t0CklTOfMBGZNPgVQDLHh",
                    "Refresh": "false"
                }
            }
        }
    }
Defines automatically created user accounts and sandboxes. Also configures automatic refreshes of sandboxes to a clean state. Each user entry will be created with the given email/password, and the sandboxes defined underneath it will also be created for the type and key/secret values.
New: Must include the NamespacePrefixes elements, to deploy what namespaces for the associated vendor. This collection is required, and at least one namespace prefix is required. 

EdFi.Ods.SandboxAdminappsettings.jsonMaximumSandboxesPerUserExample: 5The maximum number of sandboxes a sandbox admin user can create. 
EdFi.Ods.SandboxAdminappsettings.jsonDefaultClaimSetNameExample: SIS VendorThe claim set name for the default application for sandbox application clients.
EdFi.Ods.WebApiappsettings.jsonQueueAutoCreateExample: 1Whether or not a message queue should be created if it is not found. For Azure or Active Directory queues, this should be 0.
EdFi.Ods.WebApiappsettings.jsonCommitUploadCommandMessageEndPointExample: localhostThe server hosting the message queues.
EdFi.Ods.WebApiappsettings.jsonBearerTokenTimeoutMinutesExample: 30The amount of time that an OAuth token remains valid.
EdFi.Ods.WebApiappsettings.json

Caching:Security:AbsoluteExpirationMinutes

Example: 10The amount of time the security metadata from EdFi_Security database is cached. E.g., if it is set to 10 mins, the claim set changes will reflect in the API at least after 10 mins without needing to recycle API process.
EdFi.Ods.WebApiappsettings.jsonCaching:Descriptors:AbsoluteExpirationSecondsExample: 1800Number of seconds after which the descriptor cache is refreshed.
EdFi.Ods.WebApiappsettings.jsonCaching:PersonUniqueIdToUsi:AbsoluteExpirationSecondsExample: 14400Number of seconds after which the PersonUniqueIdToUsi mapping is refreshed. This settings is applied only when SlidingExpirationSeconds is not provided or set to 0.
EdFi.Ods.WebApiappsettings.jsonCaching:PersonUniqueIdToUsi:SlidingExpirationSecondsExample: 14400Number of seconds after which a PersonUniqueIdToUsi mapping is refreshed if not accessed. 
EdFi.Ods.WebApiappsettings.jsonCaching:PersonUniqueIdToUsi:SuppressStudentCacheExample: falseIndicates whether student UniqueId/USI mappings should be cached, or retrieved on demand with each request. When set to true,  caching is suppressed.
EdFi.Ods.WebApiappsettings.jsonCaching:PersonUniqueIdToUsi:SuppressStaffCacheExample: falseIndicates whether staff UniqueId/USI mappings should be cached, or retrieved on demand with each request. When set to true,  caching is suppressed.
EdFi.Ods.WebApiappsettings.jsonCaching:PersonUniqueIdToUsi:SuppressParentCacheExample: trueIndicates whether parent UniqueId/USI mappings should be cached, or retrieved on demand with each request. When set to true,  caching is suppressed.
EdFi.Ods.WebApiappsettings.jsondefaultPageSizeLimitExample: 500Maximum number of records that can be fetched in a GET request.
EdFi.Ods.WebApiappsettings.jsonApiSettings:Features:ChangeQueriestrueEnables the Changed Record Queries endpoints (database configuration remains a separate step, see Using the Changed Record Queries).
EdFi.Ods.WebApiappsettings.jsonApiSettings:Features:OpenApiMetadatatrueEnables the metadata API endpoint, used by Swagger UI. Production deployments should disable this by changing the value to false.
EdFi.Ods.WebApiappsettings.jsonApiSettings:Features:CompositestrueEnables the Composites API endpoints, including the default Enrollments composite and any custom composites that have been added to the installation.
EdFi.Ods.WebApiappsettings.jsonApiSettings:Features:ProfilestrueEnables the Profiles endpoints, including the default profiles and any custom profiles that have been added to the installation.
EdFi.Ods.WebApiappsettings.jsonApiSettings:Features:IdentityManagementfalseEnables the Identity API endpoints.
EdFi.Ods.WebApiappsettings.jsonApiSettings:Features:ExtensionstrueEnables the API endpoints created for all Extensions. An installation that is not customized at all and still has the GrandBend and Sample extensions can disable this feature in production.
EdFi.Ods.WebApiappsettings.jsonApiSettings:Features:UniqueIdValidationfalseEnables Unique ID System Integration. Must implement IUniqueIdToIdValueMapper and register within the implementation within the WebApi. 
EdFi.Ods.Web.Apiappsettings.jsonApiSettings:Features:TokenInfotrueEnables the token_info introspective endpoint.
EdFi.Ods.Web.Apiappsettings.jsonPlugin:FolderExample: ../../PluginConfigures the plugin folder that API looks to deploy extensions dynamically.
EdFi.Ods.Web.Apiappsettings.jsonPlugin:ScriptsExample: [ tpdm ]Configures the script (located in plugin folder by default) responsible for downloading the extension plugins and placing them in the plugin folder.

Environment Configuration

While appsettings.json provides the primary configuration for the ASP.NET Core applications in the ODS / API solution, appsettings.Environment.json can be used to override the settings in appsettings.json in deployment environments. In development environment, initdev creates appsettings.Development.json to override settings for development environment. Note that the settings in appsettings.Development.json are overwritten every time initdev is executed. See Configuration in ASP.NET Core for more details. 

Secret Manager 

In development environments ASP.NET Core applications in the ODS / API solution uses secret manager tool to provide a way for setting overrides away from the projects so that they aren't accidentally checked into source control. To set overrides, you can either use the .NET CLI Tool 

or Manage User Secrets gesture in Visual Studio. 

Both of the above methods will create a secret.json file in the local machine's user profile folder and will override settings in appsettings.Development.json.

Websitesecrets.json location in Windows
Ed-Fi ODS / API%APPDATA%\Microsoft\UserSecrets\f1506d66-289c-44cb-a2e2-80411cc690ec
Sandbox Administration %APPDATA%\Microsoft\UserSecrets\f1506d66-289c-44cb-a2e2-80411cc690ea
Ed-Fi ODS / API Documentation%APPDATA%\Microsoft\UserSecrets\f1506d66-289c-44cb-a2e2-80411cc690eb

e.g., Following secret.json overrides the default 'GrandBend' dataset and deploys with 'Glendale' sample dataset.

 

See Safe storage of app secrets in development in ASP.NET Core for more details.