Managing Projects

This guide covers day-to-day project management including updating details, archiving and restoring projects, switching contexts, and handling project lifecycle operations.

Project Management Overview

As a project member or administrator, you can perform various operations to keep your projects organized and functional. This guide covers all management aspects from viewing to archival.

Viewing Projects

List All Projects

View all projects in your workspace(s):

query ListProjects {
  getWorkspaceProjects(workspaceIDs: ["workspace-uuid-here"]) {
    workspaceID
    projects {
      id
      name
      key
      workspaceID
      userID
      archived
      createdAt
      projectMembers {
        id
        userID
        role
        user {
          firstName
          lastName
          email
        }
      }
    }
  }
}

What You Get:

• All projects where you're a member
• Grouped by workspace
• Member information
• Archive status

Multiple Workspaces:

query MultiWorkspaceProjects {
  getWorkspaceProjects(
    workspaceIDs: [
      "workspace-1-uuid",
      "workspace-2-uuid",
      "workspace-3-uuid"
    ]
  ) {
    workspaceID
    projects {
      id
      name
      archived
    }
  }
}

Current Workspace Only:

# Omit workspaceIDs to use current workspace
query CurrentWorkspaceProjects {
  getWorkspaceProjects {
    workspaceID
    projects {
      id
      name
    }
  }
}

View Specific Project

Get detailed information about a single project:

query GetProjectDetails {
  getProject(id: "project-uuid-here") {
    id
    name
    key
    workspaceID
    userID
    archived
    createdAt
    projectMembers {
      id
      userID
      role
      createdAt
      user {
        id
        firstName
        lastName
        email
      }
    }
  }
}

Updating Projects

Update Project Name

Modify project name:

mutation UpdateProjectName {
  editProject(
    input: {
      id: "project-uuid-here"
      name: "New Project Name"
    }
  ) {
    id
    name
    updatedAt
  }
}

Requirements:

• Must have project.update permission
• Must be project member
• Name must not be empty

Use Cases:

• Rebrand initiative
• Clarify project purpose
• Fix typos
• Align with team conventions

Example Renames:

• "Project Alpha" → "Customer Portal Backend"
• "New Project" → "Q1 Marketing Campaign"
• "Test" → "Mobile App iOS Development"

warning

Currently, only the project name can be updated. Other fields like status or workspace association are immutable after creation.

Project Lifecycle Operations

Archive Project (Soft Delete)

Archive project while preserving all data:

mutation ArchiveProject {
  archiveProject(id: "project-uuid-here") {
    id
    name
    archived
  }
}

Effects:

• archived field set to true
• Project becomes inactive
• Members lose access
• All data preserved (workflows, bots, knowledge bases)
• Can be restored anytime
• Uses project.update permission (not delete)

Use Cases:

• Completed projects (keep for reference)
• Temporarily inactive projects
• Seasonal initiatives (end of season)
• Projects on hold
• Testing completed features

What Happens to Resources:

• Workflows: Preserved but inactive
• Bots: Stopped but configuration saved
• Knowledge bases: Read-only archive
• Members: Maintain association but no access
• Permissions: Preserved for restoration

Restore Archived Project

Unarchive a previously archived project:

mutation RestoreProject {
  unarchiveProject(id: "project-uuid-here") {
    id
    name
    archived
  }
}

Effects:

• archived field set to false
• Project becomes active again
• Members regain access
• All resources reactivated
• Workflows can execute
• Bots can be started

Restoration Checklist:

• Verify all team members still need access
• Check resource dependencies
• Test workflows and bots
• Update documentation
• Notify team of reactivation

Use Cases:

• Resuming paused project
• Restarting seasonal initiative
• Bringing back reference project
• Recovering accidentally archived project

Delete Project (Future Feature)

info

Currently, projects use archive-only pattern. Hard deletion is not exposed in the current API, providing safety against accidental data loss.

Why Archive Instead of Delete:

• ✅ Data preserved for future reference
• ✅ Can be restored if decision changes
• ✅ Maintains audit trail
• ✅ No accidental data loss
• ✅ Compliance and records management

Switching Project Context

Switch Active Project

Change your current project context:

mutation SwitchProject {
  switchProject(projID: "target-project-uuid")
}

Returns: New JWT token with updated project context

Validation:

1. Checks you're a project member
2. Verifies project belongs to current workspace
3. Ensures project is not archived
4. Validates RBAC resource permissions

What Changes:

• Current project context in JWT
• Project-scoped permissions
• Resource visibility
• API operation defaults

What Stays Same:

• User identity
• Workspace context
• Organization association
• Authentication state

Client Implementation:

async function switchToProject(projectId) {
  try {
    const { data } = await apolloClient.mutate({
      mutation: SWITCH_PROJECT_MUTATION,
      variables: { projID: projectId }
    });

    // Store new JWT
    localStorage.setItem('authToken', data.switchProject);

    // Reload app with new context
    window.location.reload();
  } catch (error) {
    console.error('Project switch failed:', error);
    alert('Cannot switch to project. Verify you are a member.');
  }
}

Common Scenarios:

1. Multi-Project Developer:

Morning: Switch to "Backend API"
  → Work on authentication workflow

Afternoon: Switch to "Frontend App"
  → Build UI components

Evening: Switch to "Documentation"
  → Update API docs

2. Client Work:

Client A Project: Website redesign work
Client B Project: Marketing automation
Client C Project: Mobile app development

3. Environment Switching:

Development Project: Active feature work
Staging Project: Testing and QA
Production Project: Monitoring only

