Skip to main content

Getting Started with Projects

This guide will walk you through creating your first project, understanding its structure, adding team members, and organizing your work effectively within the Workspace Platform.

Before You Begin​

To create a project, you need:

  • Workspace Membership: Access to an active workspace
  • Create Permission: create:project permission in the workspace
  • Project Name: Descriptive name for your project
info

Every workspace comes with a default project called "My Project" that's created automatically. You can use this immediately or create additional projects.

Step 1: Create Your First Project​

Using the Web Interface​

  1. Navigate to Projects

    • Log into the Workspace Platform
    • Select your workspace
    • Go to the "Projects" section
    • Click "Create New Project"

  2. Enter Project Details

    • Name (Required): Enter descriptive project name
      • Examples: "Customer Portal Backend", "Mobile App iOS", "Marketing Campaign Q1"

  3. Create Project

    • Click "Create Project"
    • System creates project and adds you as member
    • Project is ready to use immediately

Using the GraphQL API​

mutation CreateProject {
  createProject(
    input: {
      name: "Customer Portal Backend"
    }
  ) {
    id
    name
    workspaceID
    key
    archived
    createdAt
    projectMembers {
      id
      userID
      user {
        firstName
        lastName
      }
    }
  }
}

Response:

{
  "data": {
    "createProject": {
      "id": "project-uuid",
      "name": "Customer Portal Backend",
      "workspaceID": "workspace-uuid",
      "key": "project-key-uuid-v6",
      "archived": false,
      "createdAt": "2024-01-15T10:30:00Z",
      "projectMembers": [{
        "id": "member-uuid",
        "userID": "your-user-uuid",
        "user": {
          "firstName": "John",
          "lastName": "Doe"
        }
      }]
    }
  }
}

What Happens Automatically:

  1. Project created in current workspace
  2. Unique project ID and key generated
  3. You added as first project member
  4. RBAC resource registered with project key
  5. Permissions initialized
  6. Activity logged
  7. Success notification sent

Step 2: Understand Your Project Setup​

Project Components​

After creation, your project includes:

1. Project Record

  • Unique project ID
  • Unique project key (for RBAC)
  • Your chosen name
  • Workspace association
  • Status: active
  • Archived: false

2. Project Membership

  • You're the first project member
  • Can add other team members
  • Project-level access control

3. RBAC Resource

  • Registered as RBAC resource
  • Uses project key as identifier
  • Enables hierarchical permissions
  • Resource type: project

4. Ready for Resources

  • Can create workflows (FluidGrids)
  • Can create bots (Botlit)
  • Can create knowledge bases
  • Can add team members

Step 3: View Your Project​

Get Project Details​

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

List All Your Projects​

View all projects in your workspace(s):

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

Returns: Only projects where you're a member

Multiple Workspaces​

Query projects across multiple workspaces:

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

If no workspaceIDs provided: Returns projects from your current workspace

Step 4: Add Team Members​

Add Member to Project​

mutation AddProjectMember {
  addProjectMember(
    input: {
      projectID: "project-uuid-here"
      userID: "team-member-user-uuid"
      role: "developer"
    }
  ) {
    id
    userID
    role
    projectID
  }
}

Requirements:

  • User must be a workspace member first
  • You need project.addMember permission
  • User will gain project-level access

Common Roles:

  • developer - Full development access
  • viewer - Read-only access
  • admin - Administrative access
  • team-lead - Team management access

View Project Members​

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

Step 5: Switch to Your Project​

Switch Project Context​

Change your active project:

mutation SwitchToProject {
  switchProject(projID: "project-uuid-here")
}

Returns: New JWT token with project context

Requirements:

  • Must be a project member
  • Project must belong to current workspace
  • Project must not be archived

Use Cases:

  • Working on multiple projects
  • Switching between initiatives
  • Context-specific operations
  • Project-scoped API calls

Client Implementation:

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

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

  // Refresh to load project context
  window.location.reload();
}

Step 6: Start Adding Resources​

Create Workflows (FluidGrids)​

mutation CreateWorkflow {
  createWorkflow(
    input: {
      projectID: "project-uuid-here"
      name: "User Onboarding Workflow"
      description: "Automated user onboarding process"
    }
  ) {
    id
    name
    projectID
  }
}

Create Bots (Botlit)​

mutation CreateBot {
  createBot(
    input: {
      projectID: "project-uuid-here"
      name: "Customer Support Bot"
      type: "support"
    }
  ) {
    id
    name
    projectID
  }
}

Create Knowledge Base​

