Federation admin

Location:

Admin -> Federation -> Licenses
Admin -> Federation -> Organizations
Admin -> Federation -> Division -> [division] -> [discipline]

Use this page when you are responsible for setting up, reviewing, approving, and correcting federation licenses.

Required permission level

Different parts of the license workflow require different staff roles:

Task	Minimum role
View licenses, items, organizations	Viewer
Issue, approve, suspend, or revoke a license	Manager
Approve or reject an organization	Manager
Grant or remove license issuer access	Manager
Add or edit license items (catalog)	Administrator
Map license items to classes	Administrator
Connect Stripe	Owner

Your goals on this page

This page is the control center for:

issued licenses
license items
payment and approval review
federation Stripe payout setup

The full federation admin license workflow now spans four places:

Licenses for issued licenses and license items
Organizations for issuer role on organizations
Division -> Discipline -> Class -> License rules for accepted class products
Division -> State for class memberships and progress, while Organizations -> [organization] holds representation rows

You will normally use the admin license workflow for these jobs:

Connect Stripe so payments can work
Define the federation’s license products
Decide which organizations may act as issuers when needed
Decide which classes accept which products
Review representation and progression setup if it affects the workflow
Review, approve, activate, suspend, or correct individual licenses

Before you do anything

Make sure these are already in place:

The federation exists
Divisions and disciplines exist
Federation classes exist
You know which workflow pattern the federation follows:
- organization-managed
- self-service
- hybrid

If those are not ready yet, stop here and fix them first. The rest of the workflow depends on them.

1. Connect the federation Stripe account

Before any Stripe payment can work, the federation must connect its own Stripe account.

Steps:

Open Admin -> Federation
Edit the federation
Find the Stripe payment section
Press Connect Stripe
Complete Stripe onboarding
Return to Vote4Dance
Confirm that the federation now shows connected

What success looks like:

the federation shows Stripe as connected
organization-paid and self-paid license rows can use Stripe checkout
payments will go to the federation Stripe account

What this means

license payments go to the federation connected Stripe account
Vote4Dance keeps a 5% fee
if the federation is not connected, org-paid and self-paid license checkout cannot start
hybrid payer setups still settle into the federation Stripe account

2. Manage issued licenses

Use the first list for the actual personal license rows.

Most common use on this list

Use the issued license list when:

a new application has been submitted and you need to review it
a paid row is still waiting for approval
a license needs to be activated, suspended, or corrected
a manual fix is needed for an existing license

The list now shows:

person
status
category
type
season
payment status
payer type
application source when present
item, division, organization, validity, competition, payment references, and approval timestamps when present

Use this list when you need to:

review a newly created application
correct a wrong payer or payment state
manually activate a license
suspend or cancel an existing license
inspect whether a paid license still needs approval
inspect whether the row came from self-service, organization flow, or federation admin

Add a license manually

Press Add
Search the person in User
Optionally select License item
Set Category
Set Type
Set Season year
Set Status
Optionally set Payment status
Optionally set Payer type
Optionally set Division
Optionally set Discipline
Optionally set Organization
Optionally set Payer organization
Optionally set Competition
Optionally set Valid from
Optionally set Valid to
Optionally fill Flags JSON
Optionally fill Note
Optionally fill Payment reference
Optionally fill Invoice reference
Press Save

When to use manual creation:

backfilling licenses
correcting data imported from another system
creating a license outside the normal self-service or organization flow

When not to use manual creation:

if the federation wants a normal user-facing application flow
if you are testing whether self-service or organization application works

What each field means

User: the person who owns the license
License item: the predefined product; if selected, it controls category, type, and scope
Category: role such as dancer, judge, coach, or organizer
Type: federation-specific license type text
Season year: season or calendar year
Status: current operational state
Payment status: unpaid, paid, invoiced, waived, or refunded
Payer type: self or organization
Application source: where the row started, such as self, organization, or federation_admin
Division / Discipline: scope when the license is branch-specific
Organization: the organization attached to the license when organization context is needed
Payer organization: the organization carrying payment liability when used
Competition: required for one-time or single-competition licenses
Valid from / Valid to: date window
Flags JSON: advanced machine-readable eligibility flags
Note: internal comment
Payment reference: payment identifier or external booking reference
Invoice reference: invoice identifier

Payment fields and Stripe behavior

Payment status tracks Vote4Dance’s recorded payment state for the license
Payer type says whether the checkout should be started by the person or the organization
Application source says where the workflow started
Stripe checkout is only available when the federation has connected Stripe
a successful checkout pays into the federation Stripe account and keeps 5% as the Vote4Dance fee

Approval and activation behavior

What happens when you change status manually:

federation admin can create or update licenses directly
if a federation admin sets a license to active, the backend stores approved_by_federation_at
a paid license can still remain pending if federation or organization approval is required by the federation rules

What to check before activating:

The correct person owns the license
The selected license item is correct
The payer and payment status are correct
Competition id is filled if the item is competition-scoped
Organization is correct when required
Any federation-side approval requirement has been satisfied

What to do next after activation:

