Groups Management

Overview

Groups are organizational units within schools in the RCAMS hierarchy. Each group typically represents a physical area of a school building such as a floor, wing, or department. Lights are assigned to groups, allowing for targeted emergency notifications to specific areas of a facility.

Note: All group management endpoints require basic authentication. The user must have appropriate permissions for the requested operations.

Group Management API Endpoints
Operation Endpoint Action Parameter
List Groups /group.php list
Get Group /group.php get
Create Group /group.php insert
Update Group /group.php update
Delete Group /group.php remove

List Groups

Retrieves all groups within a school.

POST/group.php

Returns a list of all groups within the specified school.

Request Parameters
Parameter Type Required Description
action String Yes Must be set to list
school_id String Yes ID of the school to list groups from
Response

Returns a list of groups with their IDs, names, and status.

Example Response
{
  "status": "OK",
  "message": "Groups found",
  "total": 3,
  "groups": [
    {
      "group_id": 1,
      "group_name": "Main Building",
      "status": "active"
    },
    {
      "group_id": 2,
      "group_name": "Gymnasium",
      "status": "active"
    },
    {
      "group_id": 3,
      "group_name": "Science Wing",
      "status": "active"
    }
  ]
}
Example Request (JavaScript)
// Set up the request

const jsonData = JSON.stringify({
  action: 'list',
  school_id: '1'
});

// Make the API call
fetch('https://rcamsapi.spheronomics.com/api/v2/group.php', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa('api_username:api_password')
  },
  body: jsonData
})
.then(response => response.json())
.then(data => {
  if (data.status === 'OK') {
    console.log(`Found ${data.total} groups:`, data.groups);
  } else {
    console.error('Error:', data.message);
  }
})
.catch(error => console.error('Error:', error));

Get Group

Retrieves details for a specific group.

POST/group.php

Returns detailed information about a specific group.

Request Parameters
Parameter Type Required Description
action String Yes Must be set to get
group_id String Yes ID of the group to retrieve
Response

Returns the details of the specified group.

Example Response
{
  "status": "OK",
  "message": "Group found",
  "group_id": "2",
  "group_name": "Gymnasium",
  "status": "active"
}
Example Request (JavaScript)
// Set up the request
const jsonData = JSON.stringify({
  action: 'get',
  group_id: '2'
});


// Make the API call
fetch('https://rcamsapi.spheronomics.com/api/v2/group.php', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa('api_username:api_password')
  },
  body: jsonData
})
.then(response => response.json())
.then(data => {
  if (data.status === 'OK') {
    console.log('Group details:', data);
  } else {
    console.error('Error:', data.message);
  }
})
.catch(error => console.error('Error:', error));

Create Group

Creates a new group within a school.

POST/group.php

Creates a new group with the specified name.

Request Parameters
Parameter Type Required Description
action String Yes Must be set to insert
school_id String Yes ID of the school to add the group to
group_name String Yes Name of the new group
Response

Returns confirmation that the group was created and provides the new group ID.

Example Response
{
  "status": "OK",
  "message": "Group added successfully",
  "group_id": "4"
}
Example Request (JavaScript)
// Set up the request
const jsonData = JSON.stringify({
  action: 'insert',
  school_id: '1',
  group_name: 'Math Department'
});

// Make the API call
fetch('https://rcamsapi.spheronomics.com/api/v2/group.php', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa('api_username:api_password')
  },
  body: jsonData
})
.then(response => response.json())
.then(data => {
  if (data.status === 'OK') {
    console.log('Group created with ID:', data.group_id);
  } else {
    console.error('Error:', data.message);
  }
})
.catch(error => console.error('Error:', error));

Update Group

Updates an existing group's information.

POST/group.php

Updates the name of an existing group.

Request Parameters
Parameter Type Required Description
action String Yes Must be set to update
group_id String Yes ID of the group to update
group_name String Yes New name for the group
Response

Returns confirmation that the group was updated.

Example Response
{
  "status": "OK",
  "message": "Group updated successfully"
}
Example Request (JavaScript)
// Set up the request
const jsonData = JSON.stringify({
  action: 'update',
  group_id: '4',
  group_name: 'Mathematics Department'
});

