Skip to main content

​
Overview

Organization hierarchy actions manage the organizational structure including organizations, sites (covered in Asset Actions), and departments. Functions are located in src/app/actions/organizations.ts and src/app/actions/departments.ts.

​
Organization Operations

​
getOrganizationsService

Retrieves a paginated list of organizations with optional filtering.
​
params
object
Query parameters for filtering and pagination
​
page
number
Page number (default: 1)
​
limit
number
Items per page (default: 10)
​
search
string
Search term
​
industry
string
Filter by industry
​
team_size
string
Filter by team size
​
data
Organization[]
Array of organization objects
​
meta
OrganizationsMeta
Pagination metadata
​
page
number
Current page number
​
limit
number
Items per page
​
total
number
Total number of organizations
​
total_pages
number
Total number of pages
​
has_next
boolean
Whether there is a next page
​
has_prev
boolean
Whether there is a previous page
"use server";
import { getOrganizationsService } from "@/app/actions";

export default async function OrganizationsPage({ searchParams }) {
  const params = await searchParams;
  const page = parseInt(String(params?.page ?? 1), 10);
  const limit = parseInt(String(params?.limit ?? 10), 10);

  const { data: organizations, meta } = await getOrganizationsService({ 
    page, 
    limit 
  });

  return <OrganizationTable data={organizations} meta={meta} />;
}
On permission errors (403), this function returns an empty data array with zero total instead of throwing.

​
getOrganizationService

Retrieves a single organization by ID.
​
id
string
required
Unique organization identifier
​
data
Organization
Complete organization object
import { getOrganizationService } from "@/app/actions";

const organization = await getOrganizationService("org-123");

console.log(organization.name);
console.log(organization.industry);
console.log(organization.team_strength);

​
addOrganizationService

Creates a new organization.
​
payload
AddOrganizationPayload
required
Organization creation data
​
name
string
required
Organization name
​
industry
string
required
Industry sector (e.g., “Manufacturing”, “Energy”, “Transportation”)
​
team_strength
string
required
Team size range (e.g., “1-10”, “10-50”, “50-100”, “100-500”, “500+”)
​
description
string
required
Organization description
​
response
ApiResponse
Standard API response object
​
success
boolean
Whether the operation succeeded
​
message
string
Response message
​
data
object
Created organization data
"use client";
import { addOrganizationService } from "@/app/actions";
import { AddOrganizationPayload } from "@/schema";
import { toast } from "sonner";

export function AddOrganizationForm() {
  const handleSubmit = async (data: AddOrganizationPayload) => {
    const payload: AddOrganizationPayload = {
      name: data.name,
      industry: data.industry,
      team_strength: data.team_strength,
      description: data.description,
    };

    const response = await addOrganizationService(payload);
    
    if (response.success) {
      toast.success("Organization created successfully");
      router.push("/organizations");
    } else {
      toast.error(response.message || "Failed to create organization");
    }
  };

  return <form onSubmit={handleSubmit}>...</form>;
}

​
editOrganizationService

Updates an existing organization.
​
id
string
required
Organization ID to update
​
payload
EditOrganizationPayload
required
Updated organization data (same structure as AddOrganizationPayload)
​
response
ApiResponse
Standard API response object
import { editOrganizationService } from "@/app/actions";
import { toast } from "sonner";

const handleUpdate = async (orgId: string, data: EditOrganizationPayload) => {
  const response = await editOrganizationService(orgId, data);
  
  if (response.success) {
    toast.success("Organization updated successfully");
  } else {
    toast.error(response.message);
  }
};

​
deleteOrganizationService

Deletes an organization.
​
id
string
required
Organization ID to delete
​
response
ApiResponse
Standard API response object
import { deleteOrganizationService } from "@/app/actions";
import { toast } from "sonner";

const handleDelete = async (orgId: string) => {
  const response = await deleteOrganizationService(orgId);
  
  if (response.success) {
    toast.success("Organization deleted successfully");
  } else {
    toast.error(response.message);
  }
};

​
Department Operations

​
getDepartmentsService

Retrieves a paginated list of departments with optional filtering.
​
params
object
Query parameters for filtering and pagination
​
page
number
Page number (default: 1)
​
limit
number
Items per page (default: 10)
​
search
string
Search term
​
organization_id
string
Filter by organization ID
​
data
Department[]
Array of department objects
​
meta
DepartmentsMeta
Pagination metadata (same structure as organizations)
import { getDepartmentsService } from "@/app/actions";

const { data: departments, meta } = await getDepartmentsService({
  page: 1,
  limit: 10,
});
On permission errors (403) or API errors, returns an empty data array with default pagination metadata.

​
getDepartmentService

