Flow Logo

Core Flow Concepts

Groups

Overview

Groups in Flow provide a powerful way to collaborate on bioinformatics projects. By creating groups, you can share projects, samples, data, and pipeline executions with your team members, lab colleagues, or external collaborators.

Groups enable:

  • Team collaboration - Share resources with multiple users at once
  • Access control - Manage who can view, edit, or share your data
  • Simplified permissions - Grant access to entire teams without individual sharing
  • Organizational structure - Reflect your lab or institutional hierarchy

Core Concepts

Group Membership Levels

Each user in a group has one of three membership levels:

  1. Invited - User has been invited but hasn't accepted yet
  2. Member - Regular member with access to shared resources
  3. Admin - Can manage the group and its members

Permission Types

When sharing resources with a group, you can grant three levels of permissions:

  1. View - Read-only access to the resource
  2. Edit - Can modify the resource
  3. Share - Can share the resource with others

Group Ownership

Resources in Flow can be owned by either:

  • Individual users - Traditional single-owner model
  • Groups - Shared ownership by all group admins

Group ownership is particularly useful for core facilities, shared instruments, or collaborative projects where no single person should have exclusive control.

Creating Groups

To create a new group:

  1. Navigate to your profile menu and select "Groups"
  2. Click "Create New Group"
  3. Provide:
    • Group Name - A descriptive name for your group
    • Slug - A unique identifier (auto-generated from name)
    • Description - Optional details about the group's purpose
# Using the Python client
import flowbio

client = flowbio.Client()
group = client.create_group(
    name="Smith Lab RNA-seq",
    description="RNA-seq analysis group for the Smith Lab"
)

Managing Groups

Inviting Members

As a group admin, you can invite new members:

  1. Go to the group's page
  2. Click "Invite Members"
  3. Enter the email addresses of users to invite
  4. Select their initial permission level

Invited users will receive an email notification and must accept the invitation to join.

Managing Members

Group admins can:

  • Promote members to admin - Share group management responsibilities
  • Demote admins to member - Remove admin privileges
  • Remove members - Revoke access to group resources
  • View member list - See all current members and their roles

Leaving a Group

Members can leave a group at any time through the group settings. However, the last admin cannot leave a group - they must either:

  • Promote another member to admin first
  • Delete the group entirely

Sharing with Groups

Sharing Projects

To share a project with a group:

  1. Navigate to the project settings
  2. Click "Share with Group"
  3. Select the group and permission level
  4. Click "Share"

All group members will immediately gain access according to the permission level you selected.

Sharing Samples

Samples can be shared with groups either:

  • Individually - Share specific samples
  • In bulk - Share multiple samples at once
  • Automatically - When uploaded to a group-owned project

Sharing Data

Data files follow the same sharing model:

# Share data with a group
data_file = client.get_data("data-123")
data_file.share_with_group(
    group_slug="smith-lab", 
    permission="view"
)

Sharing Executions

Pipeline execution results can be shared with groups, allowing team members to:

  • View execution status and logs
  • Download results
  • Use outputs in subsequent analyses

Group Permissions

Permission Inheritance

When a resource is shared with a group:

  1. All current members receive the specified permissions
  2. New members automatically gain access when they join
  3. Members who leave lose access immediately

Permission Hierarchy

Permissions follow a hierarchy:

  • Share permission includes edit and view
  • Edit permission includes view
  • View is read-only access

Checking Permissions

You can verify your permissions on any resource:

# Check if you can edit a sample
sample = client.get_sample("sample-123")
if sample.can_edit:
    print("You can edit this sample")

API Reference

REST Endpoints

  • GET /api/groups/ - List your groups
  • POST /api/groups/ - Create a new group
  • GET /api/groups/{slug}/ - Get group details
  • PUT /api/groups/{slug}/ - Update group (admin only)
  • DELETE /api/groups/{slug}/ - Delete group (admin only)

Member Management

  • POST /api/groups/{slug}/invite/ - Invite members
  • POST /api/groups/{slug}/remove/ - Remove a member
  • POST /api/groups/{slug}/promote/ - Promote to admin
  • POST /api/groups/{slug}/demote/ - Demote to member
  • POST /api/groups/{slug}/leave/ - Leave group

Best Practices

Group Organization

  1. Create purpose-specific groups - "Smith Lab RNA-seq" rather than just "Smith Lab"
  2. Use descriptive names - Include the institution, lab, or project name
  3. Document group purpose - Use the description field to explain the group's role
  4. Regular membership review - Periodically review and update member lists

Security Considerations

  1. Limit admin count - Only promote trusted users to admin
  2. Review sharing settings - Ensure appropriate permission levels
  3. Remove inactive members - Maintain group hygiene
  4. Use group ownership carefully - Understand that all admins have full control

Collaboration Patterns

  1. Project-based groups - Create groups for specific research projects
  2. Lab-wide groups - Share common resources and protocols
  3. Core facility groups - Manage client access to services
  4. Teaching groups - Share datasets and pipelines with students

Common Workflows

Setting Up a New Lab

# Create lab group
lab_group = client.create_group(
    name="Johnson Lab",
    description="Computational biology lab at University X"
)

# Create project
project = client.create_project(
    name="RNA-seq Time Series",
    group_owner=lab_group.slug  # Group owns the project
)

# All lab members can now access the project

Core Facility Management

# Create client group for a specific project
client_group = client.create_group(
    name="Project ABC - Smith Lab",
    description="Sequencing project for Smith Lab grant ABC123"
)

# Share results when ready
execution = client.get_execution("exec-123")
execution.share_with_group(
    group_slug=client_group.slug,
    permission="view"  # Clients can view but not modify
)

Teaching Environment

# Create course group
course_group = client.create_group(
    name="BIOL 585 - Fall 2024",
    description="Computational Biology course"
)

# Share example data
for sample in course_samples:
    sample.share_with_group(
        group_slug=course_group.slug,
        permission="view"
    )

# Share analysis pipeline
pipeline.share_with_group(
    group_slug=course_group.slug,
    permission="edit"  # Students can modify for assignments
)

Troubleshooting

Cannot Invite Users

  • Verify you have admin privileges in the group
  • Check that the user has a Flow account
  • Ensure the email address is correct

Cannot Leave Group

  • You may be the last admin - promote another member first
  • Check for resources you own that should be transferred

Missing Shared Resources

  • Verify your group membership status
  • Check the permission level on the shared resource
  • Ensure you've accepted the group invitation

Permission Denied

  • Confirm the resource was shared with sufficient permissions
  • Check your membership level in the group
  • Verify the sharing user had permission to share
Previous
Genomes
Next
Permissions