// Make the API call
fetch('https://rcamsapi.spheronomics.com/api/v2/group.php', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa('api_username:api_password')
  },
  body: jsonData
})
.then(response => response.json())
.then(data => {
  if (data.status === 'OK') {
    console.log('Group updated successfully');
  } else {
    console.error('Error:', data.message);
  }
})
.catch(error => console.error('Error:', error));

Delete Group

Removes a group from the system.

Warning: Deleting a group will unassign all lights currently assigned to it. Consider reassigning lights to another group before deletion.

POST/group.php

Deletes a group from the system.

Request Parameters
Parameter Type Required Description
action String Yes Must be set to remove
group_id String Yes ID of the group to delete
Response

Returns confirmation that the group was deleted.

Example Response
{
  "status": "OK",
  "message": "Group removed successfully"
}
Example Request (JavaScript)
// Set up the request
const jsonData = JSON.stringify({
  action: 'remove',
  group_id: '4'
});

// Make the API call
fetch('https://rcamsapi.spheronomics.com/api/v2/group.php', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa('api_username:api_password')
  },
  body: jsonData
})
.then(response => response.json())
.then(data => {
  if (data.status === 'OK') {
    console.log('Group removed successfully');
  } else {
    console.error('Error:', data.message);
  }
})
.catch(error => console.error('Error:', error));

Code Examples

Group Management Example

The following example demonstrates a complete flow for group management, including listing, creating, updating, and deleting groups.

Complete Group Management Example (JavaScript)
// Helper function for API requests
async function makeApiRequest(endpoint, params) {
  // API credentials - replace with actual values
  const apiUsername = 'your_api_username';
  const apiPassword = 'your_api_password';
  
  // Create form data from params
  const formData = new FormData();
  for (const [key, value] of Object.entries(params)) {
    formData.append(key, value);
  }

  // convert formData to json
  const jsonData = JSON.stringify(Object.fromEntries(formData.entries()));
  
  try {
    const response = await fetch(`https://rcamsapi.spheronomics.com/api/v2/${endpoint}`, {
      method: 'POST',
      headers: {
        'Authorization': 'Basic ' + btoa(`${apiUsername}:${apiPassword}`)
      },
      body: jsonData
    });
    
    return await response.json();
  } catch (error) {
    console.error('API request failed:', error);
    throw error;
  }
}

// Example usage - Group Management
async function groupManagementExample(schoolId) {
  try {
    // 1. List all groups in the school
    console.log(`Listing all groups in school ${schoolId}...`);
    const listResponse = await makeApiRequest('group.php', {
      action: 'list',
      school_id: schoolId
    });
    
    console.log(`Found ${listResponse.total} groups:`, listResponse.groups);
    
    // 2. Create a new group
    console.log('Creating a new group...');
    const createResponse = await makeApiRequest('group.php', {
      action: 'insert',
      school_id: schoolId,
      group_name: 'Library Wing'
    });
    
    if (createResponse.status === 'OK') {
      const newGroupId = createResponse.group_id;
      console.log(`Created group with ID: ${newGroupId}`);
      
      // 3. Get the group details
      console.log('Getting group details...');
      const getResponse = await makeApiRequest('group.php', {
        action: 'get',
        group_id: newGroupId
      });
      
      console.log('Group details:', getResponse);
      
      // 4. Update the group name
      console.log('Updating group name...');
      const updateResponse = await makeApiRequest('group.php', {
        action: 'update',
        group_id: newGroupId,
        group_name: 'Media Center Wing'
      });
      
      console.log('Update result:', updateResponse.message);
      
      // 5. Delete the group (commented out for safety)
      // Uncomment to actually delete the group
      /*
      console.log('Deleting group...');
      const deleteResponse = await makeApiRequest('group.php', {
        action: 'remove',
        group_id: newGroupId
      });
      
      console.log('Delete result:', deleteResponse.message);
      */
    }
  } catch (error) {
    console.error('An error occurred:', error);
  }
}

// Run the example (you would need a valid school ID)
/*
async function runExample() {
  
  const loginResponse = await makeApiRequest('login.php', {
    user: 'user@example.com',
    pass: 'password123'
  });
  
  if (loginResponse.status === 'OK') {
    await groupManagementExample('1'); // Replace '1' with actual school ID
  } else {
    console.error('Login failed:', loginResponse.message);
  }
}

runExample();
*/