Groups Management
Table of Contents
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.
{
"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"
}
]
}
// 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.
{
"status": "OK",
"message": "Group found",
"group_id": "2",
"group_name": "Gymnasium",
"status": "active"
}
// 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.
{
"status": "OK",
"message": "Group added successfully",
"group_id": "4"
}
// 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.
{
"status": "OK",
"message": "Group updated successfully"
}
// 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.
{
"status": "OK",
"message": "Group removed successfully"
}
// 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.
// 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();
*/