Global Administration Tasks – Setup Guide
This guide walks you through the initial global administration setup in the Ed-Fi Admin App. It is designed to help system administrators configure the core elements required for tenant and environment management. Where additional detail or screenshots are needed, you’ll find clear TODO markers.
1. Environments
Note: The default environment setup attempts to connect to AWS. If you are not using AWS, you will encounter errors at this step. You must replace or bypass the AWS-specific configuration to proceed.
Creating a New Environment
To create a new environment:
-
Navigate to Home > Environments
-
Click Connect new environment
-
Fill in the following fields:
Field Description Using Starting Blocks from Education Analytics? Toggle this switch ON if you are using Starting Blocks for your Ed-Fi deployment. Otherwise, leave it OFF. Name Enter a descriptive name for this environment. Ed-Fi API Discovery URL Enter the URL where the Ed-Fi ODS/API discovery endpoint is available (e.g., https://api.example.org
).Management API Discovery URL Enter the URL where the Admin API discovery endpoint is available. Environment Label Enter a label to identify this environment (e.g., "production", "development", "staging"). -
Click Save to create the environment.
Important:
- All URL fields must be valid, accessible endpoints
- The system will attempt to validate these connections when you save
Granting Ownership to Environments
For an environment to be managed, you must grant ownership to a team. This process allows team members to manage the environment with their different privilege levels. Follow these steps:
- Select the environment
- Click "Grant Ownership"
From step 2, follow the guide in Managing Resource Ownership to complete this process.
Environment Validations
- When an URL is invalid the error would be shown in the specific field.
- When creating an environment, the app autodetects whether it's a v6 or v7 environment. Based on this detection, the app will configure tenants accordingly. For v6 environments, there will be a default tenant created automatically. For v7 environments, you'll be able to create multiple tenants.
Single Tenant V6
Single Tenant V7
Multi-Tenant V7
2. Teams
Teams allow you to organize users and control their access to resources within the Admin App. Creating teams is essential for proper privilege management.
Creating a New Team
- Navigate to Global > Teams in the main navigation menu
- Click Create Team button
- Fill in the following information:
- Name: Enter a descriptive name for the team (e.g., "District Admins", "API Managers")
- Click Save to create the team
Best Practice:
- Use clear, descriptive names that indicate the team's purpose
Managing Teams
After creating a team, you'll have access to several important management functions:
-
Assume Team Role: Click the "Assume" button to switch to this team's context, allowing you to manage resources on behalf of the team. When you assume a team role, you can access and modify all resources the team has been granted ownership to, based on the team's assigned roles and privileges.
-
Grant Resource Ownership: Use the "Add resource" button to give the team access to specific resources like environments, tenants, or applications. This defines what this team can manage within the system.
-
Manage Team Membership: Click the "Add user" button to add users to this team. Users added to the team will inherit the access permissions defined by the team's role assignments.
These management options make it easy to configure exactly what each team can see and do within the Ed-Fi Admin App.
3. Team Memberships
Team memberships connect users to teams and determine their level of access within those teams.
Adding a Team Membership
- Navigate to Global > Team Memberships in the main navigation menu
- Click Create Team Membership button
- Fill in the following information:
- Team: Select the team this membership applies to.
- User: Select user account.
- Role: Select the role with the appropriate level of access within the team.
- Click Save to create the membership
Common Role Types Explained:
- Admin: Full administrative access to manage settings, resources, and perform all administrative functions
- Standard: Standard access to work with resources with limited administrative capabilities
- Viewer: Read-only access to resources and settings without modification privileges
4. Roles
Roles determine what actions users can perform within the Admin App. Each role contains a set of privileges that can be assigned or revoked.
Configuring Role Privileges
- Navigate to Global > Roles in the main navigation menu
- Find and click on the role you want to modify (e.g., Admin, Standard, Viewer)
- In the privileges list, select or unselect the privileges you want to grant to the role
- Click Save after modifying the role
Role Types
The Type field in the role configuration specifies the context where this role applies:
- User team: Roles that determine permissions within a specific team context
- User global: Roles that apply globally across the system for users
- Resource ownership: Roles that define permissions for managing specific resources
Critical Warning:
Do NOT enable the "row-count" permission (
team.sb-environment.edfi-tenant.ods:read-row-counts
).This permission enables the "row count" button on the ODS page, but this feature is not yet functional in this release of Admin App. Enabling it will cause errors.
5. Ownerships
Ownerships define which teams have access to specific resources in the system. Managing ownerships is crucial for proper access control and delegation of responsibilities.
Note: You will not be able to configure ownerships until an environment is created (see Step 1). If you are blocked by AWS dependencies, resolve those first.
Managing Resource Ownership
- Select the resource type (Environment, Tenant, Application, etc.)
- Select the specific resource (it may be pre-selected depending on context)
- Choose the team that should have ownership
- Select the appropriate role that defines permission level
- Click "Save"
Types of Resources That Can Be Owned
- Whole environment: Grant teams access to manage entire environments
- Tenant: Allow teams to manage specific tenants within an environment
- Ods: Define which teams can access specific ODS instances
- Ed-Org: Grant teams access to manage educational organizations
- Integration provider: Allow teams to manage integration providers
The ownership form is dynamic and adapts to your resource type selection. When you choose a specific resource type, the form will update to display only the relevant resources available for that category, streamlining the ownership assignment process.
Removing Ownerships
If you need to revoke access:
- Navigate to Global > Ownerships in the main navigation menu
- Locate the ownership you want to remove
- Click the delete (trash) icon
- Confirm the deletion when prompted
Creating Applications (Admin API v2 Mode)
To create applications in Admin API v2 mode, you must first populate the ODS instance information in the database manually. This is a prerequisite before you can register any applications.
Required Manual Database Configuration
- Connect to your database using your preferred SQL client
- Execute the following SQL to insert ODS instance records:
INSERT INTO dbo.odsinstances ("name", instancetype, connectionstring)
VALUES
('EdFi_Ods_255901', 'DistrictSpecific', 'host=SERVER_1;port=5432;username=postgres;password=CHANGEME;database=EdFi_Ods_255901'),
('EdFi_Ods_255902', 'DistrictSpecific', 'host=SERVER_2;port=5432;username=postgres;password=CHANGEME;database=EdFi_Ods_255902');
Important:
- Replace
SERVER_1
,SERVER_2
, andCHANGEME
with your actual server names and credentials- After inserting these records, you must restart the ODS/API application container for the changes to take effect
- This manual step will be automated in a future release