Page Comparison

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 OAuth endpoints, Instance type (e.g., Sandbox, Shared Instance), Token timeouts, Enabling Admin and Security datastore connections, Token timeouts, Enabling / disabling features. See See the following sections for more details on important configuration options:

Table of Contents

maxLevel	2
minLevel	2

Include Page

	_Platform Developers' Guide - Sidebar
	_Platform Developers' Guide - Sidebar

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.

.WebApiappsettingsjsonEdFi.Ods.

Application	Location	Setting Name	Value	Description
EdFi.Ods.SandboxAdmin	appsettings.json	OAuthUrl	Example: http://site-address:port/oauth	Points to the root of the authorization API in the Ed-Fi ODS / API.
EdFi.Ods	.	ApiSettings:Mode	Example: Sandbox, SharedInstance, YearSpecific, DistrictSpecific	The component settings for the API. See the following section on Developers' Guide for more information on this setting.	SwaggerUI	appsettings.json	WebApiVersionUrl	Example: http://site-address:port/	Points to the version endpoint in the Ed-Fi ODS / API.
EdFi.Ods.WebApi	appsettings.json	ConnectionStrings:EdFi_Admin	Server=(local); Database=EdFi_Admin; Trusted_Connection=True; Application Name=EdFi.Ods.WebApi;	Connection to Admin database
EdFi.Ods.WebApi	appsettings.json	ConnectionStrings:EdFi_Security	Server=(local); Database=EdFi_Security; Trusted_Connection=True; Persist Security Info=True; Application Name=EdFi.Ods.WebApi;	Connection to Security database
EdFi.Ods.WebApi	appsettings.json	ApiSettings:OdsConnectionStringEncryptionKey	Example: JivjQAm53kz9IaBLUJIk+Rd+1YaKNZ88PkxjiSsQNRQ=	AES Encryption key used to encrypt ODS connection strings configured in the Admin database. (Required everywhere other than development environment)

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:

Application

Location

Setting Name

Value

Description

EdFi.Ods.SwaggerUI

appsettings.json

SwaggerUIOptions:OAuthConfigObject:ClientId

Example:
rcKsguTICAaBm9PxyUW4i

Optionally provides the value to prefill in the "key" field of auth.

EdFi.Ods.SwaggerUI

appsettings.json

SwaggerUIOptions:OAuthConfigObject:ClientSecret

Example:
t0CklTOfMBGZNPgVQDLHh

Optionally provides the value to prefill in the "secret" field of auth.

EdFi.Ods.SwaggerUI

appsettings.json

Years

Example:

Code Block

language	xml

"Years": [
    {
      "Year": "2020"
2023",
      "IsDefault": false
    },
    {
      "Year": "2024",
      "2021"IsDefault": true
    }
  ],

Optionally provides settings for years shown in swagger for School Year selection. This setting is applicable if using Context-Based Routing for Year-Specific ODS

EdFi.Ods.SwaggerUI

appsettings.json

Tenants

Example:

Code Block

language	xml

 "Tenants": [
    {
      "Tenant": "Tenant1",
      "IsDefault": true
    },
    {
      "YearTenant": "2022"
"Tenant2",
      "IsDefault": false
    }
  ],

Optionally provides settings for years tenants shown in swagger for School Year tenant selection. This setting is applicable in a YearSpecific APIif using Multi Tenant Configuration.

EdFi.Ods.SandboxAdmin

appsettings.json

User

Example:

Code Block

language	xml

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.SandboxAdmin

appsettings.json

MaximumSandboxesPerUser

Example: 5

The maximum number of sandboxes a sandbox admin user can create.

EdFi.Ods.SandboxAdmin

appsettings.json

DefaultClaimSetName

Example: SIS Vendor

The claim set name for the default application for sandbox application clients.

EdFi.Ods.SandboxAdmin

appsettings.json

MailSettings:Smtp:UserName

Example: User.Name

The username of the credentials that are used to create an SMTP client for sending email messages from the Sandbox Admin application for new user creation and password resets

EdFi.Ods.SandboxAdmin

appsettings.json

MailSettings:Smtp:Password

Example: abcd1234

The password of the credentials that are used to create an SMTP client for sending email messages from the Sandbox Admin application for new user creation and password resets

EdFi.Ods.SandboxAdmin

appsettings.json

MailSettings:Smtp:From

Example: no-reply@ed-fi.org

The email address that will show up in the FROM field of any email messages sent from the Sandbox Admin application

EdFi.Ods.SandboxAdmin

appsettings.json

MailSettings:Smtp:Host

Example: smtp.example.com

The SMTP server that is used for sending email messages from the Sandbox Admin application. This value is necessary when the DeliveryMethod of Network is specified

