Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/sakaiproject/sakai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The AnnouncementService extends the MessageService and provides functionality for managing announcements and announcement channels in Sakai LMS. Announcements are used to broadcast information to site members. Package: org.sakaiproject.announcement.api Source: /announcement/announcement-api/api/src/java/org/sakaiproject/announcement/api/AnnouncementService.java

​
Constants

​
Application Identifiers

public static final String APPLICATION_ID = "sakai:announcement";
public static final String REF_TYPE_ANNOUNCEMENT = "announcement";
public static final String REFERENCE_ROOT = "/announcement";

​
Security Permissions

public static final String SECURE_ANNC_READ = "annc.read";
public static final String SECURE_ANNC_ADD = "annc.new";
public static final String SECURE_ANNC_REMOVE_OWN = "annc.remove.own";
public static final String SECURE_ANNC_REMOVE_ANY = "annc.remove.any";
public static final String SECURE_ANNC_UPDATE_OWN = "annc.update.own";
public static final String SECURE_ANNC_UPDATE_ANY = "annc.update.any";
public static final String SECURE_ANNC_ALL_GROUPS = "annc.all.groups";

​
Core Methods

​
Channel Management

​
getAnnouncementChannel

Retrieve a specific announcement channel. 
public AnnouncementChannel getAnnouncementChannel(String ref) 
    throws IdUnusedException, PermissionException;
​
ref
String
required
The channel reference
Returns: The AnnouncementChannel with the specified reference Throws:
  • IdUnusedException - If the channel reference is not defined
  • PermissionException - If the user lacks permissions to access the channel
Example: 
String channelRef = "/announcement/channel/" + siteId + "/main";
AnnouncementChannel channel = announcementService.getAnnouncementChannel(channelRef);

​
addAnnouncementChannel

Create a new announcement channel. 
public AnnouncementChannelEdit addAnnouncementChannel(String ref) 
    throws IdUsedException, IdInvalidException, PermissionException;
​
ref
String
required
The channel reference for the new channel
Returns: The newly created AnnouncementChannelEdit object Throws:
  • IdUsedException - If the channel reference is already in use
  • IdInvalidException - If the reference contains invalid characters
  • PermissionException - If the user lacks permission to add channels
Example: 
String channelRef = "/announcement/channel/" + siteId + "/main";
AnnouncementChannelEdit edit = announcementService.addAnnouncementChannel(channelRef);
edit.getPropertiesEdit().addProperty(ResourceProperties.PROP_DISPLAY_NAME, "Announcements");
announcementService.commitChannel(edit);

​
Message Retrieval

​
getMessages

Retrieve messages from a channel with optional filtering and merging. 
public List<AnnouncementMessage> getMessages(
    String channelReference, 
    Filter filter, 
    boolean ascending, 
    boolean merged
) throws IdUnusedException, PermissionException;
​
channelReference
String
required
The channel’s reference string
​
filter
Filter
A filtering object to accept messages, or null for no filtering
​
ascending
boolean
required
Order of messages - true for ascending, false for descending
​
merged
boolean
required
Flag to include merged channel messages from other sites/channels
Returns: List of AnnouncementMessage objects (may be empty) Example: 
String channelRef = "/announcement/channel/" + siteId + "/main";
Filter filter = announcementService.getMaxAgeInDaysAndAmountFilter(30, 10);
List<AnnouncementMessage> messages = announcementService.getMessages(
    channelRef, filter, false, false
);

​
getChannelMessages

Retrieve messages with advanced filtering options including merged channels and synoptic views. 
public List<AnnouncementMessage> getChannelMessages(
    String channelReference,
    Filter filter,
    boolean ascending,
    String mergedChannelDelimitedList,
    boolean allUserSites,
    boolean isSynopticTool,
    String siteId,
    Integer maxAgeInDays
) throws PermissionException;
​
channelReference
String
The hosting channel reference
​
filter
Filter
A filtering object, or null if no filtering is desired
​
ascending
boolean
required
Order of messages - true for ascending, false for descending
​
mergedChannelDelimitedList
String
Delimited list of channel references to merge
​
allUserSites
boolean
required
Set to true to retrieve messages from all user’s sites
​
isSynopticTool
boolean
required
Whether this is being called from a synoptic tool
​
siteId
String
The site we want messages for
​
maxAgeInDays
Integer
If filter is null, this will filter returned messages by age
Returns: List of AnnouncementMessage objects Example: 
// Get announcements from all user sites for synoptic view
List<AnnouncementMessage> messages = announcementService.getChannelMessages(
    null, null, false, null, true, true, null, 30
);

​
getVisibleMessagesOfTheDay