confirm the row shows the correct final status
confirm the payment state still matches the real payment
if the license is competition-scoped, confirm the correct competition is attached

3. Manage license items

Use License items to define the actual products available in the federation.

Use this section when

you are setting up the federation for the first time
you are adding a new annual, one-time, or branch-specific product
you need to stop using an old license product without deleting history

Add a license item

Press Add in License items
Fill the form
Press Save

Field meaning

Name: visible product name
Code: short internal code
Category: role of the item
Type: federation-specific type label
Band: optional grouping such as high, low, or similar
Division: division scope
Discipline: discipline scope inside the division
Organization mode:
- optional
- required
- disallowed
Competition scope:
- season
- single_competition
Status: active or inactive
Price: Stripe/payment reference amount
Currency: payment currency
Note: internal comment

Practical recommendation:

keep names obvious for non-experienced users
put scope in the name when needed
examples:
- Annual competition license
- One-time competition license
- Division A high license
- Advanced competition license

What good setup looks like:

users can tell the products apart by name alone
one-time products are clearly marked
scope is visible in the name when needed
inactive products stay out of normal use

4. Map license items to classes

Use Division -> [division] -> [discipline] -> class -> License rules when a class must accept exact license items.

Use this section when

you want registration to reject the wrong license immediately
different divisions or classes need different accepted products
you want progression checks to use the same class-specific product logic

The current class rule editor only offers active license items that match the same division and discipline as the class.

Add a class mapping

Open Admin -> Federation -> Division
Open the correct division
Open the correct discipline
Find the class
Press License rules
Press Add
Choose License item
Tick whether it is required for:
- registration
- progression
Press Save

Important behavior

the backend rejects mappings where item scope and class scope do not match
registration and progression checks now prefer explicit class mappings over generic license interpretation

Use explicit class mappings when:

the federation has different license requirements by division
different classes inside a division accept different license products
you want the system to reject the wrong license item immediately at registration

This is the safest model for branch-specific federations.

What success looks like:

the correct class accepts the intended product
the wrong class does not accept it
registration and progression behave as expected in testing

5. Manage organization approval and representation

Use Organizations when you need to manage federation-side organization status.

Current organization detail responsibilities:

approve the organization itself inside the federation
approve or remove license issuer access
review organization-linked licenses
review organization users
manage representation rows for the organization

How representation works

Representation is now license-derived. The system determines which organization a dance team represents by looking at the active dancer licenses held by the team’s members. The organization that holds the most active dancer licenses for those members is used as the effective representation.

The representation history table still records explicit assignments and overrides, but the primary source of truth is the license data.

Assign organization

Use the Assign organization button on the organization detail page when a dance team needs to be linked to an organization and no active license already establishes that link.

Steps:

Open Admin -> Federation -> Organizations
Open the organization
Press Assign organization in the representations section
Select the dance team
Select the organization
Optionally add a reason
Press OK

Use this when:

a team has no active dancer licenses yet and needs an explicit organization assignment
a ranking import created a team without a license and you want to fix the representation
the license-derived organization is incorrect and an explicit assignment is needed

Rename team

Use the Rename team button on any representation row to change the team name without changing its organization or license state.

Changing the organization on an active license

You cannot change the organization field on an active license directly. If the organization on an active license is wrong:

Cancel or revoke the existing license
Issue a new license with the correct organization

This applies to individual license rows. It does not affect explicit representation assignments made through the Assign organization workflow.

6. Manage issuer role on organizations

Use Organizations for federations where only approved organizations may issue or approve licenses.

Use this section when

the federation only allows approved organizations to handle certain license applications
organization-managed applications are failing because issuer approval is missing

Add a license issuer

Open Admin -> Federation -> Organizations
Find the organization
Press Add or Edit
Set Status
Optionally set Type
Optionally set Approved at
Optionally set Note
Press Save

Status meaning

pending
approved
suspended
revoked

7. Manage class memberships and progress

Use Division -> State for division-scoped class memberships and progression rows.

Use this page when you need to:

review current team memberships in federation classes
add or remove class membership rows
review or edit progress rows for a team inside that division

This page is division-scoped. Representation stays on the organization detail page instead.

8. What federation admin should check during rollout

For a new federation setup, verify this sequence:

The correct divisions and disciplines exist
The federation Stripe account is connected
License items are scoped correctly
Single-competition items really use Competition scope = single_competition
Issuer role is configured on the right organizations before org-managed applications begin
Each competitive class has the right accepted items
Payment status and payer type look correct on real applications

Common mistakes

Creating license items before the federation class structure exists
Forgetting to connect Stripe before telling users to pay
Using generic product names that dancers and clubs cannot distinguish
Forgetting to map a competition-scoped item to the relevant class
Looking for class license rules in Licenses instead of under Division -> Discipline
Looking for issuer setup in Licenses instead of Organizations
Activating a paid license even though federation or organization approval is still required

If the workflow is confusing

The page supports the full setup flow, but it does not choose federation policy for you.

Federation admin still needs the federation’s internal license setup decisions available when:

defining the first license item set
deciding which classes accept which items
deciding when payment should be enough and when extra approval should still be required