Configuration Details

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:

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.

Application	Location	Setting Name	Value	Description
EdFi.Ods.Admin.Web	Web.config	OAuthUrl	Example: http://site-address:port/oauth	Points to the root of the authorization API in the Ed-Fi ODS / API.
EdFi.Ods.WebApi	Web.config	owin:appStartup	Startup	In prior versions this value would be "ConfigurationSpecificSandbox" by default. The component settings are now specified with the apiStartup:type key shown below, and the owin:appStartup key should now be the static value of "Startup".
EdFi.Ods.WebApi	Web.config	apiStartup:type	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.SwaggerUI	Web.config	swagger.webApiMetadataUrl	Example: http://site-address:port/metadata/, http://site-address:port/metadata/schoolyear (for YearSpecific instance)	The location of the Swagger metadata in the Ed-Fi ODS / API.
EdFi.Ods.SwaggerUI	Web.config	swagger.webApiVersionUrl	Example: 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:

Application	Location	Setting Name	Value	Description
EdFi.Ods.SwaggerUI	Web.config	swagger.prepopulatedKey	Example: populatedTemplate	Optionally provides the value to prefill in the "key" field of auth.
EdFi.Ods.SwaggerUI	Web.config	swagger.prepopulatedSecret	Example: populatedTemplateSecret	Optionally provides the value to prefill in the "secret" field of auth.
EdFi.Ods.Admin.Web	Web.config	<initialization>	Example: Contents on Web.Config <initialization configSource="AdminCredential.config" /> Sample content of AdminCredential.config <initialization enabled="true"> <users> <add name="Test Admin" email="test@ed-fi.org" password="jZX5l193mIbpBP8cCdGwq" admin="true"> <namespacePrefixes> <namespacePrefix name="uri://ed-fi.org" /> <namespacePrefix name="uri://gbisd.edu" /> </namespacePrefixes> <sandboxes> <sandbox name="Populated Demonstration Sandbox" key="xY3VDi0wWdMg2XHtcb4F6" secret="7HFEdT5pNUW1mwZctGX9O" type="Sample" refresh="true" /> <sandbox name="Minimal Demonstration Sandbox" key="kgdb3JFViyYurBG5vsQO1" secret="FJ0Zud3YnaKNImXTS2sP5" type="Minimal" refresh="true" /> </sandboxes> </add> </users> </initialization>	Custom configuration section (sourced by an external config file AdminCredential.config) for defining 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. Also the keys <namespacePrefixes> and <namespacePrefix> are case sensitive.
EdFi.Ods.WebApi	Web.config	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	Web.config	CommitUploadCommandMessageEndPoint	Example: localhost	The server hosting the message queues.
EdFi.Ods.WebApi	Web.config	BearerTokenTimeoutMinutes	Example: 30	The amount of time that an OAuth token remains valid.
EdFi.Ods.WebApi	Web.config	SecurityMetadataCacheTimeoutMinutes	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	Web.config	defaultPageSizeLimit	Example:500	Maximum number of records that can be fetched in a GET request.
EdFi.Ods.WebApi	Web.config	changeQueries:featureIsEnabled	false	Enables the Changed Record Queries endpoints (database configuration remains a separate step, see Using the Changed Record Queries)
EdFi.Ods.WebApi	Web.config	openApiMetadata:featureIsEnabled	true	Enables the metadata API endpoint, used by Swagger UI. Production deployments should disable this by changing the value to false .
EdFi.Ods.WebApi	Web.config	composites:featureIsEnabled	true	Enables the Composites API endpoints, including the default Enrollments composite and any custom composites that have been added to the installation.
EdFi.Ods.WebApi	Web.config	profiles:featureIsEnabled	true	Enables the Profiles endpoints, including the default profiles and any custom profiles that have been added to the installation.
EdFi.Ods.WebApi	Web.config	identityManagement:featureIsEnabled	true	Enables the Identity API endpoints
EdFi.Ods.WebApi	Web.config	extensions:featureIsEnabled	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	Web.config	uniqueIdValidation:featureIsEnabled	false	Enables Unique ID System Integration. Must implement IUniqueIdToIdValueMapper and register within the implementation within the WebApi.
EdFi.Ods.Web.Api	Web.config	tokenInfo:featureIsEnabled	true	Enables the token_info introspective endpoint.

Configuration Transformations

To support easy configuration setup for PostgresSQL and Cloud instances, Web.config transformations are provided. Settings that apply to all configurations are found in Web.Base.Config. Specific transformations (e.g., Release, Debug, Npgsql, AzureCloudODS) are found in the respective Web.*Configuration*.config file.

CI/CD pipelines can make use of these transformations. In addition, transformations can also be applied using the following PowerShell commands by navigating to Ed-Fi-ODS-Implementation directory:

> CD C:\Ed-Fi-ODS-Implementation
> .\Initialize-PowershellForDevelopment.ps1
> Invoke-TransformConfigFile -sourceFile 'C:\Ed-Fi-ODS-Implementation\Application\EdFi.Ods.WebApi\Web.Base.config' -transformFiles 'C:\Ed-Fi-ODS-Implementation\Application\EdFi.Ods.WebApi\Web.npgsql.config'  -destinationFile 'C:\Ed-Fi-ODS-Implementation\Application\EdFi.Ods.WebApi\Web.config'