Retrieve visible Message of the Day (MOTD) announcements. 
public List<AnnouncementMessage> getVisibleMessagesOfTheDay(
    Time afterDate, 
    int numberOfAnnouncements, 
    boolean ascending
);
​
afterDate
Time
Optional lower-bound date filter - messages before this are excluded
​
numberOfAnnouncements
int
required
Maximum number of messages to return (values < 0 are treated as 0)
​
ascending
boolean
required
Sort order - true for oldest-first, false for newest-first
Returns: List of visible MOTD announcements Example: 
Time yesterday = timeService.newTime(System.currentTimeMillis() - 86400000);
List<AnnouncementMessage> motd = announcementService.getVisibleMessagesOfTheDay(
    yesterday, 5, false
);

​
Utility Methods

​
getAnnouncementReference

Get the announcement entity reference for a given context. 
public Reference getAnnouncementReference(String context);
​
context
String
required
The announcement context (site-id)
Returns: Announcement entity reference

​
getRssUrl

Get the URL to access the announcement RSS feed. 
public String getRssUrl(Reference ref);
​
ref
Reference
required
The announcement entity reference
Returns: URL for announcement RSS feed

​
clearMessagesCache

Clear the message cache for a specific channel. 
public void clearMessagesCache(String channelRef);
​
channelRef
String
required
The channel reference
Example: 
String channelRef = "/announcement/channel/" + siteId + "/main";
announcementService.clearMessagesCache(channelRef);

​
getMaxAgeInDaysAndAmountFilter

Create a filter based on maximum age and message count. 
public Filter getMaxAgeInDaysAndAmountFilter(Integer maxAgeInDays, Integer amount);
​
maxAgeInDays
Integer
Maximum age of messages in days
​
amount
Integer
Maximum number of messages to return
Returns: A Filter object configured with the specified parameters

​
Events

​
Event Types

public static final String EVENT_ANNC_UPDATE_TITLE = "annc.revise.title";
public static final String EVENT_ANNC_UPDATE_ACCESS = "annc.revise.access";
public static final String EVENT_ANNC_UPDATE_AVAILABILITY = "annc.revise.availability";
public static final String EVENT_AVAILABLE_ANNC = "annc.available.announcement";

​
Tool IDs

public static final String MOTD_TOOL_ID = "sakai.motd";
public static final String SAKAI_ANNOUNCEMENT_TOOL_ID = "sakai.announcements";
public static final String SYNOPTIC_ANNOUNCEMENT_TOOL = "sakai.synoptic.announcement";

​
Usage Examples

​
Complete Example: Creating and Posting an Announcement

import org.sakaiproject.announcement.api.*;
import org.sakaiproject.entity.api.ResourceProperties;
import org.sakaiproject.time.api.Time;
import org.sakaiproject.time.api.TimeService;

public class AnnouncementExample {
    
    private AnnouncementService announcementService;
    private TimeService timeService;
    
    public void createAnnouncement(String siteId, String title, String body) {
        try {
            // Get or create the channel
            String channelRef = "/announcement/channel/" + siteId + "/main";
            AnnouncementChannel channel;
            
            try {
                channel = announcementService.getAnnouncementChannel(channelRef);
            } catch (IdUnusedException e) {
                // Channel doesn't exist, create it
                AnnouncementChannelEdit channelEdit = 
                    announcementService.addAnnouncementChannel(channelRef);
                channelEdit.getPropertiesEdit().addProperty(
                    ResourceProperties.PROP_DISPLAY_NAME, "Announcements"
                );
                announcementService.commitChannel(channelEdit);
                channel = announcementService.getAnnouncementChannel(channelRef);
            }
            
            // Create the announcement message
            AnnouncementMessageEdit message = channel.addAnnouncementMessage();
            message.setBody(body);
            
            AnnouncementMessageHeaderEdit header = message.getAnnouncementHeaderEdit();
            header.setSubject(title);
            header.setDraft(false);
            
            // Set release and retract dates
            Time now = timeService.newTime();
            Time oneWeekLater = timeService.newTime(now.getTime() + 7 * 24 * 60 * 60 * 1000);
            header.setDate(now);
            header.setRelease(now);
            header.setRetract(oneWeekLater);
            
            // Commit the message
            channel.commitMessage(message);
            
            System.out.println("Announcement created successfully!");
            
        } catch (Exception e) {
            System.err.println("Error creating announcement: " + e.getMessage());
        }
    }
    
    public void listRecentAnnouncements(String siteId) {
        try {
            String channelRef = "/announcement/channel/" + siteId + "/main";
            Filter filter = announcementService.getMaxAgeInDaysAndAmountFilter(30, 10);
            
            List<AnnouncementMessage> messages = announcementService.getMessages(
                channelRef, filter, false, false
            );
            
            for (AnnouncementMessage msg : messages) {
                System.out.println("Title: " + msg.getAnnouncementHeader().getSubject());
                System.out.println("Date: " + msg.getAnnouncementHeader().getDate());
                System.out.println("Body: " + msg.getBody());
                System.out.println("---");
            }
            
        } catch (Exception e) {
            System.err.println("Error listing announcements: " + e.getMessage());
        }
    }
}

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us