Skip to main content

Team Operations

The Team Operations submodule handles team management, member coordination, and organizational structure administration within the DashClicks ACM system.

🎯 Overview​

This submodule manages team creation, member assignment, role coordination, and team performance tracking with comprehensive administrative oversight.

🔧 Service Methods​

Core Team Management​

getTeams()​

Retrieves comprehensive team information with member details for managed subscription products.

Core Business Logic:

  • Access Control: Validates user permissions (admin or account_manager roles only)
  • Product Team Discovery: Maps all managed subscription products (excluding 'site' and 'listings')
  • User-Team Mapping: Uses MongoDB aggregation to group users by their managed product teams
  • Team Composition: Returns structured object with team names as keys and member arrays as values
  • Member Details: Includes user ID, name, email, image, and role for each team member

Key Operations:

  1. Permission Check: Validates user has PROJECT_ROLES.ADMIN or PROJECT_ROLES.ACCOUNT_MANAGER access
  2. Team Discovery: Filters MANAGED_SUBSCRIPTIONS to exclude 'site' and 'listings'
  3. MongoDB Aggregation:
    • Matches users with dashclicks.projects.manages and active general access
    • Unwinds managed teams and groups users by team
    • Converts to key-value object format
  4. Result Formatting: Creates complete team structure with empty arrays for teams without members

Collections Used: _users

Return Type: Object with team names as keys and user arrays as values

API Endpoint: GET /v1/admin/acm/teams

createTeam() ⚠️ DEPRECATED​

Creates new teams with member assignment and role coordination.

Key Features:

  • Team Creation: New team establishment with configuration
  • Member Assignment: Initial team member assignment and role coordination
  • Icon Management: Team visual identification and branding
  • Administrative Tracking: Complete audit trail for team creation

API Endpoint: POST /v1/admin/acm/teams

Deprecation Notice: This function is no longer supported and will be removed in a future version.

updateTeam()​

Updates team membership by adding or removing users from managed product teams.

Core Business Logic:

  • Access Control: Validates user permissions (admin or account_manager roles only)
  • User Validation: Verifies all users have PROJECT_ROLES.FULFILMENT_SPECIALIST role
  • Team Operations: Supports 'add' and 'remove' operations for team membership
  • Bulk Updates: Uses MongoDB bulkWrite for efficient batch user updates
  • Data Integrity: Maintains team structure consistency during membership changes

Key Operations:

  1. Permission Check: Validates user has PROJECT_ROLES.ADMIN or PROJECT_ROLES.ACCOUNT_MANAGER access
  2. User Validation:
    • Fetches user records to verify existence
    • Validates each user has dashclicks.projects access
    • Ensures users have FULFILMENT_SPECIALIST role
  3. Team Operation Processing:
    • For 'add': Adds teamName to user's dashclicks.projects.manages array if not present
    • For 'remove': Filters teamName from user's manages array and validates team exists
  4. Bulk Database Update: Uses bulkWrite operations to update all user records efficiently

Collections Used: _users

Parameters:

  • userIds: Array of user IDs to update
  • teamName: Name of the managed product team
  • operation: Either 'add' or 'remove'

Return Type: Array of validated user data

API Endpoint: PUT /v1/admin/acm/teams

deleteTeam() ⚠️ DEPRECATED​

Removes teams from the organizational structure with member reassignment.

Key Features:

  • Team Removal: Complete team deletion with data cleanup
  • Member Reassignment: Automatic member reassignment to other teams
  • Data Integrity: Maintains data integrity during team removal
  • Administrative Tracking: Complete audit trail for team deletion

API Endpoint: DELETE /v1/admin/acm/teams

Deprecation Notice: This function is no longer supported and will be removed in a future version.

Internal Service Methods​

getUsers()​

Retrieves all users in an account with their ACM roles and team assignments.

Core Business Logic:

  • Access Control: Validates user permissions (owner or SUPER_MANAGER/MANAGER roles only)
  • User-Team Mapping: Cross-references users with AdminTeam assignments
  • Account Scoping: Filters users by specific account ID
  • Team Integration: Enriches user data with team membership information

Key Operations:

  1. Permission Check: Validates user is owner or has SUPER_MANAGER/MANAGER ACM role
  2. Parallel Data Fetch: Uses Promise.allSettled to fetch users and teams simultaneously
  3. User Aggregation: Retrieves users with name, image, and ACM role information
  4. Team Assignment: Maps users to their AdminTeam memberships with team ID and name
  5. Data Enrichment: Adds teams array to each user object with their team associations

Collections Used: _users, admin.teams

Return Type: Array of user objects with embedded team assignments

Parameters:

  • accId: Account ID to filter users
  • isOwner: Boolean indicating if requestor is account owner
  • dashclicks: User's DashClicks role information

updateUser()​

Updates user ACM roles and access permissions with team leadership validation.

Core Business Logic:

  • Access Control: Validates user permissions (owner or SUPER_MANAGER/MANAGER roles only)
  • Role Transitions: Manages ACM role changes with business rule validation
  • Team Leadership: Enforces single team lead per team constraint
  • Access Management: Enables or disables ACM access for users

