Ed-Fi Alliance

https://docs.ed-fi.org/
Admin
Ed-Fi Alliance provides education data standards, APIs, and tools for seamless, secure data exchange...
Tokens:837,805
Snippets:10,435
Trust Score:9.9
Update:4 months ago
Show doc for...
Tokens:
Raw
### Multi-Tenant Installation Configuration (PostgreSQL)

Source: https://docs.ed-fi.org/reference/ods-api/7.2/getting-started/binary-installation/singlemulti-tenant-installation-steps

Example configuration for a multi-tenant installation using PostgreSQL. Includes tenant-specific security and admin connection strings.

```json
{
  "InstallType": "MultiTenant",
  "ApiSettings": {
      "Engine": "PostgreSQL",
      "OdsTokens": "Tenant1ODS;Tenant2ODS",
      "Features": [
        ...
        {
            "IsEnabled": true,
            "Name": "MultiTenancy"
        },
        ...
      ]
  },
  "Tenants" : {
    "Tenant1": {
        "ConnectionStrings": {
            "EdFi_Security":  "host=localhost;port=5432;username=postgres;database=EdFi_Security_Tenant1;application name=EdFi.Ods.WebApi",
            "EdFi_Admin":  "host=localhost;port=5432;username=postgres;database=EdFi_Admin_Tenant1;application name=EdFi.Ods.WebApi"
        }
      },
    "Tenant2": {
        "ConnectionStrings": {
            "EdFi_Security":  "host=localhost;port=5432;username=postgres;database=EdFi_Security_Tenant2;application name=EdFi.Ods.WebApi",
            "EdFi_Admin":  "host=localhost;port=5432;username=postgres;database=EdFi_Admin_Tenant2;application name=EdFi.Ods.WebApi"
        }
      }
  }
}
```

--------------------------------

### Single-Tenant Installation Configuration (PostgreSQL)

Source: https://docs.ed-fi.org/reference/ods-api/7.2/getting-started/binary-installation/singlemulti-tenant-installation-steps

Example configuration for a single-tenant installation using PostgreSQL. Update connection strings and API settings as needed.

```json
{
  "ConnectionStrings": {
      "EdFi_Ods": "host=localhost;port=5432;username=postgres;database=EdFi_{0};Application Name=EdFi.Ods.WebApi",
      "EdFi_Security": "host=localhost;port=5432;username=postgres;database=EdFi_Security;Application Name=EdFi.Ods.WebApi",
      "EdFi_Admin": "host=localhost;port=5432;username=postgres;database=EdFi_Admin;Application Name=EdFi.Ods.WebApi",
      "EdFi_Master": "host=localhost;port=5432;username=postgres;database=postgres;Application Name=EdFi.Ods.WebApi"
  },
  "InstallType": "SingleTenant",
  "ApiSettings": {
      "Engine": "PostgreSQL",
      "MinimalTemplateScript": "TPDMCorePostgreSqlMinimalTemplate",
      "PopulatedTemplateScript": "TPDMCorePostgreSqlPopulatedTemplate"
  }
}
```

--------------------------------

### Install and Run OneRoster from Source

Source: https://docs.ed-fi.org/reference/oneroster/getting-started/deploy-postgres

Installs Node.js dependencies and starts the OneRoster service from the source code. Navigate to the project root before running these commands.

```bash
cd edfi-oneroster

npm install

node server.js
```

--------------------------------

### Single-Tenant Installation Configuration (SQL Server)

Source: https://docs.ed-fi.org/reference/ods-api/7.2/getting-started/binary-installation/singlemulti-tenant-installation-steps

Example configuration for a single-tenant installation using SQL Server. Update connection strings and API settings as needed.

```json
{
  "ConnectionStrings": {
      "EdFi_Ods": "server=(local);trusted_connection=True;database=EdFi_{0};Application Name=EdFi.Ods.WebApi",
      "EdFi_Security": "server=(local);trusted_connection=True;database=EdFi_Security;persist security info=True;Application Name=EdFi.Ods.WebApi",
      "EdFi_Admin": "server=(local);trusted_connection=True;database=EdFi_Admin;Application Name=EdFi.Ods.WebApi",
      "EdFi_Master": "server=(local);trusted_connection=True;database=master;Application Name=EdFi.Ods.WebApi"
  },
  "InstallType": "SingleTenant",
  "ApiSettings": {
      "Engine": "SQLServer",
      "MinimalTemplateScript": "TPDMCoreMinimalTemplate",
      "PopulatedTemplateScript": "TPDMCorePopulatedTemplate"
  }
}
```