Retrieves a single department by ID.
​
id
string
required
Department ID
​
data
Department
Complete department object
import { getDepartmentService } from "@/app/actions";

const department = await getDepartmentService("dept-123");
console.log(department.name);

​
addDepartmentService

Creates a new department.
​
payload
AddDepartmentPayload
required
Department creation data
​
name
string
required
Department name
​
description
string
required
Department description
​
organization_id
string
required
Parent organization ID
​
response
ApiResponse
Standard API response object
"use client";
import { addDepartmentService } from "@/app/actions";
import { AddDepartmentPayload } from "@/schema";
import { toast } from "sonner";

export function AddDepartmentForm() {
  const handleSubmit = async (data: AddDepartmentPayload) => {
    const payload: AddDepartmentPayload = {
      name: data.name,
      description: data.description,
      organization_id: data.organization_id,
    };

    const response = await addDepartmentService(payload);
    
    if (response.success) {
      toast.success("Department created successfully");
      router.push("/departments");
    } else {
      toast.error(response.message || "Failed to create department");
    }
  };

  return <form onSubmit={handleSubmit}>...</form>;
}
The payload is automatically transformed to match the API format with nested organization object.

​
editDepartmentService

Updates an existing department.
​
id
string
required
Department ID to update
​
payload
EditDepartmentPayload
required
Updated department data (same structure as AddDepartmentPayload)
​
response
ApiResponse
Standard API response object
import { editDepartmentService } from "@/app/actions";
import { toast } from "sonner";

const handleUpdate = async (deptId: string, data: EditDepartmentPayload) => {
  const response = await editDepartmentService(deptId, data);
  
  if (response.success) {
    toast.success("Department updated successfully");
  } else {
    toast.error(response.message);
  }
};

​
deleteDepartmentService

Deletes a department.
​
id
string
required
Department ID to delete
​
response
ApiResponse
Standard API response object
import { deleteDepartmentService } from "@/app/actions";
import { toast } from "sonner";

const handleDelete = async (deptId: string) => {
  const response = await deleteDepartmentService(deptId);
  
  if (response.success) {
    toast.success("Department deleted successfully");
  } else {
    toast.error(response.message);
  }
};

​
Common Workflows

​
Create Organizational Hierarchy

import { 
  addOrganizationService, 
  addDepartmentService,
  addSiteService 
} from "@/app/actions";
import { toast } from "sonner";

// 1. Create organization
const orgResponse = await addOrganizationService({
  name: "Acme Manufacturing",
  industry: "Manufacturing",
  team_strength: "100-500",
  description: "Industrial equipment manufacturer",
});

if (!orgResponse.success) {
  toast.error("Failed to create organization");
  return;
}

const orgId = orgResponse.data?.data?.id;

// 2. Create departments
const departments = [
  {
    name: "Maintenance",
    description: "Equipment maintenance and repair",
    organization_id: orgId,
  },
  {
    name: "Operations",
    description: "Production operations",
    organization_id: orgId,
  },
];

for (const dept of departments) {
  await addDepartmentService(dept);
}

// 3. Create sites
const siteResponse = await addSiteService({
  name: "Main Production Facility",
  organization_id: orgId,
  // ... other site fields
});

if (siteResponse.success) {
  toast.success("Organization hierarchy created successfully");
}

​
List All Resources in Organization

import { 
  getDepartmentsService,
  getSitesService,
  getAssetsService 
} from "@/app/actions";

export default async function OrganizationOverview({ orgId }) {
  const [departments, sites, assets] = await Promise.all([
    getDepartmentsService({ organization_id: orgId }),
    getSitesService({ organization_id: orgId }),
    getAssetsService({ organization_id: orgId }),
  ]);

  return (
    <div>
      <h2>Organization Resources</h2>
      <p>{departments.data.length} departments</p>
      <p>{sites.data.length} sites</p>
      <p>{assets.data.length} assets</p>
      
      <DepartmentList departments={departments.data} />
      <SiteList sites={sites.data} />
      <AssetList assets={assets.data} />
    </div>
  );
}

​
Type Definitions

Import types from @/types and schemas from @/schema: 
import { Organization, Department } from "@/types";
import { 
  AddOrganizationPayload, 
  EditOrganizationPayload,
  AddDepartmentPayload,
  EditDepartmentPayload,
  ADD_ORGANIZATION_SCHEMA,
  ADD_DEPARTMENT_SCHEMA 
} from "@/schema";
import { ApiResponse } from "@/app/actions";
import { 
  OrganizationsMeta,
  DepartmentsMeta 
} from "@/app/actions";

Build docs developers (and LLMs) love

Get started for freeTalk to us