Collaboration

​

Overview

​

Collaboration Model

​

Key Fields

• project: Foreign key to the Project
• collaborator: Foreign key to User (Person or Team)
• role: Collaboration role (Admin, Manager, Editor, Reporter, Reader)
• is_incognito: Whether collaborator is hidden in UI and billing
• created_by: User who added the collaborator
• created_at: Timestamp when added
• updated_by: User who last updated the collaborator
• updated_at: Timestamp of last update

​

Collaboration Roles

​

Admin

• Manage collaborators
• Delete the project
• Update project settings
• Upload/download files
• Create and apply deltas
• Trigger packaging jobs

​

Manager

• Manage collaborators (cannot remove admins)
• Update project settings
• Upload/download files
• Create and apply deltas
• Trigger packaging jobs

​

Editor

• Upload/download files
• Create and apply deltas
• Trigger packaging jobs
• Cannot modify project settings or collaborators

​

Reporter

• Create deltas (submit field data)
• Download project files
• Cannot upload files directly
• Cannot apply deltas

​

Reader

• Download project files
• View project information
• Cannot make any changes

​

Adding Collaborators

​

API Endpoint

POST /api/v1/collaborators/{projectid}/

​

Request Body

{
  "collaborator": "username",
  "role": "editor"
}

​

Example with cURL

curl -X POST https://app.qfield.cloud/api/v1/collaborators/{projectid}/ \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "collaborator": "field_worker_1",
    "role": "reporter"
  }'

​

Validation Rules

1. Cannot add project owner - The owner is implicitly an admin
2. Organization membership required - For organization-owned projects, collaborators must be organization members
3. No duplicate collaborators - Each user can only be added once per project
4. Subscription limits - Private projects enforce max collaborator limits based on the owner’s plan

​

Organization-Owned Projects

​

Member Requirements

if project.owner.is_organization:
    organization = Organization.objects.get(pk=project.owner.pk)
    if collaborator.is_person:
        # Must be organization member or owner
        if not (
            organization.members.filter(member=collaborator).exists()
            or collaborator == organization.organization_owner
        ):
            raise ValidationError("Cannot add non-member as collaborator")

​

Team Collaborators

{
  "collaborator": "@organization_name/team_name",
  "role": "editor"
}

​

Managing Collaborators

​

List Collaborators

GET /api/v1/collaborators/{projectid}/

​

Update Collaborator Role

PATCH /api/v1/collaborators/{projectid}/{username}/

{
  "role": "manager"
}

​

Remove Collaborator

DELETE /api/v1/collaborators/{projectid}/{username}/

​

Permissions System

​

Role Origin

class RoleOrigins(models.TextChoices):
    PROJECTOWNER = "project_owner"
    ORGANIZATIONOWNER = "organization_owner"
    ORGANIZATIONADMIN = "organization_admin"
    COLLABORATOR = "collaborator"
    TEAMMEMBER = "team_member"
    PUBLIC = "public"

​

Permission Checks

• can_create_collaborators(user, project) - Check if user can add collaborators
• can_update_collaborators(user, project) - Check if user can modify collaborators
• can_delete_collaborators(user, project) - Check if user can remove collaborators
• can_read_collaborators(user, project) - Check if user can view collaborator list

​

Subscription Limits

​

Collaborator Validation

max_premium_collaborators_per_private_project_q = Q(
    project__owner__useraccount__current_subscription_vw__plan__max_premium_collaborators_per_private_project=V(-1)
) | Q(
    project__owner__useraccount__current_subscription_vw__plan__max_premium_collaborators_per_private_project__gte=count
)

• -1: Unlimited collaborators
• n > 0: Maximum of n collaborators

​

Direct Collaborators

@property
def direct_collaborators(self) -> ProjectCollaboratorQueryset:
    if self.owner.is_organization:
        exclude_pks = [self.owner.organization.organization_owner_id]
    else:
        exclude_pks = [self.owner_id]
    
    return (
        self.collaborators.skip_incognito()
        .filter(collaborator__type=User.Type.PERSON)
        .exclude(collaborator_id__in=exclude_pks)
    )

​

Incognito Collaborators

is_incognito = models.BooleanField(
    default=False,
    help_text="Collaborators marked as incognito work normally but are not listed in the UI or counted in subscription limits"
)

• Function normally with assigned role
• Hidden from collaborator lists in UI
• Not counted toward subscription limits
• Used for OPENGIS.ch support access

​

Project Roles View

class ProjectRolesView(models.Model):
    user = models.ForeignKey(User, related_name="project_roles")
    project = models.ForeignKey(Project, related_name="user_roles")
    name = models.CharField(choices=ProjectCollaborator.Roles.choices)
    origin = models.CharField(choices=ProjectQueryset.RoleOrigins.choices)
    is_incognito = models.BooleanField()

​

Best Practices

​

Role Selection Guidelines

• Admin: Project leads, IT administrators
• Manager: Field coordinators, data managers
• Editor: GIS analysts, data collectors with upload rights
• Reporter: Field workers using QField mobile
• Reader: Stakeholders needing view-only access

​

Security Considerations

1. Principle of least privilege - Grant minimum necessary permissions
2. Regular audits - Review collaborator lists periodically
3. Organization structure - Use teams for consistent permissions
4. Public projects - Remember all authenticated users can read public projects

​

Performance

• Use skip_incognito() when counting collaborators for billing
• Query with select_related("collaborator") to avoid N+1 queries
• Filter invalid collaborators with validated(skip_invalid=True)

​

API Reference

​

List All Collaborators

GET /api/v1/collaborators/{projectid}/

[
  {
    "collaborator": "user1",
    "role": "editor",
    "created_at": "2024-01-15T10:30:00Z",
    "created_by": "admin_user"
  }
]

​

Get Collaborator Details

GET /api/v1/collaborators/{projectid}/{username}/

​

Update Role

PUT /api/v1/collaborators/{projectid}/{username}/

​

Remove Collaborator

DELETE /api/v1/collaborators/{projectid}/{username}/

​

Related Resources

• Projects - Creating and managing projects
• Organizations - Organization membership and teams
• Permissions - Detailed permission matrix