--------------------------------

### Multi-Tenant Installation Configuration (SQL Server)

Source: https://docs.ed-fi.org/reference/ods-api/7.2/getting-started/binary-installation/singlemulti-tenant-installation-steps

Example configuration for a multi-tenant installation using SQL Server. Includes tenant-specific security and admin connection strings.

```json
{
  "InstallType": "MultiTenant",
  "ApiSettings": {
      "Engine": "SQLServer",
      "OdsTokens": "Tenant1ODS;Tenant2ODS",
      "Features": [
        ...
        {
            "IsEnabled": true,
            "Name": "MultiTenancy"
        },
        ...
      ]
  },
  "Tenants" : {
    "Tenant1": {
        "ConnectionStrings": {
            "EdFi_Security":  "server=(local);trusted_connection=True;database=EdFi_Security_Tenant1;persist security info=True;application name=EdFi.Ods.WebApi;encrypt=False",
            "EdFi_Admin":  "server=(local);trusted_connection=True;database=EdFi_Admin_Tenant1;application name=EdFi.Ods.WebApi;encrypt=False"
        }
      },
    "Tenant2": {
        "ConnectionStrings": {
            "EdFi_Security":  "server=(local);trusted_connection=True;database=EdFi_Security_Tenant2;persist security info=True;application name=EdFi.Ods.WebApi;encrypt=False",
            "EdFi_Admin":  "server=(local);trusted_connection=True;database=EdFi_Admin_Tenant2;application name=EdFi.Ods.WebApi;encrypt=False"
        }
      }
  }
}
```

--------------------------------

### Example PowerShell Output

Source: https://docs.ed-fi.org/reference/ods-api/getting-started/source-code-installation

This is an example output showing the version details of PowerShell. It helps to confirm that a compatible version is installed.

```powershell
PS D:\> $PSVersionTable.PSVersion  

  

Major  Minor  Patch  PreReleaseLabel BuildLabel  

-----  -----  -----  --------------- ----------  

5      1      22621  4111  
```

--------------------------------

### Bulk Load Client Installation Confirmation

Source: https://docs.ed-fi.org/reference/ods-api/7.2/how-to-guides/how-to-load-the-ods-with-sample-xml-data-using-bulk-load-client-utility

Example output confirming the successful installation of the Ed-Fi Bulk Load Client. This indicates the tool is ready for use.

```text
You can invoke the tool using the following command: EdFi.BulkLoadClient.Console
Tool 'edfi.suite3.bulkloadclient.console' (version '7.2.413') was successfully installed.
```

--------------------------------

### Install Google Classroom Extractor Dependencies

Source: https://docs.ed-fi.org/getting-started/edfi-exchange/technology/ed-fi-lms-toolkit/lms-toolkit-user-guide/lms-toolkit-user-guide-extract-data-from-the-lms

Command to navigate to the Google Classroom extractor directory and install its dependencies using Poetry. This is a one-time setup step.

```bash
cd [INSTALL DIRECTORY]/LMS-Toolkit/src/google-classroom-extractor/  

# One-time execution:  

poetry install
```

--------------------------------

### Install and Build Application

Source: https://docs.ed-fi.org/reference/admin-app/system-administrators/installing

Clones the Admin App repository, installs dependencies, and builds the API.

```bash
sudo -u edfiadminapp bash

cd /opt/edfiadminapp

git clone https://github.com/Ed-Fi-Alliance-OSS/AdminApp-v4.git .

npm ci

npm run build:api
```

--------------------------------

### Example GET Response Body

Source: https://docs.ed-fi.org/reference/data-exchange/api-guidelines/design-and-implementation-guidelines/api-implementation-guidelines/handling-optimistic-concurrency-with-etags

This is the body of a GET response corresponding to the example ETag header, containing the resource's data.

```json
{
    "schoolId":12345,
    "classPeriodName":"4th Period",
    "classroomIdentificationCode":"abcde",
    "localCourseCode":"Math 101",
    "termTypeId":1,
    "schoolYear":2012,
    "uniqueSectionCode":"3FJ56",
    "sequenceOfCourse":1,
    "availableCredit":1.5
}

```

--------------------------------

### Initialize Development Environment with Sample Plugin