Project Member Management

View Project Members

See all members in a project:

query GetMembers {
  getProject(id: "project-uuid-here") {
    projectMembers {
      id
      userID
      role
      createdAt
      user {
        firstName
        lastName
        email
      }
    }
  }
}

Remove Project Member

Remove a user from the project:

mutation RemoveProjectMember {
  removeProjectMember(
    input: {
      projectID: "project-uuid-here"
      userID: "user-uuid-here"
      id: "project-member-uuid-here"
    }
  )
}

Returns: true if successful

Effects:

1. Member record deleted
2. User loses project access
3. User notified via email/in-app
4. Activity logged
5. RBAC permissions updated

Notification Sent:

Title: "Removed From The Project"
Message: "You have been removed from [Project Name] Project."
Type: Info
Channel: Email + In-app

Requirements:

• Must have project.removeMember permission
• Target user must be project member
• Cannot remove yourself if you're the only admin

tip

For detailed member management, see the Project Members guide.

Best Practices

Project Naming

Effective Names:

• Descriptive and specific
• Include key identifiers
• Follow team conventions
• Avoid abbreviations unless standard

Examples:

Good	Why	Avoid	Why Not
"Customer Portal Backend"	Clear, specific	"Project 1"	Generic
"Q1 Marketing Campaign"	Timebound, clear	"Marketing"	Too broad
"iOS Mobile App v2"	Platform, version	"App"	Ambiguous
"Data Pipeline - Analytics"	Purpose, domain	"Pipeline"	Unclear

Lifecycle Management

Archive When:

• Project completed and documented
• Temporarily inactive (< 6 months planned)
• Seasonal initiative ended
• Reference data needed
• Testing/demo completed

Restore When:

• Need to resume work
• Access historical data
• Clone as template
• Seasonal initiative restarts

Consider Permanent Deletion When:

• Never needed again
• Compliance requires removal
• Created in error
• Duplicate project

Regular Maintenance

Monthly:

• Review active projects
• Check for inactive projects to archive
• Verify member lists are current
• Update project names if needed

Quarterly:

• Full project audit
• Archive completed projects
• Review archived projects
• Delete unnecessary archived projects (if supported)
• Update documentation

Annually:

• Comprehensive project review
• Reorganize structure if needed
• Archive old reference projects
• Update naming conventions
• Train team on best practices

Troubleshooting

Issue: Can't Update Project

Symptoms: Update mutation fails or returns error

Possible Causes:

• Missing project.update permission
• Not a project member
• Project is archived
• Invalid input data

Solutions:

1. Verify you have update permissions
2. Check project membership
3. Unarchive project first if needed
4. Validate input format
5. Check RBAC role assignments

Issue: Can't Archive Project

Symptoms: Archive operation fails

Possible Causes:

• Missing project.update permission
• Project already archived
• Active resources blocking archive
• Permission sync issues

Solutions:

1. Verify update permissions
2. Check current archived status
3. Ensure you're authorized
4. Try again after delay (sync)
5. Contact workspace administrator

Issue: Can't Switch to Project

Symptoms: Switch mutation fails or returns error

Possible Causes:

• Not a project member
• Project is archived
• Project in different workspace
• Invalid project ID
• Token generation failure

Solutions:

1. Verify project membership
2. Check project archived status
3. Ensure project in current workspace
4. Validate project ID
5. Check authentication state

Issue: Members Can't Access After Restore

Symptoms: Project restored but members have issues

Possible Causes:

• JWT tokens not refreshed
• Permission sync delay
• Browser cache issues
• RBAC resources not reactivated

Solutions:

1. Have members refresh browser
2. Log out and log back in
3. Clear browser cache
4. Wait 1-2 minutes for sync
5. Verify RBAC resources active

Advanced Topics

Project Templates

Creating Reusable Structures:

1. Create template project with standard structure
2. Add common workflows, bots, knowledge bases
3. Document setup process
4. Archive template project
5. Clone structure for new projects (manual)

Template Categories:

• Client project template
• Product feature template
• Research project template
• Internal tool template

Project Migration

Moving Between Workspaces:

Currently not directly supported. Workaround:

1. Export project data (workflows, bots, docs)
2. Create new project in target workspace
3. Import resources to new project
4. Add members to new project
5. Update external references
6. Archive old project

Bulk Operations

Managing Multiple Projects:

# Archive multiple completed projects
mutation ArchiveCompleted {
  project1: archiveProject(id: "project-1-uuid") {
    id archived
  }
  project2: archiveProject(id: "project-2-uuid") {
    id archived
  }
  project3: archiveProject(id: "project-3-uuid") {
    id archived
  }
}

Script Example:

const completedProjects = [
  "project-1-uuid",
  "project-2-uuid",
  "project-3-uuid"
];

for (const projectId of completedProjects) {
  await archiveProject({ id: projectId });
  console.log(`Archived project ${projectId}`);
}

Project Analytics

Metrics to Track:

• Active vs archived projects ratio
• Average project lifespan
• Members per project
• Resource utilization
• Archive/restore frequency
• Switch frequency (context changes)

Useful Queries:

• Projects per workspace
• Projects per user
• Most/least active projects
• Recently archived projects
• Projects without recent activity

What's Next?

• Project Members: Deep dive into member management
• Getting Started: Project creation basics
• Workspace Management: Parent workspace operations
• RBAC & Permissions: Understanding permission system

---

Need Help? Contact your project administrator or workspace administrator for additional assistance with project management operations.