Key Operations:

  1. Permission Check: Validates user is owner or has SUPER_MANAGER/MANAGER ACM role
  2. User Protection: Prevents modification of SUPER_MANAGER owners
  3. Role Update Logic:
    • For TEAM_LEAD role: Validates user doesn't already lead another team
    • When removing TEAM_LEAD: Ensures team will still have a leader
    • Sets dashclicks.general to true when assigning ACM roles
  4. Access Control: Can disable ACM access by unsetting dashclicks.acm
  5. Database Update: Updates user record and returns refreshed user data

Collections Used: _users, admin.teams

Parameters:

  • accId: Account ID for user validation
  • userId: ID of user to update
  • role: New ACM role to assign
  • enabled: Boolean to enable/disable ACM access
  • isOwner: Boolean indicating if requestor is account owner
  • dashclicks: User's DashClicks role information

Return Type: Updated user object with name, image, and dashclicks information

🏗️ Technical Architecture​

Database Collections​

The service interacts with the following MongoDB collections:

  • _users: User account information with ACM roles and team assignments
  • admin.teams ⚠️ DEPRECATED: Legacy AdminTeam model for team structure
  • User.dashclicks.projects.manages: Array field storing managed product teams per user

Integration Systems​

  • Account Management: Account hierarchy and team access integration
  • User Management: Team member user account and role coordination
  • Workspace System: Team workspace and collaboration integration
  • Analytics System: Team performance metrics and reporting integration

Business Logic​

  • Team Hierarchy: Complex team organizational structure management
  • Member Coordination: Team member assignment and role management
  • Performance Tracking: Team performance monitoring and analytics
  • Access Control: Role-based team access and permission management

🔐 Authorization Framework​

Role Requirements​

All team operations require appropriate administrative permissions:

  • ACM Admin: Full team management and organizational control
  • Team Manager: Team coordination and member management
  • HR Manager: Team member assignment and role coordination
  • Operations Manager: Team performance and organizational oversight

Permission Validation​

  • Team Access: Validates access to specific team information
  • Member Management: Ensures proper permissions for member operations
  • Organizational Control: Validates authority for team structure changes
  • Multi-tenant Access: Account-based team access and permission validation

📊 Team Analytics​

Performance Metrics​

  • Team Productivity: Team performance and output tracking
  • Member Utilization: Team member workload and assignment analytics
  • Collaboration Metrics: Team coordination and communication analytics
  • Organizational Efficiency: Team structure effectiveness and optimization

Operational Insights​

  • Team Health: Team performance and member satisfaction tracking
  • Resource Allocation: Team member assignment and workload distribution
  • Growth Analysis: Team expansion and organizational development
  • Performance Trends: Team performance trends and improvement opportunities

🔄 Integration Points​

External Systems​

  • HR Systems: Human resources integration for team member management
  • Project Management: Team-project assignment and coordination
  • Communication Platforms: Team communication and collaboration integration
  • Performance Systems: Team performance tracking and evaluation

Internal Services​

  • Account Management: Account hierarchy and team access integration
  • User Management: Team member user account and role coordination
  • Analytics System: Team performance metrics and reporting integration
  • Audit System: Comprehensive team operation audit trail

📈 Business Workflows​

Team Management​

graph TD
    A[Team Creation] --> B[Member Assignment]
    B --> C[Role Coordination]
    C --> D[Performance Tracking]
    D --> E[Team Optimization]
    E --> F[Organizational Growth]

Member Coordination​

  • Assignment Process: Team member assignment and role coordination
  • Performance Monitoring: Team member performance tracking and evaluation
  • Role Management: Team member role updates and organizational changes
  • Development Tracking: Team member growth and development coordination

🛡️ Security Features​

Data Protection​

  • Team Information Security: Secure handling of team organizational data
  • Member Privacy: Team member information protection and access control
  • Access Control: Role-based access to team information and operations
  • Audit Logging: Comprehensive logging of all team operations

Operational Security​

  • Authorization Validation: Team operation authorization and permission validation
  • Data Integrity: Team data integrity and consistency maintenance
  • Change Tracking: Team modification tracking and audit trail
  • Compliance Monitoring: Organizational policy compliance and adherence

📝 Usage Examples​

Team Coordination​

// Retrieve team information
const teams = await getTeams({
  accId: accountId,
  isOwner: true,
  dashclicks: adminRoles,
});

// Update team members
await updateTeam({
  userIds: ['user1', 'user2'],
  teamName: 'Marketing Team',
  operation: 'add',
  dashclicks: managerRoles,
});

Team Operations​

// Create new team (deprecated)
const newTeam = await createTeam({
  name: 'Development Team',
  icon: 'dev-icon',
  users: ['user1', 'user2', 'user3'],
  dashclicks: adminRoles,
});

// Delete team (deprecated)
await deleteTeam({
  teamId: 'team_123',
  dashclicks: adminRoles,
});

⚠️ Important Notes​

  • Deprecation Warning: createTeam() and deleteTeam() methods are deprecated and will be removed
  • Multi-tenant Access: Team operations require proper account-based authorization
  • Member Coordination: Team member assignments require role validation and access control
  • Organizational Structure: Team hierarchy changes require administrative oversight
  • Performance Impact: Team operations affect organizational performance and coordination
  • Data Integrity: Team modifications require careful data integrity maintenance
  • Audit Requirements: All team operations require comprehensive audit trail maintenance
💬

Documentation Assistant

Ask me anything about the docs

Hi! I'm your documentation assistant. Ask me anything about the docs!

I can help you with:
- Code examples
- Configuration details
- Troubleshooting
- Best practices

Try asking: How do I configure the API?
09:31 AM