Source: https://docs.ed-fi.org/reference/ods-api/how-to-guides/how-to-deploy-an-extension-plugin

Run the `Initialize-PowershellForDevelopment.ps1` script from the `<source directory>\Ed-Fi-ODS-Implementation` folder to download and deploy the sample extension plugin artifacts to the local database.

```powershell
.\Initialize-PowershellForDevelopment.ps1  

Initdev  


```

--------------------------------

### Example HTTP Request to Get a Student Record

Source: https://docs.ed-fi.org/reference/ods-api/7.2/client-developers-guide/error-response-knowledge-base

This example demonstrates an HTTP GET request to retrieve a specific student record by its unique identifier. Access to this record depends on the client credentials having the appropriate associations (e.g., studentSchoolAssociation).

```http
GET https://api-stage.ed-fi.org:443/v7.1/api/data/v3/ed-fi/students/e31429919e6546e8905635d7858f2e80  
Authorization: Bearer fd964160527941a39875e821d2622088  
  
  

```

--------------------------------

### Copy Environment Example File

Source: https://docs.ed-fi.org/reference/admin-app/system-administrators/installing

Copies the example environment file to a new file for customization. This is the first step in configuring your deployment.

```bash
cp .env.example .env
```

--------------------------------

### Build Frontend Application

Source: https://docs.ed-fi.org/reference/admin-app/system-administrators/installing

Navigate to the cloned repository and execute the build command for the frontend.

```bash
# Go to the cloned folder
cd Ed-Fi-AdminApp
```

--------------------------------

### Example URL for GET Students

Source: https://docs.ed-fi.org/getting-started/provider-playbook/specifics-by-provider-type/student-information-system-providers/student-information-system-providers-implementation/sis-providers-sandbox/sis-providers-activity-1

This is the URL used to make a GET request to retrieve all student records from the Ed-Fi API v5.3 sandbox.

```text
https://api.ed-fi.org/v5.3/api/data/v3/ed-fi/students
```

--------------------------------

### Install Canvas Extractor Dependencies

Source: https://docs.ed-fi.org/getting-started/edfi-exchange/technology/ed-fi-lms-toolkit/lms-toolkit-user-guide/lms-toolkit-user-guide-extract-data-from-the-lms

Command to navigate to the Canvas extractor directory and install its dependencies using Poetry. This is a one-time setup step.

```bash
cd [INSTALL DIRECTORY]/LMS-Toolkit/src/canvas-extractor/  

# One-time execution:  

poetry install
```

--------------------------------

### Example Authorization Header for GET /students

Source: https://docs.ed-fi.org/getting-started/provider-playbook/implementation/getting-started-with-apis/all-providers/all-providers-activity-1

This shows the format of the Authorization header, including a Bearer token, that your browser sent with the HTTP GET request.

```plaintext
--header 'Authorization: Bearer [some long string of letters and numbers]'
```

--------------------------------

### Install Student Equity Collection

Source: https://docs.ed-fi.org/getting-started/edfi-exchange/technology/analytics-middle-tier/user-guide/collections/student-equity-collection

Installs the Student Equity Collection using the 'EQUITY' option code. Ensure you have the AMT Deployment Guide for further details.

```bash
.\EdFi.AnalyticsMiddleTier.Console.exe -c "..." -o EQUITY
```

--------------------------------

### CourseOffering Resource Example

Source: https://docs.ed-fi.org/reference/data-exchange/api-guidelines/design-and-implementation-guidelines/api-design-guidelines/resources/validation-of-natural-and-foreign-keys

This example demonstrates a CourseOffering resource where 'schoolId' values within 'schoolReference' and 'sessionReference' must be unified and match.

```json
{
  "id": "5394aabc256d4b938a8137d3b971b372",
  "courseReference": {
    "courseCode": "ALG-1",
    "educationOrganizationId": 255901001
  },
  "schoolReference": {
    "schoolId": 255901001
  },
  "sessionReference": {
    "schoolId": 255901001,
    "schoolYear": 2022,
    "sessionName": "2021-2022 Fall Semester"
  },
  "localCourseCode": "ALG-1"
}
```

--------------------------------

### Install Chronic Absenteeism Collection

Source: https://docs.ed-fi.org/getting-started/edfi-exchange/technology/analytics-middle-tier/user-guide/collections/chronic-absenteeism-collection

Installs the Chronic Absenteeism collection using the option code 'CHRAB'. Refer to the AMT Deployment Guide for more details.