EdFi.Ods.SandboxAdmin

appsettings.json

MailSettings:Smtp:Port

Example: 25

The port number used by the SMTP server for email messages. If no value is specified, then the default of 25 is used.

EdFi.Ods.SandboxAdmin

appsettings.json

MailSettings:Smtp:DeliveryMethod

Example: Network

Specifies how email messages are delivered. The valid choices for this are:

Network - Email is sent through the network to an existing SMTP server
PickupDirectoryFromIis - Email is copied to the pickup directory used by IIS for delivery via its SMTP service
SpecifiedPickupDirectory - Email is copied to the specified directory for processing by an external mail application

EdFi.Ods.SandboxAdmin

appsettings.json

MailSettings:Smtp:SpecifiedPickupDirectory:PickupDirectoryLocation

Example: C:\\temp\\location\\emails

When a Delivery Method of SpecifiedPickupDirectory is used, this is the folder where email messages will be saved to, to be picked up by an external mail application for processing and sending

EdFi.Ods.SandboxAdmin

appsettings.json

MailSettings:Smtp:EnableSsl

Example: true

Indicates whether SSL encryption is used when establishing a connection with the SMTP server. This value is only applicable when the DeliveryMethod of Network is specified

EdFi.Ods.WebApi

appsettings.json

QueueAutoCreate

Example: 1

Whether 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.WebApi

appsettings.json

CommitUploadCommandMessageEndPoint

Example: localhost

The server hosting the message queues.

EdFi.Ods.WebApi

appsettings.json

ApiSettings:BearerTokenTimeoutMinutes

Example: 30

The amount of time that an OAuth token remains valid.

EdFi.Ods.WebApi

appsettings.json

ApiSettings:Caching:Security:AbsoluteExpirationMinutes

Anchor

	securitymetadatacache
	securitymetadatacache

Example: 10

The 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.WebApi

appsettings.json

ApiSettings:Caching:Descriptors:AbsoluteExpirationSeconds

Example: 1800

Number of seconds after which the descriptor cache is refreshed.

EdFi.Ods.WebApi

appsettings.json

ApiSettings:Caching:PersonUniqueIdToUsi:AbsoluteExpirationSeconds

Example: 14400

Number 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.WebApi

appsettings.json

ApiSettings:Caching:PersonUniqueIdToUsi:SlidingExpirationSeconds

Example: 14400

Number of seconds after which a PersonUniqueIdToUsi mapping is refreshed if not accessed.

EdFi.Ods.WebApi

appsettings.json

ApiSettings:Caching:PersonUniqueIdToUsi:CacheSuppression:SuppressStudentCacheStudent

Example: false

Indicates whether student UniqueId/USI mappings should be cached, or retrieved on demand with each request. When set to true, caching is suppressed.

EdFi.Ods.WebApi

appsettings.json

ApiSettings:Caching:PersonUniqueIdToUsi:CacheSuppression:SuppressStaffCacheStaff

Example: false

Indicates whether staff UniqueId/USI mappings should be cached, or retrieved on demand with each request. When set to true, caching is suppressed.

EdFi.Ods.WebApi

appsettings.json

ApiSettings:Caching:PersonUniqueIdToUsi:CacheSuppression:SuppressParentCacheParent

Example: truefalse

Indicates whether parent UniqueId/USI mappings should be cached, or retrieved on demand with each request. When set to true, caching is suppressed. For use with data standard 4.0 and below. This setting has no affect after data standard 4.0.

EdFi.Ods.WebApi

appsettings.json

ApiSettings:Caching:PersonUniqueIdToUsi:CacheSuppression:Contact

Example: true

Indicates whether contact UniqueId/USI mappings should be cached, or retrieved on demand with each request. When set to true, caching is suppressed. For use with data standard 5.0 and above. This setting has no affect before data standard 5.0.

EdFi.Ods.WebApi

appsettings.json

ApiSettings:Features:Extensions

true

Enables 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.WebApi

appsettings.json

ApiSettings:Features:UniqueIdValidation

false

Enables Unique ID System Integration. Must implement IUniqueIdToIdValueMapper and register within the implementation within the WebApi.

EdFi.Ods.Web.Api

appsettings.json

ApiSettings:Features:TokenInfo

true

Enables the token_info introspective endpoint.

EdFi.Ods.Web.Api

appsettings.json

Plugin:Folder

Example: ../../Plugin

Configures the plugin folder that API looks to deploy extensions dynamically.

EdFi.Ods.Web.Api

appsettings.json

Plugin:Scripts

Example: [ 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.

Website	secrets.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.

Versions Compared

Old Version 12

New Version Current

Key

Required Configuration Settings

Optional Configuration Settings

Environment Configuration

Secret Manager