mutation CreateKnowledgeBase {
  createKnowledgeBase(
    input: {
      projectID: "project-uuid-here"
      name: "Product Documentation"
      description: "Internal product documentation"
    }
  ) {
    id
    name
    projectID
  }
}

Common Workflows​

Workflow 1: Development Project Setup​

Scenario: Setting up project for new feature

1. Create project: "User Authentication Feature"
2. Add team members:
   - Tech Lead (admin role)
   - 2 Developers (developer role)
   - QA Engineer (viewer role)
3. Create workflows:
   - "Auth Flow"
   - "Token Management"
4. Create bot:
   - "Auth Testing Bot"
5. Create knowledge base:
   - "Auth Implementation Docs"

Workflow 2: Client Project​

Scenario: Agency setting up client project

1. Create project: "Client ABC Website"
2. Add team members:
   - Project Manager (admin)
   - Developers (developer)
   - Client Stakeholder (viewer - read only)
3. Create workflows:
   - "Content Publishing"
   - "Image Optimization"
4. Create bot:
   - "Content Assistant"
5. Document everything in knowledge base

Workflow 3: Research Project​

Scenario: Research team setting up study

1. Create project: "Machine Learning Study 2024"
2. Add team members:
   - Principal Investigator (admin)
   - Researchers (developer)
   - Assistants (viewer)
3. Create workflows:
   - "Data Collection"
   - "Analysis Pipeline"
4. Create bot:
   - "Data Processing Bot"
5. Create knowledge base:
   - "Research Documentation"

Quick Start Checklist​

Use this checklist for your first project:

  • Create project with descriptive name
  • Verify you're added as project member
  • Add 2-3 initial team members
  • Assign appropriate roles to members
  • Create 1-2 initial workflows/bots
  • Set up project knowledge base
  • Document project purpose and structure
  • Test project switching functionality
  • Verify RBAC permissions work correctly

Troubleshooting​

"Cannot create project"​

Possible Causes:

  • Missing create:project permission
  • Not a workspace member
  • Workspace is inactive
  • Invalid input data

Solutions:

  1. Verify you're a workspace member
  2. Request create:project permission from admin
  3. Check workspace status
  4. Verify input data format

"Can't see project after creation"​

Possible Causes:

  • Project created in different workspace
  • Not added as project member
  • Browser cache issues

Solutions:

  1. Verify project ID from creation response
  2. Check which workspace project belongs to
  3. Query project directly by ID
  4. Refresh browser
  5. Switch to correct workspace

"Can't add team member"​

Possible Causes:

  • User not a workspace member
  • Missing project.addMember permission
  • User already a project member
  • Invalid user ID

Solutions:

  1. Invite user to workspace first
  2. Verify your permissions
  3. Check if user already a member
  4. Verify user ID is correct

"Can't switch to project"​

Possible Causes:

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

Solutions:

  1. Verify you're a project member
  2. Check project archived status
  3. Ensure project in current workspace
  4. Verify project ID is correct

What's Next?​

Now that your project is set up:

  1. Manage Projects: Learn project lifecycle operations
  2. Project Members: Master member management
  3. Workspace Management: Understand workspace structure
  4. RBAC & Permissions: Master permission system

Best Practices for New Projects​

Project Naming​

Good Names:

  • "Customer Portal Backend"
  • "Mobile App - iOS"
  • "Q1 Marketing Campaign"
  • "Data Analytics Pipeline"

Avoid:

  • "Project 1", "Test Project"
  • "asdf", "new project"
  • Overly long names
  • Names with special characters

Initial Structure​

Start Simple:

  • 1 project per major initiative
  • 3-5 initial team members
  • 2-3 core workflows/bots
  • 1 knowledge base for documentation

Avoid Over-Engineering:

  • Don't create projects for tiny tasks
  • Don't add entire workspace to project
  • Don't create excessive resources initially
  • Start focused, expand as needed

Team Organization​

Do:

  • Add only necessary team members
  • Assign appropriate roles from start
  • Document member responsibilities
  • Review membership as project evolves

Don't:

  • Grant admin access unnecessarily
  • Add everyone to every project
  • Forget to assign roles
  • Skip member documentation

Resource Management​

Do:

  • Create workflows for repeatable processes
  • Build bots for automation needs
  • Document everything in knowledge base
  • Organize resources logically

Don't:

  • Create workflows without clear purpose
  • Build bots without defined use cases
  • Skip documentation
  • Mix unrelated resources

Getting Help​

Congratulations! You've created your first project and understand the basics. You can now organize work, add team members, and build workflows and bots within your project.