```bash
.\EdFi.AnalyticsMiddleTier.Console.exe -c "..." -o CHRAB
```

--------------------------------

### Sample Output for Registering a New Client

Source: https://docs.ed-fi.org/reference/admin-api/getting-started/admin-api-2.3-newer/technical-articles/quick-start-calling-admin-api-2x-using-python

This is the expected JSON output upon successful registration of a new client.

```json
{
  "title": "Registered client 1 successfully.",
  "status": 200
}

  

  
```

--------------------------------

### Start PostgreSQL 16.x Instance (Linux)

Source: https://docs.ed-fi.org/reference/ods-api/technical-articles/upgrading-admin-and-security-to-pg16

Use pg_ctl to start the new PostgreSQL 16.x server instance on Linux.

```bash
/usr/pgsql-16/bin/pg_ctl -D <new PGDATA directory> start  
```

--------------------------------

### Install Dependencies with Poetry

Source: https://docs.ed-fi.org/getting-started/edfi-exchange/technology/ed-fi-lms-toolkit/lms-toolkit-user-guide/lms-toolkit-user-guide-extract-data-from-the-lms

Run this command once to install all necessary project dependencies.

```bash
poetry install
```

--------------------------------

### Copy Environment File

Source: https://docs.ed-fi.org/reference/oneroster/getting-started/docker-compose

Copy the example environment file to a new file. Use '.env.5.2.0.example' for DS 5.2 or '.env.4.0.0.example' for DS 4.0.

```bash
cp .env.5.2.0.example .env.5.2.0    # or .env.4.0.0.example for DS 4.0
```

--------------------------------

### GET Response Body with Metadata

Source: https://docs.ed-fi.org/reference/data-exchange/api-guidelines/design-and-implementation-guidelines/api-design-guidelines/rest-api-conventions/get-requests

An example of a GET response body for a single resource, including optional metadata attributes like _etag, _lastModifiedDate, and _lineage.

```json
{
  "id": "986a44e7cfcf4019b7b2ea4a640c6d20",
  "schoolReference": {
    "schoolId": 255901107
  },
  "schoolYearTypeReference": {
    "schoolYear": 2022
  },
  "calendarCode": "2010605675",
  "calendarTypeDescriptor": "uri://ed-fi.org/CalendarTypeDescriptor#Student Specific",
  "gradeLevels": [],
  "_etag": "5250159352800270276",
  "_lastModifiedDate": "2024-03-29T18:23:57.2882372Z",
  "_lineage": {
      "sourceSystem": "Example SIS",
      "apiCreateTimestamp": 1711754637,
      "apiModifyTimestamp": 1711761837,
      "modifications": []
  }
}
```

--------------------------------

### Clone and Set Up Ed-Fi Data Management Service Locally

Source: https://docs.ed-fi.org/blog/2025/03/13

Follow these steps to clone the Data-Management-Service repository, check out the 0.4.0 tag, and start the local DMS environment with search engine UI and configuration services enabled. This includes configuring Keycloak.

```bash
git clone https://github.com/Ed-Fi-Alliance-OSS/Data-Management-Service  

cd Data-Management-Service  

git checkout 0.4.0  

# Start all required services inside of Docker  
cd eng\docker-compose  
cp .env.example .env  
.\start-local-dms.ps1 -EnableSearchEngineUI -EnableConfig -r  

# Configure Keycloak  
.\setup-keycloak.ps1  
```

--------------------------------

### Install Code Generation Utility Manually

Source: https://docs.ed-fi.org/reference/ods-api/7.2/platform-dev-guide/utilities/code-generation-utility

This command installs the code generation utility manually. It checks if the utility is already installed and reports its location and version. This is useful for local development setups outside of the standard initdev process.

```powershell
PS D:\ed-fi\Ed-Fi-ODS-Implementation> Install-CodeGenUtility  
  
------------------------------  
    Install-CodeGenUtility  
------------------------------  
  
EdFi.Suite3.Ods.CodeGen version 7.2.1119 is already installed at D:\ed-fi\Ed-Fi-ODS-Implementation\tools  
Install-CodeGenUtility done in 1s.  
  
Duration Task  
-------- ----  
00:01.75 Install-CodeGenUtility  
```

--------------------------------

### View Security Visualization Tool Help

Source: https://docs.ed-fi.org/reference/ods-api/platform-dev-guide/utilities/security-visualization-tool

Run the tool with the --help parameter to view all available command-line arguments and their descriptions. This is useful for understanding the tool's capabilities and configuration options.

```powershell
PS D:\Ed-Fi-ODS\Utilities\GenerateSecurityGraphs\GenerateSecurityGraphs> .\bin\Debug\net10.0\GenerateSecurityGraphs.exe --help
```

--------------------------------

### Installation Error - Assembly Not Found

Source: https://docs.ed-fi.org/getting-started/edfi-exchange/technology/analytics-middle-tier/deployment-guide

Example of a common installation error in non-Windows environments where a required assembly is not found. This typically indicates a permissions issue with extracted files.

```text
Error:  

An assembly specified in the application dependencies manifest (EdFi.AnalyticsMiddleTier.Console.deps.json) was not found:  

package: 'System.Data.SqlClient', version '4.6.0'  

path: 'runtimes/unix/lib/netcoreapp2.1/System.Data.SqlClient.dll'
```

--------------------------------

### PostgreSQL Connection String Example

Source: https://docs.ed-fi.org/getting-started/edfi-exchange/technology/analytics-middle-tier/deployment-guide

Example of a standard .NET connection string for PostgreSQL.

```sql
host=yourServer;database=EdFi_ODS_Readonly;username=postgres;
```

--------------------------------

### Multi-Tenant Installation Parameters

Source: https://docs.ed-fi.org/reference/admin-api/getting-started/admin-api-2.3-newer/installation-2.3/iis-installation-powershell

This PowerShell script configures parameters for a multi-tenant Admin API installation, including tenant-specific database settings. The EncryptionKey must align with your ODS/API setup.

```powershell
$authenticationSettings = @{
    Authority = "https://localhost/adminapi"
    IssuerUrl = "https://localhost/adminapi"
    SigningKey = "Base64-encoded string"
    AllowRegistration = $false
}

# IMPORTANT: This key MUST match the OdsConnectionStringEncryptionKey
# used in your Ed-Fi ODS / API installation. See:
# https://docs.ed-fi.org/reference/ods-api/getting-started/binary-installation/singlemulti-tenant-installation-steps/#prepare-installation-script
$odsEncryptionKey = "Base64-encoded string"

$packageSource = Split-Path $PSScriptRoot -Parent
$adminApiSource = "$packageSource/AdminApi"

$p = @{
    IsMultiTenant = $true
    ToolsPath = "C:/temp/tools"
    AdminApiMode = "v2"
    DbConnectionInfo = $dbConnectionInfo
    PackageVersion = '2.3.1.0'
    PackageSource = $adminApiSource
    AuthenticationSettings = $authenticationSettings
    StandardVersion = '5.2.0'
    EncryptionKey = $odsEncryptionKey
    Tenants = @{
            Tenant1 = @{
                AdminDatabaseName = "EdFi_Admin_Tenant1"
                SecurityDatabaseName = "EdFi_Security_Tenant1"
            }
            Tenant2 = @{
                AdminDatabaseName = "EdFi_Admin_Tenant2"
                SecurityDatabaseName = "EdFi_Security_Tenant2"
            }
    }
}
```

--------------------------------

### Example API Path for CourseOffering Resource

Source: https://docs.ed-fi.org/getting-started/provider-playbook/common-use-cases/chronic-absenteeism-solution-guide/understanding-ed-fi-apis/api-resource-keys

Demonstrates how to access a CourseOffering resource using its unique Resource ID in the API path.

```HTTP
/courseOfferings/d0fd729db6ee4a7bbc989720e4f833f5
```

--------------------------------

### Sample Output for Get a Vendor

Source: https://docs.ed-fi.org/reference/admin-api/getting-started/admin-api-2.3-newer/technical-articles/quick-start-calling-admin-api-2x-using-python

Example JSON output when retrieving details for a specific vendor.

```json
{
  "Id": 9,
  "company": "ACME Education",
  "namespacePrefixes": "ACME",
  "contactName": "Road Runner",
  "contactEmailAddress": "roadrunner@acme.edu"
}
```

--------------------------------

### SQL Server Connection String Example

Source: https://docs.ed-fi.org/getting-started/edfi-exchange/technology/analytics-middle-tier/deployment-guide

Example of a standard .NET connection string for SQL Server.

```sql
server=yourServer;database=EdFi_ODS_ReadOnly;integrated security=sspi;
```
Tokens:
Raw